@event4u/agent-config 14.9.0 → 14.11.0

package/dist/agent-src/commands/project/analyze.md

@@ -34,6 +34,27 @@ Gather in parallel:
 - Check for module roots (resolve via `scripts/_lib/agent_settings.ts::enumerate_modules()`; Laravel shape: `app/Modules/`), multi-tenant indicators (`customer_database`)
 - Read: `AGENTS.md`, `.github/copilot-instructions.md` (if exist)
 
+**Assurance dimensions — do NOT hand-detect these.** Run
+
+```bash
+./scripts-run src/scripts/grade_target_readiness --target <project root>
+```
+
+It probes the ten readiness dimensions in one pass — test-runner config
+(vitest/jest/phpunit/pest/pytest), mutation config (`stryker.conf.*`,
+`infection.json*`, `[tool.mutmut]`), property-based libraries, static analysis
+(`phpstan.neon`, `psalm.xml`, `tsconfig.json`), architecture gates
+(`.dependency-cruiser.*`, `deptrac.yaml`), SAST (`.semgrep*`, bandit),
+lockfiles, audit steps, `CODEOWNERS`, decision-record directories — **and
+whether CI actually blocks on each**, which is the 1 → 2 distinction a
+hand-read gets wrong: a job that exists is `Present`, a job that can fail the
+build is `Enforced-in-CI`.
+
+Hand-detecting these was tried and rejected: a gather list in this file cannot
+be asserted by a test, and step 1.1 of the source roadmap requires that each
+dimension's presence be detected **and its absence not be**, both pinned by a
+vitest spec. That spec is `tests/scripts/grade_target_readiness.test.ts`.
+
 Display:
 
 ```
@@ -58,6 +79,32 @@ TECH STACK:
   Frontend:    {Vue / React / Blade / none}
   Testing:     {Pest / PHPUnit}
 
+───────────────────────────────────────────────
+READINESS  (verbatim from grade_target_readiness)
+───────────────────────────────────────────────
+
+  L{n} — bound by {dimension}
+
+  {the ten rows, exactly as the script printed them}
+
+**Print the script's output verbatim. Do not summarise it and do not compute
+anything from it.** Three rules, each of which the script already enforces and
+which this template must not undo:
+
+1. **Never emit an aggregate.** No percentage, no `x/100`, no mean, no letter
+   grade. A single number is the vanity metric this section exists to avoid, and
+   a ten-row vector with a binding dimension is the whole point of the format.
+2. **The level is the MINIMUM over the four knockout dimensions** — test presence
+   & types, static analysis & types, CI enforcement, security & supply chain.
+   Nine dimensions at 3 and one knockout at 0 is `L0`, not "mostly ready".
+3. **`not detectable` is not `0`.** A `0` claims the target lacks something; `not
+   detectable` says this tool cannot tell. For a Python target, static analysis
+   prints `not detectable — quality-tools has no Python mode`, and because that
+   dimension is a knockout it **binds at L0 with the reason shown**.
+
+Whether a missing gate then gets created in the target is out of scope here —
+this section grades, it does not install.
+
 ───────────────────────────────────────────────
 TOOLING:
 ───────────────────────────────────────────────

package/dist/agent-src/commands/review/changes.md

@@ -3,12 +3,12 @@ model_tier: high
 name: review-changes
 pack: engineering-base
 intent: "Multi-judge review of the current diff — bugs, security, tests, quality, architecture"
-routes_to: [code-review, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens]
+routes_to: [code-review, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens, overbuild-review-lens]
 replaces: []
 visibility: internal
 sub: changes
 cluster: review
-skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens, judge-synthesis, git-workflow]
+skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens, overbuild-review-lens, judge-synthesis, git-workflow]
 description: Self-review local changes before creating a PR — dispatches to six specialized judges (bug, security, tests, quality, architecture, spec) and consolidates verdicts
 suggestion:
   eligible: false
@@ -122,10 +122,21 @@ PR body, commit messages) and runs independently. The judges are:
 | [`judge-code-quality`](../../skills/judge-code-quality/SKILL.md) | Naming, SRP, DRY, dead code, consistency with codebase conventions |
 | [`architecture-review-lens`](../../skills/architecture-review-lens/SKILL.md) | Layer violations, dependency direction, leaky abstractions, cross-service contract drift |
 | [`judge-spec-compliance`](../../skills/judge-spec-compliance/SKILL.md) | Does the diff satisfy every acceptance criterion **as stated**? Reads the criteria before the diff, and never infers them from it |
+| [`overbuild-review-lens`](../../skills/overbuild-review-lens/SKILL.md) | Speculative abstraction, premature generality, features nobody asked for, a rewrite where an edit was the task |
 
-The six judges weight equally in the consolidated verdict — none
+The seven judges weight equally in the consolidated verdict — none
 overrides another.
 
+**Why the seventh exists (road-to-trigger-delivered-rule-bodies A5).**
+`overbuild-review-lens` shipped and **no command routed to it** — `grep -rln
+overbuild-review-lens dist/agent-src/commands/` returned nothing, so a lens
+built to catch the most common failure of AI-written code was reachable only by
+being asked for by name. The other six all ask whether the diff is *good*; this
+one asks whether it should have been this *large*, which is the one question a
+diff cannot answer about itself. It is dispatched on demand like the others, so
+it adds no standing token cost — verified: `check_preamble_payload_budget`'s
+measured total is unchanged by this routing.
+
 **Why the sixth exists, and why it is not a severity.** The other five all ask a
 craft-or-correctness question, so a change that is correct, clean, well-tested
 and architecturally sound — and **does not do what was asked** — used to pass
@@ -146,12 +157,12 @@ Pick dispatch mode based on diff size and environment:
 
 - **Sequential** (default, simplest) — run bug-hunter → security-auditor
   → test-coverage → code-quality → architecture-review-lens →
-  spec-compliance, collect each verdict
+  spec-compliance → overbuild, collect each verdict
 - **Parallel** — if `subagents.max_parallel` in `.agent-settings.yml` is
-  ≥ 5 and subagent dispatch is available, run all six concurrently
+  ≥ 5 and subagent dispatch is available, run all seven concurrently
   following the `do-in-parallel` pattern in
   [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md);
-  the six judges operate on the same diff but produce independent
+  the seven judges operate on the same diff but produce independent
   reports, so no shared-state risk
 
 Each judge returns its own `Judge / Model / Target / Verdict /
@@ -189,6 +200,56 @@ If picked **1**:
 
 If picked **2** → continue with internal judges only.
 
+### 4b-fresh. The fresh reviewer — the one input with no implementation context
+
+The six judges above all read **the same diff plus the task context**, and on the common
+path they run in-session: the party that wrote the diff also reads it, with the whole
+implementation context in scope. That is a self-review, and calling it a review is the
+defect `road-to-review-independence` exists to close.
+
+So a **seventh input** is added, and its distinguishing property is a negative one: it
+has **no implementation context**. Not a new mechanism —
+[`dispatch_r2_reviewer.ts`](../../../../scripts/dispatch_r2_reviewer.ts) already derives
+the scope and persists the prompt it sent:
+
+```bash
+./scripts-run src/scripts/dispatch_r2_reviewer --slug <slug> --base origin/main
+```
+
+The six in-session judges stay exactly as they are. This is an addition, not a
+replacement — a fresh reviewer is worse than a spec judge at spec compliance, and the
+point is not to be better at their job but to be uncontaminated by the author's framing.
+
+**When the route is taken.** Whenever the diff is going to a PR — i.e. every
+pre-PR review, which is what this command's own opening line describes itself as. It is
+skipped only for a diff that will not be proposed to anyone: a scratch branch, a probe,
+a measurement re-run.
+
+**When dispatch is unavailable — the honest degraded answer.** If a fresh dispatch cannot
+be made (no subagent primitive on this host, a spend ceiling, a dispatcher error), the
+review **says so in the report** and records `fresh_review: unavailable` with the reason.
+It does **not** fall back to the in-session judges and present the result as a review:
+
+```
+A SELF-REVIEW PRESENTED AS A REVIEW IS THE DEFECT, NOT THE DEGRADED MODE.
+NO FRESH REVIEWER -> THE REPORT SAYS SO. NEVER SILENTLY.
+```
+
+That wording is deliberate. A silent fallback is worse than a missing input, because the
+reader cannot tell which one they got — and this command's own `criteria_source` table
+already applies the same rule to a different input (`not_provided` is never a pass).
+
+**The implementer envelope does NOT reach this reviewer.** The judge prompts hand it over
+on purpose — `prompts/do-and-judge.md:70` carries an `IMPLEMENTER ENVELOPE:` line with the
+envelope placeholder — which is correct for a judge validating a claim and wrong for a
+reviewer whose entire value is not having the author's framing.
+
+The placeholder is described rather than written out here on purpose: step 1.3's verify is
+a grep for its **absence** from this route, and prose that trips a grep-shaped verify is a
+trap for the next reader. The asymmetry is stated in
+[`prompts/README.md`](../../../../skills/subagent-orchestration/prompts/README.md) so the
+next prompt author does not copy the envelope line into a fresh-reviewer template.
+
 ### 4c. Optional adversarial verification council (opt-in, high-risk)
 
 Read `subagents.adversarial_council` from `.agent-settings.yml` (default

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

@@ -35,6 +35,50 @@ lookup, and assess the four 95%-conditions against the seed.
 - **Explicit user bypass** ("just write it") → skip the gate for this turn;
   count the bypass.
 
+### 0b. Context probe — before step 1
+
+```bash
+agent-config roadmap:context
+```
+
+Run it before gathering any content, and surface its hits to the user as ONE
+list:
+
+- an `agents/tmp/` inbox note on the same topic (names only — the probe never
+  reads the bodies);
+- a sibling roadmap in `later/`, `stubs/`, `archive/` or the active set whose
+  slug or title shares the topic;
+- an open PR touching the paths the new roadmap would cite.
+
+This is the axis step 6's collision check cannot reach. That check is a
+recursive `find -iname`, so it already covers `later/`, `stubs/` and `archive/`
+— **lexically**. Same topic under a different name passes it clean, and the
+probe is the semantic half.
+
+Naming an overlap is **required**, not optional, and it is coordination rather
+than content generation — see the amended rule below.
+
+**Then write the `relates:` block from the hits** (template rule 18). One
+numbered-options question per hit — `extends` / `supersedes` / `depends` /
+`disjoint` — and the relation is never inferred: `extends` and `supersedes` rest
+on the same lexical evidence and are opposite decisions, so guessing manufactures
+the reflex-empty failure in a louder form. A `depends` answer mirrors into
+`depends:` in the same edit.
+
+Zero hits needs no question — it is fully determined, so write it silently:
+
+```bash
+agent-config roadmap:context --relates    # prints the block, ready to paste
+```
+
+```yaml
+relates: []   # scanned: 716 roadmap file(s), 0 sibling hits
+```
+
+The `scanned:` count is what separates *somebody looked and found nothing* from
+*nobody looked*; without it the empty list carries no information and is worse
+than an absent field.
+
 ### 1. Determine location
 
 Ask the user (in their language) where the roadmap should be created:
@@ -313,6 +357,11 @@ Failure modes covered by this hard stop:
 ### Rules
 
 - **Do NOT auto-generate content** — always ask the user for input.
+- **Naming an overlap is coordination, not content generation, and it is
+  required.** The rule above governs the roadmap's *substance*; it never
+  licenses staying silent about a sibling roadmap, an inbox note, or an open PR
+  that step 0b's probe surfaced. Report every hit, let the user decide what it
+  means, and write the outcome into the `relates:` block (template rule 18).
 - **Do NOT commit or push.**
 - **Do NOT offer execution after save** — Step 11 is a hard stop.
   Execution starts on a later turn with an explicit execution verb

package/dist/agent-src/commands/roadmap/next.md

@@ -34,20 +34,28 @@ One invocation = one roadmap = one branch = one PR.
 Selection reads live state, never memory, a dashboard count, or an
 earlier fetch (per [`direct-answers`](../../rules/direct-answers.md)
 Iron Law 2 and [`roadmap-process-loop § 1`](../../contexts/execution/roadmap-process-loop.md#1-resolve-roadmap)).
-Run as ONE block:
+Run ONE command:
 
 ```bash
-git fetch origin --prune
-git ls-tree --name-only origin/main agents/roadmaps/          # still active?
-git ls-tree --name-only origin/main agents/roadmaps/archive/   # already closed?
-gh pr list --state open --json number,title,headRefName        # in flight?
-agent-config sessions:list                                     # claimed right now?
+agent-config roadmap:context
 ```
 
-`sessions:list` without `--json` on purpose: the human form carries **both**
-axes — the live records AND the unmerged branches checked out in other
-worktrees. `--json` returns only the records unless `--branches` is passed, and
-the branch axis is the one that does not need a peer to have claimed anything.
+The four hand-written reads this block used to carry — the pruning fetch, the
+active and archived roadmap listings, the open-PR listing, and the session
+register — are now one probe
+([`roadmap_context.ts`](../../../../scripts/roadmap_context.ts)), so all five
+`/roadmap:*` entry points screen the same way instead of one command file
+screening well and four not screening at all.
+
+Both session axes are still in the report and for the same reason: the live
+records AND the unmerged branches checked out in other worktrees. The branch
+axis is the one that does not need a peer to have claimed anything, and it is
+the half that cannot be silent.
+
+The probe never refuses. With no network, no `gh`, or no authentication it
+prints `scanned: 0 PRs (network unavailable)` and exits 0 — a probe that failed
+closed would make the call site conditional, which is the failure this
+extraction removes.
 
 Excluded from the candidate set: `template.md`, `archive/`,
 `skipped/`, `later/`, anything with `status: draft` whose promotion
@@ -157,9 +165,17 @@ GOODHART MOVE THIS PACKAGE'S OWN DISCIPLINE FORBIDS.
 ### 3b. Claim the pick, so the next session's screen sees it
 
 ```bash
-agent-config sessions:claim <roadmap-slug>
+agent-config sessions:claim <roadmap-slug> [--paths src/a.ts,src/b.ts]
 ```
 
+`--paths` publishes the run's owned-path set — the same set the § 2 screen
+derived — into the session record as `owned_paths`. It is what turns the third
+collision axis on: without it a peer editing the same file under a different
+roadmap and a different branch name is invisible on every axis, which is the
+shape of the two duplications the branch axis already failed to catch. Declaring
+nothing degrades to today's behaviour exactly, and the field is absent rather
+than empty in the record.
+
 Immediately after the pick, before any branch or commit. This writes the slug
 into `agents/runtime/state/roadmap-claim-<session>.json`; the next heartbeat lifts
 it into this session's register record, so another session's step 1 excludes it

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

@@ -98,6 +98,20 @@ command already does.
    `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.
+
+   **This is a recorded exception to [`/roadmap:next` § 3](../next/command.md),
+   not an oversight.** That command's Iron Law is explicit: *"RANK BY DEFECT
+   SEVERITY, NEVER BY PERCENT-DONE OR STEP COUNT … picking by checkbox count is
+   the Goodhart move this package's own discipline forbids."* This step orders by
+   exactly that. The two are not in conflict because they answer different
+   questions: `next` **selects one** roadmap out of many and must not be gamed by
+   a cheap-to-finish file, while `--all` has already committed to draining the
+   **whole** estate — every member runs, so the ranking decides only the order in
+   which finished work becomes reviewable, never what gets done. Under a total
+   drain the Goodhart pressure is absent by construction: there is nothing to
+   pick, so a proxy cannot be optimised against.
+   The exception is scoped to `--all`. A single-roadmap invocation of this
+   command selects nothing and inherits `next`'s doctrine unchanged.
    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

package/dist/agent-src/commands/video/from-script.md

@@ -6,7 +6,7 @@ visibility: internal
 cluster: video
 sub: from-script
 description: Drive a script end-to-end through the AI video pipeline — scenes → blueprint → image → operator pick → motion → video → stitch. Preview default; --mode commit spends behind the cost gate.
-argument-hint: "<path-to-script.md> [--mode preview|commit] [--max-spend-usd <usd>] [--image-provider <id>] [--video-provider <id>]"
+argument-hint: "<path-to-script.md> [--mode preview|commit] [--max-spend-usd <usd>] [--no-calibrate] [--{image,video}-provider <id>]"
 personas: [hollywood-director, ai-video-technical-director]
 skills: [scene-expander, video-director, pixar-storyteller, character-consistency, motion-choreographer]
 suggestion:
@@ -20,7 +20,7 @@ packs:
 
 # /video:from-script
 
-`/video:from-script <path-to-script.md> [--mode preview|commit] [--max-spend-usd <usd>] [--image-provider <id>] [--video-provider <id>]`
+`/video:from-script <path-to-script.md> [--mode preview|commit] [--max-spend-usd <usd>] [--no-calibrate] [--image-provider <id>] [--video-provider <id>]`
 
 Drives a Markdown script through the full pipeline. Provider flags
 override the `<default-image-provider>` / `<default-video-provider>`
@@ -89,9 +89,66 @@ For each scene blueprint:
    `0`). When `--max-spend-usd` is set and the summed estimate exceeds
    it, hard-block before the first live call — confirmation does not
    override the cap.
-3. Call the image adapter (`run` subcommand) N times where N =
+3. **Calibration probe (default on; `--no-calibrate` skips).** Before the
+   batch, render exactly **one** still and **one** clip, then run:
+
+   ```bash
+   scripts/ai-video/lib/calibrate-cost.sh <project> <scene-id> \
+     --adapter <id> --model <id> --scenes <n>
+   ```
+
+   It reads the `charged_usd` the pipeline already writes to
+   `<project>/scenes/<id>/cost.json` and prints one line:
+
+   ```
+   calibration: modeled $0.0800/s · charged $0.1100/s · +37.5 % · extrapolated batch $4.40 (modeled $3.20)
+   ```
+
+   Re-confirm **only** when the charged figure exceeds the modeled one by
+   more than **25 %** — the script exits **13** in that case and **0**
+   otherwise. Under the threshold, print the line and continue: a calibration
+   that interrupts on every run is a confirmation nobody reads.
+
+   Exit 13 is a halt for a human, not a failure. `--max-spend-usd` is not a
+   substitute for it — that cap bounds *total spend*, while this catches a
+   wrong *per-second model*, which is what makes the total wrong in the first
+   place.
+
+   This folds into the existing `lib/operator-pick.sh` moment rather than
+   adding a gate of its own, so the operator sees the calibration line at
+   the checkpoint they were already stopping at.
+
+   `charged: null` is **not** `0`: an unpriceable or not-yet-charged scene
+   prints `charged: null`, extrapolates nothing, and never re-confirms. A
+   modeled figure is only ever corrected by a measured one.
+
+   Every reading appends one row to
+   `agents/evidence/ai-video/cost-ledger.jsonl` — see § Cost ledger below.
+   The read-back itself is not new: `lib/resume-scan.sh` already reads
+   `cost.json .charged_usd` and sums it as `spent_usd`. What is new is that
+   the number now **feeds back**: before this, money spent was recorded and
+   never read into the model it contradicted.
+
+4. Call the image adapter (`run` subcommand) N times where N =
    `<tuning/best-of-n>` (default 1).
 
+### 5b. Cost ledger — the only route from charged to modeled
+
+`manifest.cost_per_second_usd` is a **modeled** estimate. It may be
+re-modeled only from measured charges, and only with the rows it averaged
+cited in the same diff:
+
+```bash
+# one row per (adapter, model) reading, append-only
+{"adapter":"fal","model":"fal-ai/ltx-2/text-to-video","modeled":0.16,"charged":0.21,"date":"2026-08-23"}
+```
+
+`lint_adapter_tier --cost-diff <base-ref>` **warns** when a manifest's
+`cost_per_second_usd` changed in a diff that adds no ledger row. A warning,
+not a failure: re-modelling an estimate is a legitimate human act. Doing it
+silently *after* a live run measured the real charge is not — that is the
+moment a guess becomes a contradicted measurement.
+
 ### 6. Operator pick (best-of-N checkpoint)
 
 ```bash

package/dist/agent-src/commands/video/stitch.md

@@ -55,6 +55,20 @@ the first missing clip) flags. Reject any other flag — this command
 does not render, so `--image-provider` / `--video-provider` are
 contract bugs.
 
+**`--mode` and `--xfade` exist on the script and are deliberately not
+reachable from here.** `stitch.sh` now carries `--mode cut|handoff`, and in
+handoff mode an optional `--xfade <s>` (≤ 0.25) at handoff seams. `cut` is the
+default and is byte-identical to the only behaviour this command has ever
+produced. `handoff` **re-encodes** (`libx264 -crf 20 -g 8 +faststart -an`) where
+`cut` stream-copies, so it pays a generation loss and drops audio — a spend-free
+but not cost-free change of the output. Reaching it needs the seam plan that
+`lib/seam-plan.sh` builds from per-scene `continuity:` directives, which this
+command does not read. Passing either flag here is therefore rejected by the
+rule above, and that is the intended answer, not a gap: the continuity path is
+driven from `/video:from-script`, and `--crossfade` remains refused in every
+mode. Port invariants: `docs/contracts/skill-bundled-assets.md` § Port
+invariants.
+
 ### 4. Stitch
 
 ```bash

package/dist/agent-src/contexts/communication/rules-auto/guidelines-mechanics.md

@@ -11,6 +11,7 @@ before writing or reviewing code); this file is the catalog.
 |---|---|
 | `abstraction-thresholds.md` | Per-class extraction-threshold canon (code 2 · UI shell 3+ · stateful component ~4+state · utility-class string ≥3) — the single source every numeric threshold cites (ADR-213) |
 | `code-clarity.md` | Cross-language clarity rules — inline single-use values, carve-outs (side effects, loops, type narrowing, debugger) |
+| `monorepo-antipatterns.md` | Diff-detectable monorepo task-graph anti-patterns (root scripts bypassing the runner, lifecycle-hook sibling builds, `&&`-chained tasks, shared code under `apps/`, `../` in `inputs`, missing `outputs`) plus the classes deliberately not harvested |
 | `component-oriented-and-oop-development.md` | Reuse-first components (FE) + OOP-where-it-reduces-complexity (backend); carve-out index; bounded by the anti-over-engineering anchors |
 
 ## PHP (`docs/guidelines/php/`)

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

@@ -8,10 +8,62 @@ resolution, commit-step pre-scan, halt conditions, and archival check.
 The three command files are thin wrappers that bind only the **scope
 delta**.
 
-**Size budget:** ≤ 4,000 chars.
+**Size budget:** ≤ 57,000 chars — restated from the original 4,000.
+
+The old figure described nothing: the file measured 47,115 bytes against it, a
+factor of 11.8, so it was a dead budget rather than a typo. Restated at the
+measured size rather than split, because splitting a contract this load-bearing
+into referenced fragments is a large change with its own risk, and the step that
+found this asked for hygiene.
+
+**Why it moved:** this file is not a page a reader skims but the canonical
+autonomous-execution loop — roadmap discovery, cadence resolution, the step loop,
+the flip-guard, the halt list, the terminal outcomes, and the archival check. The
+original 4,000 was inherited from the sibling context docs (`≤ 3,000`, `≤ 6,000`)
+without asking whether the same shape applied.
+
+**Read it as a ratchet, not a target.** A budget that rises whenever the file
+does is not a budget. It may fall; raising it again needs the same kind of note
+as this one.
+
+**Nothing enforces this line**, and saying so is the point: no gate reads it, so
+it is a declaration a future edit can falsify exactly as the 4,000 was falsified.
+A true declaration with a stated enforcement boundary is worth more than a false
+one, and less than a check — the same `enforced_by: none` honesty the rules in
+this tree state about their own obligations.
 
 ## 1. Resolve roadmap
 
+### Context probe — unconditionally, before resolving the roadmap
+
+```bash
+agent-config roadmap:context --roadmap <slug>   # slug omitted on a bare invocation
+```
+
+Run it **before resolving the roadmap**, on every invocation, and print its
+report in the pre-run summary (§ 2). Unconditional is the whole point: the live
+merge-state clause below fires only when a message would *describe* a roadmap
+as in-flight or merged, so a run that never makes such a claim has never looked.
+Measured on the population that motivated this: 4 of 24 active roadmaps were
+already closed in an open PR, and 2 of 22 six days later — the same sample
+halved inside a week, which is why the probe re-runs on a cadence (§ 5e) rather
+than once at branch time.
+
+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.
+
 Search both locations:
 
 - `agents/roadmaps/*.md` (project root)
@@ -417,6 +469,34 @@ of [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md))
 forces an immediate regen regardless of cadence. The checkbox flip
 itself is **never** batchable — only the subprocess.
 
+### Context refresh — a comparison, not a third cadence key
+
+There is **no `roadmap.context_refresh_cadence` setting**, deliberately. The
+refresh trigger is derived:
+
+```bash
+agent-config roadmap:context --fingerprint   # cheap: one rev-parse + one gh call
+```
+
+At every phase boundary (and at run end), take the fingerprint and compare it
+with the one § 1's probe returned. **Differs → re-probe in full** and apply the
+reaction table in § 5e. **Same → nothing moved; continue without paying for a
+probe.** Cache the new value as the run's baseline either way.
+
+The fingerprint covers `origin/main` **and the head SHA of every open PR**. The
+second half is the case a `main`-only trigger misses: a peer pushing to their own
+PR branch mid-run can add a file that now overlaps this run's owned paths while
+`origin/main` has not moved at all.
+
+Why a comparison and not a knob: `docs/contracts/settings-classes.md` classifies
+a fixed-beat flag as `derivable` — "the mechanism itself can decide, from the
+situation, better than a flag can" — behind a ratchet whose count may only fall.
+A cadence enum was implemented, refused by `lint_settings_classes`, and replaced
+by this; the full reasoning, the options rejected, and what the substitution costs
+are in `agents/evidence/analysis/situational-awareness-cadence-key-decision.md`.
+Turning the refresh off is a one-line revert of this subsection, which is the same
+reversibility a `cadence: off` value would have bought.
+
 ## 5. Step loop
 
 For each open step in the working set (scope-bound — see wrapper):
@@ -510,6 +590,26 @@ For each open step in the working set (scope-bound — see wrapper):
      links the directory. Not a gate: the memo is what makes an
      autonomous resolution reviewable after the fact, which is the
      condition under which it is legitimate at all.
+4b. **Stale-artefact check — a vanished file is never a closed step.**
+
+   Before flipping anything, check the step's own cited paths against the tree:
+
+   ```
+   NEVER MARK STALE WORK COMPLETE JUST BECAUSE IT DISAPPEARED.
+   ABSENCE OF THE FILE IS ABSENCE OF EVIDENCE, NOT EVIDENCE OF COMPLETION.
+   ```
+
+   Any cited path missing → the step resolves to **`unverified`**: surface it in
+   the run report, name the missing path, and flip **no** checkbox. Not `[x]`
+   (the evidence cannot be checked), not `[-]` (nobody decided to skip it), not
+   `[~]` (nobody deferred it) — the box stays open and the report carries the
+   reason. `staleArtefactVerdict` in `roadmap_context.ts` is the predicate.
+
+   The failure this catches is quiet: "nothing to do here" reads identically to
+   "already done", and one of those is a closed step while the other is a lost
+   one. A step citing no paths is unaffected — there is nothing to check, and
+   inventing a doubt would fire this on every prose step.
+
 5. **Atomic flip — same reply, every step.**
    Flip the checkbox in `agents/roadmaps/<file>.md`: `[x]` done ·
    `[~]` partial · `[-]` skipped. **Non-skippable, non-batchable**
@@ -634,10 +734,46 @@ sibling worktree moved, the dying session finished a step it never recorded),
 and the `actual` column is what to resume from. Treating progress as corruption
 would refuse every healthy resume.
 
+**The checkpoint carries a repository fingerprint too, not only roadmap counts.**
+`context_fingerprint` is the `roadmap:context --fingerprint` value the dying run
+last held. Every other field on the checkpoint reports **roadmap** drift; none
+reported **repository** drift, so a run resumed after a long gap trusted a context
+reading it never re-took — the exact staleness § 4's refresh exists to end,
+reappearing across the one boundary a mid-run cadence cannot see.
+
+A resumed run therefore re-probes and passes the fresh fingerprint into
+`verifyCheckpoint`. A disagreement forces a full re-probe and the § 5e reactions
+**before the first step**. A `null` or absent value on either side reads as *not
+known* and never as a disagreement — the same rule `head` already follows, and for
+the same reason: a false alarm on the field whose job is to say whether anything
+moved trains the reader to skip the line.
+
 `agent-config run:supervise --once` reports which runs died with open steps
 left. It never merges, pushes, or closes anything — that boundary is a named
 rejection, not a missing feature.
 
+### 5e. Context refresh — four reactions, enumerated and closed
+
+At each due point (§ 4 — fingerprint differs) re-probe and act. **These four rows
+are the whole set.** Nothing here is a halt: none of them appears on the halt list
+and none of them is a `blocked` outcome.
+
+| # | What the refresh found | Reaction |
+|---|---|---|
+| a | A PR touching my owned paths **merged** since the last refresh | Run `sync_pr_branch` now — already the documented resolution, only push-bound until this row existed. Re-read the current step's files, continue. |
+| b | An **open** PR touches my owned paths | Continue. Name the collision in the PR description and in the final report. **Never rebase onto a foreign branch.** |
+| c | A peer session shows `PATH OVERLAP` | Take disjoint steps first if ordering allows; otherwise name it and continue. The register is advisory, never a lock. |
+| d | The roadmap itself was **archived on `origin/main`** | Stop. The same **selection error** as § 1, detected late — not a halt, and no checkbox is flipped to reach it. |
+
+Deliberately NOT a drift-level taxonomy. A severity ladder over these four would
+invite a fifth row for every new shape of surprise, and the value here is that the
+set is closed: an agent that meets something outside it has met an ordinary step,
+not a new reaction.
+
+Row (a) is the one that changes behaviour mid-run rather than only reporting. Rows
+(b) and (c) exist to make the collision **visible in the artefact** — a run that
+silently produces a conflicting PR has spent the reviewer's time, not its own.
+
 ### Halt conditions
 
 - Hard-Floor trigger ([`non-destructive-by-default`](../../rules/non-destructive-by-default.md))
@@ -681,14 +817,30 @@ 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.
 
-Three outcomes, and only one of them is success:
+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.
 
 ```