@event4u/agent-config 9.27.0 → 9.29.0

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

@@ -15,7 +15,7 @@ type: orchestrator
 suggestion:
   eligible: true
   trigger_description: "second model, GPT drüberschauen lassen, cross-model review, review gate, let another strong model check the diff, team review"
-  trigger_context: "ai_team.enabled is true AND the user wants a second strong model to review the actual working-tree diff with repo access (depth) — not a neutral artefact opinion (that is /council)"
+  trigger_context: "/team is available (codex CLI installed + authenticated, not halted) AND the user wants a second strong model to review the actual working-tree diff with repo access (depth) — not a neutral artefact opinion (that is /council)"
 workspaces:
   - agent-config-maintainer
 packs:
@@ -55,25 +55,33 @@ pre-registered benchmark (§ No-claims note).
 | Model choice | Mid-tier default (cost decision) | Strongest available — `ai_team.model: 'auto'` defers to the CLI default |
 | Write access | Never (text only; one opt-in PR comment under `pr`) | Read-only by default; `/team delegate` is the single write path, behind a second opt-in |
 
-## Default-off gate — check FIRST, before anything else
+## Availability gate — check FIRST, before anything else
 
-Read `ai_team.enabled` from `.agent-settings.yml`. Missing key or `false`
-(the shipped default) → print the enable pointer and **STOP**. Do not route,
-do not suggest a sub-command, do not probe for the plugin:
+`/team` carries no on/off setting — `ai_team.enabled` was REMOVED
+(road-to-always-on-orchestration Phase 1, Step 1.3). Availability is a FACT
+resolved from the machine: the codex CLI must resolve on `$PATH`, AND some
+auth for it must be detectable (subscription login, API key, key file, or
+env key) — the same check `agent-config doctor --check team` runs. Missing
+either → print the degrade line and **STOP**. Do not route, do not suggest
+a sub-command, do not probe for the plugin:
 
-> Team mode is disabled (`ai_team.enabled: false`, the default).
-> Enable it in `.agent-settings.yml`:
->
-> ```yaml
-> ai_team:
->   enabled: true
-> ```
->
-> Key reference: `docs/contracts/ai-team-config.md`. Then run
-> `agent-config doctor --check team` to verify plugin + auth setup.
+> codex CLI not available — `/team` needs the codex CLI installed and
+> authenticated. Install: `npm install -g @openai/codex`, then run
+> `codex login`. Verify with `agent-config doctor --check team`.
+
+Also check the one incident switch: `emergency.orchestration_halt: true`
+in `.agent-settings.yml` halts `/team` along with the rest of the always-on
+orchestration stack (subagents, council, team). Halted → print:
+
+> `/team` is halted (`emergency.orchestration_halt: true`) — the always-on
+> orchestration stack is paused for incident response. Resume: set
+> `orchestration_halt: false` with a non-empty
+> `orchestration_halt_justification` in `.agent-settings.yml`.
 
 Every sub-command repeats this check independently — the gate holds even when
-a wrapper is invoked directly.
+a wrapper is invoked directly. A leftover `ai_team.enabled` key from an
+older install is ignored (one deprecation-warning line on load) — it no
+longer gates anything.
 
 ## Sub-commands
 
@@ -89,7 +97,8 @@ rather than routing to an in-suite skill — the second column names that target
 
 ## Dispatch
 
-1. Run the default-off gate above. Disabled → enable pointer, stop.
+1. Run the availability gate above. Unavailable or halted → the matching
+   one-line block, stop.
 2. Parse the user's argument: `/team <sub-command> [args]`.
 3. Look up the sub-command in the table above; load the routed file and
    follow its `## Instructions` verbatim with the remaining args.
@@ -106,7 +115,7 @@ When the official plugin is absent on a Claude Code host, every wrapper
 fails **closed** with the doctor remediation pointer — never a silent no-op,
 never an inline reimplementation of the plugin:
 
-> ❌ Team mode is enabled, but the official plugin is not installed on this
+> ❌ `/team` is available, but the official plugin is not installed on this
 > Claude Code host. `/team <sub>` fails closed — it never reimplements the
 > plugin inline and never silently no-ops.
 >
@@ -156,4 +165,5 @@ measured improvement.
 - `adversarial-review` skill — the free single-model first rung below
   `/team adversarial`.
 - `docs/contracts/ai-team-config.md` — the `ai_team` settings block
-  (`enabled`, `model`, `allow_delegate`, `max_calls_per_day`).
+  (`model`, `allow_delegate`, `max_calls_per_day`) and the availability
+  contract (codex CLI + auth, `emergency.orchestration_halt`).

package/dist/agent-src/contexts/execution/auto-dispatch-classification.md

@@ -44,8 +44,10 @@ dwarfs the work). Below the floor → in-session.
 
 - Trivial / single-step edits below the size floor.
 - Tasks with cross-step shared mutable state that cannot be sliced.
-- Anything that fails to match a signal above → **no-op** (in-session),
-  or **ask** when `subagents.auto == ask` and the shape is borderline.
+- Anything that fails to match a signal above, once past the activation gate
+  and the size floor, is **ambiguous** → **ask**, always — a verdict to the
+  user, never a speculative spawn (always-on orchestration: there is no more
+  `subagents.auto` setting to route this on).
 
 ## Mode selection summary
 
@@ -55,6 +57,76 @@ dwarfs the work). Below the floor → in-session.
 | `parallelizable: files\|independent` / independent slices | `do-in-parallel` |
 | change needing verification (any of the above) | implementer + cross-model judge per the `subagent-orchestration` Iron Law |
 
+## Judgment ladder (Phase 2 — road-to-always-on-orchestration)
+
+One committed table replacing three scattered classification surfaces
+(the delegable-signal rules above, ad-hoc "should this be a team" calls,
+and the absence of any council-routing signal on the task side). Resolver:
+[`judgment_ladder.ts`](../../../../src/scripts/_lib/judgment_ladder.ts)
+(`classifyLadder`) — a WRAPPER around `classifyTask`, never a replacement:
+rungs 1 and 2 ARE `classifyTask`'s existing dispatch verdict.
+
+| Rung | Shape signals | Resolves to |
+|---|---|---|
+| 0 | mechanical transform, no semantics (rename / codemod / formatter-run / bulk search-and-replace), OR a lookup-class match (§ Lookup-class rung above) | deterministic script, no spawn |
+| 1 | single bounded read-heavy slice (`classifyTask` structurally cannot see this — it requires ≥2 slices, an ordered plan, or a declared `parallelizable` value) | one subagent, `lite` tier |
+| 2 | enumerable independent slices, or an ordered plan (`classifyTask` dispatch: `do-in-parallel` / `do-in-steps` both land here in this v1 — see the resolver's doc comment for why) | parallel subagents, downshifted |
+| 3 | slices that must communicate (cross-layer work, a review-with-challenge shape, an explicit shared task list) | team — only when the host reports `agent_teams: true`; else degrades to whatever `classifyTask` resolves on the same signals (usually rung 2), with a recorded `degraded_from: 3` line — never a fabricated slice count |
+| 4 | judgment under disagreement (a design decision, a proposed security downgrade, a release-gate escalation) | council |
+| ∅ | interactive-approval-required (caller-stated), trivial (below the size floor), or ambiguous | in-session; ambiguity is an `ask` VERDICT, never a speculative spawn |
+
+```
+AMBIGUITY NEVER SPAWNS. RUNG 0 NEVER SPAWNS EITHER — IT NEVER NEEDED TO.
+A MATCHED RUNG-3/4 SIGNAL WITHOUT ITS HOST PRECONDITION DEGRADES,
+RECORDED — IT NEVER SILENTLY DROPS TO ∅.
+```
+
+**Resolution order is fixed and documented on `classifyLadder` itself**:
+interactive-approval-required → rung 0 → recursive-dispatch guard →
+activation gate → rung 4 → rung 3 (+ degrade) → rungs 1/2. Two signals
+matching the same text resolve deterministically on this order, never on
+evaluation-order accident.
+
+**Recursive-dispatch guard (2.3) — honest scope.** No verified host
+discriminator exists for "is this classification running inside a
+subagent/teammate session" — this roadmap's own `point-of-action-carrier`
+blocker records the upstream PreToolUse agent-identity request as closed
+NOT_PLANNED, and no field in this repo's hook envelope carries session
+lineage. The guard is therefore a CALLER-SUPPLIED fact
+(`insideSubagentSession`), never a `process.env` probe for an unverified
+variable name — the same "no discriminator is publishable" null the
+`point-of-action-carrier` blocker already names. When set, it resolves ∅
+(in-session) for rungs 1-4; rung 0 is exempt (it never spawns).
+
+**Relationship to the council's own necessity gate.** Rung 4's three
+signals (design decision / security downgrade / release-gate escalation)
+are a deliberately narrow, TASK-side vocabulary — NOT an import of
+`ai_council/necessity.ts`'s broader `NECESSARY_TRIGGERS`
+(architecture/tradeoff/ambiguity/strategic). That module stays the
+council's own necessity gate (its `off|educate|block|warn-only` modes are
+the council-side surface); this resolver only decides whether a TASK
+should route to rung 4 in the first place.
+
+## Cheapest-sufficient-model table (Phase 2.4 — the ladder's tie-breaker)
+
+Once a slice resolves to rung 1 or 2, this table is the tie-breaker
+`classifyLadder`'s caller consults for the concrete tier — `lite` by
+default, escalating only on a named criterion. Consolidates mechanisms that
+already exist elsewhere in this contract set; this table is the ONE place
+that lists them side by side.
+
+| Escalation criterion | Tier | Basis |
+|---|---|---|
+| (none — default) | `lite` | the downshift default (`subagent-routing.md`) |
+| Slice failed verification on its current tier | next tier up (`lite`→`medium`→`medium`→`high`) | [`subagent-steering`](subagent-steering.md) § Verify-fail escalation cascade |
+| Slice touches ≥ 5 files (or > 200 lines) | `medium` | the ticket-bundle `lite` size floor (`docs/contracts/ticket-bundle-format.md`) |
+| Architecture-shaped slice (structural/boundary decision — the same shape as rung 4's design-decision signal, one level down in stakes) | `medium` | [`subagent-modes-detail`](subagent-modes-detail.md) § Severity-conditioned team composition |
+| Security-sensitive slice (auth, tenant, secrets, billing — `security-sensitive-stop`'s surface table) | `high` | [`subagent-modes-detail`](subagent-modes-detail.md) § Critical severity row |
+
+Criteria are independent and additive in the obvious way (a slice matching
+two rows takes the higher of the two tiers); this table never lowers a
+tier `inferSliceTier` (§ below) already raised.
+
 ## Per-slice tier inference (v1.5 — deterministic, task-TYPE-keyed)
 
 Once a slice is classified **delegable**, a second deterministic table infers
@@ -174,8 +246,22 @@ and the lookup corpus in
 [`src/scripts/_lib/auto_dispatch.corpus.test.ts`](../../../../src/scripts/_lib/auto_dispatch.corpus.test.ts)
 (`LOOKUP_CORPUS` — the four live-observed shapes + negative controls).
 
+The judgment ladder (§ above) is encoded in
+[`src/scripts/_lib/judgment_ladder.ts`](../../../../src/scripts/_lib/judgment_ladder.ts)
+(`classifyLadder`, plus the rung-0/1/3/4 signal-detection functions), covered
+by
+[`tests/scripts/_lib_judgment_ladder.test.ts`](../../../../tests/scripts/_lib_judgment_ladder.test.ts)
+(every rung, the rung-3 degrade path, the recursive-dispatch guard, and every
+∅ case). The delegation-nudge hook
+([`delegation_nudge_hook.ts`](../../../../src/scripts/hooks/delegation_nudge_hook.ts))
+is its first production caller — its injected line cites the resolved rung
+(`rung-2: dispatch do-in-parallel …`), scoped to the subagent dispatch rungs
+(1/2); a rung-0/3/4 verdict stays silent on this carrier until Phase 3/4 give
+team/council their own.
+
 ## Related
 
 - [`auto-orchestration-activation`](auto-orchestration-activation.md) — the enable/auto/manifest gate that runs before classification.
 - [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md) — the modes this selects.
 - [`autonomous-execution`](../../rules/autonomous-execution.md) — the N=3 budget any LLM-classification v2 must respect.
+- [`orchestration-telemetry`](orchestration-telemetry.md) § Registered always-on metrics — the judgment-ladder precision metric this ladder feeds.

package/dist/agent-src/contexts/execution/auto-orchestration-activation.md

@@ -1,55 +1,62 @@
 # Auto-Orchestration Activation
 
-How the `subagents.*` keys in `.agent-settings.yml` resolve into automatic
-subagent dispatch at runtime. Companion to
+How automatic subagent dispatch resolves at runtime. Companion to
 [`subagent-configuration`](../subagent-configuration.md) (which covers the
 model / parallelism keys) and
 [`host-capability-manifest`](host-capability-manifest.md) (which decides
 whether dispatch is physically possible on the host).
 
+Always-on orchestration (road-to-always-on-orchestration, Phase 1): the layer
+carries no per-run on/off setting. `subagents.enabled`, `subagents.auto`, and
+`subagents.host_capabilities` were removed from `.agent-settings.yml` — a
+fresh install with an empty settings file activates on any capable host.
+Activation now reads only two facts: whether the emergency incident switch is
+set, and what the host can physically do.
+
 ## Settings
 
 | Key | Default | Purpose |
 |---|---|---|
-| `subagents.enabled` | `true` | Global master switch. `false` = the whole layer is off — the canonical kill-switch. No auto-dispatch, no routing, everything runs in-session. |
-| `subagents.auto` | `on` | Auto-dispatch mode: `off` \| `ask` \| `on`. Shipped default `on` on subagent-capable hosts (flipped from `ask` 2026-07-09, ADR-117), `off` elsewhere. |
 | `subagents.downshift` | `true` | Route delegable sub-tasks to the lowest-capable tier (Phase 2). |
 | `subagents.quota_arbitrage` | `true` | Prefer a separate-quota-pool model where the host manifest allows it (Phase 2 bonus). |
 | `subagents.model_map` | `{}` | Optional per-tier model override for downshift routing. |
-| `subagents.host_capabilities` | `{}` | Optional override of the host-capability manifest. |
+| `emergency.orchestration_halt` | `false` | The ONE audited incident switch — see [`settings-classes.md`](../../../../docs/contracts/settings-classes.md) § "The one exception". NOT an activation gate: on-by-default, ceremony-free to arm, requires a non-empty `orchestration_halt_justification` to disarm. |
 
 ## Activation decision
 
 For any task, auto-dispatch is attempted **only when all hold**:
 
 ```
-subagents.enabled == true
-AND subagents.auto != off
+emergency.orchestration_halt != true
 AND host_manifest.subagent_spawn == true
 AND the task is classified delegable (see auto-dispatch-classification.md)
 ```
 
 If any condition fails → **in-session execution**, no subagent. This is the
-safe path: a missing/false manifest field, a disabled switch, or an
+safe path: an unresolved host capability, an active incident halt, or an
 unclassifiable task all degrade silently to single-agent.
 
-## `auto` mode behaviour
+## Verdict behaviour
 
-| Mode | When task is delegable | When not delegable |
-|---|---|---|
-| `off` | never dispatch (explicit command only) | in-session |
-| `ask` | ask once, then dispatch on yes (per `user-interaction`) | in-session |
-| `on` | dispatch; surface the chosen mode in one line | in-session |
+| Task shape | Verdict |
+|---|---|
+| A matched delegable signal | `dispatch` — surface the chosen mode + per-subtask tiers in one line, never silent |
+| No enumerated signal (ambiguous) | `ask` — a verdict to the user, never a speculative spawn |
+| Below the size floor, halted, or no host primitive | in-session |
 
-Under `ask` and `on`, the chosen `subagent-orchestration` mode and the
-per-subtask tiers are surfaced before/at dispatch — never silent.
+There is no more `off`/`ask`/`on` MODE setting driving this table — the row a
+task lands on is a property of the task and the host, not a configuration
+choice.
 
 ## Resolution order
 
-1. Read `subagents.*` once per run; cache for the run (no re-read mid-loop),
+1. Resolve the emergency halt from settings once per run; cache for the run,
    mirroring [`subagent-configuration § When settings change`](../subagent-configuration.md).
-2. Resolve the host-capability manifest once (cached) per
-   [`host-capability-manifest`](host-capability-manifest.md).
+2. Resolve the host-capability manifest once (cached) via
+   `probeHostCapabilities` — the committed registry row merged with
+   observable environment facts. Per
+   [`host-capability-manifest`](host-capability-manifest.md), a settings
+   override no longer participates in production resolution.
 3. Apply the activation decision above per task.
 
 ## Safety floors are never lifted
@@ -57,8 +64,9 @@ per-subtask tiers are surfaced before/at dispatch — never silent.
 Auto-dispatch never bypasses a floor. The cross-model judge Iron Law
 (`subagent-orchestration`), `verify-before-complete`, the N=3 autonomous
 budget, `scope-control`, and `non-destructive-by-default` all apply to
-auto-delegated work exactly as they do to in-session work. `enabled: false`
-disables the layer; it never disables a floor.
+auto-delegated work exactly as they do to in-session work.
+`emergency.orchestration_halt: true` disables the layer for the duration of an
+incident; it never disables a floor.
 
 ## Related
 

package/dist/agent-src/contexts/execution/host-capability-manifest.md

@@ -1,9 +1,9 @@
 # Host-Capability Manifest
 
-Resolved once per session by the **agent** (not a long-running process) and
-cached for the rest of the session. Tells the orchestration layer which
-subagent primitives the current host actually exposes, so auto-dispatch never
-attempts a primitive the host cannot run.
+Resolved once per session (via `probeHostCapabilities`, not a long-running
+process) and cached for the rest of the session. Tells the orchestration
+layer which subagent primitives the current host actually exposes, so
+auto-dispatch never attempts a primitive the host cannot run.
 
 ## Schema
 
@@ -15,19 +15,30 @@ A single JSON object, `schema_version: 1`:
   "subagent_spawn": false,
   "parallel_spawn": false,
   "status_polling": false,
-  "separate_quota_pool": false
+  "separate_quota_pool": false,
+  "agent_teams": false
 }
 ```
 
 ## Resolution
 
-The agent fills the manifest from two inputs, in order:
+`probeHostCapabilities(hostId)` (`src/scripts/_lib/host_capability.ts`) fills
+the manifest from OBSERVABLE FACTS ONLY — capability is a fact about the
+host, never a configuration decision (always-on orchestration, Phase 1):
 
-1. The agent's own knowledge of the **current host** and its documented
-   subagent primitives.
-2. An **optional** settings override `subagents.host_capabilities` in
-   `.agent-settings.yml`. Any field present there wins for that field; any
-   field omitted falls back to the safe default below.
+1. The committed `HOST_CAPABILITY_REGISTRY` row for the detected host — the
+   agent's own knowledge of documented subagent primitives.
+2. A live environment probe merged on top: `agent_teams` resolves `true`
+   when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set in the process
+   environment — the one host fact this repo can observe about Claude
+   Code's experimental multi-instance Agent Teams feature.
+3. `SAFE_DEFAULT` (all `false`) for an unrecognized host or an unset probe.
+
+`resolveHostCapabilities(hostId, override?)` still accepts an optional
+whole-object override for tests and back-compat callers, but no production
+caller passes a settings-derived override into it any more — the former
+`subagents.host_capabilities` settings key was removed. A leftover key in a
+consumer's `.agent-settings.yml` is ignored.
 
 The manifest is resolved once and cached — the agent does not re-resolve it
 mid-session.
@@ -40,10 +51,9 @@ AN UNKNOWN HOST IS ASSUMED TO HAVE NO SUBAGENT PRIMITIVE.
 A MISSING OR INVALID FIELD IS false, NEVER true.
 ```
 
-This is a hard rule. When the host is unrecognized, or a field is absent /
-malformed in the override, the field resolves to `false`. The orchestration
-layer then degrades to in-session execution rather than attempting an
-unsupported primitive.
+This is a hard rule. When the host is unrecognized, or a probed fact is
+absent, the field resolves to `false`. The orchestration layer then degrades
+to in-session execution rather than attempting an unsupported primitive.
 
 ## Fields
 
@@ -53,6 +63,7 @@ unsupported primitive.
 | `parallel_spawn` | bool | Concurrent dispatch of multiple subagents. `false` → delegation is serial, one subagent at a time. |
 | `status_polling` | bool | Monitoring running subagents (progress / completion checks). `false` → fire-and-collect only, no mid-run polling. |
 | `separate_quota_pool` | bool | Quota-arbitrage bonus (Phase 2) — subagents draw from a distinct quota pool than the session. `false` → assume shared quota. |
+| `agent_teams` | bool | Claude Code's experimental multi-instance Agent Teams primitive (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`). `false` → the [judgment ladder](auto-dispatch-classification.md#judgment-ladder-phase-2--road-to-always-on-orchestration)'s rung 3 (team) degrades to parallel subagents, recorded as `degraded_from: 3`. |
 
 A field being `true` is a **precondition**, not a mandate: `parallel_spawn:
 true` permits concurrency but the dispatch cap still applies (see

package/dist/agent-src/contexts/execution/orchestration-telemetry.md

@@ -150,9 +150,16 @@ conformant audit-log-v1 line from the counts you already have:
   [--first-pass-success true|false] [--escalated true|false]
 ```
 
-A capture **hook** is the wrong tool here: the PostToolUse payload carries no
-subagent token usage — only the orchestrator sees it (via the run result) — and
-a hook would reverse the 2026-06-30 no-hook decision. Reader:
+A capture **hook** is now the primary path where the host has a
+`post_tool_use` slot: the 2026-08-07 transcript backfill measured that
+SYNCHRONOUS dispatch results DO carry `resolvedModel` / `totalTokens` /
+`usage` — the 2026-06-30 "payload carries no usage" premise held only for
+async dispatches, which stay metrics-absent. The `orchestration-record`
+concern (`src/scripts/hooks/orchestration_record_hook.ts`, registered in
+`hook_manifest.yaml`) emits the line deterministically on every Agent/Task
+completion; measured model-carried capture before it existed was 1 of 370
+dispatches (0.27 %). The CLI above stays for hosts without the slot and for
+orchestrator-side records the hook cannot see. Reader:
 `src/scripts/orchestration_savings_report.ts`.
 
 **`token_delta` sourcing priority:**
@@ -209,6 +216,24 @@ condition outright. No consumer of `payload_hash` or `cache_hit` may wire a
 measure→adjust step off them — no default flip, no tier change, no dispatch
 throttle. They are read-only diagnostic fields.
 
+## Registered always-on metrics and kill criteria (pre-registered 2026-08-09)
+
+The always-on orchestration doctrine fixes "the stack is always available"
+and moves falsifiability into its TRIGGERS. Registered before any behaviour
+data existed, so later readings cannot be fitted to a desired outcome:
+
+| Metric | Source | Kill/tighten criterion (per layer, applied by evidence-bearing PR, never a settings flag) |
+|---|---|---|
+| Dispatch rate per delegable verdict | `orchestration_record` vs nudge/ladder verdict lines | A layer whose verdicts are measurably ignored gets its trigger set tightened or the injected line removed |
+| Judgment-ladder precision (verdict vs what the session did) | ladder verdict telemetry joined with dispatch/team records | A rung below registered precision at review gets its signal set tightened; a rung nobody hits gets removed |
+| Council fire rate + unactioned-verdict rate | pass artifacts + handoff adoption | Unactioned-verdict rate is the kill criterion for any auto-fire trigger |
+| Per-session quota burn per provider | transport/attendance records | Sustained quota exhaustion tightens `cli_call_budget` defaults, never re-introduces an activation gate |
+| Metered-fallback spend | billing-classified transport records | Target trends to ~0 on CLI hosts; a rising trend is a transport-resolution defect to fix, not a reason to disable |
+
+Review discipline: each criterion is evaluated against an accumulation
+window (the gated blockers name their own windows); a reading below the bar
+removes or tightens THE TRIGGER, and the removal PR cites the numbers.
+
 ## Related
 
 - [`audit-log-v1`](../../../../docs/contracts/audit-log-v1.md) — the frozen

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

@@ -41,6 +41,60 @@ refs-not-bodies floor as `evidence_refs`. Validator:
 `worker_budget.validateWorkerPartialResult` — the orchestrator never adopts an
 invalid partial return.
 
+## Stated assumptions — `assumptions[]`
+
+Both the result body above and the CHECKPOINT capsule below may carry:
+
+```json
+{ "statement": "<one line>", "basis": "<ref token>", "epistemic_state": "verified | assumed | gap" }
+```
+
+The vocabulary is the **Evidence-Report buckets** from
+[`evidence-discipline`](evidence-discipline.md#evidence-report--the-discovery-output)
+— pinned once, in `subagent_capsule.EPISTEMIC_STATES`, and deliberately not a
+private scale: a capsule that graded its premises differently from the rest of
+the suite would fork the vocabulary every other surface reasons in.
+
+Absent `assumptions[]` means **not recorded** — never "no assumptions were
+made". Unstated premises are the first thing compression drops, which is
+exactly why the field exists on the handoff surface.
+
+## CHECKPOINT capsule — the generation handoff
+
+`CHECKPOINT` is the fifth envelope status. A worker that reaches its budget
+**watermark** (below the stop-loss line, so it still has the headroom to
+summarise itself) returns a capsule instead of running on to be killed:
+
+```json
+{
+  "status": "CHECKPOINT",
+  "summary": "<one or two sentences>",
+  "generation": 1,
+  "done": ["file:line | id | path"],
+  "remaining": ["<one short line each>"],
+  "decisions": ["<choices the successor must not silently re-open>"],
+  "open_risks": ["<still open at handoff>"],
+  "touched_files": ["path | file:line"],
+  "assumptions": [{ "statement": "", "basis": "", "epistemic_state": "verified" }]
+}
+```
+
+**Transcript-exclusion by construction.** Every field is a ref token, a single
+short line, or a count; array entries are capped so a transcript cannot be
+reached by accumulation either. There is no field a raw transcript fits in —
+and that is load-bearing, not stylistic: the claim under test is whether a
+successor can work from the *capsule*, which is unmeasurable the moment raw
+context can ride along. Validator:
+[`subagent_capsule.validateCapsule`](../../../../src/scripts/_lib/subagent_capsule.ts);
+the orchestrator never briefs a successor from an invalid capsule.
+
+**Status today: additive and off.** Nothing reads a capsule. Emission is
+shadow-only (the worker still runs to stop-loss exactly as before) and the
+synthesis duties below have no `CHECKPOINT` branch, so the measurement is not
+confounded by the mechanism it is measuring. The recycling loop that consumes a
+capsule is gated behind `blocker: host-worker-respawn` and
+`blocker: capsule-quality-near-budget`.
+
 ## Orchestrator synthesis duties
 
 ```

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

@@ -36,24 +36,26 @@ THE SAME MINUS THE QUOTA WIN.
    the tier/model choice is unchanged. This is the only place the
    "Sonnet-has-its-own-allowance" idea lives, and it lives as a runtime-detected
    flag, never as portable prose.
-4. **Budget routing** (`subagents.budget_routing != off`,
+4. **Budget routing** (design:
    [`budget-routing` contract](../../../../docs/contracts/budget-routing.md)) →
-   AFTER the tier resolves per 1–3, apply the budget relation via
-   `pickTier` (`src/scripts/_lib/tier_budget_routing.ts`): cheapest
+   AFTER the tier resolves per 1–3, the budget relation via `pickTier`
+   (`src/scripts/_lib/tier_budget_routing.ts`) would apply: cheapest
    classifier-adequate tier WITH available budget; that tier exhausted or
    cooling → next tier up with budget; all unavailable → session model +
    surfaced one-line notice. Work is never blocked to save money. Before
    the dispatch is created, acquire the atomic reserve
    (`acquireBudgetPermit`; check state via `node src/scripts/cost/budget.mjs
    tier <t>`); a 429/quota error trips `tripCooldown` for that tier and
-   falls back per the relation — never a retry loop. Under
-   `budget_routing: ask`, the FIRST budget-motivated downshift of a session
-   is confirmed once, in the shape
-   [`settings-ask-protocol`](../../rules/settings-ask-protocol.md) fixes and
-   without persisting the answer (`subagents.budget_routing` is class C);
-   `auto` proceeds silently. Every budget-routed
-   dispatch emits one `orchestration_record` line (tier + provenance-tagged
-   token delta) so realized savings are measured, not asserted.
+   falls back per the relation — never a retry loop.
+   `subagents.budget_routing` was removed as a settings key (always-on
+   orchestration, road-to-always-on-orchestration Phase 1: no per-layer
+   on/off switch survives) — `pickTier` has NO production caller today, so
+   this point documents the DESIGNED relation, not a currently wired one;
+   wiring it is a later phase of that roadmap (council-side
+   `cli_call_budget`/`cost_budget` are the caps that replace the settings
+   gate). Every budget-routed dispatch, once wired, would emit one
+   `orchestration_record` line (tier + provenance-tagged token delta) so
+   realized savings are measured, not asserted.
 
 **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

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

@@ -64,6 +64,31 @@ 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.
 
+### Capsule watermark — the line below the kill line
+
+The budget now carries **two** lines. `capsule_watermark` sits at
+`CAPSULE_WATERMARK_FRACTION` (0.8) of `max_tokens_per_worker` and is **derived**
+from it in `composeSpawnBrief`, never set independently — a watermark that could
+drift away from the budget it sits under is a watermark nobody can reason about.
+Reaching it means: emit a `CHECKPOINT` capsule
+([response contract](subagent-response-contract.md#checkpoint-capsule--the-generation-handoff))
+**while there is still headroom to write one**. A worker at 100 % of its budget
+cannot summarise itself; that headroom is the entire mechanism.
+
+`evaluateWorkerBudget` reports the band between the two lines as
+`watermark_hit` — the only window in which a capsule can be written at all.
+
+**Shadow only, today.** The worker still runs on to the stop-loss and still
+returns the `BLOCKED` partial result exactly as before; the capsule is recorded,
+never acted on. Behaviour is unchanged on purpose, so the Phase-1 measurement is
+not confounded by the mechanism it is measuring. A second candidate trigger —
+novelty-per-step saturation
+([`capsule_trigger.ts`](../../../../src/scripts/_lib/capsule_trigger.ts),
+term-frequency, no embeddings) — is logged alongside it, and the paired
+comparison is pre-registered as `worker-capsule-trigger-arm` in
+[`docs/CLAIMS.md`](../../../../docs/CLAIMS.md) with both arms losing as an
+explicitly publishable outcome.
+
 ## Bundle resolver — bind to the existing surfaces
 
 The brief is **resolved**, not hand-built. `resolveBundle(slice)` maps a task

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

@@ -144,11 +144,14 @@ dashboards alone look fine while quality regresses.
 ## Kill-switch
 
 ```
-subagents.enabled: false   (or  subagents.auto: off)
+emergency.orchestration_halt: true
 ```
 
-A single, no-deploy settings flip fully disables the layer (`isLayerDisabled()`).
-This is the canonical disable — no code change, effective on the next run.
+A single, no-deploy settings flip fully disables the layer (`isLayerDisabled()`)
+for the duration of an incident — the one audited switch that survives
+always-on orchestration (road-to-always-on-orchestration Phase 1;
+`docs/contracts/settings-classes.md` § "The one exception"). Disarming it
+requires a non-empty `emergency.orchestration_halt_justification`.
 
 ## Reference implementation
 

package/dist/agent-src/rules/artifact-engagement-recording.md

@@ -23,7 +23,10 @@ obligation_frequency: "per-task"
 
 **Iron Law.** After a `/implement-ticket` or `/work` phase-step, emit one
 `telemetry:record` call with consulted + applied ids when telemetry is
-enabled. Default-off; opt-in via `.agent-settings.yml`. Zero overhead when
+enabled. Default-off; opt-in via `.agent-settings.yml` — which is the **project
+layer of a cascade that starts user-global**, so never read a value or its
+absence from that file alone; `agent-config settings:get <key>` reports the
+value and the file it actually came from. Zero overhead when
 disabled. Recording contract + privacy floor:
 [`contexts/contracts/artifact-engagement-flow.md`](../contexts/contracts/artifact-engagement-flow.md).
 

package/dist/agent-src/rules/autonomous-execution.md

@@ -67,7 +67,7 @@ ALLOWLIST > 20 ENTRIES IN ONE SESSION = THE LINTER IS WRONG.
 STOP. PROPOSE LINTER REDESIGN OR REMOVAL. DO NOT EXPAND THE ALLOWLIST FURTHER.
 ```
 
-Crossing 20 entries counts as the 3rd validation-target failure — fix the tool shape, not the list. Enforced at tool-call time by the `block-config-weakening` PreToolUse guard (`src/scripts/hooks/block_config_weakening.ts`): it counts allowlist entries added per session, warns from 5, and blocks past 20. Baselines and budget thresholds warn only — a rising count there may be a legitimate ratchet reset, which the edit alone cannot distinguish. Verify with the narrowest tool that proves the target green (a single `curl` / Playwright spec for HTTP/UI, the test runner with a `--filter`, an `xdebug` step-through) — never a meta-pipeline as per-iteration probe. Failed-attempt detail, suppression-sweep equivalents, probe-efficiency detail, and adaptive effort & stop (RDP): [`autonomy-mechanics § Validation-loop budget`](../contexts/execution/autonomy-mechanics.md).
+Crossing 20 entries counts as the 3rd validation-target failure — fix the tool shape, not the list. Enforced at tool-call time by the `block-config-weakening` PreToolUse guard (`src/scripts/hooks/block_config_weakening.ts`) **on the three hosts that have a `pre_tool_use` slot at all** — augment, claude, cowork: it counts allowlist entries added per session, warns from 5, and blocks past 20. On cursor, cline, windsurf, gemini and copilot the guard has nowhere to bind, so there the cap is model-carried and "enforced at tool-call time" is not a claim this rule can make. Run `agent-config hooks:status` to see which slots are bound on the host you are actually on — the sibling rules `git-history-discipline` and `evaluator-independence` qualify the identical slot, and an unqualified claim here would read as a guarantee the manifest does not give. Baselines and budget thresholds warn only — a rising count there may be a legitimate ratchet reset, which the edit alone cannot distinguish. Verify with the narrowest tool that proves the target green (a single `curl` / Playwright spec for HTTP/UI, the test runner with a `--filter`, an `xdebug` step-through) — never a meta-pipeline as per-iteration probe. Failed-attempt detail, suppression-sweep equivalents, probe-efficiency detail, and adaptive effort & stop (RDP): [`autonomy-mechanics § Validation-loop budget`](../contexts/execution/autonomy-mechanics.md).
 
 Body migrated to `contexts/execution/autonomy-mechanics.md` (per P4 of `road-to-kernel-and-router.md`) — opt-in detection summary, task-scope shapes table, N=3 mechanics, allowlist-antipattern detail, probe efficiency, adaptive effort (RDP).
 Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).