@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/installed-tools-lockfile.md

@@ -1,144 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Installed-Tools Lockfile — Wire Contract
-
-Canonical wire-format spec for `agents/installed-tools.lock` — the
-project-committed bill of materials for AI tooling installed into this
-repository.
-
-- **Authoritative module:** [`scripts/_lib/installed_tools.py`](../../src/scripts/_lib/installed_tools.py)
-- **ADR:** [`docs/decisions/ADR-008-installed-tools-manifest.md`](../decisions/ADR-008-installed-tools-manifest.md)
-- **Workflow guide:** [`docs/guidelines/agent-infra/installed-tools-manifest.md`](../guidelines/agent-infra/installed-tools-manifest.md)
-- **Active roadmap:** P1.1 of the `road-to-multi-package-coexistence`
-  roadmap (see `agents/roadmaps/` for current status).
-
-## Versions
-
-| Version | Status | Writer | Reader |
-|---|---|---|---|
-| **1** | legacy | not emitted by current code | tolerated by `read_manifest` |
-| **2** | current | `write_manifest` always emits this | tolerated by `read_manifest` |
-
-`SCHEMA_VERSION = 2` · `SCHEMA_VERSIONS_SUPPORTED = (1, 2)`. The reader
-must accept any version in `SCHEMA_VERSIONS_SUPPORTED`; the writer must
-always emit the highest. Bumps are breaking on the writer side and
-require a migration plan.
-
-## Schema v2 — wire format
-
-```yaml
-schema_version: 2
-agent_config_version: "2.2.0"
-deploy_roots:                          # optional, top-level (P1.1)
-  - .augment/rules
-  - .cursor/rules
-tools:
-  - name: claude-code                  # one of _VALID_TOOLS
-    scope: global                      # global | project
-    bridge_marker: ~/.claude/PROJECT_MANAGED_BY_AGENT_CONFIG
-    installed_at: "2026-05-12"
-    status: installed                  # optional: installed | uninstalling (P2.2)
-    files:                             # optional, per-tool (P1.1)
-      - path: .augment/rules/r1.md
-        kind: deployed                 # one of FILE_KINDS
-        sha256: "<64 hex chars>"
-      - path: .cursorrules
-        kind: bridge
-        sha256: null                   # null permitted for non-content markers
-    merged_keys:                       # optional, per-tool (P1.1)
-      - file: .mcp.json
-        json_pointer: "/mcpServers/agent-config"
-```
-
-### Top-level fields
-
-| Field | Type | Owner | Notes |
-|---|---|---|---|
-| `schema_version` | int | machine | always `2` on write |
-| `agent_config_version` | str | machine | last writer's package version |
-| `deploy_roots` | list[str] | machine | optional; directories the doctor command surveys for foreign files. Omitted when empty. Falls back to `DEFAULT_DEPLOY_ROOTS` when consumers need a survey scope and no explicit list is present. |
-| `tools` | list[obj] | machine | install-order preserved, not alphabetised |
-
-### Per-tool fields
-
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| `name` | str | yes | one of `_VALID_TOOLS` in `scripts/install.py` |
-| `scope` | str | yes | `global` (user-home) or `project` (workspace bridge) |
-| `bridge_marker` | str | yes | absolute / `~`-prefixed for global; repo-relative for project |
-| `installed_at` | str | yes | ISO date; informational only |
-| `status` | str | no | `installed` (default when absent) or `uninstalling`; two-phase uninstall (P2.2). A crashed uninstall leaves the entry in `uninstalling` — `agent-config prune --resume-uninstall` sweeps only those entries' `files[]` without touching healthy tools or unmanaged drift. |
-| `files` | list[obj] | no | content the installer deployed for this tool |
-| `merged_keys` | list[obj] | no | named keys this tool inserted into shared JSON files |
-
-### `files[]` entries
-
-| Field | Type | Notes |
-|---|---|---|
-| `path` | str | repo-relative for project-scope, `~`-prefixed for global |
-| `kind` | str | one of `FILE_KINDS = {bridge, deployed, marker}` |
-| `sha256` | str / null | 64 hex chars of the file's SHA-256 at install time, or `null` for markers / pointers without content |
-
-`kind` semantics:
-
-- **`bridge`** — team-pointer marker like `.cursorrules` or `.windsurf/PROJECT_MANAGED_BY_AGENT_CONFIG`. Existence-tracked, content-untracked.
-- **`deployed`** — bundle content the installer wrote (e.g. `.augment/rules/*.md`). Content-tracked via `sha256` so drift is detectable.
-- **`marker`** — one-off sentinel (e.g. `claude-desktop` install marker). Existence-only.
-
-### `merged_keys[]` entries
-
-| Field | Type | Notes |
-|---|---|---|
-| `file` | str | repo-relative path to the shared file (e.g. `.mcp.json`) |
-| `json_pointer` | str | RFC 6901 pointer. **Constraint:** must target an object key, never an array index. Array-index pointers shift on neighbour-tool uninstall and corrupt other packages' ownership. |
-
-The pointer constraint is enforced at write time in P1.5; readers in v2.x
-must reject manifests that contain array-index pointers.
-
-## Compatibility — reader tolerance
-
-- `read_manifest` accepts both v1 and v2 wire formats.
-- When `pyyaml` is available, v2 round-trips fully.
-- When `pyyaml` is missing, the manual fallback parser extracts v1-equivalent fields (top-level scalars + per-tool scalar fields) and **silently drops** v2 nested fields (`files`, `merged_keys`, `deploy_roots`). Callers that need full v2 fidelity must ensure `pyyaml` is on the path.
-
-## Compatibility — writer behaviour
-
-- `write_manifest(path, version, tools, *, deploy_roots=None)` always emits `schema_version: 2`.
-- Optional v2 fields (`deploy_roots`, per-tool `files` / `merged_keys` / `status`) are emitted only when non-empty, so a v1-shaped call produces a v2 file that is structurally minimal and v1-readable for the core fields.
-- All writes are crash-safe via [`scripts/_lib/fs_atomic.py`](../../src/scripts/_lib/fs_atomic.py) (`write_atomic`: tmp + fsync + rename + parent-dir fsync). See P1.0 of the multi-package roadmap.
-
-## Determinism
-
-Required by P1.3 (not yet enforced in v2.0 of the writer):
-
-1. `tools[]` order = install order (no re-sort).
-2. `files[]` order within a tool = sorted by `path` ascending.
-3. `merged_keys[]` order within a tool = sorted by `(file, json_pointer)` ascending.
-4. `deploy_roots[]` order = as supplied by the writer (caller-controlled).
-
-Determinism is what lets the doctor command produce stable diffs across team members.
-
-## Inline package tag (P5 — non-authoritative)
-
-Deployed Markdown files may carry a frontmatter tag that records provenance for human readers:
-
-```yaml
----
-title: My rule
-package: event4u/agent-config
-source_path: config/rules/general.md
----
-```
-
-Properties:
-
-- **Optional.** Files without a leading `---` frontmatter block are deployed as-is; no synthetic frontmatter is added (P5.1).
-- **Human-readable only.** The lockfile remains the single source of truth for ownership, prune, and uninstall decisions. Removing or hand-editing the inline tag does **not** alter prune / uninstall semantics (P5.3).
-- **Surfaced by doctor.** A frontmatter-bearing file whose `package:` value disagrees with this writer's identifier — or whose `package:` key has been removed — appears under the `tag-drift` category of `agent-config doctor` (P5.2). Tag-drift exit code = 1, same as other drift; fix hint points at `--force` re-install.
-- **Idempotent.** Re-installation rewrites the same `package:` / `source_path:` values; running install twice produces byte-identical Markdown.
-- **`source_path:` (not `source:`).** The injected provenance-path key is named `source_path:` to avoid collision with the established `source: package` origin-type marker used by 200+ rule files in this and downstream packages. The injector treats `source:` as a foreign key and never rewrites it.
-
-Neighbour packages writing into the same project SHOULD use their own `package:` identifier so doctor can distinguish authored ownership at a glance, but they MUST still register their files in the manifest — the inline tag is a UX affordance, not a substitute for the lockfile entry.

package/docs/contracts/installer-agent-mode.md

@@ -1,137 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-19
----
-
-# Installer agent-mode protocol — JSON-over-stdio contract
-
-> Companion to [ADR-016](../decisions/ADR-016-installer-architecture.md)
-> § 4 and § 6. The ADR is the decision; this file is the worked-example
-> reference that agents (Claude, Cursor, GPT, …) and the installer
-> CLI share at runtime.
-
-## Source of truth
-
-The agent-mode state machine lives in
-[`packages/core/installer/src/agent-mode/machine.ts`](../../packages/core/installer/src/agent-mode/machine.ts).
-Envelope construction and `--answer` parsing live in
-[`protocol.ts`](../../packages/core/installer/src/agent-mode/protocol.ts).
-Both are unit-tested under
-[`packages/core/installer/tests/agent-mode-*.test.ts`](../../packages/core/installer/tests/).
-
-## Design constraints
-
-- **Stateless across invocations** — the installer keeps no
-  server-side session. Every turn carries the full conversation as
-  repeated `--answer key=value` flags. An agent may re-issue from
-  scratch at any time.
-- **Strict question-id sequencing** — answers must arrive in the
-  order the installer asks them (`q1.workspaces`, then `q2.packs`,
-  then optional `q3.confirm`). Out-of-order or unknown ids return
-  an `error` envelope, exit code 2.
-- **Single-line JSON per turn** — stdout emits exactly one
-  newline-terminated JSON object per invocation; stderr is reserved
-  for diagnostics and is not part of the contract.
-- **`protocol_version: 1`** — every envelope carries it; agents
-  refusing the version negotiate by aborting.
-
-## Envelope shapes
-
-### `question`
-
-The installer is waiting for the next answer.
-
-```json
-{
-  "status": "question",
-  "protocol_version": 1,
-  "id": "q1.workspaces",
-  "prompt": "Which workspaces does this project need? (multi, comma-separated)",
-  "choices": [
-    { "value": "engineering", "label": "Engineering" },
-    { "value": "product", "label": "Product" }
-  ],
-  "multi": true,
-  "next_call": "init --agent --answer q1.workspaces=<value>"
-}
-```
-
-- `id` — the canonical question identifier; the agent echoes it as
-  `--answer <id>=<value>`.
-- `multi: true` — comma-separated values allowed; `multi: false` —
-  exactly one value.
-- `next_call` — the literal command the agent should issue next,
-  with `<value>` (and prior answers) substituted in.
-
-### `done`
-
-Terminal success; no further calls needed.
-
-```json
-{
-  "status": "done",
-  "protocol_version": 1,
-  "summary": { "files_written": 83, "lockfile_sha256": "c45b3035…" }
-}
-```
-
-### `error`
-
-Terminal failure; exit code 2.
-
-```json
-{
-  "status": "error",
-  "protocol_version": 1,
-  "reason": "out_of_order",
-  "expected_question_id": "q1.workspaces",
-  "received": "q2.packs"
-}
-```
-
-Defined `reason` values: `answer_malformed`, `out_of_order`,
-`unknown_workspace`, `unknown_pack`, `aborted_by_agent`.
-
-## Turn-by-turn worked example
-
-```bash
-# Turn 1 — discover workspaces
-$ installer init --agent
-{"status":"question","id":"q1.workspaces", … "next_call":"… --answer q1.workspaces=<value>"}
-
-# Turn 2 — answer workspaces, discover packs
-$ installer init --agent --answer q1.workspaces=engineering
-{"status":"question","id":"q2.packs", … "next_call":"… --answer q1.workspaces=engineering --answer q2.packs=<value>"}
-
-# Turn 3 — answer packs, install completes
-$ installer init --agent --answer q1.workspaces=engineering --answer q2.packs=engineering-base
-{"status":"done","summary":{"files_written":83,"lockfile_sha256":"c45b3035…"}}
-```
-
-When the pack selection pulls in extras via `requires_hint`, the
-installer inserts a `q3.confirm` turn before completing:
-
-```bash
-$ installer init --agent --answer q1.workspaces=engineering --answer q2.packs=symfony
-{"status":"question","id":"q3.confirm", "prompt":"Auto-added packs: php. Continue?", "choices":[{"value":"yes","label":"yes"},{"value":"no","label":"no"}], "multi":false, … }
-```
-
-`q3.confirm=no` returns `reason: "aborted_by_agent"`.
-
-## Flags relevant to agent mode
-
-- `--manifest <path>` — override the manifest location (defaults to
-  walking up for `dist/discovery/discovery-manifest.json`).
-- `--project-root <path>` — destination project root.
-- `--dry-run` — resolve and emit the `done` envelope without
-  touching disk; used by agents that want a plan preview.
-
-## Failure modes guarded against
-
-- **Agent loops** — `protocol_version` mismatch on any side aborts
-  immediately; no implicit version negotiation.
-- **State drift between turns** — the installer never reads
-  workdir state to recover answers; every fact must be carried in
-  `--answer` flags.
-- **Silent partial install** — on any error after `q2.packs`,
-  exit code 2 with no disk writes (atomic via `StagingSession`).

package/docs/contracts/iron-law-overrides.txt

@@ -1,26 +0,0 @@
-# Iron-Law-override allowlist for the kernel-budget check.
-#
-# Source contract: docs/contracts/kernel-membership.md § 5.1
-# Enforced by:     scripts/measure_rule_budget.py --kernel-budget-check
-#
-# A rule listed here is allowed to exceed the per-rule hard cap
-# (PER_RULE_HARD = 2 500 chars) up to the override ceiling
-# (PER_RULE_OVERRIDE_CEILING = 4 000 chars). Adding an entry requires a
-# numbered ADR in docs/decisions/ that justifies the Iron-Law density
-# (e.g. multiple Iron-Law fences, exhaustive enumeration that cannot be
-# safely externalised, pre-send/pre-act gate that loses meaning if split).
-#
-# Format: one rule-id per line. Comments start with '#'. Blank lines OK.
-
-# ADR-002 (2026-05-06) — kernel-bucket cap raise + per-rule overrides.
-# Source: docs/decisions/ADR-002-kernel-bucket-overrides.md
-# Empirical r_actual=0.795 vs r_projected=0.712. The 6 rules below carry
-# Iron-Law fences + non-externalisable enumerations; further condensation
-# would force semantic loss. All sit ≤ 4 000-char override ceiling.
-ask-when-uncertain
-commit-policy
-direct-answers
-language-and-tone
-no-cheap-questions
-non-destructive-by-default
-scope-control

package/docs/contracts/kernel-membership.md

@@ -1,339 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-
-# Kernel Membership — Phase 1.3 of road-to-kernel-and-router
-
-> **Status:** active · **Stability:** beta · **Owner:** road-to-kernel-and-router P1.3
-> · **Source of truth:** `docs/contracts/rule-classification.md` § 3.1
-> · **Pilot artifacts:** `docs/contracts/pilot/`
-
-Locks the kernel set and the empirical condensation rate `r` derived
-from the P1.3 pilot. Phase 2.2 executes against this contract.
-
-## § 1 — Inclusion criteria (kernel-only)
-
-A rule belongs in the kernel iff it satisfies **all** of:
-
-1. **Iron-Law floor.** Carries an Iron Law fence (```...```) that
-   governs every reply or every action — no skill, no command, no
-   guideline can override it.
-2. **Mode-independent.** Fires under `off`, `auto`, `on`, every
-   role mode, every cost profile.
-3. **Pre-send OR pre-act gate.** Either (3a) scans the reply draft
-   before transmission (prose, tone, language, claim verification),
-   or (3b) fires before tool execution / commit / workflow progression
-   (safety, permission, scope). Post-hoc remediation does not
-   qualify.
-4. **Cross-cutting.** Applies across at least two of the categories
-   (behaviour, safety, tone, ask-policy) and cannot be scoped to a
-   sub-domain (a stack, a workflow, a single artifact type).
-5. **Ask-policy floor.** *(included by criterion #1+#4 union, but
-   surfaced explicitly: rules governing when/how the agent may ask
-   the user a question — wrong ask-behaviour breaks the agent's core
-   contract with the user, so `ask-when-uncertain` and
-   `no-cheap-questions` are first-class kernel members even though
-   they fire during deliberation, not strictly pre-send.)*
-
-All other rules → `condense-and-keep` (auto-tier) or migrate to
-skill / guideline per `rule-classification.md`.
-
-> **Council amendment (P1.4).** Criterion #3 originally read "must be
-> checked before the agent emits the next token". Sonnet 4.5 noted
-> this conflated pre-send (scanning the draft) with pre-act (gating
-> tool execution); split per #3a / #3b above. Criterion #5 surfaced
-> the ask-policy floor that the original four-gate test left as an
-> implicit consequence of #1+#4. Both amendments preserve the
-> existing 9-rule kernel set. See
-> `agents/runtime/council/sessions/20260506T044941Z-phase1-cross-check-r2.json`. <!-- council-ref-allowed: contract decision trace -->
-
-## § 2 — Empirical condensation rate (pilot)
-
-Pilot picks (per P1.3 algorithm: shortest / median / longest of the 9
-always-rules in `rule-classification.md` § 3.1):
-
-| pilot | original | condensed | r | per-rule cap (2.5k) | Iron-Law SHA |
-|---|---:|---:|---:|---|---|
-| agent-authority   | 1217 | 1020 | 0.838 | OK        | match (`e3b0c442…`) |
-| direct-answers    | 3991 | 2841 | 0.712 | +341 over | match (`ef438530…`) |
-| language-and-tone | 5318 | 3602 | 0.677 | +1102 over | match (`c017b26f…`) |
-
-| statistic | value |
-|---|---:|
-| mean r (outlier-skewed by lean pilot) | 0.742 |
-| **median r** (locked for projection) | **0.712** |
-| max r (already-lean floor) | 0.838 |
-| min r (most condensable) | 0.677 |
-
-Locked `r = 0.712` (median) for P2.2 projection. Council amendment
-(P1.4) — the original lock was the **mean** (0.742), but Sonnet 4.5
-flagged outlier skew: `agent-authority` at 1217 chars pre-pilot was
-already near the condensation floor (`r = 0.838`), pulling the mean
-above the typical band. Median (0.712) is robust to the lean
-outlier and sits inside the roadmap-stated 0.6–0.75 band. Risk
-asymmetry confirms the choice: under-estimating condensed size
-blows the 25k cap mid-P2.2 (no abort path); over-estimating just
-yields headroom. GPT-4o concurred. Source:
-`agents/runtime/council/sessions/20260506T044941Z-phase1-cross-check-r2.json`. <!-- council-ref-allowed: contract decision trace -->
-
-**Pilot caveat — already-lean floor.** `agent-authority` (1217 chars
-pre-pilot) yielded only `r = 0.838`. Pre-condensed rules give less
-back; rules > 3k chars give more back. Future kernel additions
-≤ 1.5k chars should not assume the median — they may already be at
-floor.
-
-**Iron-Law preservation verified.** All three pilot SHAs match the
-originals (whitespace-normalised, case-folded, fence content only).
-
-## § 3 — Projection & demotion log
-
-Algorithm (per roadmap P1.3): `projected = current × r`; if sum > 25k,
-demote largest projected, re-sum; abort after 3 rounds.
-
-| round | candidates | sum-of-current | sum-of-projected (× 0.712) | budget |
-|---:|:--|---:|---:|---|
-| 0 | all 9 always-rules | 32403 | **23071** | ≤ 25 000 ✓ |
-
-**Result: 0 demotions fired.** All 9 always-rules stay in the kernel
-under median projection. Headroom = 1929 chars (= ~one median rule)
-absorbs pilot variance for the 6 untested rules.
-
-**2026-07-06 demotion (council: claude-sonnet-4-5 + gpt-4o, 2-round
-debate).** `user-interrupt-priority` had been added as an 11th-hour
-`type: always` rule without a membership amendment, pushing the live
-always set to 10 and the Augment workspace-guidelines budget past its
-empirical cap. Demoted back to `type: auto` (trigger-loaded); its
-one-line interrupt essence lives in `agent-authority § Rules` so the
-always-loaded surface keeps the STOP → run → ASK contract visible.
-The locked kernel remains the 9 rules below. In the same pass the 9
-rules' post-P2.2 prose growth was telegraph-trimmed back under the
-26k bucket (Iron-Law fences byte-stable; load-bearing additions —
-direct-answers' live-state clause, verify-before-complete's mechanics
-pointer — retained per council verdict).
-
-## § 4 — Locked kernel set
-
-| id | current | projected (× 0.712) | inclusion criterion |
-|---|---:|---:|---|
-| agent-authority           | 1217 |  867 | (4) cross-cutting router-of-routers † |
-| ask-when-uncertain        | 4096 | 2916 | (1)(5) Iron Law + ask-policy floor |
-| commit-policy             | 2972 | 2116 | (1)(2) safety-floor Iron Law |
-| direct-answers            | 3991 | 2842 | (1)(3a) three Iron Laws, pre-send gate |
-| language-and-tone         | 5318 | 3786 | (1)(3a) language-mirror, pre-send gate |
-| no-cheap-questions        | 3875 | 2759 | (1)(2)(5) ask-policy floor |
-| non-destructive-by-default| 4222 | 3006 | (1)(2)(3b) safety-floor Hard Floor |
-| scope-control             | 4368 | 3110 | (1)(3b) safety-floor permission gate |
-| verify-before-complete    | 2344 | 1669 | (1) completion-claim gate (post-act, pre-claim) ‡ |
-| **total**                 | **32403** | **23071** | **≤ 25 000** ✓ |
-
-### § 4.1 — Post-P2.2 locked kernel (empirical, 2026-05-06)
-
-P2.2 applied condensation (imperative rewrite, examples → guidelines,
-rationale → contexts) + verified Iron-Law fence preservation.
-Empirical r=0.795 (vs 0.712 projected). Bucket cap raised 25k → 26k
-via `docs/decisions/ADR-002-kernel-bucket-overrides.md`. Six rules
-sit in the override band (≤ 4k ceiling).
-
-| id | post-P2.2 chars | r_actual | Iron-Law SHA-256 (normalised) | per-rule status |
-|---|---:|---:|---|---|
-| agent-authority           | 1020 | 0.838 | `e3b0c44298fc1c14…` (no fence) | OK ≤ 2.5k |
-| ask-when-uncertain        | 3130 | 0.764 | `6376ee72bbfd1eba…` | override (ADR-002) |
-| commit-policy             | 2354 | 0.792 | `e55af7f8a8053…` | OK ≤ 2.5k |
-| direct-answers            | 2841 | 0.712 | `ef4385308f52a8e4…` | override (ADR-002) |
-| language-and-tone         | 3602 | 0.677 | `c017b26f80c7aa01…` | override (ADR-002) |
-| no-cheap-questions        | 3238 | 0.836 | `86e023bee76a0a49…` | override (ADR-002) |
-| non-destructive-by-default| 3420 | 0.810 | `17e6ed8b418d9c49…` | override (ADR-002) |
-| scope-control             | 3641 | 0.834 | `03afe036755c8046…` | override (ADR-002) |
-| verify-before-complete    | 2344 | 1.000 | `abc942cf369ed60e…` | warn (> 2k target, ≤ 2.5k cap) |
-| **total**                 | **25590** | **0.795** | — | **≤ 26 000** ✓ |
-
-Acceptance gates (P2.2 § Equivalence):
-- ✅ `measure_rule_budget.py --kernel-budget-check` exits 0
-- ✅ `iron_law_sha.py --all-kernel` confirms byte-identical fence content for all 8 fence-bearing rules
-- ✅ `pytest tests/golden/` 29/29 green
-
-Future edits to any kernel rule must keep the Iron-Law SHA stable
-(or land a deliberate ADR-tracked SHA update). Cap re-raise requires
-a new ADR.
-
-### § 4.2 — Post-P2.2 kernel addition (`user-interrupt-priority`)
-
-After the P2.2 lock, `user-interrupt-priority` was admitted as the
-10th kernel rule. It satisfies criterion (1) (Iron Law: stop → ask
-→ resume on user-interrupt signals) and criterion (3a) (pre-send
-gate — must fire before continuing the current task). The smoke
-baseline is bumped accordingly:
-
-- `scripts/smoke/kernel.sh` — `EXPECTED_KERNEL_COUNT=10`,
-  `EXPECTED_FENCE_CARRIERS=9`.
-- `docs/contracts/smoke-contracts.md` § 3.1 — `10 kernel rules · 9
-  carry Iron-Law fences · 1 dispatch index · ≤ 2 budget breaches`.
-
-The § 4 / § 4.1 tables remain the locked P2.2 baseline (9-rule
-snapshot, 2026-05-06); the 10th rule is tracked separately here
-until the next kernel re-measurement.
-
-† **agent-authority swap candidate (P1.4 ADR).** Sonnet 4.5 argues
-this is a routing index (zero Iron Law fences, dispatches to other
-kernel rules) and should be `condense-and-keep` (auto-tier-3),
-freeing 867 projected chars. The Council also recommends promoting
-`autonomous-execution` (5631 → 4009 projected) into kernel as a
-mode-independent Band-4 authority. Net effect: 23071 − 867 + 4009 =
-26213, **over the 25k cap by 1213 chars**. **Resolved by
-`docs/decisions/ADR-001-kernel-swap-deferred.md` (variant a):**
-status quo through P2.2 + P3.1, swap re-evaluated as a P3.2 ADR
-once the router schema and compiler ship.
-
-‡ **verify-before-complete borderline.** Council split criterion #3
-into pre-send (#3a) / pre-act (#3b); this rule fires post-act,
-pre-claim. Treated as Iron Law under criterion #1 alone (no #3
-flag). Demotion candidate if the swap above forces a third
-demotion round.
-
-## § 5 — ADR candidates (P2.1 input)
-
-Two distinct ADR classes land in P2.1 from this contract.
-
-### § 5.1 — Iron-Law-override ADRs (per-rule cap)
-
-**Council amendment (P1.4).** Per-rule cap raised from 1.5k to **2.5k**.
-Both Council members concurred — the original 1.5k figure forced 8 of
-9 kernel rules into ADR territory (process theatre, not governance).
-The 2.5k cap fits 7 of 9 rules without ADR; only the two largest
-remain as legitimate Iron-Law-density exceptions.
-
-Rules that land **above the 2.5k per-rule cap** even after condensation
-and Iron-Law preservation:
-
-| rule | post-condensation chars | over-cap (2.5k) | reason cap cannot be hit |
-|---|---:|---:|---|
-| direct-answers    | 2842 | +342  | Three Iron-Law fences (≈ 470 chars) + severity-tiered claim table required for invented-facts gate |
-| language-and-tone | 3786 | +1286 | Iron-Law fence + exhaustive user-visible-prose catalog + pre-send gate are co-load-bearing |
-| autonomous-execution* | 4009 | +1509 | (*if swap accepted per § 4 †) trivial-vs-blocking matrix + opt-in detection table |
-
-`*` = conditional on the agent-authority / autonomous-execution swap
-ADR (see § 5.2).
-
-Per roadmap § "Iron-Law over budget = ADR exception, not auto-
-condense" — these surface as `iron-law-override` exceptions for P2.1
-to gate behind ADRs in `docs/decisions/`.
-
-The remaining 6 always-rules project to 1669–2916 chars post-
-condensation — all under the 2.5k cap with no ADR needed. P2.2
-measures the real post-condensation sizes; if any breach the cap, an
-ADR lands per-rule.
-
-### § 5.2 — Kernel-set swap ADR (agent-authority ↔ autonomous-execution)
-
-Sonnet 4.5 flagged that `agent-authority` carries no Iron-Law fence
-(it is a routing index, not a governance rule) and that
-`autonomous-execution` does carry a mode-independent Band-4 authority
-that fires on every action decision. Swap proposal: `agent-authority`
-→ auto-tier-3 (router-loaded), `autonomous-execution` → kernel.
-
-| variant | sum-projected (× 0.712) | bucket budget | per-rule ADRs |
-|---|---:|---|---|
-| (a) status quo (current § 4)        | 23 071 | ✓ ≤ 25k | 2 (`direct-answers`, `language-and-tone`) |
-| (b) swap, raise hard cap to 27k     | 26 213 | ✓ ≤ 27k | 3 (+`autonomous-execution`) |
-| (c) swap + demote verify-before-complete | 24 545 | ✓ ≤ 25k | 3 (+`autonomous-execution`) |
-
-**Resolution: `docs/decisions/ADR-001-kernel-swap-deferred.md`
-(accepted variant a).** Status quo preserves the locked 25k cap and
-the 9-rule set through P2.2. Re-evaluation trigger fires at P3.2
-once the router schema and compiler ship; at that point
-`agent-authority`'s routing role becomes redundant (each kernel rule
-carries its own band as frontmatter, compiled into `dist/router.json`),
-clearing the way for the swap under a fresh ADR.
-
-## § 6 — Abort criteria for P2.2
-
-**Council amendment (P1.4).** Sonnet 4.5 flagged that P2.2 condenses
-in place with no defined abort path. The following triggers force
-revert + re-projection rather than mid-phase scramble:
-
-- **Iron-Law drift.** Any kernel rule loses Iron-Law SHA equivalence
-  after condensation (whitespace-normalised, case-folded fence-block
-  content). Single occurrence aborts the rule's condensation.
-- **Bucket overflow.** Kernel sum post-condensation > 27 500 chars
-  (10 % over hard cap). Aborts the entire P2.2 phase.
-- **Single-rule runaway.** Any kernel rule post-condensation
-  > 4 000 chars. Aborts that rule's condensation; flag for ADR.
-- **Empirical r drift.** Median of measured r across the first 4
-  condensed rules deviates > 0.10 from the locked 0.712 (i.e.,
-  measured median outside [0.612, 0.812]). P2.2 pauses, re-locks r,
-  re-runs § 3 projection.
-
-On abort: revert all P2.2 edits in scope, re-run P1.3 projection
-with the trigger-relaxed parameter, lock new value, re-attempt.
-
-## § 7 — Verification
-
-| check | command | acceptance |
-|---|---|---|
-| Pilot reproducibility | `./scripts-run src/scripts/_pilot_measure` | r-values, sum, SHAs identical across runs |
-| Iron-Law preservation | SHA-256 of fence-block content (whitespace-norm, case-fold) | all 3 pilots match originals |
-| Bucket projection | `r_median × sum(always)` | ≤ 25 000 chars |
-| Per-rule cap (P2.1) | `measure_rule_budget.py --kernel-budget-check` (P2 deliverable) | each ≤ 2 500 chars OR ADR |
-
-## § 8 — What this contract does NOT do
-
-- It does **not** edit any source rule. P2.2 ships condensation to
-  `.agent-src.uncondensed/rules/`.
-- It does **not** lock per-rule `chars` (only the bucket sum). Per-
-  rule values are projections; P2.2 measures real post-condensation.
-- It does **not** decide kernel additions. Adding a rule to the
-  kernel requires an ADR per roadmap § "Sequencing-drift time-box"
-  and re-runs P1.3 with the new candidate.
-- It does **not** specify P3 router state-machine primitives
-  (once / every-turn / on-mode-switch). Council flagged this as a
-  P3.1 deliverable dependency before any P4 migration ships.
-- It does **not** specify P4 migration shapes (replace / merge /
-  stub / disappear). Council flagged this as a P4 deliverable spec.
-
-## § 9 — Provenance
-
-| date | source | scope |
-|---|---|---|
-| 2026-05-06 | `scripts/measure_rule_budget.py` | baseline (32 403 chars across 9 always-rules) |
-| 2026-05-06 | `docs/contracts/pilot/*.md` + `scripts/_pilot_measure.py` | empirical r distribution (3 pilots) |
-| 2026-05-06 | `agents/runtime/council/sessions/20260506T044821Z-phase1-cross-check.json` | Council R1 (truncated at 1024 tokens) | <!-- council-ref-allowed: contract decision trace -->
-| 2026-05-06 | `agents/runtime/council/sessions/20260506T044941Z-phase1-cross-check-r2.json` | Council R2 (3500 tokens) — locks median r, splits criterion #3, adds criterion #5, raises per-rule cap to 2.5k, defines abort criteria | <!-- council-ref-allowed: contract decision trace -->
-| 2026-05-06 | this file | kernel set locked: 9 rules, projected 23 071 chars (median r = 0.712) |
-| 2026-05-06 | P2.2 condensation + `scripts/iron_law_sha.py --all-kernel` | empirical: 25 590 chars (r_actual = 0.795 across kernel; longer rules condense less than the pilot median) — see `docs/decisions/ADR-002-kernel-bucket-overrides.md` (KERNEL_HARD raised 25k → 26k, 6 per-rule overrides ≤ 4k ceiling, all Iron-Law SHAs preserved) |
-
-## § 10 — Changing a protected invariant
-
-The semantic-invariants gate (`src/scripts/check_rule_invariants.ts` over
-`tests/golden/invariants.json`, 19 protected strings across the 9 kernel
-rules) enforces string presence in BOTH `src/rules/` and the
-`dist/agent-src/rules/` projection. String matching is deliberately the
-current enforcement: it is zero-cost and trips on casual edits. Its known
-brittleness — a semantically equivalent rewording breaks the gate — is
-handled by process, not by weakening the gate.
-
-**Rewording a protected string is allowed, but never "update the gate
-green".** A PR that changes an entry in `tests/golden/invariants.json`
-MUST:
-
-1. Name WHICH invariant changes and WHY the wording changes (PR body).
-2. State old/new side-by-side with an explicit assertion-equivalence
-   sentence ("the new wording still guarantees X").
-3. Re-run and quote `check_rule_invariants.ts --mutation-selftest` in the
-   PR (the selftest guards the checker against silently-green
-   normalisation bugs after the edit).
-4. Cite the behavioral eval covering the invariant where one exists; where
-   none exists, say so explicitly — an uncovered invariant rewording gets
-   extra review scrutiny, not less.
-
-Kernel-edit slow-rollout rules (own PR, ≥ 24 h soak between kernel merges,
-per `scope-control § kernel-rule-edits`) apply on top — the invariants file
-is part of the kernel surface.
-
-**ID migration is gated, not planned.** Migrating string fragments to
-frontmatter invariant IDs happens only after behavioral evals cover ≥ 10
-of the 19 invariants. Until then, IDs would claim guarantees nothing
-verifies — an ID whose text drifted validates nothing, and that failure is
-silent, unlike a string miss (council convergence, anthropic/
-claude-sonnet-4-5 + openai/gpt-4o, 2026-07-10).