ceo-orchestration 1.0.0

package/.claude/adr/ADR-151-fan-plan-advisory-bridge.md

@@ -0,0 +1,178 @@
+---
+id: ADR-151
+title: /fan-plan advisory bridge — parse [P?][USn][path] ACs into a PROPOSE-only read-only fan-out
+status: ACCEPTED
+proposed_at: 2026-06-17
+proposing_session: S240
+accepted_at: 2026-06-17
+accepting_session: S241
+related_plans: [PLAN-138, PLAN-134, PLAN-110]
+related_adrs: [ADR-138, ADR-136-AMEND-1, ADR-144, ADR-132, ADR-107]
+risk_tier: B
+debate_required: true
+---
+
+# ADR-151 — /fan-plan advisory bridge
+
+**Status:** ACCEPTED (S241, 2026-06-17 — shipped + CI green in PLAN-138 Wave B)
+**Enforcement commit:** `bbe279ea` (PLAN-138 Wave B — `/fan-plan` command + parser shipped; ADR-138 g1 Codex ≥3-iter ACCEPT; CI green)
+
+**Enforcement boundary:** advisory PROPOSE-ONLY — `/fan-plan` parses AC
+lines and PRINTS a proposed read-only fan-out plan; it NEVER calls
+`parallel()`/`agent()` and never auto-spawns. No hook emits
+`permissionDecision`; the parser is fail-open (lenient: warn, never raise).
+
+## Context
+
+`github/spec-kit` (baseline pin **v0.11.0**, 2026-06-16) structures every
+task line in its `tasks.md` template with an optional priority prefix
+`[P0]/[P1]/[P2]/[P3]`, an optional user-story group `[USn]`, and a file
+anchor `[path]` (spec-kit `templates/commands/tasks.md`). ceo-orchestration
+formalized that **text-only** AC-line convention in **ADR-138** (ACCEPTED,
+S177) and explicitly reserved a parser for a follow-up under its
+**§Future Work (RESERVED)** clause — gated on (g1) Codex ≥3-iter ACCEPT on
+the parser, (g2) an Owner GPG-signed sentinel for any hook addition, and
+(g3) a backward-compat re-test of all PLANs `001-109+` (i.e. the full
+current corpus, enumerated at execution time — not a hardcoded count).
+
+PLAN-138 Wave B is the round-2 spec-kit residual that picks up exactly this
+reserved parser. The parser reads the `[P?][USn][path]` grammar (ADR-138
+lines 54-70) and proposes grouping `[P]`-parallel ACs by path into a
+**read-only** investigation fan-out — the only fan-out shape the framework
+permits per **ADR-136-AMEND-1**:
+
+- **§4.1 Read-only only.** `agent()`/`parallel()`/`pipeline()` are confined
+  to investigation / audit / recon fan-out. Any write, canonical-path edit,
+  Owner-GPG ceremony, or `audit_emit` write path runs sequentially through
+  the Owner-GPG sentinel (`check_canonical_edit.py`) and `/debate`-VETO.
+- **§4.3 Structured returns.** A `parallel()` return MUST carry the ADR-141
+  8-field shard schema; a free-prose reducer is a governance violation.
+
+`/fan-plan` is therefore a **bridge**: it turns an AC block into a *proposal*
+for the existing, confined fan-out machinery (the `audit-fanout` workflow
+shape) — it does not introduce a new engine (PLAN-110 anti-goal #3) and it
+does not auto-execute (anti-goal #1).
+
+## Decision drivers
+
+- **ADR-138 §Future Work (RESERVED).** The parser is the explicitly reserved
+  follow-up; this ADR records the g1/g2/g3 acceptance contract it must meet.
+- **ADR-136-AMEND-1 §4.1 (read-only confinement) + §4.3 (8-field structured
+  returns).** Any fan-out the bridge proposes must stay inside this
+  confinement — investigation only, schema-bound returns, never a write path.
+- **ADR-144 §S220 (opts.model INERT for Workflow subagents).** With the
+  global subagent override at `inherit`, a per-call `opts.model` is silently
+  ignored: a fanned-out subagent runs the **session** model, not a requested
+  downgraded tier. PLAN-134 GATE-W0a confirmed this empirically (verdict
+  FAIL: `opts.model` had no measurable effect). This is the cost-envelope
+  driver — the bridge cannot promise a cheaper tier.
+- **ADR-132 (advisory-only planner doctrine) + ADR-107 (pair-rail mandatory
+  L2+).** `/fan-plan` follows the `/goap` advisory-only precedent; its parser
+  is L2 and gated by the Codex pair-rail (g1).
+
+## Options considered
+
+### Option 1 — Auto-spawning fan-out command (REJECTED)
+
+Parse the AC block and directly call `parallel()` over the `[P]`-parallel
+groups. **Rejected** — violates PLAN-110 anti-goal #1 (no `EXECUTE_COMMAND`
+auto-execution) and removes the Owner from the spawn loop. The whole point of
+ADR-136-AMEND-1 §4.1 is that the Owner-GPG sentinel and `/debate`-VETO are
+not bypassable by a fan-out child; an auto-spawning bridge would route around
+the human checkpoint.
+
+### Option 2 — Advisory PROPOSE-ONLY bridge, prompt-enforced (RECOMMENDED)
+
+Parse the AC block, PRINT a `PROPOSED read-only fan-out (Owner must confirm
+each spawn)` block with a cost envelope, then STOP. The command body never
+calls `parallel()`/`agent()`. Non-auto-spawn rests on **prompt-discipline**
+this round (see §Consequences negative). **Recommended** — lowest blast
+radius, satisfies the ADR-138 reserved-parser intent, imports no anti-goal,
+keeps the Owner in the loop.
+
+### Option 3 — Advisory bridge + a NEW `CEO_FANPLAN_CONFIRMED` spawn-hook
+(DEFERRED)
+
+Add hook-enforced parity with `/goap`'s `CEO_GOAP_CONFIRMED` gate in
+`check_agent_spawn.py`. **Deferred** — a new governance hook is itself an
+ADR-138 g2 event (Owner GPG sentinel) and widens PLAN-138's scope; recorded
+as the optional follow-up in §Consequences and PLAN-138 OQ-B.
+
+## Decision
+
+Adopt **Option 2**: ship `/fan-plan` as an **advisory PROPOSE-ONLY bridge**.
+
+- A stdlib-only, py3.9-safe, **ReDoS-safe** parser (`fan-plan-parser.py`)
+  reads the `[P?][USn][path]` grammar per ADR-138, lenient (warn, never
+  raise), with defaults priority→`P1`, story→`null`, path→`null`. It can
+  scan the full plan corpus by parsed numeric id (g3 backward-compat).
+- A `/fan-plan` command (`commands/fan-plan.md`, modeled on `commands/goap.md`)
+  invokes the parser and PRINTS a proposed read-only fan-out grouping
+  `[P]`-parallel ACs by path, **including a COST ENVELOPE** that states the
+  proposed agent count and the inert-model caveat (per ADR-144 §S220), then
+  STOPS. It never calls `parallel()`/`agent()`.
+- Kill-switch `CEO_FANPLAN=0` disables the command.
+
+### Acceptance contract (ADR-138 g1/g2/g3)
+
+- **g1** — Codex pair-rail ≥3-iter ACCEPT on the parser code (recorded at
+  PLAN-138 execution, V2).
+- **g2** — Owner GPG-signed sentinel for the canonical/cache-stable edits
+  (PLAN-138 V3 ceremony).
+- **g3** — the parser re-tests ALL plans `001-current` (the full enumerated
+  corpus on disk, not a hardcoded floor) with zero raised exceptions and zero
+  rejected lines (lenient backward-compat).
+
+## Consequences
+
+### Positive
+
+- Picks up ADR-138's reserved parser as an advisory, reversible addition.
+- Reuses the existing confined `audit-fanout` fan-out shape (ADR-136-AMEND-1)
+  — no new engine, no anti-goal imported.
+- Keeps the Owner in the spawn loop; the cost envelope makes the
+  inert-model reality (`opts.model` ignored → session-model tier) explicit at
+  the point of proposal.
+
+### Negative (recorded honestly)
+
+- **`opts.model` is EMPIRICALLY INERT for Workflow subagents** (ADR-144 §S220
+  + PLAN-134 GATE-W0a FAIL). A proposed fan-out therefore runs the **session
+  model** — the bridge **cannot promise a downgraded tier**. A `/fan-plan`
+  proposed from a CEO Opus session fans out at Opus tier; the cost envelope
+  states this so the Owner is not misled into expecting Haiku-tier pricing.
+- **Non-auto-spawn rests on PROMPT-DISCIPLINE ONLY.** Unlike `/goap`, whose
+  non-delegation is hook-enforced (`check_agent_spawn.py` blocks any
+  GOAP-tagged spawn lacking `CEO_GOAP_CONFIRMED=1` + a `## GOAP CONFIRM`
+  block), `/fan-plan`'s "PROPOSE-only, never auto-spawn" boundary is
+  **structurally weaker** — it is a contract in the command prompt, not a
+  hook gate. An optional deferred follow-up would add
+  `CEO_FANPLAN_CONFIRMED` spawn-hook parity in `check_agent_spawn.py`; it is
+  NOT shipped this round because a new governance hook is itself an ADR-138 g2
+  event and widens scope (see Option 3 + PLAN-138 OQ-B).
+
+### Neutral
+
+- PROPOSED status only — ship the code, leave the ADR PROPOSED, promote in a
+  dedicated ceremony (PLAN-138 OQ1 default, ADR-136/137 precedent).
+- The parser is lenient by design: malformed AC lines degrade to defaults,
+  never block.
+
+## Blast radius
+
+**L2.** Adds one advisory command (`commands/fan-plan.md`), one stdlib-only
+parser script (`scripts/fan-plan-parser.py`), one test file, and this ADR.
+No hook is added or modified this round; no `permissionDecision` is emitted;
+no canonical guard is weakened. The parser is read-only over the plan corpus.
+A revert removes the command + parser + ADR with no migration. The only
+governance surface touched is the cache-stable command/skill inventory count,
+reconciled in PLAN-138 Wave V under the Owner GPG ceremony.
+
+## References
+
+- ADR-138 §Future Work (RESERVED) — the reserved parser this ADR implements
+- ADR-136-AMEND-1 §4.1 (read-only confinement) + §4.3 (8-field returns)
+- ADR-144 §S220 (opts.model inert for Workflow subagents) + PLAN-134 GATE-W0a
+- ADR-132 (advisory-only planner doctrine) — `/goap` precedent
+- PLAN-138 Wave B (B.1-B.6) + OQ-B (enforcement strength)
+- spec-kit v0.11.0 `templates/commands/tasks.md` — `[P?][USn][path]` grammar

package/.claude/adr/ADR-152-claude-md-decomposition.md

@@ -0,0 +1,262 @@
+---
+status: PROPOSED
+---
+
+<!-- NUMBER-COLLISION RISK (PLAN-135 W4 unit d2, authored on branch plan-135-exec):
+     ADR-150 is the highest ADR on disk at authoring time (2026-06-12). The
+     PARALLEL PLAN-134 terminal holds a deferred, un-numbered routing ADR
+     (PLAN-134-mission-completion-sota-arc.md "ROUTING ADR DIRECTION",
+     Owner-confirmed S229) that is expected to take ADR-151. This file
+     therefore takes ADR-152 and leaves ADR-153 as headroom. AT CEREMONY
+     TIME: re-grep `.claude/adr/` for the highest allocated number BEFORE
+     applying; if 152 is taken, allocate a fresh ID per the ADR-117
+     collision policy (never reuse, never <base>a- except for amendments)
+     and update this header + the d2 manifest. S229/S230 two-live-terminal
+     precedent makes this risk real, not theoretical. -->
+
+# ADR-152: CLAUDE.md decomposition — `@imports` vs `.claude/rules/` + `paths:` (D1-measurement-gated)
+
+**Status:** PROPOSED — decision FRAMEWORK complete; the decision itself is
+NOT taken. Status flips to ACCEPTED only per §Decision gate below (all
+`MEASURED:<tbd>` slots filled from D1's PROBE-LOG.md and the §Decision rule
+evaluated). Acceptance does NOT authorize execution — execution is its own
+follow-up Owner ceremony (PLAN-135 W4 d2 plan text; §0 Gate-1 blast radius).
+**Date:** 2026-06-12 (PLAN-135 W4 unit d2; harvest item D2)
+**Enforcement commit:** n/a (documentation-only at acceptance; the follow-up
+execution ceremony commit will be recorded here as an addendum when it lands)
+**Decision drivers:**
+- CLAUDE.md is 39,461 B against the 40,000 B CI cap (`validate-governance.sh:603`,
+  `CLAUDE_MD_SIZE_LIMIT`; also `generate-ceremony.sh` post-size FAIL) — 539 B
+  (~1.3%) headroom. S230 went CI-red on exactly this cap after a routine S229
+  closeout and forced an emergency compaction.
+- The volatile tail (§6 Current Work → EOF, i.e. §6-archived clusters +
+  §CHANGELOG) is 28,231 B = **72% of the file** (~7,060 tokens est.) and is
+  the ONLY part edited at every closeout; the stable doctrine head is ~28%.
+- The §0 Gate-1 no-edit rule's cost premise (any mid-session edit
+  invalidates the prompt cache; 5-min TTL) is under active falsification by
+  D1 (PLAN-135 W4 d1) — this ADR must not bake in either premise before
+  D1's numbers exist.
+- Harvest D2 verdict: GAP · medium · "framework + every adopter with a fat
+  CLAUDE.md"; harvest mandates picking ONE option after `/context`
+  measurement and mirroring the choice into `templates/CLAUDE.md`.
+
+## Context
+
+`CLAUDE.md` is the Gate-1 master context: read at every session boot,
+declared cache-stable, and guarded by the §0 cache-discipline rule
+(closeout-ceremony-only edits). Three pressures now act on the monolith:
+
+1. **Byte cap.** The 40,000 B governance cap leaves ~539 B of headroom.
+   Every closeout grows the CHANGELOG; compaction ceremonies (S230's
+   S159-S174 super-rollup is the latest) are recurring manual toil whose
+   trigger is a CI red, not a plan.
+2. **Blast radius of the §0 discipline.** Because the volatile tail lives
+   in the same file as the stable doctrine head, a 1-line CHANGELOG entry
+   carries the same Gate-1/canonical-ceremony weight as a doctrine change.
+   72% of the file's bytes churn; ~28% are the actual rules.
+3. **Falsified-or-not cost premise.** `docs/opus-4-7-operations.md` §2
+   claims 5-min TTL and full-cache invalidation on any Gate-1 edit; the
+   harvest (D1) asserts 1h subscription TTL and prefix preservation on
+   mid-session CLAUDE.md edits. D1 built the measurement protocol
+   (research/D1-CACHE-MEASUREMENT-PROTOCOL.md, sessions S-A..S-F, verdicts
+   PRESERVED/PARTIAL/INVALIDATED → doctrine Variant A/B). Measurement is
+   PENDING-LIVE. Two conflicting folklore boot numbers (~27,300 ops-doc vs
+   ~44,786 CLAUDE.md §0) get re-baselined by D1 S-F.
+
+The harness offers two decomposition mechanisms (harvest D2 mechanics):
+
+- **`@imports`** — `@.claude/context/changelog.md` style inline imports
+  resolved into context at session start. Content still loads every
+  session; the FILE boundary moves.
+- **`.claude/rules/*.md` with `paths:` frontmatter** — rule files loaded
+  conditionally, only when the session touches matching paths (e.g. hooks
+  conventions load only when `.claude/hooks/**` is touched). Content does
+  NOT load in sessions that never match.
+
+PLAN-135 W4 d2 deliverable is this measured ADR — a decision framework with
+explicit measurement slots, NOT an executed decomposition.
+
+## Decision drivers
+
+- (see bullets in header; plus:)
+- Determinism of governance context: PROTOCOL.md assumes the CEO has the
+  governance rules in-context every session. Any mechanism that makes rule
+  loading conditional must exclude load-bearing governance text.
+- Adopter parity: whatever ships must be mirrored in `templates/CLAUDE.md`
+  and survive `scripts/install.sh` / `scripts/upgrade.sh` (both canonical).
+- Tooling coupling: `validate-governance.sh` CLAUDE.md size check,
+  `generate-ceremony.sh` post-size gate, and any hook/script that greps
+  CLAUDE.md must keep working against the decomposed layout.
+
+## Options considered
+
+### Option A: `@imports` — volatile-tail extraction
+
+Move the volatile tail (§6-archived clusters + §CHANGELOG; optionally §6
+Current Work) to `@.claude/context/changelog.md`; CLAUDE.md keeps the
+stable doctrine head plus one import line. Closeout then touches ONLY the
+imported file.
+
+**Pros:**
+- Defuses the 40,000 B cap structurally and permanently: the capped file
+  drops to ~11,2 kB and stops growing; compaction ceremonies stop being
+  CI-emergency-driven (the context file can rotate/archive on its own
+  schedule).
+- Closeout edits land in a non-doctrine file — the Gate-1 head becomes
+  byte-stable across sessions, which is the strongest available prefix-
+  stability posture under EITHER D1 variant.
+- Deterministic: imported content loads every session exactly like today —
+  zero change to what the CEO sees; no governance-text conditionality.
+- Cheapest template mirror (one import line + one new file).
+
+**Cons:**
+- ZERO fixed-context shrink: imports are inlined at boot, so every session
+  still pays the ~7,060-token tail (M1 unchanged).
+- Cache benefit is unproven: editing the imported file changes the
+  assembled prompt too. If the import sits at the prompt tail, only the
+  suffix re-pays; if not, it may invalidate exactly like an in-file edit.
+  This is measurement slot M4 — unknowable from doctrine.
+- Adds a harness-behavior dependency (import resolution order/position) to
+  the Gate-1 contract; §0 prose and GATE-1 reading list must enumerate the
+  imported file.
+
+### Option B: `.claude/rules/*.md` with `paths:` gating
+
+Carve per-area conventions out of CLAUDE.md §5 Critical Rules (and team-doc
+adjacents) into `paths:`-gated rule files: e.g. Python/hook-test
+conventions load only when touching `.claude/hooks/**`, plan-naming rules
+only under `.claude/plans/**`.
+
+**Pros:**
+- The ONLY option that shrinks the fixed per-session context: sessions
+  that never touch a gated area never load its rules (slot M5).
+- Per-area isolation additionally shrinks the §0 blast radius: editing a
+  gated rule file mid-session perturbs only sessions that loaded it.
+- Scales with domain growth (151 skills, domain profiles) better than a
+  monolith ever can.
+
+**Cons:**
+- Nondeterministic governance context: the same session type can see
+  different rule sets — weakens the "the CEO always saw rule X" audit
+  assumption; load-bearing governance (spawn protocol, canonical-edit
+  discipline, Gate ordering) is INELIGIBLE for gating, so only a subset of
+  CLAUDE.md (mostly §5 conventions) qualifies. The volatile tail —
+  the actual byte-cap driver — is NOT rules-shaped and does not fit this
+  mechanism (the CHANGELOG can't be `paths:`-gated meaningfully).
+- Does NOT defuse the byte cap by itself (the tail stays in CLAUDE.md).
+- Heavier template/adopter mirror (a rules directory + frontmatter
+  semantics that adopters must understand); `paths:` matching semantics
+  are harness-version-dependent and need a smoke test in
+  `smoke-install-parity.sh`.
+
+### Option C: status quo (null option)
+
+Keep the monolith; manage the cap by scheduled compaction (super-rollups).
+
+**Pros:** zero migration risk; zero new harness dependencies; current
+practice demonstrably works (S230 compaction took one session).
+**Cons:** recurring manual toil with a CI-red failure mode; 72% volatile
+byte share keeps the Gate-1 discipline's blast radius maximal; headroom is
+~539 B so the NEXT normal closeout likely goes red again.
+
+## Decision
+
+**NOT YET TAKEN.** The decision is produced by the rule below the moment
+the measurement slots are filled from D1's PROBE-LOG.md. The chosen option
+will be recorded here, in place, with the numbers.
+
+### Measurement slots (source: D1 campaign, PLAN-135/research/D1-CACHE-MEASUREMENT-PROTOCOL.md)
+
+| Slot | Definition | Source | Value |
+|------|------------|--------|-------|
+| M1 | Gate-boot tokens, live re-baseline (replaces the ~27,300 / ~44,786 folklore pair) | D1 S-F (`/context`, live read-only) | MEASURED:<tbd> |
+| M2 | Mid-session CLAUDE.md-edit cache verdict ∈ {PRESERVED, PARTIAL, INVALIDATED} | D1 S-B (cache_read(T_p) vs cache_read(T3) rule) | MEASURED:<tbd> |
+| M3 | If M2=PARTIAL: re-pay tokens = cache_creation(T_p) − baseline | D1 S-B | MEASURED:<tbd> |
+| M4 | Tail-import-edit cache verdict: same S-B probe shape but the edit targets an `@import`-ed tail file (1 extra rep; extension of S-B — add to PROBE-LOG before the campaign runs) | D1 S-B extension | MEASURED:<tbd> |
+| M5 | Option-B conditional-load saving: tokens of `paths:`-eligible rule text NOT loaded in a representative non-matching session | post-carve `/context` delta (estimable statically from §5 byte share before the campaign) | MEASURED:<tbd> |
+
+Static facts (measured at authoring, 2026-06-12, NOT slots): CLAUDE.md
+39,461 B / cap 40,000 B (headroom 539 B); volatile tail §6→EOF 28,231 B =
+72% (~7,060 tok est.; CHANGELOG alone 24,079 B); `templates/CLAUDE.md`
+4,504 B (no cap pressure on the adopter side yet).
+
+### Decision rule (D1-gated; materiality threshold = 10% of M1, matching D1's own cost-immateriality bar)
+
+- **R1 — M2 = INVALIDATED (D1 doctrine Variant A; cost premise TRUE).**
+  The §0 rule survives; cache cost is real. Choose **Option A** iff M4
+  shows the tail-import edit is PRESERVED or re-pays < 10% of M1 (suffix-
+  only re-pay) — Option A then converts every closeout from "invalidate
+  the gate-boot" to "cost-immaterial tail re-pay" AND defuses the byte
+  cap. If M4 is also INVALIDATED end-to-end, Option A still wins on the
+  byte cap + closeout ergonomics alone, but §0 cost language is RETAINED
+  and closeout stays ceremony-end-only. Option B is taken INSTEAD only if
+  M5 ≥ 10% of M1 (rare under Variant A: the eligible §5 subset is small).
+- **R2 — M2 = PRESERVED, or PARTIAL with M3 < 10% of M1 (Variant B; cost
+  premise FALSE/immaterial).** Cache protection is no longer a driver;
+  decide on fixed-context shrink vs byte cap. Choose **Option B** iff
+  M5 ≥ 10% of M1 AND the gated subset contains zero load-bearing
+  governance text (reviewer-checkable list in the execution plan);
+  otherwise choose **Option A** purely for the structural byte-cap defuse
+  + closeout isolation. If, with numbers in hand, A's gains are judged
+  not worth a Gate-1 migration ceremony, record **Option C** and close
+  this ADR as the honest null (the cap then needs a standing compaction
+  routine instead — e.g. a nightly-hygiene staleness line).
+- **R3 — pick ONE.** Hybrid (A+B together) is explicitly OUT at this
+  decision point per harvest D2 ("Escolher UM após medir"); revisiting a
+  hybrid requires a fresh ADR with the first option's post-execution
+  numbers as its baseline.
+- **Mirror clause (applies to A and B).** The chosen mechanism ships to
+  `templates/CLAUDE.md` in the SAME execution ceremony, with
+  `smoke-install-parity.sh` extended to assert the decomposed layout
+  installs cleanly (S228 E8-gate precedent).
+
+## Decision gate (status-flip rule — explicit)
+
+This ADR remains **PROPOSED** until ALL of:
+
+1. Every `MEASURED:<tbd>` slot above is replaced with a value from D1's
+   filled PROBE-LOG.md (scratch-worktree campaign S-A..S-F + the M4
+   extension rep);
+2. The §Decision rule is evaluated against those values and the resulting
+   option (A, B, or C) is written into §Decision with the numbers inline;
+3. The companion D1 doctrine fix (research/D1-PROPOSED-DOC-FIX.md →
+   `docs/opus-4-7-operations.md` §2 Variant A or B) has landed or lands in
+   the same promotion, so this ADR and §2 never assert different premises.
+
+Only then: PROPOSED → ACCEPTED. **ACCEPTED still does NOT execute the
+decomposition.** Execution (moving CLAUDE.md content, §0/GATE-1 prose swap,
+templates mirror, tooling updates) is a separate follow-up **Owner
+ceremony** — CLAUDE.md is Gate-1 (closeout-ceremony-only edit per §0) and
+`templates/`-adjacent install scripts are canonical-guarded. If D1's
+campaign is abandoned, the terminal state is RETRACTED, not silent decay.
+
+## Consequences
+
+- (+) The decision cannot be taken on folklore: both the 5-min-TTL premise
+  and its falsification are excluded until measured (the exact failure
+  mode D1 exists to kill).
+- (+) Whatever lands, the 40,000 B cap stops being an ambush: Option A
+  removes it structurally; Options B/C force an explicit standing
+  mitigation into the record.
+- (+) Adopters inherit a measured pattern via the templates mirror, not a
+  meta-repo idiosyncrasy.
+- (−) The byte-cap exposure persists until the follow-up ceremony executes
+  — at 539 B headroom the next closeout may red CI again; interim
+  mitigation stays manual compaction.
+- (−) Two-ceremony latency (accept, then execute) on a change whose Option-A
+  form is mechanically trivial; accepted deliberately because the §0 blast
+  radius is the whole reason this is an ADR.
+- (~) M4/M5 add one rep + one static estimate to the D1 campaign scope;
+  scope-cut already flagged in the d1 manifest open items.
+
+## Blast radius
+
+**L3+.** Touches the Gate-1 contract itself: `CLAUDE.md` (§0 discipline +
+GATE-1 reading list + physical layout), `templates/CLAUDE.md`,
+`docs/opus-4-7-operations.md` §2 cascade (cost-of-operation.md,
+opus-4-7-baseline.md per D1's ledger), `validate-governance.sh` CLAUDE.md
+size-check semantics, `generate-ceremony.sh` post-size gate,
+`smoke-install-parity.sh`, `scripts/install.sh`/`upgrade.sh` parity, and —
+via the templates mirror — every adopter repo with a fat CLAUDE.md. Hence:
+debate-eligible, Codex pair-rail on the execution plan, Owner GPG ceremony
+for execution.

package/.claude/adr/ADR-153-compaction-continuity.md

@@ -0,0 +1,141 @@
+---
+status: ACCEPTED
+---
+
+# ADR-153 — Compaction-continuity: PreCompact snapshot + PostCompact governance reinjection (H1)
+
+- **Status:** ACCEPTED (S242, 2026-06-17 — both hooks registered in `.claude/settings.json` (`PreCompact`/`PostCompact`) with the two audit actions wired; Codex pair-rail satisfied at the PLAN-135 W2 merge `019ec0a1` + FOLLOWUP `019ec445`, re-confirmed Codex R-sweep thread `019ed788`)
+- **Date:** 2026-06-13 (proposed) / 2026-06-17 (accepted, S242)
+- **Enforcement commit:** `ab5114ab` (PLAN-135 W2 — `check_precompact_continuity.py` + `check_postcompact_reinject.py` + the `compaction_continuity_snapshot` / `compaction_context_reinjected` audit actions; hardened `26651bac`). Residual: live fires-proof (a real paid compaction emitting the events) remains PENDING-LIVE — an honest boundary, not a blocker.
+- **Decision drivers:**
+  - Harvest item **H1** (`HARVEST-REPORT.md` lines 48-49): "Compaction é a OUTRA forma de morte do estado de sessão (o closeout-guard cobre só Stop)." A 101-agent audit or any context-ceiling marathon collapses the transcript; the session-start governance reads (Gate-1: CLAUDE.md, PROTOCOL.md, team.md) and the active-PLAN/execution-unit position are summarized away, and the post-compaction model can silently drift off-protocol. This is a real class of protocol amnesia (Top-10 #5: "amnésia por compaction").
+  - **The closeout-guard (S228) covers only `Stop`.** Compaction is a second, untracked death of session state. The fix mirrors the closeout-guard's shape — a fail-open advisory lifecycle hook — but on the compaction lifecycle pair.
+  - **Doctrine 3** (PLAN-135 plan lines 73-78): "No setting, frontmatter field, or **hook event** is declared adopted until a live probe proves it changes behaviour / actually fires" (W0a `opts.model` was inert; S217: registered ≠ fires). `PreCompact`/`PostCompact` are NEW harness events — each ships with a fires-probe.
+
+## Context
+
+When the Claude Code harness compacts a long conversation it fires `PreCompact` (manual `/compact` or auto context-window threshold) and, after the summary lands, `PostCompact`. The post-compaction transcript no longer contains the literal Gate-1 reads or the running plan/execution-unit context — they were inputs to the summary, not preserved verbatim. For the ceo-orchestration meta-repo (where a single session can run a 101-agent audit), that means the CEO can resume after a compaction having "forgotten" which PLAN is active, where in the execution unit it was, and that an Owner-GPG ceremony was pending.
+
+Two hooks close the gap:
+
+1. **`PreCompact` — `check_precompact_continuity.py`** snapshots, BEFORE the transcript collapses, the governance state the summary would lose: the active `plan_id` (derived from the audit-log `plan_transition` events — never an env var, which is agent-spoofable: scratchpad_lib doctrine), the execution-unit position (the first unchecked `- [ ]` checkbox in the plan file — repo-relative path + line + label), the pending Owner-GPG ceremony flags (executable `finish-*.sh` newer than the last tag — the closeout-guard's own signal), and a READ-ONLY breadcrumb of the audit HMAC-chain anchor (last-hmac hex prefix + chain-length counter). The snapshot is written to the **plan-scoped scratchpad** (`_lib/scratchpad_lib` → `_lib/state_store`, ADR-027/ADR-034): plan-scoped, secrets-redacted, 64 KiB cap, `set`-overwrites.
+2. **`PostCompact` — `check_postcompact_reinject.py`** reads that snapshot back and reinjects governance **POINTERS** via `hookSpecificOutput.additionalContext` so the model re-anchors on protocol.
+
+## Decision drivers
+
+- A compaction that erases protocol state is the same failure mode the closeout-guard addresses on `Stop`, on a different lifecycle edge — it earns the same fail-open advisory treatment.
+- The snapshot must survive the compaction. The scratchpad is the only durable, plan-scoped, session-surviving state surface in the framework (the audit log is append-only and not keyed for retrieval; the transcript is exactly what compaction destroys).
+- The reinjection payload is a prompt-injection surface: anything a `PostCompact` hook writes into `additionalContext` enters the model's context unconditionally. Disk-sourced strings (a plan label, a ceremony path) must never be injected as raw bodies.
+
+## Options considered
+
+- **Option A — PostCompact re-injects the FULL snapshot body (plan text, CLAUDE.md excerpt, ceremony script contents) into `additionalContext`.** Rejected: injecting raw file bodies into the model context is a prompt-injection surface (a malicious plan label or a crafted filename could carry instructions); it also bloats the just-compacted context, defeating the compaction. The hook should re-anchor, not re-inflate.
+- **Option B — PreCompact snapshots to the plan scratchpad; PostCompact reinjects POINTERS ONLY (sanitized, clamped, bounded), telling the model WHERE to look, not WHAT the files say.** ADOPTED. The pointers-only doctrine below is the invariant.
+
+## Decision
+
+**The compaction-continuity pair.**
+
+1. **PreCompact snapshots to the plan-scoped scratchpad.** `check_precompact_continuity.py` writes ONE JSON blob under the scratchpad key `compaction_continuity` (`set` overwrites the prior snapshot) containing: `plan_id`, `execution_unit` (`{plan_path, line, label}` — sanitized + clamped), `ceremony_flags` (sanitized repo-relative `finish-*.sh` paths, bounded to 5), and `hmac_chain` (`{chain_length, last_hmac_prefix}` — the HMAC anchor is READ-ONLY and only the first 12 hex chars of the last-hmac are kept: enough to detect a post-compaction chain divergence, not enough to be a forgery oracle). The plan-id is derived from the audit-log `plan_transition` events via `scratchpad_lib.resolve_plan_id` — NEVER from an env var (agent-spoofable, consensus M2). The HMAC-sidecar reads respect the audit filelock (best-effort; a one-event race on an advisory anchor is harmless).
+
+2. **PostCompact reinjects POINTERS ONLY (pointers-only doctrine — NORMATIVE).** `check_postcompact_reinject.py` reads the snapshot and emits `hookSpecificOutput.additionalContext` carrying a bounded (≤9) list of governance POINTERS: a durable Gate-1 re-read reminder (always present), the active PLAN id, the execution-unit position, the pending-ceremony breadcrumbs, the HMAC anchor (integrity reference only), and the scratchpad address for the full detail. It NEVER injects file CONTENTS (plan body, CLAUDE.md text, a ceremony script's body) — that is the Option-A injection surface. Every value is sanitized to printable-ASCII + clamped (the closeout-guard `_sanitize_path` hardening, Codex S228 P0). The model is told WHERE to look, not WHAT the files say.
+
+3. **Closed-enum audit, never the body.** PreCompact emits ONE `compaction_continuity_snapshot` (caller fields: `trigger` ∈ {manual, auto, other}, `plan_id` PLAN-NNN-or-`unknown`, `chain_length` clamped int, `snapshot_outcome` ∈ {written, scratchpad_unavailable, error, other}). PostCompact emits ONE `compaction_context_reinjected` (caller fields: `plan_id`, `snapshot_found` bool, `snapshot_age_s` clamped int, `pointer_count` 0..9). Both route through dedicated deny-by-default scrub branches + per-action allowlists (`_COMPACTION_CONTINUITY_SNAPSHOT_ALLOWLIST` / `_COMPACTION_CONTEXT_REINJECTED_ALLOWLIST`), NEVER `_EMIT_GENERIC_PASSTHROUGH`. The snapshot body and the reinjected pointer TEXT are NEVER on the audit wire — the wire carries closed enums + counters only.
+
+**Fail-open §5 everywhere.** Both hooks are ADVISORY and fail-open: a parse error, a plan-id derivation failure, a missing scratchpad, or a budget-blown subprocess emits a stderr breadcrumb + `{}` and never blocks a compaction. A crashed snapshot must not stop the harness from compacting. **Kill-switch:** `CEO_COMPACTION_CONTINUITY=0` disables both halves.
+
+## H2 coverage boundary
+
+The H2 ConfigChange guard (`.claude/hooks/check_config_change.py`) audits and
+advisory-blocks out-of-band `settings.json` tamper — the class S197 proved is
+invisible to the rail (settings/config is not canonical-guarded; an edit to
+`settings.local.json` left no trace). H2 resolves the multi-layer settings via
+the shared `_lib/effective_config` resolver (the same FORBIDDEN-KEYS single
+source W1 S3 uses) and, on a `ConfigChange` event, emits
+`config_change_observed` on the benign path or `config_change_forbidden_key`
+(one per tamper class) with a `{"decision":"block",...}` decision on the
+forbidden-key path, so the operator sees the tamper at the moment of the edit
+rather than only at the next boot.
+
+**The honest limitation (debate R1 — stated here, not buried).** H2 is itself
+a hook, and a governance hook has two structural blind spots that no amount of
+hook logic can close:
+
+1. **Self-disarm.** `disableAllHooks` is precisely one of the forbidden keys
+   H2 polices — but once that key lands in any settings layer, *no* further
+   `ConfigChange` hook runs. A single same-session edit that sets
+   `disableAllHooks: true` can therefore slip past H2 if the harness applies
+   the disarm before re-dispatching the event. H2 catches the *first* such
+   edit it observes; it cannot catch the one that disarms it.
+2. **Outside-harness blindness.** A text editor (or any non-Claude process)
+   writing a settings file on disk fires no `ConfigChange` event at all. H2
+   only ever sees changes that flow through the harness.
+
+**This is by design, not a defect to fix in W2.** H2 is a near-real-time
+*detector* of in-harness config tamper, not a *guarantee* of config
+integrity. The named compensators are independent channels that close the
+window H2 cannot:
+
+- **S3 boot tripwires** (W1 — `/ceo-boot` `check_settings_tamper_tripwires`):
+  on the NEXT boot, S3 re-scans the RESOLVED multi-layer settings (including
+  the gitignored, sentinel-blind `settings.local.json`) plus the import-time
+  env snapshot, using the same `_lib/effective_config` classifier. Anything
+  H2's same-session window missed — including an edit that disarmed H2 itself
+  — surfaces at the next session start. S3 is advisory and fires next boot, so
+  there is a same-session lag, but the tamper does not stay hidden.
+- **W5 O10 OTEL hook-execution witness** (PENDING — cut-2 risk): an
+  out-of-band record that a hook actually ran, independent of the hook's own
+  fail-open emit. O10 is the channel that detects the degraded-rail state
+  (hooks present on disk but not executing) that the self-disarm produces.
+  Until O10 lands, the same-session disarm window is real and documented.
+
+**Surface scope (narrower than S3, deliberately).** H2 block-scopes only the
+settings-FILE surfaces a `ConfigChange` event represents — the `user` /
+`project` / `local` / `managed` layers. The process-`env` snapshot and the
+on-disk hook census are S3's boot surfaces, not a settings-file change, so H2
+treats env/census findings as observe-only and never blocks on them (a
+settings layer's *own* `env` block IS a settings-file change and IS in scope,
+classified under that layer's name). This keeps H2's block authority tied
+exactly to what a `ConfigChange` event means, and avoids H2 and S3 fighting
+over the same finding at different lifecycle moments.
+
+**Audit faithfulness.** Both `config_change_observed` and
+`config_change_forbidden_key` route through their dedicated deny-by-default
+`_scrub_` branch + per-action allowlist in `audit_emit` (NEVER
+`_EMIT_GENERIC_PASSTHROUGH`). The changed file's PATH and BODY, any settings
+key or value (an attacker endpoint URL, an off-allowlist model id, an
+`apiKeyHelper` path, a dangerously-flag value), and the `effective_config`
+finding DETAIL string are NEVER persisted on the audit wire; only the
+closed-enum `tamper_class` + `layer` + a clamped integer `finding_count`
+travel. The block decision's `reason` likewise names the tamper CLASS and
+LAYER only — never the finding detail — so the detail cannot leak through the
+decision channel the operator's terminal echoes. The same no-value-echo
+contract as `settings_tamper_detected`
+([[feedback-closed-enum-breadcrumb-must-not-echo-rejected-value]]).
+
+**Fail-open.** Every infra condition (resolver unavailable, classify failure,
+malformed stdin, missing settings) fails toward `{}` (allow) with a stderr
+breadcrumb — H2 NEVER manufactures a spurious block from an infra error. The
+only non-empty decision H2 ever returns is the forbidden-key block on a real,
+classified finding. Kill-switch: `CEO_CONFIG_CHANGE_GUARD=0`.
+
+Recorded in `THREAT-MODEL-WORKSHEET.md` §2 and `HONEST-LIMITATIONS`.
+
+## Consequences
+
+- **(+)** Protocol amnesia by compaction closes: after any compaction the model is re-anchored on the active PLAN, the execution-unit position, the Gate-1 reads, and any pending Owner ceremony — without re-inflating the just-compacted context.
+- **(+)** Native-under-rail (Doctrine 1): the compaction lifecycle (a harness-native event) becomes a governance surface UNDER the hook rail; no native control is retired.
+- **(+)** Two NEW closed-enum actions (`compaction_continuity_snapshot` + `compaction_context_reinjected`) carry closed enums + counters only — the snapshot body and the reinjected pointers never reach the audit wire.
+- **(−)** Two NEW hook files (`check_precompact_continuity.py`, `check_postcompact_reinject.py`) + two NEW harness events registered in BOTH settings surfaces (dual-merge parity, S228) + 2 new actions (count consolidation: shared W2 count/SHA pins) + the SPEC v2.43 rows. The CLAUDE.md hook-count doc gates move (`48 Python hook scripts` → +2; `39 registered hooks` → +2) at closeout.
+- **(~)** `PreCompact`/`PostCompact` are now live governance surfaces. The `additionalContext` reinjection is bounded by the pointers-only doctrine; widening it to inject any file body requires amending this ADR.
+
+## Residual risks
+
+- **Fires-proof is PENDING-LIVE.** Auto-compaction is hard to force offline and a real `claude -p` compaction cycle is a paid action; the `$0` `probe_hook_events_fire.py` proves the breadcrumb-assert harness MECHANICS but not that the installed CLI actually emits `PreCompact`/`PostCompact`. The real per-event fire-assert is the W2 ceremony rehearsal (the printed recipe). This is the honest boundary of a $0 probe and is exactly the Doctrine 3 "registered ≠ fires" risk H1 flags but cannot itself retire at $0.
+- **Snapshot staleness.** A snapshot from a prior session (same plan scope) could be read post-compaction in a new session. PostCompact records `snapshot_age_s` and flags a >12h snapshot as possibly-stale in the reinjected pointers; the operator verifies plan state before relying on the unit pointer. The durable Gate-1 reminder is always reinjected regardless.
+- **Plan-id derivation can fail.** If the session has no `plan_transition` event yet, `plan_id` resolves to `unknown`, the scratchpad write is skipped (no plan scope to write into), and `snapshot_outcome=scratchpad_unavailable` / PostCompact `snapshot_found=False` — but the durable Gate-1 pointer is still reinjected. Fail-open by design.
+- **§H2 disarm window** (shared, above): a hook is disarmed by `disableAllHooks`; compensators are the S3 boot tripwires + the W5 O10 OTEL witness.
+
+## Blast radius
+
+L3+ — introduces two NEW harness lifecycle events (`PreCompact`, `PostCompact`) to the governance rail, two NEW closed-enum audit actions, and a NEW prompt-injection-bearing output channel (`additionalContext` reinjection, bounded by the pointers-only doctrine). Codex pair-rail review is mandatory for this unit (PLAN-135 plan line 622: "V2 Codex pair-rail (mandatory for W2 hooks)").