@event4u/agent-config 9.9.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-response-contract.md

@@ -23,9 +23,9 @@ orchestrator synthesises and re-verifies.
 
 ## Budget-hit partial result
 
-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))
-→ return is `BLOCKED` envelope whose body is this shape instead:
+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
 {
@@ -36,9 +36,9 @@ Worker's `max_tokens_per_worker` stop-loss fires
 }
 ```
 
-`budget_hit: true` is the escalation flag; `found` follows same
+`budget_hit: true` is the escalation flag; `found` follows the same
 refs-not-bodies floor as `evidence_refs`. Validator:
-`worker_budget.validateWorkerPartialResult` — orchestrator never adopts
+`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

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

@@ -51,7 +51,7 @@ A WORKER OVERRUNNING ITS BUDGET 20× IS A DISPATCH ERROR ON THE WRONG RUNG,
 NOT DILIGENCE.
 ```
 
-Budgets keyed by the worker's resolved tier
+Budgets are keyed by the worker's resolved tier
 (`worker_budget.budgetForTier`; start values `lite: 15k` — the lookup-class
 seed — `medium: 60k`, `high: 150k`, refined from `budget_hit` telemetry, never
 final). On hit the worker returns a `BLOCKED` envelope whose body is the
@@ -60,9 +60,9 @@ partial-result shape from the
 what was found (refs), what remains, suggested next rung. The stop-loss
 **composes** with the N=3 validation budget
 ([`autonomous-execution`](../../rules/autonomous-execution.md)) and the
-ADR-109 response contract — replaces nothing. Live evidence (2026-07-28):
-four lookup-class workers burned 280–327k tokens each on tasks a
-deterministic primitive answers for <1k.
+ADR-109 response contract — it replaces nothing. Live evidence
+(2026-07-28): four lookup-class workers burned 280–327k tokens each on tasks
+a deterministic primitive answers for <1k.
 
 ## Bundle resolver — bind to the existing surfaces
 
@@ -98,14 +98,14 @@ covered by
 
 ## Worker rtk allowlist — wrap only the measured class
 
-Worker tool loops wrap a command with rtk **only** when that command class
-measured ≥ ~50% output saving in `internal/bench/rtk-savings/RESULTS.md`
-(`git status`, full-format `git log -N`, `ls -la`); the ~0%-class
-(`--oneline`, `--stat` views, `npm ls`) stays unwrapped — wrap overhead
-without return. Deterministic list: `src/scripts/_lib/rtk_allowlist.ts`
-(`shouldWrapWithRtk`); congruence with RESULTS.md is test-enforced
-(`tests/scripts/_lib_rtk_allowlist.test.ts`) — numbers live in the bench
-file, referenced, never duplicated.
+A worker's tool loop wraps a command with rtk **only** when that command
+class measured ≥ ~50% output saving in
+`internal/bench/rtk-savings/RESULTS.md` (`git status`, full-format
+`git log -N`, `ls -la`); the ~0%-class (`--oneline`, `--stat` views,
+`npm ls`) stays unwrapped — wrap overhead without return. Deterministic
+list: `src/scripts/_lib/rtk_allowlist.ts` (`shouldWrapWithRtk`); congruence
+with RESULTS.md is test-enforced (`tests/scripts/_lib_rtk_allowlist.test.ts`)
+— the numbers live in the bench file, referenced, never duplicated.
 
 ## Prefix stability — deterministic payload ordering
 
@@ -113,7 +113,7 @@ Spawn payloads serialize **static prefix first** (role contract, profile,
 personas, budget — byte-identical across dispatches of the same
 configuration), **variable task part last**; no timestamps, no random IDs
 (`serializeSpawnPayload` / `spawnPayloadHash`). Provider prompt-caching keys
-on the stable prefix; `payload_hash` + `cache_hit` audit fields
+on the stable prefix; the `payload_hash` + `cache_hit` audit fields
 ([`orchestration-telemetry`](orchestration-telemetry.md)) measure whether it
 actually hits. Measurement only — no savings claim without provider-response
 evidence.