@event4u/agent-config 16.4.0 → 17.0.0

package/dist/agent-src/contexts/execution/roadmap-process-loop-close.md

@@ -0,0 +1,235 @@
+# Roadmap-Process Loop — Branches (close)
+
+Branch-only body of [`roadmap-process-loop`](roadmap-process-loop.md), moved
+out verbatim so the core stays a single read. Each section below is loaded
+from the pointer line the core carries at the moved section's place, and only
+when a run reaches that branch; the Iron-Law fences stay in the core.
+
+### Terminal outcomes — `complete`, or a genuine external impossibility
+
+The halt list above answers *"what interrupts runnable work"*. This answers
+*"what does the run report when the roadmap is not finished and the remaining
+work is not the agent's to do"* — and under
+[ADR-237](../../../docs/decisions/ADR-237-end-to-end-execution-authority.md) that
+second set is much smaller than it looks.
+
+**The measurement that motivated the old answer, and the reading that replaced
+it.** Measured 2026-08-19 across the twelve most nearly complete roadmaps:
+**zero** could reach `count_open == 0` in one PR, because every remaining step
+needed "a human action" — flip branch protection, authorise paid spend, install a
+binary, wait out a soak window, edit a file a hook denies. The census was sound.
+The reading was not: it counted actions a human *conventionally* performs,
+without asking per action whether a human was **necessary**. Flipping a branch
+setting, pushing, opening a PR, re-running CI, updating a merge base, fixing a
+test, spending inside a budget — the agent can do all of it. That is remediation
+work, and a `process-full` invocation grants it.
+
+Four outcomes, and only one of them is success:
+
+| Outcome | When | What it reports |
+|---|---|---|
+| `complete` | `count_open == 0` and the PR is open | the roadmap is finished; archival check runs (§ 6) |
+| `blocked` | every remaining open step is **externally impossible** for the agent | the work that DID close, plus the specific impossibility |
+| `superseded` | the remaining work **already landed** on `origin/main`, in a merged PR | which steps the tree already satisfies, with the PR number and the evidence per step |
+| a halt | one of the five conditions above fired | the halt, its evidence, and what remains |
+
+**Why `superseded` is here and not on the halt list.** A run that meets a merged
+PR which already closed its remaining steps had, until this row existed, no legal
+move: *"let the open PRs merge first"* is a forbidden non-halt reason below, the
+halt list calls itself exhaustive, and neither `complete` nor `blocked` is true —
+the work is done and it was not externally impossible. The only two available
+actions were a rule violation or duplicate work. This row is the third.
+
+It is a **report**, not a licence to flip anything. Marking a step the tree
+already closed is a separate, deliberately unbuilt mechanism: it needs the step's
+own `verify:` green against `origin/main`, a decision memo, and a one-strike kill
+criterion, and an autonomous run writing a completion marker into the source of
+truth is not switched on unasked. Until it is, `superseded` reports and the boxes
+stay open — the same discipline the `[~]` prohibition below enforces for
+`blocked`.
+
+`blocked-preflight` **no longer exists** (ADR-237 § 4). A run always starts.
+
+**Externally impossible — the whole list**, aligned with ADR-268 § 7. A missing
+**owner-owned** decision — `product-owned`, `business-owned` or
+`destructive-owned`, and nothing else · a missing permission, secret or access ·
+a required credential that does not exist and the agent cannot create · a
+purchase beyond the delegated budget · physical hardware access · another person
+or organisation must act · a wait that is factually mandatory and cannot be
+simulated or verified · contradictory requirements · technical impossibility
+under the stated constraints · a needed crossing of a real authority boundary.
+
+**Not externally impossible — every one of these is work.** An unprotected
+branch · a branch to create · a push · a PR to open · a repository or branch
+setting the agent can change · a workflow to start · CI to re-run · a merge base
+to update · conflicts · failing tests · local configuration · a paid call under
+the ceiling · a failed first approach · dependency trouble · "this could be
+risky" · "a maintainer should do this".
+
+`blocked-by:` stays — it is how the withdrawn `run-continuation` read
+blockedness, and what `lint_roadmap_blockers` still validates — but a
+blocker entry is the record of a decision the agent **correctly did not own**;
+what it may point at narrows accordingly
+([`decision-closure-execution`](decision-closure-execution.md)).
+
+The `[~]` prohibition is load-bearing and was the one point the council split on.
+Deferring a blocked step to `[~]` would let the run reach `count_open == 0` and
+report completion — laundering unfinished work through a glyph, which is exactly
+what Iron Law 3 of [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
+exists to catch on the archival side. So the boxes stay open and the outcome
+carries the truth instead. **ADR-237 keeps this clause verbatim** — narrowing
+`blocked` makes it more important, not less, because a run with more authority
+has more ways to reach a clean-looking count.
+
+Revalidation is the second half of the same discipline: the set is recomputed at
+the moment of reporting, because steps unblock during a run (a prerequisite
+closes, a `Run:` succeeds, a peer merges, a setting the run itself changed). If
+any remaining step is one the agent could execute, `blocked` is refused and the
+loop continues.
+
+### Non-halt — gating notes, "optional" tags
+
+The following are **authoring annotations**, never halt conditions. Do
+**not** stop execution when the roadmap text contains them:
+
+- `(deferred)` / `(later)` / `(optional)` tags on a step
+- "Gate: Phase 1 ships and …" prose inside a later phase
+
+`process-step` and `process-phase` honor scope by stopping at their
+configured boundary anyway. `process-full` processes every open step
+regardless of these annotations — see
+[`/roadmap:process-full § Iron Law`](../../commands/roadmap/process-full.md#iron-law--full-is-full).
+Time-boxed plate / horizon framing is opt-in via
+`roadmap.horizon_weeks` in `.agent-settings.yml` (default `0` =
+forbidden, per template rule 16). When `0` and encountered in legacy
+text, treat as ordinary prose; never use it to gate execution. When
+`> 0`, plate framing is allowed in authoring but is still **not** a
+halt condition — phase ordering and explicit dependency gates govern
+execution either way.
+
+## 6. Final report and archival
+
+- **End state under an accepted execution contract** (per-mode table:
+  [`roadmap-execution-contract § 4`](roadmap-execution-contract.md)):
+  all steps `[x]` · quality green per cadence · work committed in
+  chunks on the run's feature branch · pushed to that branch · ONE PR
+  open (description-only flow) · archival sweep run. **No mode merges by
+  itself:** a merge needs the owner's explicit auto-merge instruction and
+  runs through `/pr:merge` § 9a's danger gate (ADR-282). Without a contract
+  (interactive mode), the run ends after the archival check with no
+  git delivery beyond explicitly authorized commit steps.
+- **Sampled depth audit.** For every step whose receipt reads `active` (a
+  lowered depth), `./scripts-run src/scripts/probe_depth_shadow --audit-sample
+  <roadmap.md#step> --class R0|R1` decides whether it gets a full round-1
+  completion review after merge. If sampled, run that review and append one row to
+  `src/config/depth-audit-samples.json`: `escaped` when it found a high or
+  critical row the lowered depth skipped. `step_receipt` reads that file and
+  returns a class past the threshold to full depth; `probe_depth_shadow
+  --flip-readiness` names it for the owner report.
+
+### 6-refusals. Host-classifier refusals — hand off, never route around
+
+When the host's own classifier refuses a step of an owner-directed task, the
+run never reaches the same outcome by another tool, in smaller pieces or in
+another encoding, and never records a way around it. It finishes what does not
+depend on the refused step, then — owner present — asks once in-session for an
+explicit authorization of that exact step and, on a yes, re-runs the SAME step
+ONCE so the classifier decides again with the owner's word in front of it
+(ADR-282 § Part B). Refused again, or no owner present, it writes ONE
+continuation prompt for the owner and names its path in one line:
+
+```bash
+./scripts-run src/scripts/refusal_envelope --input <envelope.json>
+```
+
+The input is task · done · refusals · remaining · the owner-directive record
+when there is one; the envelope lands at `agents/tmp/round-<hex>/prompt.md`.
+Lane refusals arrive in each lane's `classifier_refusals` field and go into the
+same single envelope (ADR-282 § Part B).
+
+### 6a. Deferred-resolution gate — Iron Law 3
+
+**Default: the sweep resolves it.** `archive_completed_roadmaps --all` carries
+every bare `[~]` step, plus every open blocker such a step names, into a
+`<slug>-carried` follow-up created in the same change (`deferral_carry.ts`),
+annotates the parent `carried-to=<slug>`, and archives — the "carry item +
+blocker" council row below, executed deterministically, so a finished
+`/roadmap:process-full` run ends archived instead of parked at 100 %. The
+manual flow below applies only to what the sweep refuses: an open blocker no
+deferred step names, a hand-written annotation that fails validation, or a run
+with `--no-carry`.
+
+**Owner-dependent blockers stop the carry.** When a carried step names a blocker
+whose `Owner:` is the human (`maintainer` / `user` / `owner`, or any value that is
+not `implementer` / `council` / `agent` / `ai`), the sweep writes nothing and
+prints a `❓` block plus one `OWNER-DECISION {json}` line. Put that decision to
+the owner as ONE numbered-options question, never resolve it yourself:
+
+1. **Archive it** — run the printed `archive_command` (`… --owner-decision later --only <roadmap>`):
+   the parent archives, the steps and their blockers park in
+   `later/<slug>-carried.md`.
+2. **Step by step** — show the FIRST step (`first_step`, verbatim) with its
+   blocker's question, in the same message, so the owner can answer it or push
+   it to later in one reply. An answer → do the step, flip it, show the next
+   one. "Later" → leave that step `[~]` and show the next one. When no step is
+   left to show, run that `archive_command`: what is still
+   deferred parks, the parent archives.
+
+A **subagent** never answers this and never passes `--owner-decision` itself: it
+stops and returns the `OWNER-DECISION` line verbatim, and the orchestrator puts
+it to the owner. A non-interactive run ends on the question, not on a report.
+
+Before any `git mv` to `archive/` the sweep refused, count `[~]` items in the
+closing roadmap. If `count_deferred > 0`, archival is **blocked** per
+[`roadmap-progress-sync § Iron Law 3`](../../rules/roadmap-progress-sync.md).
+The loop MUST:
+
+1. Enumerate every `[~]` step (phase + text + optional
+   `<!-- deferred: ... -->` annotation).
+2. Surface the numbered-options block from
+   [`roadmap-management § 4b`](../../skills/roadmap-management/SKILL.md) —
+   five choices: follow-up (draft), follow-up (ready + blocked),
+   keep-in-archive (intentional drop), restore to `[ ]`, convert
+   to `[-]` cancelled.
+3. **Route by the preservation test**, per
+   [`roadmap-progress-sync § Who resolves it`](../../rules/roadmap-progress-sync.md):
+   a disposition that keeps the criterion ALIVE in the active estate
+   (fix now · carry item + blocker into a follow-up created in the SAME
+   change · merge into existing active work · restore to `[ ]`) may be
+   resolved by the council, recorded at the item. A disposition that
+   drops, weakens or permanently accepts the loss of it — cancel to
+   `[-]`, keep-in-archive, scope cut — reaches the **user**, and the
+   autonomous mandate (`/work`, `/roadmap:process-full`, "decide for
+   me") does **not** lift that half. In doubt: user. A council verdict
+   naming a follow-up that does not exist yet fails closed to the user.
+4. On picks 1 / 2 → run the "Spawn follow-up from deferred items"
+   procedure in [`roadmap-management`](../../skills/roadmap-management/SKILL.md).
+   On picks 3 / 4 / 5 → apply the change, re-evaluate the decision
+   table, archive when the gate clears.
+
+`count_deferred == 0` → archive. **Primary path:** run the
+`archive_completed_roadmaps --all` sweep — it is untracked-safe (`git mv`,
+or a plain `mv` in a pre-first-commit / untracked consumer), rewrites inbound
+refs (on the index when tracked, on the filesystem when not), and regenerates
+the dashboard. This entry point is **PR-independent** (gap B): it does not need
+`/create-pr` to have run. **Fallback only when that script is not vendored** in
+the consumer: emit a one-line instruction to vendor it (run `agents:init`),
+then apply the manual procedure in
+[`roadmap-management`](../../skills/roadmap-management/SKILL.md) (mkdir
+`archive/`, `mv`, inbound-ref rewrite, dashboard regen). NEVER silently
+delegate to a bare `git mv` that fails on untracked files and leaves a
+completed roadmap rotting in the active tree.
+
+## Scope deltas — what each wrapper binds
+
+| Wrapper | Working set | Stop after | Execution contract (§ 3) |
+|---|---|---|---|
+| `process-step` | Single first open step | One iteration of § 5 | Never — mode ignored |
+| `process-phase` | All open steps in first phase with `count_open > 0` | Phase boundary; per-phase quality if cadence ≠ `end_of_roadmap` | When `execution.mode: autonomous \| phase-checkpoints` |
+| `process-full` | Every open step across every phase, in order | Roadmap fully closed (or halt) | When `execution.mode: autonomous \| phase-checkpoints` |
+
+`process-full` runs the per-phase quality pipeline at every phase
+boundary when cadence is `per_phase` or `per_step`; on red it halts
+before the next phase. Phase-internal `(deferred)` / `(optional)` /
+"gated on Phase N" annotations do not stop the run — those are
+authoring notes, not halt conditions.

package/dist/agent-src/contexts/execution/roadmap-process-loop-prescan.md

@@ -0,0 +1,216 @@
+# Roadmap-Process Loop — Branches (prescan)
+
+Branch-only body of [`roadmap-process-loop`](roadmap-process-loop.md), moved
+out verbatim so the core stays a single read. Each section below is loaded
+from the pointer line the core carries at the moved section's place, and only
+when a run reaches that branch; the Iron-Law fences stay in the core.
+
+### Context probe — unconditionally, before resolving the roadmap
+
+The report carries open PRs with the files they change, remote branches carrying
+a roadmap slug, live sessions on both axes, `agents/tmp/` note names, sibling
+roadmaps on the same topic, and roadmap-to-PR file overlap. Two readings act:
+
+- **The roadmap is closed in an open PR** → name the PR number and stop. This is
+  a **selection error**, not a halt: nothing on the halt list fired, the run
+  simply picked work that is already done. It does not touch the halt list and
+  it is not a `blocked` outcome.
+- **The roadmap is partially covered by an open PR** → name the PR and continue,
+  on a branch cut from `origin/main`. Never rebase onto the foreign branch.
+
+Same honesty boundary the probe states in its own header: **the probe is
+deterministic once invoked, and the invocation is model-carried.** Nothing fires
+it and nothing notices when it is skipped.
+
+### Live merge-state before any "in-flight / merged / handled" claim
+
+When selection reasoning would **exclude** a roadmap — or a pre-run summary,
+decision, or any user-facing message would **describe** one — as *in-flight*,
+*handled by an open PR*, *already merged*, or *not yet merged*, verify that
+claim **live at the moment of the claim** (`gh pr view <n> --json state,mergedAt`
+or `gh pr list --search "<slug>"`). Never infer merge state from:
+
+- the **dashboard's open-count** — it lags: a completed roadmap is archived in
+  the **merging** PR, so a roadmap can still read "open" on `main` while its PR
+  is already merged (archive not yet on your checkout), or read "open" seconds
+  before a merge you never re-checked;
+- **session memory** ("I opened a PR for this earlier") or an **earlier fetch** —
+  a merge can land between your fetch and your message.
+
+A stale merge-state claim ships an unnecessary user-facing message about work
+that is already done — the exact failure this clause prevents. This is the
+[`direct-answers`](../../rules/direct-answers.md) Iron-Law-2 live-state rule
+(git/PR state never from memory), applied to roadmap selection.
+
+## 2. Pre-run summary — gate or inline note
+
+The command name already names the scope; asking "Go / Different
+roadmap / …" on every run is noise, so there is no confirmation gate and
+no setting to bring one back (the `roadmap.skip_pre_run_gate` key was
+retired on 2026-10-09 with its default, `true`, as fixed behavior).
+
+### 3a. Mode derivation ladder — first source wins
+
+Resolve the mode from the first source that answers, and **state which rung
+answered** in the pre-run summary so the derivation is auditable rather than
+implicit:
+
+| # | Source | Wins when |
+|---|---|---|
+| 1 | **Explicit invocation suffix** — `… autonomous` / `… phase-checkpoints` / `… interactive` in the invocation | the user typed it this turn |
+| 2 | **Frontmatter `execution.mode`** | the roadmap declares one |
+| 3 | **Invocation form** (table below) | neither of the above answered |
+
+Rung 3, by wrapper:
+
+| Wrapper | Derived mode | Contract |
+|---|---|---|
+| `/roadmap:process-full` | `autonomous`, **preselected** | offered |
+| `/roadmap:next` | `phase-checkpoints`, **preselected** | offered |
+| `/roadmap:process-phase` | `phase-checkpoints` | offered |
+| `/roadmap:process-step` | — | none (one step needs no run contract) |
+
+Still **exactly one confirmation**, never two: rung 3 changes which option the
+contract screen arrives preselected on, never whether the screen is shown. The
+screen's `3. Run interactive instead` option
+([`roadmap-execution-contract § 2`](roadmap-execution-contract.md)) stays on it
+in every case, so a derived mode is always one keystroke from being refused.
+
+<!-- decision 2026-08-20: /roadmap:next preselects `phase-checkpoints`, not
+     `autonomous`. AI council 2/2 (anthropic + openai) on the
+     `autonomy-defaults-sheet` fork of road-to-user-out-of-the-loop, record
+     agents/evidence/council/drain-blocker-dispositions-a.md. Reasoning: the two
+     wrappers differ in what the user has actually seen at Accept time.
+     `process-full` names one roadmap the user chose, so `autonomous` is a
+     preselection over a scope they read. `/roadmap:next` SELECTS the roadmap
+     itself, so `autonomous` there preselects full autonomy over a target the
+     user has not seen — the one rung where the derivation picks the object and
+     the scope in the same keystroke. Reversibility: this is a preselected
+     option on a screen that still offers `1. Go — start processing
+     autonomously`, so the aggressive path costs one keystroke and no rebuild;
+     flipping the row back is a one-line edit with no dependent mechanism.
+     Deliberately scoped to `/roadmap:next` only — the blocker's question named
+     that wrapper, and Phase 1 Step 1 of the parent roadmap landed with
+     `process-full` → `autonomous` explicitly, so widening the change would
+     silently reverse an already-shipped step nobody asked to revisit. -->
+
+
+**Why the old fallback was a defect and not a conservative default.** Absent
+`execution.mode` used to mean the legacy commit-step scan, which derives no
+contract at all — no batched artifact drafting, no council auto-enable, no
+push/PR grant. Measured 2026-08-17: **27 of 37 active roadmaps carry no
+`execution.mode`**, so roughly three quarters of the corpus ran the degraded
+path *under the wrapper built for the opposite*, and silently — the user saw a
+`process-full` invocation behave like an interactive one with no line saying so.
+A default that contradicts the wrapper the user just typed is a wrong answer,
+not a safe one.
+
+**Kill criteria — carried here, at the flip, not only in the roadmap that
+made it.** A default flip whose reversal condition lives in a roadmap is a
+flip nobody can reverse once that roadmap is archived, which is why both
+conditions below sit next to the table they govern:
+
+- **The ladder itself** (absent `execution.mode` derives a mode instead of
+  falling back to interactive): `3. Run interactive instead` chosen at the
+  contract screen in **more than 40 % of 20 runs** reverts rung 3, leaving
+  the ladder at explicit-suffix-then-frontmatter only. **No instrument
+  today** — nothing records which contract option was chosen, so the rate is
+  unmeasured rather than low. Stated so the gap is visible at the flip.
+- **The `/roadmap:next` row** (`phase-checkpoints` rather than
+  `autonomous`): reverted if checkpoint-mode runs on that wrapper are
+  observed to stop at a phase boundary the user then waves through without
+  a change — that is a contact the preselection bought nothing for. Same
+  missing instrument, same honesty: this is a condition, not a reading.
+
+**What this does NOT change.** A derived mode grants nothing on its own:
+authorization is still the single Accept on the contract screen, per
+[`roadmap-execution-contract § Principle`](roadmap-execution-contract.md). The
+Hard Floor, the locked decision classes, and the kernel-edit soak are untouched.
+
+### 3b. Contract or commit-step ask
+
+**Derived `autonomous` or `phase-checkpoints`** → load
+[`roadmap-execution-contract`](roadmap-execution-contract.md) and run
+its four-class pre-scan over every open step:
+
+1. commit-shaped steps (patterns below),
+2. git-shape needs (branch / push / PR / delivery),
+3. artifact-authoring steps (new or materially rewritten skill / rule /
+   command / guideline — feeds the batched drafting-protocol research
+   pass, run at contract time against current artifact state),
+4. open questions / ambiguity markers (incl. `ask-when-uncertain`
+   vague-trigger patterns).
+
+Surface the contract summary; the user's single **Accept** activates
+all run grants (branch, chunked commits, push to the run's own feature
+branch only, PR-open, batched artifact drafting, council auto-enable) —
+cached for the run, never re-asked. The contract never lifts a Hard
+Floor or any safety floor; boundaries + per-mode gate table live in the
+contract context.
+
+**Derived `interactive`** — i.e. the user asked for it explicitly (rung 1), the
+frontmatter declares it (rung 2), or the invocation was `process-step` (rung 3)
+→ legacy commit-step scan only: lines matching `commit:` / `git commit` /
+`Commit phase`. An ABSENT field no longer reaches this branch; that is the whole
+change in § 3a.
+
+- **No commit steps** → nothing to ask. Never commit, never re-ask
+  per [`commit-policy`](../../rules/commit-policy.md).
+- **Commit steps present, autonomous conversation mode**
+  (`personal.autonomy: on`, or `auto` after opt-in) → ask **once**
+  upfront:
+  > "Roadmap contains N commit steps. Authorize all of them for this
+  > run? (yes / no / list them)"
+  Cache the answer for the whole run; do **not** re-ask per step.
+  Hard-Floor diffs (bulk deletions, infra) still trigger the
+  per-commit gate from [`commit-mechanics`](../authority/commit-mechanics.md).
+- **Commit steps present, non-autonomous** → same one-shot pre-scan
+  ask as above, before the run starts; never per step
+  (per [`commit-mechanics`](../authority/commit-mechanics.md) —
+  `commit-policy` § NEVER ask about committing holds regardless of
+  autonomy).
+
+### 3c. Capability screen — can the agent do this at all?
+
+**Rewritten by [ADR-237](../../../docs/decisions/ADR-237-end-to-end-execution-authority.md),
+which supersedes ADR-235.** This section used to be a *preflight refusal*: a run
+with no "runnable" open step created no branch and wrote nothing. That is gone.
+The invocation is a delegation, so the question is no longer *is this step
+runnable under current governance* but *is this step possible for the agent at
+all.*
+
+Run once at the end of the pre-scan, and again immediately before any `blocked`
+report.
+
+**The screen, in order:**
+
+1. **Can the agent execute it?** Through the filesystem, git, `gh`, an API, a
+   CLI, a tool, a model, a council — anything machine-executable. If yes, the
+   step is **work**. Stop here; no blocker citation changes that.
+2. **Is the authority already implied by the invocation?** For a `process-full`
+   run: branches, chunked commits, pushing that branch, opening and updating the
+   PR, reversible repository/branch settings, CI runs and re-runs, merge-base
+   updates, conflict resolution, project-local dependencies, and paid calls
+   inside whatever `cost.budgets` windows are configured — none configured,
+   none applies (ADR-279). If yes → **run it**.
+3. **Is it on the EXCLUDED list?** Merging to a production trunk, deploying,
+   production data / secrets / IAM / DNS, bulk deletion outside the roadmap's
+   scope, an irreversible external action beyond the PR itself. Those keep their
+   own this-turn confirmation ([`non-destructive-by-default`](../../rules/non-destructive-by-default.md))
+   and are a **halt**, not a blocker.
+4. **Otherwise it is externally impossible**, and only then is it a blocker: a
+   credential that does not exist and cannot be created · a purchase beyond the
+   budget · physical hardware access · another person or organisation must act ·
+   a wait that is factually mandatory and unverifiable.
+
+**A `## Blockers` entry is evidence, never a verdict.** A `Class: 3` label on an
+action the agent can perform is a **defect in the roadmap**, and the run repairs
+the label rather than obeying it — recording what it did and why. Class `0`/`1`
+entries carry a `Run:` the agent executes, exactly as before. Class `2`
+(consent-once) is pre-cleared for the duration of a `process-full` run when the
+consent it wants is one the invocation already gave; a `2` asking for something
+the invocation did NOT give (an EXCLUDED action, a spend crossing) still reaches
+the owner.
+
+**No citation → work**, and the default direction is unchanged: the failure this
+screen must not have is declining work an agent could have done.