Skip to content

File HB-001 for UI-path merge-queue enable; correct research doc §10.3 #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AceHack merged 2 commits into from
Apr 21, 2026
Merged

File HB-001 for UI-path merge-queue enable; correct research doc §10.3 #42

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
07d912e
Reshape HB-001 to org-migration + CodeQL path-gate for docs-only PRs
AceHack Apr 21, 2026
efa9ab9
codeql path-gate: per-language SARIF categories + fork-PR guard
AceHack Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 188 additions & 0 deletions .github/workflows/codeql.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,28 @@
# 6. `concurrency: cancel-in-progress` cuts stale runs on
# force-push; 30-minute timeout caps the CodeQL DB-build
# tail which is a known flaky source.
# 7. `path-gate` job runs before analyze. It checks whether
# any code-scanned paths changed; if not (pure docs /
# memory / .claude PR), it uploads a minimal
# no-findings SARIF per language (one per analyze-matrix
# category: `/language:actions/` and `/language:csharp/`)
# to the code-scanning service and the `analyze` matrix
# is skipped. This keeps the repository-level
# `code_scanning` ruleset rule ("Require code scanning
# results") satisfied on every PR — docs-only PRs no
# longer NEUTRAL the aggregated `CodeQL` status check,
# which the rule interprets as "no results" and blocks
# on. Code-touching PRs still run the full analysis as
# before.
#
# Fork-PR guard: external-contributor PRs get
# downgraded `GITHUB_TOKEN` permissions, so the
# synthetic SARIF upload (needs `security-events:
# write`) would 403 and leave the required check
# unsatisfied. The decide step forces `code_changed=true`
# on fork PRs so they fall through to full `analyze`
# instead of the short-circuit; CodeQL's analyze handles
# fork-PR permissions via its own fallback path.
#
# SECURITY NOTE on `${{ ... }}` expressions
# ------------------------------------------
Expand Down Expand Up @@ -72,8 +94,174 @@ concurrency:
cancel-in-progress: true

jobs:
# Fast pre-check: decide whether any code-scanned paths
# actually changed in this PR / merge-group. On pure docs /
# memory / .claude-only PRs we short-circuit to uploading a
# minimal no-findings SARIF so the `code_scanning` ruleset
# rule sees "results" and does not block on NEUTRAL.
#
# Push and schedule events always fall through to the full
# analyze matrix - those runs establish the baseline for the
# default branch.
path-gate:
name: Path gate
runs-on: ubuntu-22.04
permissions:
contents: read
security-events: write
outputs:
Comment thread
AceHack marked this conversation as resolved.
code_changed: ${{ steps.decide.outputs.code_changed }}
steps:
- name: Checkout (full history for diff)
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
fetch-depth: 0

- name: Decide whether code paths changed
id: decide
shell: bash
env:
GH_EVENT: ${{ github.event_name }}
BASE_SHA: ${{ github.event.pull_request.base.sha }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
MG_BASE: ${{ github.event.merge_group.base_sha }}
MG_HEAD: ${{ github.event.merge_group.head_sha }}
# Fork-PR detection: on PRs from forks, GITHUB_TOKEN is
# downgraded to read-only for security-events, so the
# synthetic empty-SARIF upload would 403 and leave the
# required check unsatisfied. Force full-analysis path
# on fork PRs so they don't become unmergeable; CodeQL
# analyze handles fork-PR permissions via its own
# fallback. Same-repo PRs use "" == "" (the head repo
# is the base repo).
HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
BASE_REPO: ${{ github.repository }}
run: |
set -uo pipefail
# Safe default: when unsure, run full analysis.
decide_fallback_true() {
echo "code_changed=true" >> "$GITHUB_OUTPUT"
exit 0
}
# push and schedule always run full analysis.
if [ "${GH_EVENT}" = "push" ] || [ "${GH_EVENT}" = "schedule" ]; then
decide_fallback_true
fi
# Fork-PR guard: skip the short-circuit on external
# contributor PRs (see HEAD_REPO comment above).
if [ "${GH_EVENT}" = "pull_request" ] && [ -n "${HEAD_REPO}" ] && [ "${HEAD_REPO}" != "${BASE_REPO}" ]; then
decide_fallback_true
fi
if [ "${GH_EVENT}" = "pull_request" ]; then
base="${BASE_SHA}"; head="${HEAD_SHA}"
else
base="${MG_BASE}"; head="${MG_HEAD}"
fi
if [ -z "${base}" ] || [ -z "${head}" ]; then
decide_fallback_true
fi
# Ensure base ref is in history (shallow fetches may miss it).
git cat-file -e "${base}^{commit}" 2>/dev/null || {
git fetch --no-tags --depth=200 origin "${base}" 2>/dev/null || true
}
if ! changed=$(git diff --name-only "${base}...${head}" 2>/dev/null); then
decide_fallback_true
fi
# Code-scanned paths: C#/F# sources, project files,
# build props, the GitHub Actions workflows that
# CodeQL's `actions` language leg covers, the
# CodeQL workflow/config themselves (a change to
# either MUST rerun the real analysis), and the
# toolchain install script (affects the csharp build).
#
# Note: `case` pattern `*` matches across `/` in bash,
# so `src/*` covers any depth under `src/`.
code_changed=false
while IFS= read -r f; do
[ -z "${f}" ] && continue
case "${f}" in
src/*|test/*) code_changed=true ;;
*.cs|*.fs|*.fsproj|*.csproj|*.sln) code_changed=true ;;
Directory.Build.props|Directory.Packages.props) code_changed=true ;;
.github/workflows/*|.github/codeql/*) code_changed=true ;;
tools/setup/*) code_changed=true ;;
esac
[ "${code_changed}" = "true" ] && break
done <<< "${changed}"
echo "code_changed=${code_changed}" >> "$GITHUB_OUTPUT"

# Docs-only branch: synthesise a minimal empty SARIF per
# language and upload each under the matching analyze-job
# category (/language:actions/ and /language:csharp/) so
# GitHub code scanning records "analysis ran, no new
# alerts" (SUCCESS aggregate check) rather than NEUTRAL.
# Categories must match the `analyze` matrix categories or
# the code-scanning service treats them as unrelated
# configurations. The `category:` action-param overrides
# whatever `automationDetails.id` is in the SARIF, so the
# upload steps below set it explicitly per language.
- name: Emit no-findings SARIF (docs-only PRs)
if: steps.decide.outputs.code_changed != 'true'
env:
HEAD_SHA_ENV: ${{ github.event.pull_request.head.sha || github.event.merge_group.head_sha || github.sha }}
run: |
set -euo pipefail
mkdir -p sarif
for lang in actions csharp; do
cat > "sarif/empty-${lang}.sarif" <<SARIF
{
"version": "2.1.0",
"\$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
"runs": [
{
"tool": {
"driver": {
"name": "CodeQL",
"semanticVersion": "0.0.0",
"informationUri": "https://codeql.github.com/",
"rules": []
}
},
"results": [],
"automationDetails": {
"id": "/language:${lang}/"
},
"versionControlProvenance": [
{
"repositoryUri": "https://github.com/${GITHUB_REPOSITORY}",
"revisionId": "${HEAD_SHA_ENV}",
"branch": "${GITHUB_REF_NAME}"
}
]
}
]
}
SARIF
done

# One upload step per language; each sets `category:` to
# match the analyze-job category for that language. Split
# (rather than a single directory upload) so the `category:`
# action-param -- which overrides SARIF automationDetails --
# can differ per file.
- name: Upload no-findings SARIF (actions)
if: steps.decide.outputs.code_changed != 'true'
uses: github/codeql-action/upload-sarif@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4.35.2
with:
sarif_file: sarif/empty-actions.sarif
category: "/language:actions"

- name: Upload no-findings SARIF (csharp)
if: steps.decide.outputs.code_changed != 'true'
uses: github/codeql-action/upload-sarif@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4.35.2
with:
sarif_file: sarif/empty-csharp.sarif
category: "/language:csharp"

analyze:
name: Analyze (${{ matrix.language }})
needs: path-gate
if: needs.path-gate.outputs.code_changed == 'true'
runs-on: ubuntu-22.04
timeout-minutes: 30

Expand Down
32 changes: 28 additions & 4 deletions docs/HUMAN-BACKLOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,33 @@ Each row is one entry in the table below. Columns:
- **Resolution** — when Resolved, what the human decided
and why. Blank while Open.

## Name attribution — explicit carve-out

`docs/AGENT-BEST-PRACTICES.md` §"No name attribution in code,
docs, or skills" instructs docs to use role-refs ("the human
maintainer") instead of personal names. **This file is a
deliberate exception** by the maintainer's own directive
(2026-04-20: *"can you put my tasks at the top of the human
backlog i don't want to have to go digging through it to find
my tasks"*). The `For:` column and the per-addressee sub-table
headers intrinsically require personal names to do their job —
a human must be able to find their own asks at a glance.

The carve-out is narrow:

- **In scope for names:** the `For:` column and the sub-table
headers (`### For: Aaron`, `### For: <other name>`, etc.),
plus direct quotations in `Source` or `Ask` fields where
redaction would lose evidential value.
- **Out of scope for names:** any prose *outside* the row
schema in this file (e.g. the intro, filing rules, prior
art). Those paragraphs continue to use role-refs. Other
docs / skills / code still follow the BP unchanged.

This carve-out is also recorded in
`memory/feedback_maintainer_name_redaction.md` (exempt-surfaces
list) so the doc-set and the agent memory stay consistent.
Comment thread
AceHack marked this conversation as resolved.

## Rows

Rows are grouped by `For:` addressee so a given human can
Expand All @@ -204,10 +231,7 @@ are ordered by `State: Open` first, then `Stale`, then

| ID | When | Category | Ask | Source | State | Resolution |
|---|---|---|---|---|---|---|

*(Aaron currently has no open asks — the 2026-04-20 pm
signoff released all previously gated items. When new
asks arise for Aaron, they land in this sub-table.)*
| HB-001 | 2026-04-21 | decision / org-migration | Plan + execute the migration of `AceHack/Zeta` → `Lucent-Financial-Group/Zeta` (Aaron's LFG umbrella org — `project_lucent_financial_group_external_umbrella.md`). Drivers: (a) GitHub gates merge queue and other org-level features to organization-owned repos — user-owned repos cannot enable merge queue on any plan tier, which is the real blocker behind the `422 Invalid rule 'merge_queue':` failure against `POST /repos/AceHack/Zeta/rulesets` (see §10.3 of `docs/research/parallel-worktree-safety-2026-04-22.md`); (b) aligns the repo with Aaron's stated destination for external contributors. **Constraints (Aaron 2026-04-21):** (1) **preserve all current settings** — rulesets, required checks (gate + CodeQL + semgrep), branch-protection behaviours, auto-delete-head-branch, auto-merge, Dependabot, CodeScanning, Copilot Code Review, concurrency groups, workflow triggers incl. `merge_group:`; (2) **public from the start** at the new location — no private-during-transition staging period. No deadline — "at some point". Until transferred, the factory accepts the rebase-tax on serial PRs and relies on `gh pr merge --auto --squash` alone (merge queue off). | `docs/research/parallel-worktree-safety-2026-04-22.md` §10.3; session transcript 2026-04-21 (Aaron: "we can move tih to https://github.com/Lucent-Financial-Group at some point it's my org for LFG" + "we need to move it to lucent for contributor at some point anyways, we want to keep all the settings we have now" + "i think we are going to have to go without merge queue parallelism for now" + "we can just make it public from the start") | Open | — |
Comment thread
AceHack marked this conversation as resolved.

### For: `any` (any human contributor)

Expand Down
78 changes: 55 additions & 23 deletions docs/research/parallel-worktree-safety-2026-04-22.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -342,11 +342,18 @@ agents both editing `docs/BACKLOG.md` in parallel worktrees still
produce a merge conflict at queue time; the queue just makes the
firing deterministic.

### 10.3 Action — enable merge queue (2026-04-22, direct)
### 10.3 Action — merge queue prerequisites + platform gate

Aaron 2026-04-22: *"i'm the admin you can toggle it all you want"* —
standing permission granted; no HB-001 filing needed, admin toggles
done inline. Discovered state and actions:
standing permission for repo-settings toggles was granted and used
for the workflow-trigger prerequisite (landed inline via PR #41).
Enabling merge queue *itself*, however, turned out to be
platform-gated in a way the permission cannot reach — see the
"Merge queue ruleset config" block below. The durable resolution
moved out of the admin-toggle surface onto the org-migration
surface, filed as `HB-001` in `docs/HUMAN-BACKLOG.md`.

Discovered state and actions taken:

**Already on (no action needed):**

Expand All @@ -367,26 +374,51 @@ listen to `merge_group` events, or merges deadlock. Added
(all six required checks) and `.github/workflows/codeql.yml` (best-
effort though not required). Landed as PR #41 to main.

**Merge queue ruleset config (2026-04-22 landed):**

Created repository ruleset "Merge queue for main":

- Target: `~DEFAULT_BRANCH` (`main`).
- Rule type: `merge_queue`.
- `merge_method: SQUASH` — matches current `gh pr merge --squash`
convention.
- `grouping_strategy: ALLGREEN` — safer than `HEADGREEN`; a failing
PR in the group fails the whole group rather than partially merging.
- `min_entries_to_merge: 1`, `max_entries_to_merge: 5`,
`min_entries_to_merge_wait_minutes: 5`,
`max_entries_to_merge_wait_minutes: 60`,
`max_entries_to_build: 5`,
`check_response_timeout_minutes: 60` — conservative defaults;
revisit after observing a month of queue traffic.
- Required checks stay the same six classic-branch-protection
requires; the queue re-runs them against the merge-group branch.

Once both are enabled, the agent convention shifts from:
**Merge queue ruleset config — blocked at the platform level (not the API):**

Attempted to create a repository ruleset "Merge queue for main"
via `POST /repos/AceHack/Zeta/rulesets` targeting `~DEFAULT_BRANCH`.
GitHub returned `422 Validation Failed` with the body
`{"errors":["Invalid rule 'merge_queue': "]}` — empty error detail.
Tried both the original params and the docs-example params
verbatim; same response in both cases. The failure class initially
looked like the public-beta instability reported in
[community discussion #156625](https://github.com/orgs/community/discussions/156625).

Escalated to the UI path (Settings → Rules → Rulesets → "New
branch ruleset") expecting a ~30-second toggle. Aaron reported the
UI path equally missing: *"so it's missing for me in the UI too,
it's supposed to be there becasue we are public, i also turned up
the settings"*. Diagnosis via `gh api /users/AceHack --jq '.type'`
returned `"User"` — not `"Organization"`. Per GitHub platform
rules, **merge queue is an organization-only feature** regardless
of plan tier or public/private status; user-owned repos cannot
enable it through the UI, the REST API, or any other surface. The
empty-body `422` from the ruleset API is the platform gate, not a
beta-API quirk.

**Resolution path — HB-001 (org migration).** Filed for Aaron in
`docs/HUMAN-BACKLOG.md`. The durable fix is migrating
`AceHack/Zeta` → `Lucent-Financial-Group/Zeta` (Aaron's LFG
umbrella org, see `memory/persona/project_lucent_financial_group_external_umbrella.md`),
which Aaron has independently flagged as the right home for
external contributors. **Constraint: preserve all current
Comment thread
AceHack marked this conversation as resolved.
settings** — rulesets, required checks (gate + CodeQL + semgrep),
auto-delete-head-branch, auto-merge, Dependabot, CodeScanning,
Copilot Code Review, concurrency groups, workflow triggers incl.
`merge_group:`. No deadline ("at some point"); accepted 2026-04-21.

**Interim policy — skip merge-queue parallelism, accept
rebase-tax.** Per Aaron 2026-04-21: *"i think we are going to have
to go without merge queue parallelism for now."* The factory keeps
the `merge_group:` workflow triggers landed via PR #41 (they are
no-ops until merge queue is enabled, so harmless) and relies on
`gh pr merge --auto --squash` alone. Serial PRs pay the rebase
cost; the structural fix is the org migration, not a workflow
tweak.

Once the org migration lands and merge queue can be enabled, the
agent convention shifts from:

> Open PR → wait for CI → manually `gh pr merge`

Expand Down
Loading