@event4u/agent-config 14.7.0 → 14.8.0

package/README.md

@@ -4,7 +4,7 @@
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config) [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fevent4u-app%2Fagent-config.svg)](https://mcptoplist.com/server/glama%2Fevent4u-app%2Fagent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-290-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-119-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-200-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-107-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
+[![Skills](https://img.shields.io/badge/Skills-290-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-119-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-201-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-107-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
 
 **Try it in 30 seconds** — drop one read-only subagent into any repo and watch it gate "done": `@production-validator check this branch is actually done`. No wizard, no lock-in, nothing else installed — the [30-second wedge ↓](#quickstart) is the whole first step. Start at the proof, not the catalog: **[event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/)**.
 

package/dist/agent-src/commands/evals/git-pr-merge.json

@@ -0,0 +1,13 @@
+{
+  "command": "git-pr-merge",
+  "intent": "Prepare an open PR to mergeable — sync, resolve conflicts semantically, drive CI green — and merge it when the invocation says so",
+  "cases": [
+    { "prompt": "merge PR 1478", "expected": "git-pr-merge" },
+    { "prompt": "get this pull request mergeable and merge it", "expected": "git-pr-merge" },
+    { "prompt": "drain all the open PRs — sync each one with main, fix CI, merge", "expected": "git-pr-merge" },
+    { "prompt": "bring PR 1502 up to date with main and get its checks green, but don't merge it", "expected": "git-pr-merge" },
+    { "prompt": "the open PRs all conflict with each other now — work through the queue", "expected": "git-pr-merge" },
+    { "prompt": "open a pull request for this branch", "expected": "git-pr-create" },
+    { "prompt": "write me a PR description I can paste", "expected": "git-pr-create-description-only" }
+  ]
+}

package/dist/agent-src/commands/evals/roadmap.json

@@ -1,6 +1,6 @@
 {
   "command": "roadmap",
-  "intent": "Roadmap dispatcher — create, process-step, process-phase, process-full, ai-council",
+  "intent": "Roadmap dispatcher — create, materialize, process-step, process-phase, process-full (incl. --all estate drain), next, ai-council",
   "cases": [
     {
       "prompt": "create a roadmap for this initiative",
@@ -37,6 +37,22 @@
     {
       "prompt": "either roadmap it or turn it into a feature plan, your pick",
       "expected": "roadmap"
+    },
+    {
+      "prompt": "drain every open roadmap, one PR each",
+      "expected": "roadmap"
+    },
+    {
+      "prompt": "arbeite alle Roadmaps der Reihe nach ab",
+      "expected": "roadmap"
+    },
+    {
+      "prompt": "work through the whole roadmap estate in a worktree",
+      "expected": "roadmap"
+    },
+    {
+      "prompt": "merge all the open pull requests",
+      "expected": "git-pr-merge"
     }
   ]
 }

package/dist/agent-src/commands/pr/create.md

@@ -153,8 +153,20 @@ merge into instead of against the repo default.
 `./scripts-run src/scripts/sync_pr_branch` resolves the base from the open PR
 (so a stacked or release-line PR is measured against what it actually merges
 into), fetches, and merges it in when the branch is behind. On a conflict it
-STOPS and splits the conflicted paths into generated and authored — the first has
-one correct resolution (regenerate), the second has none a script may choose.
+STOPS and splits the conflicted paths into generated, remeasured and authored —
+the first has one correct resolution (regenerate), the second's is to re-run the
+measurement on the merged tree (a ratchet baseline, where picking a side is how
+the ratchet silently loosens), and the third has none a script may choose.
+
+**On `CONFLICTING`, run this before touching the GitHub web editor.** The web
+editor cannot tell generated from authored, so it presents a mechanical
+regenerate and a real human decision as the same three-way merge — which is the
+failure path road-to-merge-hotspot-drawdown was opened over — a branch resolved
+in the web editor while behind its base. The observation itself lives in the
+maintainer handover that roadmap cites as its Source, not in the roadmap's own
+§ 0, so do not expect to find it there. Adoption of this line is not measurable
+without telemetry this repository has ruled out; it is a checklist item, not a
+gate.
 Deliberately not in the pre-push hook: it mutates the tree, and a hook that
 rewrites the tree mid-push turns one rejected push into an unreviewed commit.
 Detection belongs in the hook and is already there; resolution is a step you run

package/dist/agent-src/commands/pr/merge.md

@@ -0,0 +1,379 @@
+---
+model_tier: medium
+name: git-pr-merge
+disable-model-invocation: true
+argument-hint: "[all|<pr-number>] [--no-merge]"
+pack: git
+intent: "Prepare an open PR to mergeable — sync the base in, resolve conflicts semantically, drive required checks green — merging itself is gated and inert"
+routes_to: [git-workflow, github-ci]
+replaces: []
+visibility: advanced
+cluster: git-pr-merge
+skills: [git-workflow, github-ci]
+description: Prepare one open PR to mergeable, or the whole open-PR queue with `all` — merging is specified but gated, so today every invocation stops at mergeable-and-open
+suggestion:
+  eligible: false
+  rationale: "Merging is irreversible and gated on the user's own word in the invocation — a suggested merge would manufacture the authorization the Hard Floor requires the user to give."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - git
+---
+
+# /git-pr-merge
+
+Prepare an open pull request until it is genuinely mergeable — its base merged
+in, its conflicts resolved by class rather than by taste, its required checks
+green on the head that will actually be merged — and then merge it, if and only
+if the invocation authorised that.
+
+```
+THE MERGE STEP (§ 9) IS SPECIFIED AND NOT YET ACTIVE. `--no-merge` IS THE
+OPERATIVE PATH TODAY, AND A BARE INVOCATION BEHAVES AS IF IT CARRIED IT.
+ACTIVATION NEEDS THE OWNER DECISION IN THE `merge-authority` BLOCKER OF
+`road-to-drain-commands` — NEVER A COMMAND EDIT, AND NEVER A GUARD EDIT.
+```
+
+**The invocation is the authorization, and nothing else is.** `pr-merge` is a
+`BLOCK_OPS` member in `block_unauthorized_git.ts` because it is irreversible.
+This command would consume the authorization the user's own prompt text already
+wrote to the per-session ledger on `UserPromptSubmit`; it introduces no second
+authorization store, and it never writes one. When that window closes the run
+stops and reports (§ 7) — the window never grows.
+
+Why it ships inert rather than not at all: everything before § 9 — the target
+manifest, the four conflict classes, the superseded check, the bounded CI
+repair, the cutoff — is the expensive, error-prone half, it is what the live
+runs actually proved, and none of it merges anything. `--no-merge` delivers all
+of it today.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+
+*(none, deliberately.)* `all` changes **cardinality**, not lifecycle, so it is
+an argument rather than a second command — the locked registry's rule that
+"sibling variants become a flag, never a second command"
+([`command-clusters`](../../../../../docs/contracts/command-clusters.md)) applied
+to this cluster. A future sub belongs here only if it has a materially
+different lifecycle, not a different count.
+
+## Dispatch
+
+Every row below **prepares** — the merge step is gated (see the banner above),
+so today every row ends at mergeable-and-open. The column says what each row
+selects, not that it merges.
+
+| Invocation | Selects | Prepares | Merges |
+|---|---|---|---|
+| `/pr:merge <N>` | exactly PR N | yes | only once the gate opens |
+| `/pr:merge` | ONE PR: green first, then infrastructure/tooling before content, then smallest diff (`changedFiles`, then additions+deletions), tiebreak ascending number | yes | only once the gate opens |
+| `/pr:merge all` | the whole open-PR list, under § 6's cutoff | yes | only once the gate opens |
+| `… --no-merge` | as above | yes | **never**, explicitly. This is the form [`/roadmap:process-full`](../../../product-basic/roadmap/process-full/command.md) calls for its delivery loop. |
+
+**Bare invocation** (`/pr:merge` with no argument) is a **documented default
+flow**, not a menu: it runs the auto-selection in row 2 and says which PR it
+picked and why, before touching it. A menu would be the wrong shape here —
+selection is deterministic from the queue-order rule in § 1, so asking the user
+to pick would hand back a decision the command can compute. When the open-PR
+list is empty there is nothing to select and the command reports that and
+stops.
+
+## 1. Snapshot the target — an immutable manifest
+
+Compute the queue ONCE at invocation and record it as a manifest of
+`(PR number, head SHA)` pairs:
+
+```bash
+gh pr list --state open --limit 100 \
+  --json number,title,headRefName,headRefOid,baseRefName,additions,deletions,changedFiles,mergeable,updatedAt
+gh api repos/:owner/:repo/git/ref/heads/<baseRefName> --jq .object.sha   # per distinct base
+```
+
+`baseRefName` and the base SHA are part of the record, not incidental: § 2 and
+§ 4 both consume `<base>`, and § 8's kill switch "the base advanced by an actor
+other than this run" is undetectable without a base SHA to compare against.
+
+`--limit 100` caps the manifest. A queue above 100 open PRs is drained
+**partially**, and the run must say so rather than reporting completion — the
+§ 6 bound reads "initial manifest + one batch", and the manifest is what the
+cap truncated.
+
+The manifest is the authorization's target set and is **never silently
+refreshed by a third party's push**. It is, by design, advanced by *this run's
+own* commits — § 2 merges the base in and § 5 pushes, so a prepared PR's head
+is never the snapshot head, and a naive "refuse when the SHA moved" check would
+fire on every PR the run touches.
+
+So the record carries **two** SHAs per PR and they mean different things:
+
+| Field | Set at | Meaning |
+|---|---|---|
+| `pr_number` | snapshot | Immutable. A change is branch substitution — refuse. |
+| `observed_head` | snapshot, then **updated by this run after each of its own pushes** | The head this run last produced. |
+| `base_ref` + `base_sha` | snapshot | The base the PR was prepared against; § 8's "base advanced by another actor" compares against it. |
+
+Before every merge, re-read the PR and refuse when the live head is **neither**
+the snapshot head **nor** the head this run last pushed. That is the
+force-push-after-authorization case, and it is the only one the check exists
+for. A PR that appeared after the snapshot is not in scope for this run — § 6
+says what happens to it.
+
+## 2. Sync with the base
+
+```bash
+git fetch origin
+gh pr checkout <N>
+git merge origin/<base> --no-edit
+```
+
+Merge the base **into** the branch. Never rebase a branch that is already
+pushed ([`git-history-discipline`](../../../../rules/git-history-discipline.md)).
+
+## 3. Resolve conflicts by class, never by taste
+
+Conflicts between queued PRs are expected, not exceptional: in this repository
+every roadmap PR touches `agents/roadmaps-progress.md` and
+`src/config/estate-count-budget.json`, so each merge re-conflicts every
+remaining PR. Resolve semantically, by these enumerated classes:
+
+| Class | Files | Resolution |
+|---|---|---|
+| Roadmap files | `agents/roadmaps/**` | Union of completions. Never un-check a box either side checked; never resurrect a roadmap either side archived or parked. |
+| Generated artefacts | `agents/roadmaps-progress.md` · `src/config/estate-count-budget.json` · `docs/catalog.md` · `docs/command-flows.md` · `agents/index.md` · any file whose first three lines say generated / do-not-edit | Never hand-merge. Take either side, then **regenerate** with the repo's own task and commit the regenerated output. |
+| Archive move vs. edit | `agents/roadmaps/{archive,later,skipped}/**` — one side renamed or deleted, the other edited | The archived end-state wins. Re-apply the edit at the new path if it still matters; otherwise drop it and record the drop in the summary. |
+| Evidence files | `agents/evidence/**` | Append-only. Keep both sides. |
+
+```
+A CONFLICT OUTSIDE THESE FOUR CLASSES HALTS THE RUN.
+IT IS NOT RESOLVED BY JUDGEMENT AND NOT ESCALATED TO A WARNING.
+```
+
+The classes exist so a merge resolution is reproducible by a second reader. An
+unenumerated conflict is a case nobody has decided yet, and deciding it silently
+inside a drain loop is how work disappears.
+
+## 4. Superseded check — before any CI is spent
+
+If the effective diff against the base is empty after syncing, the PR's content
+already landed elsewhere. Distinguish genuinely empty from generated-artefact
+churn that regeneration on the base would produce anyway — the latter is not
+emptiness.
+
+The probe is **not** a bare diff: taken literally, a bare diff closes every
+roadmap PR in this repository, because after a base sync and a regenerate the
+only remaining hunks are exactly the generated-artefact churn § 3 tells you to
+regenerate. Exclude those paths before deciding:
+
+```bash
+git diff origin/<base>...HEAD --stat -- . \
+  ':(exclude)agents/roadmaps-progress.md' \
+  ':(exclude)src/config/estate-count-budget.json' \
+  ':(exclude)docs/catalog.md' ':(exclude)agents/index.md'
+```
+
+Empty **after that exclusion** ⇒ superseded. **Never merge an empty PR to make
+the queue count fall — and never close one on a bare diff.**
+
+```
+CLOSING SOMEONE ELSE'S PR IS AN IRREVERSIBLE EXTERNAL ACTION AND IS NOT
+GUARDED: `pr-close` IS NOT A `GitOp` AT ALL — NOT IN `BLOCK_OPS`, NOT EVEN
+IN `WARN_OPS`. NOTHING WILL STOP IT, WHICH IS WHY THIS COMMAND MUST.
+
+THE RUN NEVER CLOSES A PR ON ITS OWN HEURISTIC. IT STOPS AND ASKS, NAMING
+THE EXACT OBJECT: THE PR NUMBER, ITS TITLE, ITS AUTHOR, AND THE PRs THE
+CONTENT LANDED VIA. ONE CONFIRMATION PER PR, THIS TURN, PER
+non-destructive-by-default. NEVER A BATCH APPROVAL FOR "THE SUPERSEDED ONES".
+IT CANNOT NAME WHERE THE CONTENT LANDED → DO NOT EVEN ASK; LEAVE THE PR OPEN
+AND RECORD IT AS `blocked-external`.
+```
+
+The asymmetry is deliberate and worth stating, because it looks inconsistent:
+merging is gated on an owner *decision* recorded once in a blocker, while
+closing is gated on a *per-object* confirmation every time. Merging this run's
+own PR is an action the run's whole design is about; closing a PR someone else
+opened is not, it destroys their work in progress, and no guard in this tree
+sees it happen. The cheaper gate goes on the action nothing else watches.
+
+## 5. Drive CI green — bounded
+
+Push, then wait for the verdict on the pushed head. Green means **the required
+checks succeeded for the exact head SHA that will be merged** — never a local
+run, never an earlier commit ([`/git-pr-create` § 4d](../create/command.md)).
+
+- **Root-cause fixes only**, inside the PR's own scope.
+- **One rerun for a known flake class** (`gh run rerun <id> --failed`) before
+  red counts as real.
+- **N=3 per validation target, six touches per PR per pass — two different
+  units, and the smaller one binds first.** The always-loaded
+  [`autonomous-execution`](../../../../rules/autonomous-execution.md) cap is
+  three consecutive failed attempts on ONE target (a named failing test, a lint
+  rule id, one CI job) and it is not lifted here. The six is a per-PR ceiling
+  across *distinct* targets: a PR whose CI peels one failure to reveal a
+  different one may be worked six times, never one target four times. Hitting
+  N=3 on a single target ends the PR's pass immediately, whatever the six says.
+  Exhaustion of either posts a diagnosis comment and moves the PR to the end of
+  the queue once; a second exhaustion is terminal.
+
+```
+THESE ARE HALTS, NOT OPTIONS OF LAST RESORT:
+DEPENDENCY CHANGES · WORKFLOW CHANGES · DELETING OR SKIPPING A TEST ·
+LOOSENING A THRESHOLD · WEAKENING A GATE · AN EXPECTED-FAIL MARKER ·
+A BRANCH-PROTECTION CHANGE.
+"DRIVE CI GREEN" AUTHORIZES DIAGNOSIS AND REPAIR, NEVER REMOVING THE CHECK
+THAT WOULD HAVE CAUGHT THE PROBLEM.
+```
+
+## 6. `all` — the queue, and the cutoff that ends it
+
+Process the manifest in the order § 1 recorded it — the queue-order rule in the
+Dispatch table's second row is the traversal for `all` too, not only for
+single-PR selection, so two runs over the same queue agree.
+
+After each merge the base has moved, so the next PR is re-synced against the
+NEW base — that is the loop, and it is why pre-greening several PRs ahead of
+their merges is wasted work.
+
+**While the merge step is gated, that loop does not turn**, and the section
+below is written for when it does. Nothing merges, so the base does not
+advance, no PR leaves the open list, and an `all` run is a **preparation
+sweep**: it syncs, classifies, greens and reports each PR once, then stops. It
+does not re-prepare a PR its own predecessor invalidated, because it has no
+predecessor that landed. The cutoff below still bounds it; the window below
+still cannot close it, for the reason § 7 gives.
+
+**Cutoff.** When the manifest is exhausted, recompute the open-PR list
+**exactly once**. PRs that appeared during the run are drained as ONE final
+straggler batch. After that batch the run ends unconditionally; anything
+arriving during or after it is recorded as `arrived-after-cutoff` and is not
+processed.
+
+```
+THE CUTOFF IS THE TERMINATION PROOF.
+WITHOUT IT, "THE QUEUE MUST SHRINK" DOES NOT TERMINATE AGAINST A SECOND
+SESSION THAT KEEPS OPENING PRs — THE RECOMPUTE JUST REFILLS IT.
+BOUND: INITIAL MANIFEST + ONE BATCH, WHATEVER ELSE IS HAPPENING IN THE REPO.
+```
+
+**Window-aware scheduling.** A green, waiting PR is spent authorization window,
+because the next merge re-conflicts it. When the projected remaining work
+exceeds the remaining window, stop entering CI-fix loops and merge everything
+already green first. Pre-greening several PRs ahead of their merge is forbidden
+under window pressure.
+
+**The signal, named — otherwise neither this rule nor § 7 is actionable.** The
+window is the per-session authorization ledger's own freshness bound. Read it,
+never write it:
+
+```bash
+cat "agents/state/git-authorization/$(<session-slug>).json"   # detected_at
+```
+
+Remaining window = `detected_at + LEDGER_MAX_AGE_MS − now`. Take the constant
+from the guard source **only after** `check_hook_bundle_content` says the
+source and the executing bundle agree — reading the source alone is the
+2026-08-21 failure re-expressed as an instruction, since the bundle is what
+enforces the value and a source edit without a rebuild is silently inert. Under
+pressure means
+the remaining window is shorter than one CI cycle on this repository. The read
+is the whole interaction: the run never edits that file, the constant, or the
+built bundle.
+
+## 7. Expiry is a reported state, never a stall
+
+```
+WHEN THE AUTHORIZATION WINDOW CLOSES WITH WORK LEFT, THE RUN STOPS CLEANLY
+AND REPORTS. IT NEVER RETRIES THE GUARD, AND IT NEVER EDITS THE GUARD,
+ITS SOURCE, OR ITS BUNDLES — READ-ONLY VERIFICATION ONLY.
+```
+
+**Unreachable while the merge step is gated**, and stated rather than left for
+a reader to discover: with nothing merging, the run performs no `BLOCK_OPS`
+operation (`push` and `commit` are `WARN_OPS`), so the window governs nothing
+it does. This section is the contract for when the gate opens.
+
+Write the summary as-is with a `window-expired` disposition per unprocessed PR
+and name the exact re-authorization needed. Widening `LEDGER_MAX_AGE_MS` is
+forbidden practice: on 2026-08-21 it was patched to six hours for a drain run
+and the widening reached the trunk.
+
+## 8. Kill switches, and what happens after a merge
+
+**Armed during preparation, not only before a merge** — otherwise every switch
+below is unreachable while the merge step is gated, and a preparation sweep has
+no way to stop at all. Each one aborts the current PR and ends the run on any
+of:
+
+- target number or head SHA differs from the manifest;
+- the base advanced by an actor other than this run;
+- a review was dismissed, or the required-check set changed;
+- a conflict outside the four enumerated classes;
+- guard or hook-bundle verification failed;
+- the first unexplained CI-repair failure.
+
+```
+A COMPLETED MERGE IS THE COMMIT POINT.
+NEVER AUTO-REVERT AN EARLIER MERGE AS "ROLLBACK" — AFTER FIVE MERGES THERE IS
+NO ROLLBACK, ONLY COMPENSATION, AND COMPENSATION IS A SEPARATELY AUTHORIZED
+HUMAN DECISION. STOP, EMIT THE MERGE SHAs AND THE REASON, HAND OVER.
+```
+
+## 9. Merge, and the summary
+
+```bash
+gh pr merge <N> --<detected-method> --delete-branch
+```
+
+Detect the method once, at invocation, and reuse it for the whole queue:
+
+```bash
+gh repo view --json mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed
+```
+
+The mapping is explicit, because `<detected-method>` has to be derivable from
+the text: `mergeCommitAllowed` → `--merge`, `squashMergeAllowed` → `--squash`,
+`rebaseMergeAllowed` → `--rebase`.
+
+Exactly one allowed → that is the method. More than one → read the last twenty
+merges on the base (`git log --first-parent origin/<base> -20 --format=%s`) and
+take the shape they overwhelmingly share. **A mixed history with no clear
+majority is not a tie to break — it is a stop:** report it and let the operator
+name the method. Inventing one is what the next sentence forbids, and a wrong
+merge shape is not revertible by this command (§ 8). Never force-merge past a
+failing required check, never admin-bypass.
+
+On queue empty or terminal-only, `all` writes
+`agents/evidence/pr-drain-run-summary.md` <!-- ref-ignore --> (created by the
+run, so it does not exist until one has happened): one row per PR with queue
+position, the `base_ref@base_sha` it was prepared against — without it a
+"prepared" row records nothing checkable, since mergeability is a fact about a
+base and not about a queue —
+conflict classes hit, CI iterations used, disposition, and any edits dropped in
+conflict resolution. The disposition set is closed:
+
+`merged <sha>` · `superseded-closed` · `blocked-external` · `twice-exhausted` ·
+`window-expired` · `arrived-after-cutoff`
+
+## Rules
+
+- **Never merge while the gate is closed.** Until the `merge-authority`
+  blocker resolves, every invocation stops at mergeable-and-open, `--no-merge`
+  or not. Once it opens, `--no-merge` is still the explicit way to say stop.
+- **Never widen, patch, or rebuild-around the git guard.** Verification of the
+  authorization window is read-only.
+- **Never rebase a pushed branch**; the base is merged in.
+- **Never hand-merge a generated artefact**; regenerate it.
+- **Never resolve a conflict outside the four classes**; halt instead.
+- **Never call CI green off a local run**; re-verify on the pushed head.
+- **Never auto-revert a completed merge.**
+- **Mergeability is per-PR against a recorded base SHA**, never a property of
+  the queue: making PR *n* mergeable against base `M` says nothing about its
+  state once PR *n−1* advances the base.
+
+## See also
+
+- [`/git-pr-create`](../create/command.md) — opens the PR this command finishes.
+- [`/roadmap:process-full`](../../../product-basic/roadmap/process-full/command.md) — delegates here for its delivery loop.
+- [`git-history-discipline`](../../../../rules/git-history-discipline.md) — never rewrite pushed history.
+- [`non-destructive-by-default`](../../../../rules/non-destructive-by-default.md) — the Hard Floor a merge sits under.

package/dist/agent-src/commands/roadmap/process-full.md

@@ -7,7 +7,7 @@ cluster: roadmap
 sub: process-full
 skills: [agent-docs-writing, ai-council, roadmap-management]
 description: Autonomously process every open step across every phase of a roadmap until the file is fully closed. Largest execution scope of the /roadmap cluster — runs continuously across phase boundaries.
-argument-hint: "[roadmap]"
+argument-hint: "[roadmap] [--all] [--worktree]"
 suggestion:
   eligible: false
   rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
@@ -80,6 +80,116 @@ with the **scope delta below**.
   archival check from
   [`roadmap-process-loop § 6`](../../contexts/execution/roadmap-process-loop.md#6-final-report-and-archival).
 
+## The three flags
+
+### `--all` — the estate, one roadmap at a time
+
+`--all` changes **cardinality, not lifecycle**: the same single-roadmap loop,
+iterated over the whole active estate. It is a flag rather than a
+`/roadmap:process-all` command because
+[`command-clusters`](../../../../../docs/contracts/command-clusters.md) says
+sibling variants become a flag, and a drain is a count of the thing this
+command already does.
+
+1. **Recompute the inventory live.** Never from memory, never from the
+   dashboard count — the same live-screen rule
+   [`/roadmap:next` § 1](../next/command.md) already carries. The corpus is the
+   non-draft roadmaps directly under `agents/roadmaps/`; `later/`, `skipped/`,
+   `archive/` and `stubs/` are out of scope.
+2. **Order the queue.** Roadmaps at or above 10 % checkbox progress first, in
+   **descending** progress — nearly-done first, because they convert soonest.
+   Roadmaps below 10 % are appended after, ascending by declared `complexity:`
+   tier (lightweight → bounded → structural), tiebreak ascending total
+   checkbox count. Both buckets need a **total** order or two runs over the
+   same estate disagree: within the first, ties on progress break by ascending
+   total checkbox count and then by ascending filename; within the second, by
+   ascending filename after the checkbox count.
+3. **Loop.** Per roadmap: branch from the updated default, run this command's
+   normal single-roadmap loop, deliver per § Delivery, then take the next
+   roadmap against the default **as it stands at that moment** — re-fetched,
+   never assumed. One roadmap = one branch = one PR, the existing invariant
+   iterated, not a new one.
+
+**What `--all` can and cannot promise, stated plainly because the honest
+version is weaker than the obvious one.** Nothing in the run
+merges, so the default does not advance because of this run, and every PR after
+the first is mergeable *against the base recorded when it was prepared* rather
+than against the base after its predecessors land. In a repository where every
+roadmap PR touches the same generated files, that means an `--all` hand-off is
+**one immediately-mergeable PR plus N−1 prepared ones**, each needing a
+re-sync at merge time. That is still the expensive half — conflicts classified,
+CI green once, superseded PRs closed — but it is not "N mergeable PRs", and the
+run reports it in those words.
+
+**A blocked roadmap never stalls the estate queue.** Inside a roadmap the five
+halt conditions and the terminal outcomes keep full authority. Between
+roadmaps, the § Halt-conditions table below is the single statement of what
+ends the roadmap and what ends the loop — including the two halts that are
+safety floors and therefore end the run. A `blocked` roadmap is recorded and
+the loop continues to the next one.
+
+### Delivery — every run, flag or not
+
+On outcome `complete`, open the PR as today, then run
+[`/pr:merge <N> --no-merge`](../../../git/pr/merge/command.md) on it: sync the
+base in, resolve conflicts by that command's four enumerated classes, drive the
+required checks green on the pushed head. **This is unconditional** — a bare
+`/roadmap:process-full` delivers a mergeable PR, not merely an open one, and
+waiting on that remote CI is part of the run per the Iron Law below. It is
+the whole of what this command delivers: there is no flag that carries it
+further, and § Merging below says why.
+
+### Merging — out of scope, cancelled rather than deferred
+
+```
+THIS COMMAND NEVER MERGES. THERE IS NO FLAG THAT MAKES IT MERGE.
+THE RUN ENDS AT MERGEABLE-AND-OPEN, ALWAYS, AND SAYS SO.
+A FUTURE MERGE CAPABILITY NEEDS A NEW ROADMAP AND AN OWNER RULING —
+NOT A COMMAND EDIT, AND NOT A FLAG THAT ALREADY SITS HERE INERT.
+```
+
+A `--merge` flag was specified here and has been **removed**. The
+`merge-authority` blocker of `road-to-drain-commands` closed as *not authorized
+in this roadmap*: activating the flag would have lowered
+[`non-destructive-by-default`](../../../../rules/non-destructive-by-default.md)'s
+per-turn confirmation floor for a production-branch merge, which
+[`decision-revisit-gate`](../../../../rules/decision-revisit-gate.md)'s
+owner-reserved table reserves to the owner. No owner ruling was available to the
+run that closed the roadmap, and an AI-council pass (2/2 convergent, 2026-08-22)
+ruled that a council may cancel an unauthorized implementation but may not
+manufacture the owner decision. The policy question is therefore **undecided,
+not rejected** — see
+[ADR-239](../../../../../docs/decisions/ADR-239-drain-command-surface-and-merge-authority.md)
+§ Disposition.
+
+The flag was removed rather than left inert deliberately: an archived roadmap
+must not leave latent executable authority behind a documented switch.
+
+Three independent findings stand behind the safety requirement, and any future
+attempt starts from them rather than re-deriving them: the AI council's Q1
+verdict (2026-08-21 — mergeability-only until authorization is target-bound and
+tamper-resistant), the committed `road-to-gate-preauth-authorization` stub (an
+authorization the agent can write is not an authorization), and the runtime
+guard that refused this roadmap's own attempt to edit the canonical loop
+contract.
+
+**Mergeability is per-PR against a recorded base, never a queue property.**
+When every PR in the estate touches the same generated files — in this
+repository `agents/roadmaps-progress.md` and
+`src/config/estate-count-budget.json` — making PR *n* mergeable against base
+SHA `M` says nothing about its state once PR *n−1* advances the base to `M1`.
+Report "mergeable against base `<SHA>`", never "the queue is mergeable".
+
+### `--worktree` — isolate the workspace
+
+Route workspace creation through [`/worktree:create`](../../../engineering-base/worktree/create/command.md)
+in full, including its
+[§ 4b seeding allow/deny list](../../../../skills/using-git-worktrees/SKILL.md#4b-seed-the-worktree--allow--deny-list),
+which is the authority on what may be copied and what must never be — not
+restated here, because a second copy of a safety list is a copy that can
+drift. Under `--all` the worktree is created
+once and re-branched per roadmap; `/worktree:cleanup` runs at end of run.
+
 ## Iron Law — Full is Full
 
 ```
@@ -87,9 +197,15 @@ with the **scope delta below**.
 TO COMPLETION, ACROSS EVERY PHASE. ONLY THE FIVE HALT CONDITIONS STOP IT.
 PHASE-INTERNAL "(DEFERRED)" / "(OPTIONAL)" / "GATED ON PHASE X" NOTES DO
 NOT NARROW THE WORKING SET. A PHASE BOUNDARY IS NOT A STOP.
+UNDER `--all`, A ROADMAP BOUNDARY IS NOT A STOP EITHER — BUT A HARD-FLOOR OR
+SECURITY-SENSITIVE HALT ENDS THE WHOLE RUN, NOT JUST THE ROADMAP. THE TABLE
+UNDER THE HALT CONDITIONS IS THE ONLY STATEMENT OF WHICH ENDS WHICH.
+WAITING ON REMOTE CI FOR THE DELIVERY LOOP IS PART OF THE RUN. "CI IS
+RUNNING" IS NOT A BOUNDARY, NOT A HALT, AND NOT A REPORT — THE RUN ENDS
+AT A MERGEABLE PR, NEVER AT AN OFFER TO GO CHECK ON ONE.
 ```
 
-The **five — and only five — halt conditions** (exhaustive; nothing else
+The **six — and only six — halt conditions** (exhaustive; nothing else
 stops the run):
 
 1. **Hard-Floor** trigger ([`non-destructive-by-default`](../../rules/non-destructive-by-default.md)).
@@ -97,6 +213,38 @@ stops the run):
 3. **Security-sensitive** surface reached.
 4. **Scope-out-of-roadmap** work discovered.
 5. **Test / quality red** that cannot be cleared within the N=3 budget.
+6. **A merge conflict outside the four enumerated classes** of
+   [`/pr:merge` § 3](../../../git/pr/merge/command.md), during the delivery
+   loop. Added when delivery became unconditional: the loop runs on every
+   completed run, `--all` or not, so its stop is a stop of this command and
+   calling it "a kill switch rather than a halt reason" would not change that —
+   a run that stops has stopped. It fires only where a run reaches delivery,
+   which is the one thing that distinguishes it from the five above.
+
+**Under `--all`, which of these end the roadmap and which end the loop.** Two
+of the five are safety floors and they end the **whole run**, not the current
+roadmap:
+
+| Halt | Under `--all` |
+|---|---|
+| 1. Hard-Floor trigger | **Ends the run.** Stop and obtain this-turn confirmation. [`non-destructive-by-default`](../../rules/non-destructive-by-default.md) states that no roadmap authorization lifts the floor, and "record it and take the next roadmap" is exactly the roadmap-as-authorization bypass it names. |
+| 3. Security-sensitive surface | **Ends the run**, same reasoning. |
+| 2. Council-off + genuine ambiguity | Ends the roadmap; the loop records it and continues. |
+| 4. Scope-out-of-roadmap work | Ends the roadmap; the loop records it and continues. |
+| 5. Test / quality red past N=3 | Ends the roadmap; the loop records it and continues. |
+| 6. Unenumerated merge conflict in delivery | Ends the roadmap; the loop records it and continues. |
+
+**And the conditions that end the loop without ending a roadmap:**
+estate-queue exhaustion (always), a
+[`/pr:merge` § 8](../../../git/pr/merge/command.md) kill switch (always — that
+section arms its checks during **preparation**, not only before a merge, which
+is what keeps them reachable while the merge step is gated), and
+authorization-window expiry — which is **unreachable in this command**,
+because it never performs a `BLOCK_OPS` operation for the window to govern. Three conditions, one of them currently inert, and this
+table is the only place the set is stated.
+
+Nothing here widens a run without `--all`: it still has exactly the six
+above, all of them ending the run because there is no loop to continue.
 
 ```
 FORBIDDEN NON-HALT REASONS — NEVER STOP THE RUN FOR ANY OF THESE:
@@ -109,7 +257,13 @@ FORBIDDEN NON-HALT REASONS — NEVER STOP THE RUN FOR ANY OF THESE:
     runnable test over PRE-EXISTING blockers, never by how a step feels
   · "the branch is not protected" / "a branch must be created"
   · "a PR must be opened" / "a GitHub setting must change"
-  · "CI must be re-run" / "the merge base needs updating" / "there are conflicts"
+  · "CI must be re-run" / "the merge base needs updating" / "there are
+    conflicts" — resolving these IS the work. The one exception, and it is a
+    kill switch rather than a halt reason: a conflict **outside** the four
+    enumerated classes of [`/pr:merge` § 3](../../../git/pr/merge/command.md)
+    stops the delivery loop, because that is a case nobody has decided yet and
+    deciding it silently is how work disappears. An enumerated conflict is
+    never a stop.
   · "a paid service is needed" — authorised under the ceiling below
   · "a maintainer should do this" when the agent can perform the same action
   · any agent-invented caution not in the five halt conditions above.