@event4u/agent-config 9.8.0 → 9.10.0

package/dist/agent-src/contexts/execution/project-intelligence.md

@@ -1,10 +1,11 @@
 # Project Intelligence — Evidence v2 self-building context (capture auto, trust gated)
 
-Definitional spine for **Evidence v2**: agent builds project- (and optionally user-)
-context *while working*, so the next agent starts smarter. Additive on the v1
-[`evidence-discipline`](evidence-discipline.md) — weakens **no** v1 invariant. Loaded
-alongside the v1 spine by [`source-discovery-gate`](../../rules/source-discovery-gate.md);
-executable Class-A procedure is [`standards-from-config`](../../skills/standards-from-config/SKILL.md).
+Definitional spine for **Evidence v2**: the agent builds project- (and optionally
+user-) context *while working*, so the next agent starts smarter. Additive on the
+v1 [`evidence-discipline`](evidence-discipline.md) — it does **not** weaken a
+single v1 invariant. Loaded alongside the v1 spine by
+[`source-discovery-gate`](../../rules/source-discovery-gate.md); the executable
+Class-A procedure is [`standards-from-config`](../../skills/standards-from-config/SKILL.md).
 
 ## The one guiding principle
 
@@ -15,14 +16,15 @@ THE ONLY DEFENSE IS THAT NOTHING SELF-WRITTEN IS DURABLE, TRUSTED, SHARED TRUTH
 UNTIL EVIDENCE OR A HUMAN CONFIRMS IT.
 ```
 
-v1 trust-tiering pulled one level up: in v1 a card's *positive structure* is a
-hypothesis; in v2 a *learned lesson about the project or the user* is equally a
-hypothesis. Both are leads, not truth.
+This is the v1 trust-tiering pulled one level up: in v1 a card's *positive
+structure* is a hypothesis; in v2 a *learned lesson about the project or the user*
+is equally a hypothesis. Both are leads, not truth.
 
 ## Three context classes — different problems, different validation
 
-Not one promote-from-intake flow. A/B/C are three problems with different validation
-logic and storage; the human promotion gate may be unified, the validation rules are not.
+Not one promote-from-intake flow. A/B/C are three problems with different
+validation logic and storage; the human promotion gate may be unified, the
+validation rules are not.
 
 | Class | Question | Evidence source | Problem type | Trust | Storage |
 |---|---|---|---|---|---|
@@ -30,7 +32,7 @@ logic and storage; the human promotion gate may be unified, the validation rules
 | **B — observed convention** | how is this usually built? | ≥N real files | statistical/sampling (decays as code evolves) | medium — lead, confirm against code | `curated/conventions/` (% match) |
 | **C — learned lesson** | what recurred as a mistake? | a real failure (test/error/revert) | causal inference (needs counter-evidence) | lowest — intake until curated | `curated/lessons/` (symptom/hypothesis + history) |
 
-Fixed lines: **A is derived evidence** (the config *is* the standard; card is
+Fixed lines: **A is derived evidence** (the config *is* the standard; the card is
 pointer+digest, never a flattened claim — conflicts surface as two pointers). The
 *convention* of an endpoint is Class B and card-able; the **concrete shape of a
 concrete endpoint stays v1** — read fresh, never cached.
@@ -43,10 +45,10 @@ OBSERVE  →  write INTAKE  →  (human promotion gate)  →  commit CURATED
              low-trust)            user-confirmed)             team-visible)
 ```
 
-Agent MAY *suggest* an intake signal in its reply ("I notice X — record as
+The agent MAY *suggest* an intake signal in its reply ("I notice X — record as
 context?") but never treats it as fact and never silently commits
-([`scope-control`](../../rules/scope-control.md): create/draft ≠ commit). Intake
-*grows* automatically; only the step to trusted, shared truth is human.
+([`scope-control`](../../rules/scope-control.md): create/draft ≠ commit). The
+intake *grows* automatically; only the step to trusted, shared truth is human.
 
 ## Memory tiers — three, not two
 
@@ -56,69 +58,75 @@ context?") but never treats it as fact and never silently commits
 | **intake** | `agents/memory/intake/` | gitignored | *generalizable* observations — promotion candidates only | via human gate |
 | **curated** | `agents/memory/<type>/*.yml`, `agents/settings/contexts/` | tracked | human-promoted shared truth | (is the promoted state) |
 
-Trial-and-error and transient state go to **ephemeral** (never promoted), keeping the
-intake promotion queue free of per-session noise. Only generalizable observations reach
+Not everything that helps the next agent should be committed. Trial-and-error and
+transient state go to **ephemeral** (never promoted), keeping the intake
+promotion queue free of per-session noise. Only generalizable observations reach
 intake.
 
 ## Class B — verifiability boundary, static-consensus, deviation-staleness (council 2026-06-16)
 
-A dogfood eval (claude-sonnet-4-5 + gpt-4o, design mode, 2 rounds) surfaced a trap
-and re-framed how Class B is built:
+A dogfood eval (claude-sonnet-4-5 + gpt-4o, design mode, 2 rounds) surfaced a
+trap and re-framed how Class B is built:
 
 - **Linter-enforced ≠ observed.** A convention the tooling *enforces* (required
-  sections, frontmatter keys) is a **Class-A constraint**, not Class-B — capturing
-  it as B is double-counting; a careful agent reaches it by running the linter.
-  **Class B is only for conventions the tooling does NOT enforce** (response-shape
-  `{data, meta}`, `config/` not `configs/`, test-description phrasing, section
-  *ordering* the linter ignores). Verifiability is the boundary: prefer
-  mechanically-checkable; gate subjective ones behind higher evidence
-  (`observed_n ≥ 10`).
-- **Problem is consensus-detection, not capture.** "How is this usually built?" is
-  answered by a **static-analysis consensus pass** over the real codebase ("87% of
-  test files are `*.test.ts`"), human-curated to the dominant pattern — not by an
-  agent free-writing observations into intake.
-- **Staleness = deviation metric (not a calendar).** Re-run the consensus pass on a
-  cadence / in CI; when dominant pattern's share drops below threshold (e.g. 87% →
-  < 70%), flag for re-review. Cheap, evidence-grounded, no background daemon.
-- **Auto-capture loop is deferred.** Agent-driven capture→intake loop is **not** built
-  on current evidence (eval was invalid for B — it tested a Class-A constraint). Gated
-  on a re-run with a *discriminating* non-linter convention. Static-consensus pass
-  banks most of the cost win without accumulation risk. Re-evaluate only if
-  static-consensus proves insufficient.
+  sections, frontmatter keys) is a **Class-A constraint**, not a Class-B observed
+  convention — capturing it as B is double-counting, and a careful agent reaches
+  it by running the linter. **Class B is only for conventions the tooling does
+  NOT enforce** (response-shape `{data, meta}`, `config/` not `configs/`, test-
+  description phrasing, section *ordering* the linter ignores). Verifiability, not
+  topic, is the boundary: prefer mechanically-checkable conventions; gate
+  subjective ones behind higher evidence (`observed_n ≥ 10`).
+- **The problem is consensus-detection, not capture.** "How is this usually
+  built?" is answered by a **static-analysis consensus pass** over the real
+  codebase ("87% of test files are `*.test.ts`"), human-curated to the dominant
+  pattern — not by an agent free-writing observations into intake.
+- **Staleness = deviation metric (not a calendar).** Re-run the consensus pass on
+  a cadence / in CI; when the dominant pattern's share drops below a threshold
+  (e.g. 87% → < 70%), flag the convention for re-review. This is the Class-B
+  staleness mechanism — cheap, evidence-grounded, no background daemon.
+- **Auto-capture loop is deferred.** An agent-driven capture→intake loop is **not**
+  built on the current evidence (the eval was invalid for B — it tested a Class-A
+  constraint). It is gated on a re-run with a *discriminating* non-linter
+  convention AND is the more expensive path; the static-consensus pass banks most
+  of the cost win without the accumulation risk. Re-evaluate only if the
+  static-consensus path proves insufficient.
 
 ## Class B storage + the human gate's teeth
 
-Curated Class-B conventions under `agents/memory/curated/conventions/` with:
+Curated Class-B conventions live under `agents/memory/curated/conventions/` with:
 
-- **Two-stage split** — freshly captured/consensus-derived convention lands in
-  `quarantine/` (not yet agent-readable); human promotes to `approved/`
-  (agent-readable). Auto-derived noise never reaches agent context before review.
+- a **two-stage split** — a freshly captured/consensus-derived convention lands in
+  `quarantine/` (not yet agent-readable as a heuristic); a human promotes it to
+  `approved/` (agent-readable). Auto-derived noise never reaches agent context
+  before review.
 - **B-specific validation** (statistical, not causal): each convention carries
-  `observed_n`, `dominant_share`, `confirm_against` (sibling/code to check before
-  relying on it). Separate validation logic from Class-C lessons.
-- **Gate teeth:** promotion shows original-vs-derived diff + deviation metric;
-  convention below consensus threshold cannot be promoted.
+  `observed_n`, `dominant_share`, and `confirm_against` (the sibling/code to check
+  before relying on it). Separate validation logic from Class-C lessons, even if
+  the human promotion gate is unified.
+- **gate teeth:** promotion shows an original-vs-derived diff + the deviation
+  metric; a convention below the consensus threshold cannot be promoted.
 
 ## Class C — learned lessons (the safety spec; accumulation layer eval-gated)
 
-Riskiest class: an *inference* about why something went wrong. **Accumulation layer**
-(agent writing lessons into intake during normal work) is **NOT built** until a 3-arm
-eval shows accumulated context lowers error rate at acceptable cost on a
-*discriminating* task. What IS specified now is the **shape a lesson must take** so
-it cannot calcify a wrong belief.
+The riskiest class: an *inference* about why something went wrong. The
+**accumulation layer** (an agent writing lessons into intake during normal work)
+is **NOT built** until a 3-arm eval shows accumulated context lowers the error
+rate at acceptable cost on a *discriminating* task — and `proprietary`/global
+scope is gated separately. What IS specified now is the **shape a lesson must
+take** so that, if built, it cannot calcify a wrong belief.
 
 ### Evidence ≠ diagnosis (the core split)
 
 A lesson has two parts with different trust:
 
-- **`symptom` (durable-ish, falsifiable):** *what* really went wrong — real error
-  text, failing test name, reverted commit SHA. Timestamped, cited.
-- **`hypothesis` (inference, low-trust, decaying):** *why* — agent's causal theory.
-  Marked a hypothesis, **never** a durable lesson, until repeatedly confirmed. A
-  wrong cause-theory must never harden into superstition.
+- **`symptom` (durable-ish, falsifiable):** *what* really went wrong — the real
+  error text, the failing test name, the reverted commit SHA. Timestamped, cited.
+- **`hypothesis` (inference, low-trust, decaying):** *why* — the agent's causal
+  theory. Marked a hypothesis, **never** a durable lesson, until repeatedly
+  confirmed. A wrong cause-theory must never harden into superstition.
 
-Card holds symptom as fact, diagnosis as hypothesis. Human promotion gate confirms
-the *causal claim*, not just "did the symptom happen".
+The card holds the symptom as fact and the diagnosis as hypothesis. The human
+promotion gate confirms the *causal claim*, not just "did the symptom happen".
 
 ### Test-tracking history (makes anti-calcification enforceable)
 
@@ -136,17 +144,18 @@ lesson:
     counter_evidence_ratio_gt: 0.3    # ≥30% disconfirmations → demote
 ```
 
-`event` logged when a *situation the lesson claims to govern* recurs:
-`confirmed` (claim held), `not_applicable` (situation changed — lesson no longer
-governs), `counter_evidence` (claim failed). Absence of recurrence is **not**
-confirmation.
+`event` is logged when a *situation the lesson claims to govern* recurs:
+`confirmed` (the claim held), `not_applicable` (the situation changed — the
+lesson no longer governs it), `counter_evidence` (the claim failed). Absence of
+recurrence is **not** confirmation.
 
 ### Anti-calcification check
 
-Curated lesson that hits either decay trigger (`no_confirmation_for_days` or
+A curated lesson that hits either decay trigger (`no_confirmation_for_days` or
 `counter_evidence_ratio_gt`) is **automatically demoted to hypothesis** — by a
 periodic pass / CI step, wired alongside the accumulation layer if it ships.
-Self-improvement requires forgetting; without demotion, lessons rot into noise.
+Self-improvement requires forgetting; without demotion, accumulated lessons rot
+into noise and the agent gets *worse*.
 
 ### Subject-not-person privacy floor
 
@@ -163,11 +172,13 @@ deliberately, never silently.
 ### The existence gate (why the accumulation layer is deferred)
 
 `Self-improving` is a hypothesis, not a law — accumulated context can *raise* the
-error rate. Accumulation layer ships only if a 3-arm eval (no-context / v1 /
-v2-accumulated) on a *discriminating* task shows it lowers error rate at acceptable
-cost. Kill-criterion: if it does not, layer is not built and agent runs v1 + Class A
-(the rollback target in [`evidence-discipline`](evidence-discipline.md)). Eval
-requires real multi-task spend and valid (non-saturated) task design.
+error rate (calcified diagnoses, stale conventions, context-window flood). The
+accumulation layer ships only if a 3-arm eval (no-context / v1 / v2-accumulated)
+on a *discriminating* task (not a saturated one — see the Class-B council note)
+shows it lowers the error rate at acceptable cost. Kill-criterion: if it does
+not, the layer is not built and the agent runs v1 + Class A (the rollback target
+in [`evidence-discipline`](evidence-discipline.md)). This eval requires real
+multi-task spend and a valid (non-saturated) task design.
 
 ## The v1↔v2 isolation contract (the load-bearing guardrail)
 
@@ -177,12 +188,13 @@ v2 CONTEXT SKILLS ARE WRITE-ONLY INTO INTAKE. A STRUCTURAL CLAIM STILL REQUIRES
 FRESH SOURCE PER v1, REGARDLESS OF WHAT CURATED CONTEXT "KNOWS".
 ```
 
-Dominant failure: once something is in `curated/`, agent has no incentive to re-check,
-and v2's cached claims contaminate v1's read-fresh discipline. Defense is behavioral,
-enforced by skill design (not a deployment boundary): v2 context informs *where to
-look* and *what to expect* (heuristics), but field/endpoint/column/value is still
-confirmed against a live source this session. Class A is the one high-trust class,
-and even it is read for heuristics, never to skip a structural read.
+The dominant failure: once something is in `curated/`, the agent has no incentive
+to re-check, and v2's cached claims contaminate v1's read-fresh discipline. The
+defense is behavioral, enforced by skill design (not a deployment boundary): v2
+context informs *where to look* and *what convention to expect* (heuristics), but
+a field/endpoint/column/value is still confirmed against a live source this
+session. Class A is the one high-trust class, and even it is read for heuristics,
+never to skip a structural read.
 
 ## Redaction on every intake write
 
@@ -191,20 +203,23 @@ THE PRIVACY REDACTOR RUNS ON EVERY INTAKE WRITE, BEFORE THE FILE IS CREATED.
 A HALT-TRIGGER BLOCKS THE WRITE — IT DOES NOT SILENTLY SCRUB-AND-CONTINUE.
 ```
 
-v1 regex-denylist redactor (`low-impact-corpus-privacy-floor` +
-`source-confidentiality`) gates every intake write. On a hit it **blocks** the write
-and surfaces the offending pattern; never silently rewrites. Promotion review shows
-original-vs-redacted diff so a human sees what was scrubbed.
+The v1 regex-denylist redactor (`low-impact-corpus-privacy-floor` +
+`source-confidentiality` pattern set) gates every intake write. On a hit it
+**blocks** the write and surfaces the offending pattern; it never silently
+rewrites. Promotion review shows an original-vs-redacted diff so a human sees what
+was scrubbed. Closes the "Class-B auto-capture leaks a secret-in-pattern (e.g. a
+header value) before redaction runs" gap.
 
 ## Multi-agent concurrency
 
 Parallel agents share one project tree. Intake writes therefore:
 
-- carry an **agent-id / random suffix** in filename (no overwrite of another agent's
-  pending intake);
-- pass a **promotion conflict check** — human promotion flow surfaces near-duplicate /
-  conflicting pending intake from other agents for human resolution rather than
-  last-write-wins.
+- carry an **agent-id / random suffix** in the filename (no overwrite of another
+  agent's pending intake);
+- pass a **promotion conflict check** — the human promotion flow surfaces
+  near-duplicate / conflicting pending intake from other agents (e.g. agent A
+  proposes "handlers return `{status,data}`" while agent B has pending
+  "`{ok,result}`") for human resolution rather than last-write-wins.
 
 ## Context budget + prioritisation
 
@@ -214,7 +229,7 @@ unreviewable queue. Quantitative ceilings (starting values, tune on evidence):
 | Bound | Start | Over-budget action |
 |---|---|---|
 | total curated size (A+B+C) | ~50 KB | lowest-confidence / oldest items expire or need re-review |
-| pending intake queue | ~20 | block new intake until queue drains |
+| pending intake queue | ~20 | block new intake until the queue drains |
 | Class A budget | unlimited | deterministic, low-entropy |
 | Class B per domain | ~10 conventions | demote the weakest by % match |
 | Class C active lessons | ~5, sorted by confirmation count | demote the least-confirmed |
@@ -223,27 +238,31 @@ v2 must never become a write-only structure that grows forever.
 
 ## v1→v2 migration
 
-When v2 ships, existing v1 context-documents are **not** silently re-trusted. They
-keep their v1 semantics (present-state snapshots a human curates); v2 adds A/B/C-tagged
-classes *alongside* them. No existing card's trust level changes without an explicit
-human pass — trust-semantics change cannot silently corrupt an existing project's
-evidence base.
+When v2 ships, existing v1 context-documents are **not** silently re-trusted.
+They keep their v1 semantics (present-state snapshots a human curates); v2 adds
+the A/B/C-tagged classes *alongside* them. No existing card's trust level changes
+without an explicit human pass — the trust-semantics change cannot silently
+corrupt an existing project's evidence base.
 
 ## Global promotion (A/B/C) — reuse the measure-then-decide gate, never auto
 
-No new mechanism: global promotion reuses the ADR-100 / **ADR-103** gate
-(`knowledge.global_sharing`, **default-off until cross-project reuse is measured
-across ≥ 2 real projects**; `record-seen` sightings are the instrument).
-
-- **Class A / B (conventions):** project-local committed by default. Global only when
-  the *same* convention is empirically reused across ≥ 2 projects — **manually
-  promoted, never auto**, through the measure-then-decide gate, same privacy floor
-  (slugs / subject only, never contents / persons).
-- **Class C (lessons):** global only for cross-project **subject** lessons. Same gate,
-  same floor. Killing the global layer never kills project-local lessons (v1 F-5 holds).
-- **Suggestion-gated, always.** Agent may *surface* a promotion candidate; human
-  decides. **No runtime self-modifying trusted store** — global store stays file-first,
-  leads-only cache (ADR-100 Decision-3).
+No new mechanism: global promotion of any v2 class reuses the ADR-100 /
+**ADR-103** gate (`knowledge.global_sharing`, **default-off until cross-project
+reuse is measured across ≥ 2 real projects**; the `record-seen` sightings are the
+instrument).
+
+- **Class A / B (conventions):** project-local committed by default (they belong
+  to the repo). Global only when the *same* convention is empirically reused
+  across ≥ 2 projects — **manually promoted, never auto**, through the
+  measure-then-decide gate, with the same privacy floor (slugs / subject only,
+  never contents / persons).
+- **Class C (lessons):** global only for cross-project **subject** lessons
+  ("this *kind* of integration is often wired wrong"), same gate, same floor.
+  Killing the global layer never kills the project-local lessons (v1 F-5 holds).
+- **Suggestion-gated, always.** The agent may *surface* a promotion candidate;
+  the human decides. There is **no runtime self-modifying trusted store** — the
+  global store stays a file-first, leads-only cache whose positive content is
+  re-confirmed against the live source this session (ADR-100 Decision-3).
 
 ## Reaffirmed v1 invariants (v2 weakens none)
 
@@ -253,7 +272,7 @@ across ≥ 2 real projects**; `record-seen` sightings are the instrument).
 3. Trust-tiering holds — self-written is hypothesis until evidence/human confirms;
    Class A is high-trust *because* config-derived.
 4. Honest enforcement — the self-capture log is instrumentation; the teeth are
-   pointer-CI + eval gates + human promotion gate.
+   pointer-CI + the eval gates + the human promotion gate.
 5. No auto-commit, no auto-promote, no runtime self-modifying trusted store.
 
 ## See also

package/dist/agent-src/contexts/execution/roadmap-execution-contract.md

@@ -1,40 +1,41 @@
 # Roadmap Execution Contract
 
-Loaded by [`roadmap-process-loop § 3`](roadmap-process-loop.md) when
+Loaded by [`roadmap-process-loop § 3`](roadmap-process-loop.md) when the
 resolved roadmap declares `execution.mode` in frontmatter
 (`autonomous` | `phase-checkpoints`; absent / `interactive` = legacy
-behavior, this context stays unloaded). Defines the run-start
-pre-scan, the contract summary user confirms ONCE, the grants that
+behavior, this context stays unloaded). Defines the run-start pre-scan,
+the contract summary the user confirms ONCE, the grants that
 confirmation activates, and the per-mode gate table.
 
 ## Principle — declaration vs. authorization
 
 `execution.mode` in frontmatter is a **declaration of intent** written
-at authoring time. Grants nothing. Authorization happens exactly once
-per run: user invokes `/roadmap:process-*` (a this-turn action), loop
-derives the contract below from roadmap's CURRENT content, and user's
-single confirmation converts declared mode into this-turn grants
-**cached for this run only** (same mechanism as commit pre-scan it
-extends). Stale frontmatter is harmless: no confirmation, no grants.
+at authoring time. It grants nothing. Authorization happens exactly
+once per run: the user invokes `/roadmap:process-*` (a this-turn
+action), the loop derives the contract below from the roadmap's
+CURRENT content, and the user's single confirmation converts the
+declared mode into this-turn grants **cached for this run only**
+(same mechanism as the commit pre-scan it extends). Stale frontmatter
+is harmless: no confirmation, no grants.
 
 ## 1. Pre-scan — four detection classes
 
 Scan every open step (text + inline notes) for:
 
 1. **Commit-shaped steps** — `commit:` / `git commit` / `Commit phase`
-   (existing § 3 scan).
+   (the existing § 3 scan).
 2. **Git-shape needs** — steps requiring a branch / push / PR
    (`branch`, `push`, `open a PR`, `create PR`, "in a worktree"), plus
-   run's own delivery needs when roadmap's definition of done includes
-   shipping (autonomous mode default, § 4).
+   the run's own delivery needs when the roadmap's definition of done
+   includes shipping (autonomous mode default, § 4).
 3. **Artifact-authoring steps** — steps that create or materially
    rewrite a skill / rule / command / guideline (verbs `add`/`create`/
    `write`/`rewrite` + artifact nouns, or paths under
-   `src/{skills,rules}/`, command/guideline trees). Feed the batched
-   [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md)
+   `src/{skills,rules}/`, command/guideline trees). These feed the
+   batched [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md)
    research pass (§ 3 below).
 4. **Open questions / ambiguity** — explicit `?` markers, "decide
-   whether", options left unresolved, or steps matching
+   whether", options left unresolved, or steps matching the
    [`ask-when-uncertain`](../../rules/ask-when-uncertain.md)
    vague-trigger patterns.
 
@@ -63,9 +64,10 @@ Always active regardless of this contract (never lifted):
 2. Adjust (name the change) · 3. Run interactive instead · 4. Abort
 ```
 
-Accept = ONE authorization of the run. Cache all grants; never re-ask
-inside the run. Adjust → apply, re-show once. Contract re-derived on
-every invocation — always reflects roadmap's and repo's current state.
+Accept = the ONE authorization of the run. Cache all grants; never
+re-ask inside the run. Adjust → apply, re-show once. The contract is
+re-derived on every invocation — it always reflects the roadmap's and
+repo's current state.
 
 ## 3. Grants activated by acceptance
 
@@ -78,7 +80,7 @@ every invocation — always reflects roadmap's and repo's current state.
 | Batched artifact drafting | The drafting-protocol **Research/overlap pass runs NOW at contract time against current artifact state**; results cached; Understand/Draft phases run non-interactively during the run. Artifacts NOT in the batch still trigger the interactive protocol |
 | Council auto-enable | In-run open questions route to the AI council silently; `high_impact` / `user_required` classifications STILL escalate to the user per [`ask-when-uncertain`](../../rules/ask-when-uncertain.md). **No council configured** → the contract summary says so and in-run true ambiguity halts (never silent guessing) |
 
-Grants satisfy [`scope-control`](../../rules/scope-control.md)'s
+These grants satisfy [`scope-control`](../../rules/scope-control.md)'s
 "standing instruction" clause for the run — see
 [`scope-mechanics § Roadmap execution contract`](../authority/scope-mechanics.md).
 
@@ -90,8 +92,8 @@ Grants satisfy [`scope-control`](../../rules/scope-control.md)'s
 | `phase-checkpoints` | Same end state | Safety floors + a compact status + "continue?" prompt at each phase boundary |
 | `interactive` (absent field) | Legacy: work lands, no git delivery without per-op permission | All gates as authored by their owning rules |
 
-If roadmap contains **no** delivery need and no commit steps, git
-grants are omitted from the contract (nothing to authorize —
+If the roadmap contains **no** delivery need and no commit steps, the
+git grants are omitted from the contract (nothing to authorize —
 [`commit-policy`](../../rules/commit-policy.md) default: never commit).
 
 ## 5. What acceptance can NEVER cover

package/dist/agent-src/contexts/execution/subagent-modes-detail.md

@@ -1,11 +1,112 @@
-# Subagent Modes — worktree + live-app-judge + adversarial-council detail
-
-Extended detail for the heaviest [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md)
-modes — `do-in-worktrees` (mode 7), `do-with-live-app-judge` (mode 8), and
-`adversarial-verification-council` (mode 9). Split out of the skill body to keep
-it under the size budget; the mode list, selection rules, and the six common
-modes stay inline in the skill. Pull this when you actually dispatch one of these
-modes.
+# Subagent Modes — per-mode detail (decision rows, contracts, heavy modes)
+
+Extended detail for the [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md)
+modes. Split out of the skill body to keep it under the size budget; the mode
+list, form gate, selection rules, and procedure stay inline in the skill. Pull
+this when you dispatch a mode and need its decision row, execution contract, or
+the heavy-mode detail (modes 7–9).
+
+## Modes 1–6 — decision rows and execution contracts
+
+### Mode 1 — do-and-judge
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Single-change task with non-trivial risk | Tiny fix, or spike/exploration | implementer = session; judge = one tier up |
+
+### Mode 2 — do-and-judge-two-stage
+
+Implementer produces a diff; **two judges run sequentially** — first a
+spec-compliance reviewer (does the diff satisfy the stated spec /
+acceptance criteria?), then a code-quality reviewer (is the diff well-
+written for the codebase it lands in?). The orchestrator only proceeds
+to stage two if stage one returns `DONE` or `DONE_WITH_CONCERNS`. A
+stage-one `BLOCKED` shortcuts the loop — there is no point quality-
+reviewing a diff that does not satisfy the spec.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Spec is contested or AC are detailed; diff size makes one judge prone to missing one axis (correctness vs craft) | Spec is one sentence, or the diff is one line (collapse to mode 1) | implementer = session; spec-judge = one tier up; quality-judge = same tier as spec-judge, fresh context |
+
+**Why two stages, not one judge with both rubrics:** combining the
+rubrics in one prompt reliably regresses one of them — the judge "spends
+attention" on whichever rubric appears last. Splitting the prompts
+forces each judge to commit fully to its rubric.
+
+**Stage-routing rule:**
+- Stage-1 returns `DONE` → run stage-2.
+- Stage-1 returns `DONE_WITH_CONCERNS` → run stage-2; concerns carry
+  forward to the final envelope.
+- Stage-1 returns `NEEDS_CONTEXT` → pause; stage-2 does not run.
+- Stage-1 returns `BLOCKED` → final verdict is `BLOCKED`; stage-2
+  does not run (saves cost).
+
+### Mode 3 — do-in-steps
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Multi-step plan with ordered dependencies | Single-step change, or when steps are independent (use `do-in-parallel`) | implementer = session; judge = one tier up |
+
+### Mode 4 — do-in-parallel
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Independent slices (different files, non-overlapping) | Any slice touches shared state | implementer = session; judge = one tier up, run once |
+
+### Mode 5 — do-competitively
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Broad solution space (algorithm choice, API shape) | Well-defined problem with one good answer | implementers = same tier (≥2 instances); judge = one tier up |
+
+### Mode 6 — judge-with-debate
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Security, data integrity, public API change | Routine internal refactor | judges = same tier (2x); meta-judge = one tier up |
+
+## Severity-conditioned team composition — conditions pattern
+
+Guidance, not a new object class (persona-catalog disposition; AI council
+2026-07-27, claude-sonnet-4-5 + gpt-4o: capture as guidance on this
+existing surface — no roster schema, no linter, no fourth scoping
+ontology). Incident-style severity tiers refine composition and
+activation **within** the form the static gate already picked — severity
+never overrides the form gate, the Iron Law, or any safety floor.
+
+| Severity | Composition + activation | Existing mode(s) |
+|---|---|---|
+| Critical — prod impact, security, data integrity | Full parallel team; debate-grade review on the aggregate | `do-in-parallel` + `judge-with-debate` (Mode 9 where opted in) |
+| High — contested spec, cross-layer risk | Implementer + two sequential judges | `do-and-judge-two-stage` |
+| Medium — routine multi-step | Implementer + judge between steps | `do-in-steps` / `do-and-judge` |
+| Low — small, reversible | Solo with async review | in-session (`none`); optional single async judge |
+
+At equal severity the cheapest-mode preference (skill § 3. Pick the mode)
+still applies; escalate one tier only on a named risk signal, never on
+vibes.
+
+## Status taxonomy — rationale and routing semantics
+
+Every implementer or judge return conforms to
+[`schemas/subagent-status.json`](../../../skills/subagent-orchestration/schemas/subagent-status.json).
+Four statuses, no free-form alternatives:
+
+| Status | Meaning | Required keys (beyond `status`, `summary`) |
+|---|---|---|
+| `DONE` | Work shipped, all gates green. | `evidence[]` |
+| `DONE_WITH_CONCERNS` | Work shipped but caller must act on concerns. | `evidence[]`, `concerns[]` |
+| `NEEDS_CONTEXT` | Paused; caller can unblock by answering. | `blocking_question` |
+| `BLOCKED` | No path forward exists. | `blocking_reason` |
+
+**Why a fixed taxonomy:** orchestrators (`/do-and-judge`, `/do-in-steps`)
+route on status. Free-form "kind of done" returns force the orchestrator
+to interpret prose, which silently regresses the two-revision ceiling and
+the judge-rejected-do-not-apply rule. The schema makes routing mechanical.
+
+**Distinguishing `NEEDS_CONTEXT` from `BLOCKED`:** `NEEDS_CONTEXT` means
+*"you, the caller, can fix this by telling me X"*. `BLOCKED` means
+*"no input from you unblocks this — escalate or rescope"*. If a subagent
+is unsure, it picks `BLOCKED` and the caller can downgrade.
 
 ## Mode 7 — do-in-worktrees
 

package/dist/agent-src/contexts/execution/subagent-response-contract.md

@@ -21,6 +21,26 @@ orchestrator synthesises and re-verifies.
   never inline content — same minimal-slice / privacy floor as the spawn contract.
 - `mutating` marks a finding whose action changes files/state (feeds the verify link).
 
+## Budget-hit partial result
+
+When the worker's `max_tokens_per_worker` stop-loss fires
+([spawn contract § Per-worker token stop-loss](subagent-spawn-contract.md#per-worker-token-stop-loss-l0b--hard-budget-structured-escalation)),
+the return is a `BLOCKED` envelope whose body is this shape instead:
+
+```json
+{
+  "budget_hit": true,
+  "found": ["file:line | id | path"],
+  "remaining": "<what stays unexplored, one sentence>",
+  "suggested_next_rung": "primitive | higher-tier-subagent | in-session"
+}
+```
+
+`budget_hit: true` is the escalation flag; `found` follows the same
+refs-not-bodies floor as `evidence_refs`. Validator:
+`worker_budget.validateWorkerPartialResult` — the orchestrator never adopts an
+invalid partial return.
+
 ## Orchestrator synthesis duties
 
 ```

package/dist/agent-src/contexts/execution/subagent-routing.md

@@ -37,6 +37,17 @@ THE SAME MINUS THE QUOTA WIN.
    "Sonnet-has-its-own-allowance" idea lives, and it lives as a runtime-detected
    flag, never as portable prose.
 
+**Cache trade-off (road-to-cache-economy Phase 4).** A tier downshift changes
+the sub-task's model, and the prompt cache is keyed by `(model, prefix)` — so
+a downshifted leg forfeits its model-scoped cache reads AND splits a cohort's
+shared prefix into two caches (downshifted legs vs. session-tier legs). The
+per-call model saving and the forfeited cache-read saving pull in opposite
+directions; which wins is a measured question, not a default this policy
+resolves — see
+[`docs/contracts/ai-council-config.md`](../../../../docs/contracts/ai-council-config.md)
+§ `model_downgrade` for the analogous downgrade/cache coupling this suite
+already ships on the council side.
+
 ## Why vendor-neutral
 
 A separate-quota-pool is a billing quirk of one host at one time. Encoding it