@event4u/agent-config 14.10.0 → 14.12.0

package/dist/agent-src/commands/design.md

@@ -0,0 +1,88 @@
+---
+model_tier: medium
+name: design
+disable-model-invocation: true
+argument-hint: "[audit|render|review|polish|quieter|bolder|distill|harden|clarify] [path]"
+pack: engineering-base
+intent: "Design dispatcher — inventory, capture, review, or run one bounded intervention verb"
+routes_to: [existing-ui-audit, design-review, fe-design]
+replaces: []
+visibility: internal
+description: Design orchestrator — routes audit/render/review to the Class-A commands and the six intervention verbs to fe-design with a declared operation
+cluster: design
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "audit this UI, render it, review the design, polish or tighten this screen"
+  trigger_context: "user wants something done to an existing UI surface without naming which design workflow"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /design
+
+One entry point for work on an existing UI surface. A **command**, not a skill —
+the skill catalogue is already the largest standing cost in this suite, and this
+adds a router rather than a 295th entry to it.
+
+## Sub-commands
+
+| Verb | Routes to | What it does |
+|---|---|---|
+| `audit` | `agent-config ui:audit` | Inventory the tree into `agents/runtime/state/ui-audit.json`. Class A. |
+| `render` | `agent-config ui:render` | Capture desktop / 375 / 320 into `agents/runtime/state/render/`. Class A. |
+| `review` | [`design-review`](../../../skills/design-review/SKILL.md) | Two-pass review — judgement before detector, or the `DEGRADED: single-context` banner. |
+| `polish` | [`fe-design`](../../../skills/fe-design/SKILL.md) | Spacing, rhythm, alignment. |
+| `quieter` | `fe-design` | Spacing, weight, contrast within the palette. |
+| `bolder` | `fe-design` | Palette, type family, weight, scale. |
+| `distill` | `fe-design` | Content density, spacing. |
+| `harden` | `fe-design` | Accessibility, focus, contrast within the palette. |
+| `clarify` | `fe-design` | Hierarchy, copy, labels. |
+
+## The six verbs are one field, not six commands
+
+Each verb declares the `ui_authority` dimensions it may touch
+([contract](../../../docs/contracts/ui-authority.md) § The six operations).
+That makes a collision **decidable** rather than a judgement call:
+
+```
+A VERB WHOSE DECLARED DIMENSIONS COLLIDE WITH A CONSTRAINT SURFACES A
+`conflicts[]` ENTRY AND PERFORMS NO WRITE. IT NEVER "MOSTLY" APPLIES.
+```
+
+`bolder` under `change_intent: preserve` is the worked case: it wants `palette`
+and `type_family`, both locked, so it reports two conflicts and writes nothing.
+`polish` under the same authority is clean, because spacing and rhythm are
+outside the preserve threshold — which is the whole reason that threshold is
+narrow.
+
+## No argument — the menu is built from artefacts, not from a list
+
+With no verb, read what is actually on disk and offer only what applies:
+
+1. `agents/runtime/state/ui-audit.json` — present and fresh? Its `audit_path`
+   and `coherence_signals` say whether an audit is needed at all.
+2. `agents/runtime/state/render/*/manifest.json` — the last capture, its
+   `verification`, and any `horizontal_overflow: true` viewport.
+3. The changed UI files in the working tree, per `_lib/ui_surface.ts`.
+
+A menu assembled from those three is a menu about this repository. A fixed list
+of nine verbs is a menu about this command, which is not what the user asked.
+
+## Order
+
+`audit` before any write on a non-trivial change; `render` before a verdict that
+claims anything about a viewport; `review` after the write. A verdict with no
+render says which static checks ran and scopes itself — it never says "looks
+good" with nothing behind it.
+
+## Do NOT
+
+- Do NOT add a tenth verb without removing one. The point of one field is that
+  the set stays small enough to reason about.
+- Do NOT apply a verb whose conflicts array is non-empty.
+- Do NOT infer `surface_mode` or `change_intent` here — read the authority
+  object. Re-deriving them is the drift the contract exists to prevent.
+- Do NOT promote this to a skill. The routing is the whole content.

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/evidence-discipline.md

@@ -95,6 +95,32 @@ L0–L4 are human shorthand for how deep a discovery went; they are documentatio
 only. The **same** evidence rules apply at every tier — no enforced state
 machine, no per-tier evidence relaxation.
 
+## Re-orient when the tree contradicts what you last read
+
+External edits invalidate evidence. When the user mentions they changed something
+outside this session, or a read contradicts the last known state of a file, the
+prior observation is **stale, not wrong** — and acting on it overwrites work that
+is not yours.
+
+Five steps, in order:
+
+1. Treat every prior observation of the affected paths as invalidated.
+2. Re-read the state — `git status`, then the affected files themselves.
+3. Reconstruct the assumption that broke. A file did not vanish; it was renamed,
+   a block moved, a symbol was extracted. Find where it went before concluding
+   it is gone.
+4. Preserve the external work. Never restore from your own stale copy.
+5. Say what changed if the scope or the conclusion moved, rather than
+   continuing as though the earlier reading still held.
+
+The failure this prevents is narrower than "be careful": it is re-applying a
+diff computed against a tree that no longer exists, which looks like a clean
+apply and silently reverts somebody's edit.
+
+**No gate covers this.** It is a re-read the transcript cannot distinguish from
+a first read, so it is model-carried — the same honesty boundary § Honest
+enforcement reality states for the rest of this file.
+
 ## Honest enforcement reality
 
 ```