@event4u/agent-config 9.8.0 → 9.10.0

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

@@ -13,7 +13,8 @@ task without re-inventing any taxonomy.
   "role_mode": "developer|reviewer|tester|po|incident|planner|null",
   "profile": "<active profile id or null>",
   "personas": ["<persona id>", "..."],
-  "knowledge_refs": ["<id-or-path>", "..."]
+  "knowledge_refs": ["<id-or-path>", "..."],
+  "max_tokens_per_worker": 15000
 }
 ```
 
@@ -41,6 +42,28 @@ private-data leg stays narrow: the composer rejects inline bodies (multi-line /
 oversized entries), accepts only ref-like tokens, and caps the count. Anything
 dropped is recorded in `warnings` and surfaced — never silently widened.
 
+## Per-worker token stop-loss (L0b) — hard budget, structured escalation
+
+```
+EVERY DISPATCHED WORKER CARRIES A max_tokens_per_worker BUDGET FOR ITS TIER.
+ON HIT: RETURN A STRUCTURED PARTIAL RESULT + ESCALATION FLAG — STOP EXPLORING.
+A WORKER OVERRUNNING ITS BUDGET 20× IS A DISPATCH ERROR ON THE WRONG RUNG,
+NOT DILIGENCE.
+```
+
+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
+partial-result shape from the
+[response contract](subagent-response-contract.md#budget-hit-partial-result):
+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 — 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
 
 The brief is **resolved**, not hand-built. `resolveBundle(slice)` maps a task
@@ -64,9 +87,36 @@ only, never bodies.
 
 [`src/scripts/_lib/subagent_spawn.ts`](../../../../src/scripts/_lib/subagent_spawn.ts)
 (`composeSpawnBrief`) + [`src/scripts/_lib/subagent_bundle.ts`](../../../../src/scripts/_lib/subagent_bundle.ts)
-(`resolveBundle`, `filterKnowledgeByPolicy`, `bundleAuditLine`), covered by
+(`resolveBundle`, `filterKnowledgeByPolicy`, `bundleAuditLine`) +
+[`src/scripts/_lib/worker_budget.ts`](../../../../src/scripts/_lib/worker_budget.ts)
+(`budgetForTier`, `evaluateWorkerBudget`, `validateWorkerPartialResult`),
+covered by
 [`tests/scripts/_lib_subagent_spawn.test.ts`](../../../../tests/scripts/_lib_subagent_spawn.test.ts)
-+ [`tests/scripts/_lib_subagent_bundle.test.ts`](../../../../tests/scripts/_lib_subagent_bundle.test.ts).
++ [`tests/scripts/_lib_subagent_bundle.test.ts`](../../../../tests/scripts/_lib_subagent_bundle.test.ts)
++ [`tests/scripts/_lib_worker_budget.test.ts`](../../../../tests/scripts/_lib_worker_budget.test.ts)
+(the budget-hit partial-result fixture).
+
+## Worker rtk allowlist — wrap only the measured class
+
+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
+
+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; 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.
 
 ## Worker-prompt rules — verbatim at spawn
 

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

@@ -31,22 +31,22 @@ dispatch → monitor → status → escalate / kill
 
 ## Transient-failure retry — tier downshift
 
-On transient subagent failure (HTTP 429, 5xx, timeout), retry **once** at the
-next-lower model tier (haiku → if already haiku, escalate to `spawn_failure`
-counter) before counting a failed attempt. Max one downshift per call.
-Downshifted retry also fails → increment `spawn_failure_rate` normally. Never
-downshift twice on the same slot — deterministic cap prevents silent drift to the
-cheapest model on every failure.
+On a transient subagent failure (HTTP 429, 5xx, or timeout), retry **once** at
+the next-lower model tier (haiku → if already haiku, escalate to the `spawn_failure`
+counter) before counting a failed attempt. Maximum one downshift per subagent
+call. If the downshifted retry also fails, increment the `spawn_failure_rate`
+counter normally. Never downshift twice on the same slot — deterministic cap
+prevents silent drift to the cheapest model on every failure.
 
-Only automatic response to a transient failure; structural/semantic errors (e.g.
-`BLOCKED` envelope) do **not** trigger a downshift — escalate to the orchestrator
-immediately.
+This is the only automatic response to a transient failure; structural or
+semantic errors (e.g. `BLOCKED` status envelope) do not trigger a tier
+downshift — they escalate to the orchestrator immediately.
 
 ## Verify-fail escalation — the downshift cascade (M3)
 
 Cheap-first cascade for DOWNSHIFTED slices only
 (road-to-cost-aware-model-routing, council 2026-07-08). Transient failures
-(above) and verify-fails are distinct: transient retries downward once; a
+(above) and verify-fails are distinct: a transient retries downward once; a
 **verification failure escalates upward**.
 
 ```
@@ -59,16 +59,16 @@ NEVER THE SUBAGENT'S OWN CONFIDENCE.
 ```
 
 - **Scope:** slices with `tier_source: static | inferred` only. `inherit`
-  slices keep existing same-tier retry semantics — no behavior change outside
-  the downshift path.
+  slices keep the existing same-tier retry semantics — no behavior change
+  outside the downshift path.
 - **Budget accounting:** each escalated attempt consumes one of the slice's
   three attempts (`budgetHalt()` unchanged). Two failed attempts mark the
   slice failed; the orchestrator replans — a slice's verify-fail never
   poisons the orchestrator trajectory, only the final verified return (or
-  failure mark) enters its context.
+  the failure mark) enters its context.
 - **Telemetry:** the re-dispatch records `escalated_from: <failed tier>` and
   appends to `verify_result_by_tier`.
-- **Economics guard:** a class escalating > 40% of the time is cheaper
+- **Economics guard:** a class that escalates > 40% of the time is cheaper
   started on the higher tier — the escalation-rate tripwire (below) promotes
   its static default; the cascade is for the tail, not the norm.
 
@@ -76,29 +76,30 @@ Deterministic reference: `escalateOnVerifyFail()`.
 
 ## Failure-type stop — the N=3 budget applied per subagent type
 
-Two consecutive **verification-failed** returns from one subagent type in a
-session exhaust that type's dispatch budget: 2 failures + escalation ARE the
-three N=3 attempts — an application of that budget at type granularity,
-**not a new mechanism, not a circuit breaker**. On fire the orchestrator:
+Two consecutive **verification-failed** returns from the same subagent type in
+one session exhaust that type's dispatch budget: the two failures plus the
+escalation step ARE the three attempts of the existing N=3 budget — this is an
+application of that budget at type granularity, **not a new mechanism and not
+a circuit breaker**. When it fires the orchestrator:
 
-1. stops dispatching that type for the rest of the session,
+1. stops dispatching that subagent type for the rest of the session,
 2. surfaces both failed returns to the human,
 3. runs the remaining slices in-session.
 
-Iron Law below unchanged — no automatic cohort-disable; the stop is
-session-scoped orchestrator state, never a persisted flip. Deterministic
-reference: `typeStop()`.
+The Iron Law below stands unchanged — there is still no automatic
+cohort-disable, and the stop is session-scoped state the orchestrator holds,
+never a persisted flip. Deterministic reference: `typeStop()`.
 
 ## Ordered-slice dependency gate (do-in-steps)
 
-An ordered slice **declares its parent**; no slice dispatches before the
-parent's return is verified by the orchestrator. Makes the implicit
-`do-in-steps` contract ("step N output → judge → step N+1 input") explicit
-and checkable: `sliceDispatchAllowed(declaredParent, verifiedReturns)`
-refuses dispatch while the parent lacks a verified return in session state.
-Root / independent slices (no declared parent) always pass. A refused slice
-is not an error — the ordering contract doing its job; verify (or revise)
-the parent first.
+An ordered slice **declares its parent**; no slice dispatches before its
+parent's return has been verified by the orchestrator. This makes the
+implicit `do-in-steps` contract ("step N output → judge → step N+1 input")
+explicit and checkable: `sliceDispatchAllowed(declaredParent,
+verifiedReturns)` refuses the dispatch while the parent lacks a verified
+return in session state. Root / independent slices (no declared parent)
+always pass. A refused slice is not an error — it is the ordering contract
+doing its job; the orchestrator verifies (or revises) the parent first.
 
 ## Rollback guardrails — surfaced, not auto-disabled
 
@@ -131,13 +132,13 @@ not a new mechanism:
 
 | Tripwire | Threshold | Action when fired |
 |---|---|---|
-| **Escalation-rate promotion** | per-class escalation rate > 40% over the rolling window | Class's default tier is wrong — cascading it costs more than starting high (decision-theoretic escalation analysis). Promote the class's static default one tier, log the promotion; do not keep cascading. |
-| **Verify-pass drift** | a tier's verify-pass rate drops below its trailing baseline | Verifier or model drift — a drifting verifier silently escalates everything (cost ~3x). Surface the drift with per-tier numbers; never silently absorb the extra escalations. |
+| **Escalation-rate promotion** | per-class escalation rate > 40% over the rolling window | The class's default tier is wrong — cascading it costs more than starting high (decision-theoretic escalation analysis). Promote the class's static default one tier and log the promotion; do not keep cascading. |
+| **Verify-pass drift** | a tier's verify-pass rate drops below its trailing baseline | Verifier or model drift — a drifting verifier silently escalates everything (cost ~3x). Surface the drift to the user with the per-tier numbers; never silently absorb the extra escalations. |
 
 Deterministic references: `escalationPromotionCandidates()` and
-`verifyPassDrift()` over `readTierRoutingMetrics()` aggregates. Per-tier
+`verifyPassDrift()` over `readTierRoutingMetrics()` aggregates. The per-tier
 quality view (spend by tier, escalation count by class, verify-pass rate by
-tier) surfaces via `/cost:report` — the delayed-signal quality guard: cost
+tier) is surfaced via `/cost:report` — the delayed-signal quality guard: cost
 dashboards alone look fine while quality regresses.
 
 ## Kill-switch
@@ -162,3 +163,4 @@ This is the canonical disable — no code change, effective on the next run.
 - [`autonomous-execution`](../../rules/autonomous-execution.md) — the N=3 budget.
 - [`auto-orchestration-activation`](auto-orchestration-activation.md) — `enabled`/`auto` keys.
 - [`orchestration-telemetry`](orchestration-telemetry.md) — the audit signals the guardrails read.
+- [`subagent-response-contract`](subagent-response-contract.md) — the structured body returned inside this 4-status envelope + the orchestrator's synthesis duties.

package/dist/agent-src/contexts/execution/toolchain-resolver.md

@@ -1,7 +1,7 @@
 # Toolchain Resolver Contract
 
 Loaded by every engineering command that runs tests or quality tools
-(`/tests execute`, `/tests create`, `/fix quality`, `/review-changes`,
+(`/tests execute`, `/tests create`, `/fix quality`, `/review changes`,
 `/work`). Holds the single source of truth for **stack-adaptive
 toolchain resolution**: detect the consumer's test runner / quality
 tools and run the right one — instead of a per-stack command explosion.

package/dist/agent-src/contexts/execution/user-memory-channels.md

@@ -0,0 +1,189 @@
+# User-memory channels — the two write paths GATHER SIGNAL feeds
+
+Migrated out of [`memory-consolidation`](../../../skills/memory-consolidation/SKILL.md)
+on 2026-07-30 (P4 pattern: the skill keeps the obligation surface, the
+mechanics live here). The skill had grown to 554 lines and tripped the
+size warning; these two channel sections were the growth. Nothing was
+dropped — the text below is the extracted body verbatim.
+
+Both channels are governed by the council cut in
+[`global-user-memory-cut`](../../../../agents/settings/contexts/global-user-memory-cut.md)
+and the schema contract `docs/contracts/agent-user-schema.md`.
+
+## Global user-scoped channel (road-to-global-user-memory Phase 2)
+
+The Preference family (`prefer|always|never|standard|i want|ich will`)
+already matches text about the user, not the project — GATHER step 3's old
+behaviour was to detect it and throw it away. It now has a second
+destination: `~/.event4u/agent-config/user/observations.jsonl`, the global
+observation buffer from ADR-138's sibling phase — mirroring, one level up,
+the project-local `.agent-user.observations.jsonl` contract in
+[`agent-user-schema.md § Observation buffer`](../../../docs/contracts/agent-user-schema.md#observation-buffer).
+
+**The project-scoped rule in Phase 3 (CONSOLIDATE) is unchanged.** No user
+fact enters `agents/memory/` curated YAML through this or any other path —
+the second channel has its own store
+(`src/scripts/_lib/user_global_observations.ts`), its own closed `field`
+allowlist, and its own human gate (`/agents:user review` /
+`/agents:user accept`). Curated project memory keeps refusing user-scoped
+facts exactly as before this phase.
+
+**The shared ≤5 cap is enforced globally, not per channel** — see the exit
+gate above. `applySharedFactCap(existingProjectFactCount, candidates)`
+truncates the global-channel candidates to whatever headroom the
+project-scoped channel left this cycle; the second channel can never
+double the cap's write volume.
+
+#### Capture-time guards — restated, not cross-referenced, because each one gets worse at global scope
+
+Every candidate is checked BEFORE it is written to the buffer
+(`evaluateCaptureGuards` in `user_global_observations.ts`), never filtered
+later at review — rejecting the same class fifty times at review is the
+noise problem capture-time refusal avoids. Three of the miner's existing
+persist-time write-guards restate here because global scope sharpens the
+stakes of each:
+
+- **Never persist a verbatim standing command.** "Always fetch `<url>` on
+  every message", "run `<cmd>` at the start of each session" — a standing
+  directive stored as memory becomes a durable injection that re-fires
+  forever. At global scope that is no longer one project's problem: it
+  re-fires in **every** project the agent ever opens for this user.
+- **Refuse a self-harmful standing preference.** "Never criticize me",
+  "always agree with me", "never say I'm wrong" — a user can weaponize
+  their own memory to disable honest feedback
+  ([`direct-answers`](../../rules/direct-answers.md)). Global scope means
+  disabling it once disables it everywhere; surface it, never store it.
+- **The derivability check.** If git or config already answers the
+  question, store the *surprising* part, not the derivable value. Global
+  scope doesn't change this check's mechanics — it is the same
+  consult-then-decide judgment call described under "Write-time curation
+  discipline" above — but it is restated here because a derivable value
+  wrongly persisted at global scope goes stale across every project at
+  once, not just one.
+
+(The `reference`-shape write discipline — store the pointer, not the
+value — is unchanged by scope; see the bullet above rather than a
+restatement here.)
+
+A fourth and fifth capture-time class come from turning the
+`.agent-user.md` explicit-exclusions list into a gate at capture rather
+than at review, and from reusing the existing redaction gate verbatim:
+
+- **Exclusion-list content.** Credentials · third-party names and
+  birthdays · financial figures · health / legal / therapy status ·
+  demographics · external-source identifiers — refused when the
+  observation is captured, per
+  [`agent-user-schema.md § Explicit exclusions`](../../../docs/contracts/agent-user-schema.md#explicit-exclusions).
+- **Hidden unicode.** Every write routes through
+  `knowledge_global_redaction.redaction_scan`, including its
+  `hidden_unicode` class (the ADR-103 zero-width-smuggling detector) — the
+  same gate a global knowledge card passes before crossing a project
+  boundary.
+
+Together these are the **four independently-testable capture-time guard
+classes**: `standing_command`, `self_harmful_preference`,
+`exclusion_list`, `hidden_unicode` — each has its own test in
+`tests/lib/user_global_observations.test.ts` that fails if its guard is
+removed.
+
+#### The write path stays human-gated
+
+`appendGlobalObservation` only ever appends to the buffer — it never
+touches `profile.md`. The buffer is reviewed via `/agents:user review` and
+applied via `/agents:user accept`
+(`applyObservationToGlobalProfile` in `agent_user_profile.ts`), which
+remains the **only** function anywhere in this channel that writes
+`profile.md`. Nothing here runs automatically end-to-end; the human accept
+step is still the gate ADR-138 and this phase both depend on.
+
+## Project attribution channel (road-to-global-user-memory Phase 3)
+
+CONSOLIDATE step 2 below assumes `agents/memory/intake/` exists and is
+this package's own managed tree. It is not, for every project — the
+operator's third ask ("P: project facts with no managed folder") covers
+exactly the case where a repo has no managed `agents/` folder to write
+project-scoped facts into at all.
+
+**Check ORIENT step 2's premise before CONSOLIDATE writes anywhere.**
+Resolve [`detect_managed_agents_folder`](../../../src/scripts/_lib/managed_agents_folder.ts)
+against the project root once, during ORIENT:
+
+- `managed` → CONSOLIDATE proceeds exactly as written below; nothing in
+  this section changes.
+- `unmanaged` / `not-a-project` → a project-scoped fact has nowhere local
+  to land. Route it through
+  [`routeProjectObservation`](../../../src/scripts/_lib/user_global_observations.ts)
+  instead of writing to `agents/memory/intake/` (which would either fail
+  or, worse, scaffold an unmanaged `agents/` directory as an unintended
+  side effect). This attaches a `context` object
+  (`project_path`/`project_name`/`first_seen`) and a `seen_count`/
+  `seen_in[]` recurrence tally to the fact and appends it to the SAME
+  global buffer Phase 2 uses — never a second store, never a
+  project-indexed directory (the council's round-2 namespace refusal; see
+  [`agent-user-schema.md § Project attribution`](../../../docs/contracts/agent-user-schema.md#project-attribution-road-to-global-user-memory-phase-3)).
+
+**This is the only generalisation path.** A fact recurring in a
+*different* unmanaged project (Jaccard similarity ≥ `MERGE_THRESHOLD`,
+the identical dedup primitive `_lib/text_similarity.ts` uses elsewhere)
+bumps `seen_count`; at `seen_count ≥ 3` it surfaces in `/agents:user
+review` as a promotion candidate, with a mandatory `promotion_reason` as
+human input before `/agents:user accept` writes anything to `profile.md`.
+The agent never infers the cross-project pattern itself — `seen_count`
+only grows one write at a time, from this router observing a genuinely
+new project, never a batch scan across the store (the same non-goal §
+Global user-scoped channel already restates for the U layer).
+
+
+## TranscriptAdapter contract
+
+The miner is host-agnostic by design. A `TranscriptAdapter` for host
+`X` ships:
+
+- **Discover:** function returning the absolute path(s) of session
+  transcripts for the active project, scoped to the `--since` window.
+  Phase 1 ships the Claude-Code adapter only; absent adapter →
+  `not-supported-on-this-host`.
+- **Iterate:** generator yielding turn objects with `{role, ts,
+  text}`. Adapter strips IDE chrome and tool-call boilerplate before
+  yielding.
+- **Redact:** function applied to every yielded text — drops user
+  names, file paths outside the repo root, and any personal
+  identifier the consumer project lists in
+  `.agent-settings.yml` under `memory.redact_patterns`.
+
+The GATHER implementation lives in the single mining command
+`/memory:mine-session` (`scripts/mine_session.ts`). It reads the
+**cross-host** chat-history JSONL log (`agents/runtime/.agent-chat-history`,
+written by platform hooks on every host), falling back to the per-host
+Claude-Code transcript when the log is absent. `--mode=[signals|proposals|both]`
+selects intake signals and/or rule/skill proposal seeds — the latter folds in
+the former `/chat-history learn`.
+
+
+## In-task notes → cross-run lessons (RDP)
+
+The Reasoning Discipline Protocol writes an **in-task** session-notes file
+(hypotheses, killed beliefs, predictions, decisions, uncertainty — structure in
+[`notes-first-reasoning`](../../rules/notes-first-reasoning.md)). That file is
+ephemeral working state, not curated memory. This skill is the **promotion path**:
+when an in-task killed-belief, calibrated prediction, or decision *generalises*
+beyond the task, consolidate it here as a durable cross-run lesson (one lesson per
+file, with why it mattered). Apply the same signal-vs-noise discipline — most
+in-task notes stay in-task and are discarded with the task.
+
+
+## Runnable example
+
+After a 4-day refactor of `app/Services/PaymentGateway`, run a
+consolidation cycle:
+
+- `/memory:mine-session --since 2026-05-06 --confirm-transcript-access --preview`.
+- Miner surfaces 4 facts: 1 correction (`PaymentGateway::charge` must
+  not throw on idempotency replays — `convention`), 1 decision
+  (Laravel example: `Stripe webhook signing key lives in `config/services.php` only —
+  `gotcha`), 2 patterns (`PaymentGatewayTest` flakes when seeded data
+  carries timestamps in microseconds — `pattern + gotcha`).
+- Report cites 0 stale flags. Re-run with `--commit-intake` after
+  spot-checking the 4 facts.
+- Hand off to `/memory:promote` for the curated-YAML write.
+

package/dist/agent-src/contexts/execution/verification-mechanics.md

@@ -90,3 +90,12 @@ Minimum evidence:
 Completion wording: _"hotfix applied, full verification deferred per
 break-glass"_ — never _"done"_ or _"verified"_. The normal gate resumes
 on the follow-up PR.
+
+## Migrated from `verify-before-complete` (kernel-budget relief, 2026-07-30)
+
+### Examples
+
+Wrong/right/why demos (hedged claims, trusting earlier runs,
+partial-verification creep): [`verify-before-complete-demos`](../../../../docs/guidelines/agent-infra/verify-before-complete-demos.md).
+Outcome baseline:
+[`tests/golden/outcomes/verify_before_complete.json`](../../../../tests/golden/outcomes/verify_before_complete.json).

package/dist/agent-src/contexts/model-recommendations.md

@@ -61,8 +61,9 @@ implementer never downshifts its judge.
 ## Cost cross-link
 
 Tier choice is also a **billing lever** — for the dollar side (caching, batch,
-model tiering, effort right-sizing) route via `token-optimizer` skill's index
-branch (`api-cost-levers` row); `/cost:report` names the dominant lever.
+model tiering, effort right-sizing) route via the `token-optimizer` skill's
+index branch (`api-cost-levers` row); `/cost:report` names the dominant lever
+for the session.
 
 ## Detection Heuristics
 

package/dist/agent-src/contexts/subagent-configuration.md

@@ -29,9 +29,9 @@ If the session runs on **haiku**, judge defaults to sonnet.
 implementer on a downshifted tier (per the category → tier defaults in
 [`model-recommendations § Subagent Category → Tier Defaults`](model-recommendations.md)),
 the judge still resolves one tier above the IMPLEMENTER's resolved tier —
-a `lite` implementer gets at least a `medium` judge. Downshifting an
+so a `lite` implementer gets at least a `medium` judge. Downshifting an
 implementer never downshifts its judge below what the verify contract
-requires; a judge is never `lite`.
+requires, and a judge is never `lite`.
 
 ## Resolution order
 
@@ -67,5 +67,5 @@ The commands read `.agent-settings.yml` fresh on each run.
 
 - [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md) — the skill
 - [`model-recommendations`](model-recommendations.md) — tier definitions
-- `guideline:agent-infra/model-recommendation` § Orchestrator → subagent model routing — per-subtask model right-sizing (downgrade easy work, keep strong model for hard)
+- `guideline:agent-infra/model-recommendation` § Orchestrator → subagent model routing — per-subtask model right-sizing (downgrade easy work, keep the strong model for hard)
 - [`/do-and-judge`](../commands/do-and-judge.md), [`/do-in-steps`](../commands/do-in-steps.md), [`/judge`](../commands/judge.md) — commands that read these keys

package/dist/agent-src/ghostwriter/README.md

@@ -49,7 +49,7 @@ New fixtures require reviewer sign-off on the allowlist change.
 
 ## Schema
 
-See [`docs/contracts/ghostwriter-schema.md`](../../docs/contracts/ghostwriter-schema.md)
+See [`docs/contracts/ghostwriter-schema.md`](../docs/contracts/ghostwriter-schema.md)
 for the locked v1 frontmatter, field reference, confidence derivation,
 verification enum, ethics floor, lint rules, and command surface.
 
@@ -57,5 +57,5 @@ verification enum, ethics floor, lint rules, and command surface.
 
 - [`personas/README.md`](../personas/README.md) — sibling primitive,
   distinct voice axis.
-- [`docs/contracts/agent-user-schema.md`](../../docs/contracts/agent-user-schema.md)
+- [`docs/contracts/agent-user-schema.md`](../docs/contracts/agent-user-schema.md)
   — the maintainer-self primitive that `/post-as:me` consumes.

package/dist/agent-src/packs/README.md

@@ -4,7 +4,7 @@ Seed packs that bundle `(profile + preset + command-set +
 skill-allowlist + personas)` into a single opinionated stance. A
 user adopts a pack instead of picking five independent settings.
 
-**Schema:** [`docs/contracts/workflow-packs.md`](../../docs/contracts/workflow-packs.md).
+**Schema:** [`docs/contracts/workflow-packs.md`](../docs/contracts/workflow-packs.md).
 
 ## Shipped packs
 

package/dist/agent-src/personas/README.md

@@ -34,7 +34,7 @@ Personas fix that: one definition, many skills.
 
 ## Schema
 
-Locked in [`../../docs/contracts/persona-schema.md`](../../docs/contracts/persona-schema.md).
+Locked in [`../docs/contracts/persona-schema.md`](../../docs/contracts/persona-schema.md).
 Two-tier hybrid (council iter-1 A-OQ1 verdict (c)):
 
 - **Core** — 5 sections (Focus · Mindset · Unique Questions · Output
@@ -101,8 +101,8 @@ cast (usually Core-6 for review skills, empty for others).
 
 ## Related
 
-- [`../../docs/contracts/persona-schema.md`](../../docs/contracts/persona-schema.md) — locked schema (Core / Specialist)
-- [`../../docs/guidelines/agent-infra/role-contracts.md`](../../docs/guidelines/agent-infra/role-contracts.md) — workflow modes personas compose with
+- [`../docs/contracts/persona-schema.md`](../../docs/contracts/persona-schema.md) — locked schema (Core / Specialist)
+- [`../docs/guidelines/agent-infra/role-contracts.md`](../../docs/guidelines/agent-infra/role-contracts.md) — workflow modes personas compose with
 - [`../rules/artifact-drafting-protocol.md`](../rules/artifact-drafting-protocol.md) — mandatory per new persona
 
 ## See also — sibling voice primitives
@@ -110,5 +110,5 @@ cast (usually Core-6 for review skills, empty for others).
 Personas are one of three voice primitives. Same shape (Markdown +
 frontmatter), distinct purpose — **no folding, no shared schema**:
 
-- [`../../docs/contracts/agent-user-schema.md`](../../docs/contracts/agent-user-schema.md) — `.agent-user.md`, the maintainer's own voice (`/post-as:me`, no disclosure footer).
-- [`../../docs/contracts/ghostwriter-schema.md`](../../docs/contracts/ghostwriter-schema.md) — `agents/reference/ghostwriter/<slug>.md`, captured public-figure voice (`/ghostwriter:write` / `/post-as:ghostwriter`, mandatory disclosure footer).
+- [`../docs/contracts/agent-user-schema.md`](../../docs/contracts/agent-user-schema.md) — `.agent-user.md`, the maintainer's own voice (`/post-as:me`, no disclosure footer).
+- [`../docs/contracts/ghostwriter-schema.md`](../../docs/contracts/ghostwriter-schema.md) — `agents/reference/ghostwriter/<slug>.md`, captured public-figure voice (`/ghostwriter:write` / `/post-as:ghostwriter`, mandatory disclosure footer).

package/dist/agent-src/personas/_template-specialist/persona.md

@@ -30,8 +30,8 @@ responsible for.
 
 ## Unique Questions
 
-Three or more questions no other persona asks verbatim. Each must
-be falsifiable against the artefact under review.
+Three or more questions no other persona asks verbatim. Each must be
+falsifiable against the artefact under review.
 
 - {Question 1 — direct, scoped, answerable from the diff/plan.}
 - {Question 2.}
@@ -44,7 +44,7 @@ How findings are phrased when this lens is invoked.
 
 - Format: bullets · table · numbered list — pick one.
 - Severity vocabulary: e.g. `must-fix · should-fix · nit`.
-- Citation rule: every finding cites a file:line or contract path.
+- Citation rule: every finding cites a file:line or a contract path.
 - Length: short — one screen unless the diff is genuinely large.
 
 ## Anti-Patterns

package/dist/agent-src/personas/backend-architect.md

@@ -11,14 +11,15 @@ mode: reviewer
 ## Focus
 
 System shape behind the diff. Reads every change against the layered
-boundaries it crosses — controller → service → domain → persistence —
-and asks whether the boundary remains coherent after. Notices when a
-module quietly absorbs a responsibility belonging elsewhere, when a
-transaction grows new side-effects, when an interface gains implicit
-clients.
+boundaries it crosses — controller → service → domain → persistence
+— and asks whether the boundary remains coherent after. Notices when
+a module quietly absorbs a responsibility that belonged elsewhere,
+when a transaction grows new side-effects, when an interface gains
+implicit clients.
 
-Not the code-quality lens; does not chase naming or DRY. Chases
-coupling, leakage, and decisions hard to undo.
+This persona is not the code-quality lens; it does not chase naming
+or DRY. It chases coupling, leakage, and decisions that are hard to
+undo.
 
 ## Mindset
 
@@ -26,34 +27,34 @@ coupling, leakage, and decisions hard to undo.
   versioning event in disguise.
 - Transaction boundaries are part of the API — extending one across
   a network call is the change, not the symptom.
-- A service calling another service's repository signals the seam is
-  wrong, not that the call is convenient.
+- A service that calls another service's repository is a sign the
+  seam is wrong, not that the call is convenient.
 - Backwards-compatible-on-the-wire ≠ backwards-compatible — query
-  shapes, lock orderings, event payloads count too.
+  shapes, lock orderings, and event payloads count too.
 
 ## Unique Questions
 
 - Which seam does this change cross, and is the new dependency
   direction the one we want long-term?
-- What is the transaction boundary now, and does the diff stretch it
-  across an external call, queue, or tenant?
-- Which downstream consumer of this API will silently break — caller
-  signature, event payload, or query result shape?
+- What is the transaction boundary now, and does the diff stretch
+  it across an external call, queue, or tenant?
+- Which downstream consumer of this API will silently break — the
+  caller signature, the event payload, or the query result shape?
 - Is this the right module to own this responsibility, or has it
   drifted in because the right module felt expensive to touch?
 
 ## Output Expectations
 
-Numbered findings, each citing `path:line` and naming the boundary
-at risk. Severity: `must-fix` for new cyclic deps, widened
-transaction scope, breaking contract changes; `should-fix` for
-module misownership; `nit` for naming inside the seam. End with a
-one-sentence verdict on whether the change is locally clean but
+Findings as a numbered list, each citing `path:line` and naming the
+boundary at risk. Severity: `must-fix` for new cyclic dependencies,
+widened transaction scope, or breaking contract changes; `should-fix`
+for module misownership; `nit` for naming inside the seam. End with
+a one-sentence verdict on whether the change is locally clean but
 architecturally regressive.
 
 ## Anti-Patterns
 
-- Do NOT review test coverage — `qa`'s lens.
+- Do NOT review test coverage — that is `qa`'s lens.
 - Do NOT comment on naming or formatting unless it signals a
   boundary leak.
 - Do NOT suggest rewrites — surface the boundary risk, propose the
@@ -65,13 +66,13 @@ architecturally regressive.
 - A new dependency edge between layers (controller → repository
   bypassing service) is `must-fix`.
 - A method's return type widening from a domain object to a raw
-  array or `mixed` is `must-fix` — removes a contract.
-- A transaction boundary newly spanning HTTP, queue dispatch, or
+  array or `mixed` is `must-fix` — it removes a contract.
+- A transaction boundary that newly spans HTTP, queue dispatch, or
   cross-tenant work is `must-fix`.
 - An event payload field rename without a deprecation cycle is
   `must-fix` — consumers exist outside this repo.
 - A service method calling another service's models or repository
-  directly is `must-fix` — seam is wrong.
+  directly is `must-fix` — the seam is wrong.
 
 ## Workflows