ceo-orchestration 1.0.0

package/.claude/adr/ADR-054-AMEND-1-anthropic-admin-key-tier.md

@@ -0,0 +1,131 @@
+# ADR-054-AMEND-1 — Anthropic Admin API key tier (admin blast radius ≠ inference blast radius)
+
+---
+adr_id: ADR-054-AMEND-1
+title: Anthropic Admin API key tier — categorically larger blast radius, own custody + cadence
+status: PROPOSED
+amends: ADR-054
+proposed_at: 2026-06-12
+proposed_by: CEO (PLAN-135 W5, unit O9)
+session_origin: PLAN-135 W5 exec session (branch plan-135-exec, 2026-06-12)
+risk_tier: B
+debate_required: true
+related_plans: [PLAN-135, PLAN-134]
+related_adrs: [ADR-054, ADR-150]
+---
+
+## §1 Scope
+
+ADR-054 ("GitHub Token Rotation Cadence", ACCEPTED 2026-04-18) defines the
+rotation schedule for the framework's credential classes: fine-grained PAT,
+classic PAT, `ANTHROPIC_API_KEY` (inference), `GITHUB_TOKEN`, NPM OIDC. It has
+**no Anthropic *Admin* API key class at all** — PLAN-135 W5 introduces one
+(`key-hygiene.py` Admin-API list/deactivate; O3 `cc-analytics-pull.py` is the
+read-only analytics consumer of the same tier), so the tier must be doctrined
+BEFORE any standing admin credential exists.
+
+This amendment ADDS the admin-key tier to ADR-054's table and custody rules.
+Every existing ADR-054 row and procedural rule is **unchanged**.
+
+## §2 The load-bearing doctrine
+
+**The Anthropic Admin API key's blast radius is categorically LARGER than
+inference keys — not a bigger quantity of the same risk, a different
+category.** Per `THREAT-MODEL-WORKSHEET.md` §3 (PLAN-135, debate R1):
+
+> Org-level Anthropic Admin API key — blast radius categorically larger than
+> inference keys: deactivate ALL org keys, read org-wide usage/cost.
+
+A leaked inference key burns quota (bounded by spend alerts; ADR-054 treats it
+as a 90-day-cadence vault secret). A leaked admin key (`sk-ant-admin…`, or an
+`org:admin` OAuth token) can **deactivate every API key in the organization**
+(an org-wide availability kill-switch — the S206 incident response weaponized
+against us) and **read org-wide usage/cost data** (cross-workspace privacy
+exposure). No spend alert bounds either. Therefore the admin tier gets
+strictly stronger custody than any row already in ADR-054 — quota-burn
+mitigations are NOT accepted as sufficient for this class.
+
+## §3 Amendment to the ADR-054 rotation table
+
+ADD one row:
+
+| Token class | Cadence | Target scope | Evidence |
+|-------------|---------|--------------|----------|
+| Anthropic Admin API key (`sk-ant-admin…`) | **Provision-on-demand, deactivate within 24h of use.** Any deliberately-standing admin key: 90-day rotation + quarterly necessity review (default answer: do not keep one) | Org key management + org-wide usage/cost read. **NEVER CI, NEVER repo, NEVER settings.json** | `docs/rotation-log.md` row per provision / use / deactivation (`key-hygiene.py` auto-appends the mutation rows — the audit pair) |
+
+## §4 Custody rules (per THREAT-MODEL-WORKSHEET.md §3 mitigations — normative)
+
+1. **Never in repo or settings.** The admin key lives in the OS keychain /
+   Owner-launch environment ONLY (`ANTHROPIC_ADMIN_KEY`), exported for the
+   single command that needs it. Its *name* (not value) is documented in
+   `docs/rotation-log.md`. `key-hygiene.py` deliberately exposes **no CLI
+   flag** for the key and redacts every `sk-ant-…`-shaped substring from all
+   error paths (the S206 urllib-trace leak class).
+2. **Read-only by default.** The O3 analytics client (`cc-analytics-pull.py`)
+   is READ-ONLY (analytics endpoints; no key-management writes) and fail-soft
+   when the key is absent.
+3. **Human gate on every mutation.** The `key-hygiene.py` deactivate path
+   requires interactive Owner confirmation (explicit `--confirm`; refusal
+   with zero network I/O without it) and writes a rotation-log entry — the
+   **audit pair**: no admin-key mutation without a paired append-only record.
+4. **No agent autonomy.** No agent, hook, workflow, or routine may invoke the
+   deactivate/incident path autonomously. `--confirm` is an Owner act.
+5. **WIF retires the long-lived CI inference secret.** With the GitHub-OIDC
+   federation path live (`docs/BRANCH-PROTECTION.md` §WIF, this same O9
+   unit), the standing-CI-secret class that motivated S206 shrinks toward
+   zero — and the admin key must never be its replacement in CI.
+
+## §5 Threat model (worksheet §3, verbatim-faithful)
+
+- **Threat actors:** (a) key leakage via repo/transcript/audit-log; (b) an
+  agent invoking `key-hygiene.py` destructively; (c) CI secret theft (the
+  S206 class).
+- **Attack vectors:** committed key; key echoed into transcripts;
+  `key-hygiene.py deactivate` called without a human gate; long-lived CI
+  secret reuse.
+- **Mappings:** vector 1-2 → custody rule 1 (env-only + redaction); vector 3
+  → custody rules 3-4 (`--confirm` + no-autonomy); vector 4 → custody rule 5
+  (WIF) + the table row's NEVER-CI scope.
+
+## §6 Residual risk (recorded, not mitigated here)
+
+A read-only analytics scope still reads **org-wide** usage — a privacy (not
+integrity) exposure. PLAN-135 §OQ4 puts the provisioning decision explicitly
+on the Owner: whether an admin-tier key exists at all, and with which scope,
+is an Owner call per provisioning event, not a framework default.
+
+## §7 Consequences
+
+- (+) The S206 incident response becomes one audited command
+  (`key-hygiene.py incident --confirm`) instead of a manual Console sweep.
+- (+) Auditors get an explicit tier for the highest-blast-radius credential
+  the org can mint, with evidence in the same append-only log as every other
+  class.
+- (−) Provision-on-demand adds ~2-5 min of Owner friction per admin
+  operation. Accepted: admin operations are rare (incidents, quarterly
+  reviews) and the friction IS the control.
+- (~) ADR-054's existing rows, procedures, and residuals (`RR-1` markdown
+  ledger falsifiability) are unchanged and inherited by the new row.
+
+## §8 Promotion gates + revisit triggers
+
+Stays PROPOSED until the PLAN-135 W5 ceremony (debate per plan §W5 "O9's
+ADR — each needs its ceremony" + Codex pair-rail + Owner-GPG sentinel on the
+canonical `.claude/adr/` copy).
+
+Revisit when: (a) Anthropic ships finer-grained admin scopes (split
+key-management from usage-read → re-tier); (b) the first standing admin key
+is provisioned (necessity review becomes live, not hypothetical); (c) a WIF
+path exists for admin-scoped operations (would retire the standing-key
+question entirely).
+
+## References
+
+- `.claude/adr/ADR-054-github-token-rotation.md` — the amended base
+- `.claude/plans/PLAN-135/research/THREAT-MODEL-WORKSHEET.md` §3 admin-keys
+- `.claude/plans/PLAN-135-anthropic-surface-harvest.md` §W5 O9
+- `.claude/scripts/key-hygiene.py` — list/deactivate/incident + audit pair
+- `docs/BRANCH-PROTECTION.md` §"WIF — keyless CI via GitHub OIDC"
+- `docs/rotation-log.md` — 2026-06-03 S206 compromise row (the motivating
+  incident)
+- ADR-150 — commit-signing policy (sibling credential-provenance doctrine)

package/.claude/adr/ADR-054-github-token-rotation.md

@@ -0,0 +1,111 @@
+# ADR-054: GitHub Token Rotation Cadence
+
+**Status:** ACCEPTED
+**Date:** 2026-04-18 (PLAN-025 Batch G)
+**Deciders:** CEO, DevOps & Platform Engineer, Principal Security
+**Blast radius:** L2 (procedural; no code change)
+**Supersedes:** none
+**Superseded by:** none
+
+## Context
+
+The framework uses GitHub tokens in 4 contexts:
+
+1. **`GITHUB_TOKEN`** (workflow-scoped): automatic per-workflow token
+   provided by GitHub Actions. No rotation needed; scoped + ephemeral.
+
+2. **`ANTHROPIC_API_KEY`** (repo secret): Claude API credential used
+   by `adapter-live.yml` + any dogfooding session. Rotation tracked
+   in `docs/rotation-log.md` (shared secret in org secret vault).
+
+3. **Personal Access Tokens (PATs)** — used by Owner for local dev +
+   CI access when `gh` CLI operates against the repo. These are
+   long-lived by default and need explicit rotation.
+
+4. **NPM publish token** (OIDC-provenanced, workflow-scoped):
+   `npm-publish.yml` exchanges GitHub OIDC for a short-lived NPM
+   token. No long-lived secret stored.
+
+PLAN-024 F-wf-001 flagged that the framework documents SHA-pinned
+actions + fork-safe triggers + least-privilege permissions, but had
+no explicit policy for GitHub PAT rotation. SOC2 auditors and
+adopter operators both need a documented cadence to audit against.
+
+## Decision drivers
+
+1. **GitHub's own recommendation** — rotate PATs at least every 90
+   days; fine-grained tokens with explicit expiration are preferred
+   over classic PATs.
+2. **Adopter audit readiness** — SOC2 Type II + ISO 27001 both
+   expect a documented rotation cadence with evidence of execution.
+3. **Dogfood reality** — the framework Owner uses `gh` daily via a
+   classic PAT; forcing overly-short rotation creates friction that
+   leads to rotation-skipping.
+4. **Blast radius** — a leaked PAT has write access to the repo;
+   the `CEO_SOTA_DISABLE=1` + CODEOWNERS chain limits damage but
+   doesn't revoke write access. Rotation + token-scoping are
+   complementary.
+
+## Decision
+
+**Adopt the following rotation schedule:**
+
+| Token class | Cadence | Target scope | Evidence |
+|-------------|---------|--------------|----------|
+| Fine-grained PAT (preferred) | 90 days | repo-only, Contents:read, Actions:read/write | `docs/rotation-log.md` entry per rotation |
+| Classic PAT (legacy) | 60 days | `repo` + `workflow` | `docs/rotation-log.md` entry per rotation |
+| `ANTHROPIC_API_KEY` | 90 days | API-key vault only | `docs/rotation-log.md` §ANTHROPIC |
+| `GITHUB_TOKEN` | N/A (auto per-run) | workflow-scoped | GitHub Actions log |
+| NPM publish (OIDC) | N/A (exchanged per-run) | workflow-scoped | `npm-publish.yml` provenance |
+
+**Key procedural rules:**
+
+- Every rotation writes a one-line entry to `docs/rotation-log.md` with:
+  date (UTC ISO-8601), token class, old-fingerprint (last 4 chars),
+  new-fingerprint (last 4 chars), rotator handle.
+- The old token is REVOKED within 24h of the new one taking effect.
+- On rotation-skip (365 days without rotation): the Owner reviews
+  and either rotates or documents a justified exception in the
+  rotation log under `### Known-long-lived`.
+- Fine-grained PATs are PREFERRED over classic PATs. New tokens MUST
+  be fine-grained unless a workflow requires classic-PAT scopes.
+
+## Consequences
+
+### Positive (+)
+
+- Explicit cadence that adopter auditors can verify.
+- Rotation-log entries enable forensic reconstruction of "which
+  token signed commit X" post-incident.
+- Fine-grained preference narrows blast radius per-token.
+
+### Negative (−)
+
+- 60-90 day rotation cadence adds ~5-10 min of Owner overhead per
+  quarter. Acceptable for a one-Owner project.
+- Rotation-log is markdown, not a signed ledger; a Tier-2 insider
+  with repo write could falsify entries. Documented as residual per
+  threat-model §RR-1.
+
+### Neutral (~)
+
+- No code change. Pure procedural/policy documentation.
+- Existing `docs/rotation-log.md` format unchanged.
+
+## Revisit trigger
+
+- First rotation-skip incident reveals the cadence is unrealistic
+- SOC2 Type II auditor requests tighter cadence (e.g. 30 days)
+- GitHub deprecates classic PATs entirely
+
+## References
+
+- `docs/rotation-log.md` — rotation history (append-only)
+- `SECURITY.md` §Known residuals — token rotation policy link
+- `docs/threat-model.md` §RR-1 — workstation compromise scenario
+- PLAN-024 F-wf-001 — originating finding
+- `.github/workflows/shadow-ci.yml` — token-rotation-aware workflow
+
+## Enforcement commit
+
+`1ae10b63b783` (retrofit — PLAN-050 Phase 2 / PLAN-045 F-06-03; this anchors the file's introduction commit, not a runtime-behavior commit. For ADRs whose decision was wired into hooks/scripts in a later commit, amend this line manually.)

package/.claude/adr/ADR-055-AMEND-1-spool-writer-async-drain.md

@@ -0,0 +1,170 @@
+---
+id: ADR-055-AMEND-1
+title: ADR-055 §Components amendment — multi-PID spool-writer with async drain + 4-tuple total order
+status: ACCEPTED
+proposed_at: 2026-05-14
+proposed_by: CEO (S121 lineage correction; PLAN-094 §5 ceremony)
+accepted_at: 2026-05-14
+accepted_by: "Owner (post-Codex-Pair-Rail-iter-7-ACCEPT 2026-05-14; thread 019e2655-76e9-7591-8330-778a25a63053 gpt-5.5; canonical-promotion sentinel at .claude/plans/PLAN-094/architect/round-1/approved.md GPG-signed 0000000000000000000000000000000000000000)"
+amendment_of: ADR-055 (Audit-log HMAC chain for tamper detection — 2026-04-18 via PLAN-023)
+amends_section: §Components §3 (audit_emit FileLock-internal HMAC integration) + §Canonicalization contract (4-tuple total-order extension for spool-era entries)
+veto_floor: ADR-052 (security-engineer VETO — audit-log integrity)
+codex_pair_rail: required per ADR-107 §Pair-Rail mechanics; model=gpt-5.5 is advisory S120 process lesson, not load-bearing on ADR-107
+related_plans: [PLAN-023, PLAN-094]
+related_adrs: [ADR-055, ADR-053, ADR-052, ADR-107, ADR-108, ADR-115, ADR-124, ADR-125, ADR-043, ADR-005]
+supersedes: []
+amends:
+  - target: ADR-055 §Components §3 (_lib/audit_emit.py kernel-guarded HMAC integration)
+    original_clause: "integrates HMAC compute+write INSIDE the existing FileLock block. Read-modify-write sequence atomic against concurrent subprocess writes (chain-fork defect avoided)."
+    amended_clause: "Writes go to a per-PID spool file fsync'd outside the canonical FileLock; a deferred _drain_spool() step under FileLock atomically renames each spool to a .draining suffix (race-free vs concurrent writers), reads + sorts entries by 4-tuple (wall_ns, pid, spool_uuid, ordinal_within_file), reconstructs prev_hmac from canonical-log TAIL (NOT sidecar — idempotent under partial-crash), computes HMAC chain, atomically appends + fsyncs to canonical log, updates sidecar as cache, releases lock. Chain-fork defect remains avoided (FileLock still serializes chain extension); per-emit critical path no longer pays canonical-log fsync."
+  - target: ADR-055 §Canonicalization contract
+    original_clause: "Any future field that participates in the HMAC MUST be: serializable by canonical_json.encode; NFC-normalized at emit time; introduced via SPEC/v1 audit-log.schema.md bump (additive)."
+    amended_clause: "...AND for NEW spool-era entries only (pre-spool-era v1.6.0..v1.25.0 HMAC-bearing entries remain verifier-valid under ADR-055 §Backward compatibility transition rule): the 4-tuple total-order key (wall_ns int, pid int, spool_uuid str, ordinal_within_file int) MUST be present on every entry pre-HMAC-compute. The spool_uuid is a per-spool random nonce (16-hex from secrets.token_hex(8)) in the spool header line, matched by every body entry. Drain validates 4-tuple presence + monotonicity + uniqueness before chain extension."
+tags: [governance, audit-log, perf, async-drain, spool-writer, amendment, anti-churn, s121-lineage-corrected]
+authorization: PLAN-094 Wave A atomic ceremony (gated by this AMEND-1 ACCEPTED)
+target_telemetry_window_days: 30
+revert_trigger_hmac_break_rate: 0.001
+---
+
+# ADR-055-AMEND-1 — Multi-PID spool-writer with async drain
+
+## §1. Status
+
+PROPOSED at draft time (PLAN-094 §5 ceremony — S121 lineage correction).
+Flips to ACCEPTED at the PLAN-094 Wave A atomic ceremony commit, gated by:
+
+1. Codex MCP Pair-Rail review per ADR-107 §Pair-Rail mechanics (audit-log durability is veto-floor; ACCEPT before status flip)
+2. ADR-052 security-engineer VETO consensus on spool durability + 4-tuple total-order design
+3. ADR-055 canonical edit `## Amended-by` cross-ref appendix in the SAME commit (sentinel `.claude/plans/PLAN-094/architect/round-1/approved.md` + `.asc` GPG by Owner 00000000)
+
+Wave A implementation lands AFTER ACCEPTED + PLAN-092/093 `status: done`.
+
+## §2. Context
+
+**Driver**: PLAN-090 AC9c spawn-hook +19.5ms p95 regression (vs `.claude/plans/PLAN-090/baseline-pre-wave-a-perf.json` p95=53.73ms / p99=55.46ms) blocking PLAN-090 close. ADR-055 §Components §3's "~15-25µs added inside the FileLock" cost (single-writer assumption) compounds to +19.5ms p95 under 6 concurrent hook subprocesses contending on canonical-log FileLock + per-emit fsync.
+
+PLAN-094 Wave A redesigned writer as durable spool + drain-on-next-invoke. Original ADR-055 §Components §3 wording ("HMAC compute+write INSIDE the existing FileLock block") directly contradicts this redesign; ADR-115 maintenance-mode requires explicit amendment over silent override.
+
+**Lineage correction (S121 2026-05-14)**: S119 R2 iter-5 ACCEPT approved this proposal under wrong predecessor (`ADR-040-AMEND-3-async-flush-semantics`). ADR-040 governs Live Adapter (credential/cost/cascading) — orthogonal to audit-log writer durability. Codex gpt-5.5 caught the error during S120 ADR-127 R2 (thread `019e23c0`). ADR-055-AMEND-1 is the corrected predecessor. AMEND-1 is correct numbering (no prior ADR-055 amendments exist on disk).
+
+## §3. Decision drivers
+
+- **Per-emit critical path budget**: original design's 1 fsync per emit × 18 concurrent emits = 18 fsyncs/cycle. Spool-writer amortizes to 1 canonical-log fsync per drain (every ≥100ms or ≥50 events).
+- **Anti-churn (ADR-115)**: original Components §3 single-writer FileLock design was deliberate. Structural change requires explicit amendment.
+- **HMAC chain integrity preservation**: 4-tuple `(wall_ns, pid, spool_uuid, ordinal_within_file)` replaces FileLock-serialization-of-chain. PID + spool_uuid (16-hex nonce per spool, distinct across PID-recycle) + ordinal_within_file break wall-clock collisions (NTP slew acknowledged, not pretended-away).
+- **Reversibility**: `CEO_AUDIT_SYNC_MODE=1` reverts WRITER to sync-fsync-per-call (behavioral, NOT byte-identical — spool-era canonical entries persist on disk; Tier-B per ADR-125).
+- **VETO-floor mandate (ADR-052)**: audit-log integrity changes are security-engineer VETO; Codex Pair-Rail ACCEPT required.
+
+## §4. Decision (the amendment)
+
+### §Components §3-amended
+
+> **`_lib/audit_emit.py`** (kernel-guarded) writes to a per-PID spool file `~/.claude/projects/<slug>/state/audit-spool.<pid>.jsonl` (sequential append + fsync; ~0.2-1ms p99 SSD). A deferred `_drain_spool()` step — triggered on emit when `spool_tail_mtime > 100ms ago` OR `spool_size > 50 events` — runs a **5-phase atomic protocol**:
+
+**Phase 1 — Lock acquisition** (deadlock-free): drain acquires canonical `audit-log.jsonl` FileLock. Writers acquire only their own spool's flock + journal's flock. No writer holds canonical FileLock; no AB-BA cycle.
+
+**Phase 2 — Stale `.draining.*` sweep + atomic rename + header validation**:
+- Step 2a: scan state dir for pre-existing `audit-spool.*.draining.*` files from previous crashed drains; merge into current batch preserving each entry's original `_drain_epoch`
+- Step 2b: assign `drain_epoch = secrets.token_hex(4)`; atomically rename each `audit-spool.<pid>.jsonl` → `audit-spool.<pid>.draining.<drain_epoch>` (POSIX rename atomic; concurrent writers miss the file and create fresh spool with new `_spool_uuid`)
+- Header validation: read first line, verify well-formed JSON with `_spool_uuid` / `_pid` / `_created_wall_ns` / `_created_monotonic_ns`; validate `header._spool_uuid == body[0].spool_uuid` (cheap sentinel; full-body invariant enforced transitively via HMAC input); mismatch → quarantine that file only (`.malformed.<drain_epoch>` + `audit_spool_tamper_detected` forensic)
+
+**Phase 3 — Sort + 4-tuple uniqueness**:
+- Read body lines (skip header)
+- Sort by `(wall_ns, pid, spool_uuid, ordinal_within_file)`
+- Reject duplicate full 4-tuples (`audit_spool_duplicate_tuple_rejected`)
+
+**Phase 4 — Idempotent chain reconstruction**:
+- **Reconstruct `prev_hmac` from canonical-log TAIL**, NOT sidecar — sidecar is a CACHE; canonical log is source of truth
+- Hard batch cap K_MAX=100 entries; skip-guard search window K_TAIL_WINDOW=200
+- **Skip-already-drained guard**: for each entry's `sha256_of_canonical_json_bytes`, check against last K_TAIL_WINDOW `_drain_sha256` values of canonical tail; hit → already drained (idempotent retry)
+- **Unexpected-skip forensic**: in steady-state, skip should NEVER fire. Emit `audit_spool_unexpected_skip` with severity branching: `drain_in_recovery_mode=True` → INFORMATIONAL; `False` → CORRECTNESS ALARM (drain bug or canonical-tail tamper; ≥3 alarm-severity in 24h → Wave A rollback)
+- Compute HMAC chain via `_lib/audit_hmac.compute_entry_hmac()` (UNCHANGED primitive)
+- Each canonical entry carries 2 additional fields: `_drain_sha256` + `_drain_epoch` (idempotence marker + crash-cycle traceability)
+- **Trust boundary for `_drain_sha256`**: deterministic idempotence marker, NOT authenticity proof. Fake-injection requires audit-key compromise (same envelope as forgery); skip-guard correctness depends on canonical-tail integrity = same trust envelope as HMAC chain. NO new trust surface.
+
+**Phase 5 — Atomic append + atomic split + cleanup**:
+- Atomically append remaining entries + single canonical fsync
+- Update `audit-log.last-hmac` sidecar via `write_last_hmac()` (CACHE only) + increment `audit-log.chain-length` canary
+- For each `.draining.<drain_epoch>` file: if fully consumed → unlink; if partially consumed → **atomic split** (preserves original header verbatim + writes unconsumed remainder to `.tmp` → fsync → atomic rename to `.draining.<new_epoch>` → unlink original; preserves `header._spool_uuid == body[i].spool_uuid` invariant; preserves `_drain_sha256` reproducibility)
+- Single-cycle invariant: each Phase 5 completion leaves AT MOST ONE valid `.draining.*` per spool with ONLY unconsumed entries. Under N-consecutive partial crashes, no entry appears twice in K_TAIL_WINDOW.
+- Drain bounded ≤5ms p99 for ≤50 entries (PLAN-094 AC9); ≤20ms p99 for ≤K_MAX=100
+
+**Quarantine recovery (non-wedging)**: per-spool-file quarantine; one bad spool isolated, others continue drain. Owner-driven inspection + replay or archive. Chain extension never blocked by quarantine; affected events counted in `truly_lost`.
+
+### Loss accounting (best-effort journal — NOT load-bearing on correctness)
+
+Per-PID journal `state/audit-pending.<pid>.journal` with buffered appends (Python `buffering=8192`); journal fsync every 100ms OR 10 emits (amortized via drain trigger). Envelopes: `{record_id, spool_uuid, ordinal_within_file, sha256_of_line, op, drain_epoch_at_commit}` (NO `journal_hmac` chain — file perms 0600 + audit-key co-location SAME trust as ADR-055 §Threat model). Two-phase begin/commit per emit; drain Phase 5 appends `op:"drained"`. Session-start "forensic aggregation" sweep (aggregation lock; winner-takes-all + idempotent rename). 6-counter session report: `audit_flush_dropped_count(begin_no_commit, commit_no_drained, recovered, truly_lost, tamper_rejected, intentionally_deleted)`.
+
+Hot-path cost reduces from iter-2's 3 fsyncs to 1 fsync per emit (spool only).
+
+### New audit events (registered via Wave 0 `_KNOWN_ACTIONS`; Sec MF-3 whitelisted fields)
+
+`audit_flush_dropped_count` (6-counter) · `audit_spool_stale_recovered` · `audit_spool_partial_line_discarded` · `audit_spool_tamper_detected` (`mismatch_kind ∈ {sha256_mismatch, missing_commit_envelope, malformed_spool_header, header_body_uuid_mismatch}`) · `audit_spool_duplicate_tuple_rejected` · `audit_spool_intentionally_deleted` · `audit_spool_unexpected_skip` (severity-branched)
+
+### §Canonicalization contract-amended
+
+EXTENDED (not replaced) — scoped strictly to NEW spool-era entries; pre-spool-era v1.6.0..v1.25.0 entries remain verifier-valid under ADR-055 §Backward compatibility transition rule. New requirement: 4-tuple `(wall_ns, pid, spool_uuid, ordinal_within_file)` present pre-HMAC-compute on every spool-era entry.
+
+**Verifier transition contract**: `audit-verify-chain.py` is EXTENDED in Wave A (exit-code contract UNCHANGED 0/1/2/3/4; new sub-code under exit 1 for spool-era transition violation). One-way rule: first `spool_uuid` entry locks subsequent entries to full 4-tuple + `_drain_sha256`. A v1.25.0-era entry (no 4-tuple) appearing AFTER a spool-era entry is `transition_violation`. Wave A test delta enumerated in editorial draft (22 tests T1..T22).
+
+## §5. Revert path
+
+**Behavioral rollback (NOT byte-identical — Tier-B per ADR-125)**:
+
+- `export CEO_AUDIT_SYNC_MODE=1` reverts WRITER to pre-Wave-A sync-fsync-per-call (matches original ADR-055 §Components §3 byte-for-byte).
+- **Clean rollback requires log rotation** immediately after env flip: spool-era 4-tuple entries on canonical log create transition-rule violation forensic signal if a non-4-tuple entry appears AFTER. Old-verifier (pre-Wave-A) ignores additive fields cleanly; chain still verifies internally; transition rule not enforced.
+- `git revert` Wave A commit if module-code bug; status flip → `SUPERSEDED-BY-REVERT`; Owner GPG-signed commit; no new ADR.
+
+**Revert triggers (any one)**:
+1. HMAC chain break rate > 0.1% over 30-day window (auto-revert via `ceo-health`)
+2. Single critical-severity incident: drain lock contention caused production tool-call timeout
+3. `truly_lost > 0` over 7-day window (disk fault; forensic alarm)
+4. Owner explicit revert directive
+
+## §6. Consequences
+
+**Positive**: PLAN-090 AC9c +19.5ms p95 regression closed; HMAC chain integrity preserved (FileLock-serialized extension); multi-PID concurrent writer support explicit; new forensic events; behavioral reversibility; new tamper-detection forensics extending ADR-055 §Threat model.
+
+**Negative**: additional filesystem objects (`audit-spool.<pid>.jsonl` + per-PID journals; gitignored; 7d stale TTL); drain bounded ≤5ms p99 adds latency to every Nth emit; spool format is new ABI surface (JSON; forward+backward compatible).
+
+**Neutral**:
+- ADR-055 §Components §2 (`_lib/audit_hmac.py`) UNCHANGED. Cryptographic primitive preserved. Sidecar reduced to CACHE (canonical-tail reconstruction handles staleness).
+- ADR-055 §Threat model defenses PRESERVED. Spool-level tamper detected via Phase 4 sha256 skip-guard reconciliation + Phase 2 header validation (NOT journal HMAC envelope; iter-3 dropped journal chain after compaction race + perf budget findings).
+- ADR-055 §Backward compatibility EXTENDED: existing v1.6.0 transition rule unchanged; NEW v1.25.0 → spool-era one-way transition rule applies.
+- **Forensic ordering change**: HMAC chain order shifts from FileLock-acquisition-order (original §3) to 4-tuple drain-sort-order (this amendment). `audit-verify-chain.py` exit-code contract UNCHANGED; internal logic EXTENDED. OTEL anchor follow-up (ADR-055 §Out of scope) MUST anchor drained entries in drain-order. INCIDENT-RESPONSE forensics: emit-time order recoverable from spool BEFORE drain truncates (7d TTL window).
+
+## §7. Authorization + anti-churn scope
+
+ADR-055-AMEND-1 is a doctrine ADR (documentation + ABI extension); runtime artifact is PLAN-094 Wave A. Acceptance ceremony = atomic commit + Owner GPG (`feedback_sentinel_signing_discipline.md`).
+
+**Anti-churn scope justification**: this amendment is in-scope via **ADR-124 §Part 2 mechanical scope test** — maps to canonical roadmap item R-037 (audit_emit fsync chain-decoupling at `.claude/plans/PLAN-084/canonical/PLAN-084-evolution-roadmap.md:214`). Driver is PLAN-090 AC9c regression evidence linking to R-037 burn-down. **ADR-115 §exception #1 is NOT the scope path** — that exception is P0 security only.
+
+NO `CEO_KERNEL_OVERRIDE` required (ADR-055 file not in `_KERNEL_PATHS`). PLAN-094 Wave A's ADR-055 `## Amended-by` appendix IS canonical-guard path (sentinel-signed via standard `approved.md` + `.asc` pattern).
+
+## §8. Related work
+
+- **ADR-055** — Audit-log HMAC chain (original 2026-04-18); §Components §3 extended; §Canonicalization gains 4-tuple
+- **ADR-053** — Sentinel HMAC (deferred; complementary trust boundary; this amendment does NOT touch sentinel scope)
+- **ADR-052** — VETO floor (security-engineer authority)
+- **ADR-107** — Pair-Rail asymmetric VETO matrix (ACCEPT verdict required; gpt-5.5 model is S120 advisory)
+- **ADR-108** — Pair-Rail dispatcher protocol
+- **ADR-115** — maintenance-mode doctrine (NOT scope path — see §7)
+- **ADR-124** — post-audit-SOTA-execution-mode (§Part 2 mechanical scope test = scope path)
+- **ADR-125** — risk-tiered defaulting (this amendment = Tier-B)
+- **ADR-043** — SOC2 audit-trail mapping (SPEC/v1 schema bump review)
+- **ADR-005** — Event-stream v2 (new `audit_spool_*` actions; schema alignment review)
+- **PLAN-094** — Wave A implementation (gated by this AMEND-1 ACCEPTED); editorial draft at `.claude/plans/PLAN-094/ADR-055-AMEND-1-draft.md` (981 LoC, Codex R2 thread `019e2655-...` 7-iter ACCEPT)
+- **PLAN-090 AC9c** — spawn-hook +19.5ms p95 regression (driver)
+- **PLAN-023** — original ADR-055 plan of record
+- `_lib/audit_emit.py` — Wave A implementation site
+- `_lib/audit_hmac.py` — UNCHANGED (cryptographic primitive preserved)
+- `_lib/canonical_json.py` — UNCHANGED
+- `audit-verify-chain.py` — exit-code contract UNCHANGED; internal logic EXTENDED in Wave A
+
+## §9. Enforcement commit
+
+This amendment ADR is documentation + ABI specification. Runtime enforcement ships at PLAN-094 Wave A ceremony commit. ADR-055 `## Amended-by` appendix lands in the SAME commit. Both SHAs recorded in PLAN-094 progress log §11.
+
+---
+
+**Editorial reference**: `.claude/plans/PLAN-094/ADR-055-AMEND-1-draft.md` (981 LoC; full design rationale, fold logs across 7 Codex R2 iterations, expanded 22-test Wave A delta). This canonical is field-by-field equivalent (S120 doctrine), NOT byte-identical.

package/.claude/adr/ADR-055-AMEND-2-chain-reset-marker.md

@@ -0,0 +1,126 @@
+---
+id: ADR-055-AMEND-2
+title: HMAC chain rotation chain_reset_marker + rotation manifest sidecar
+status: ACCEPTED
+decision_date: 2026-05-21
+accepted_at: 2026-05-28
+accepting_session: S181
+authorization: "PLAN-118 WS-D Wave-A debate 0 VETO (security-engineer PROCEED + identity-trust-architect PROCEED + qa-architect ADJUST→satisfied) + Codex promotion review thread 019e70af-9565-7742-9c54-c398be202bc5 (BLOCK on session test-pollution → resolved by final ceremonial rotation → ACCEPT-WITH-FIXES → ACCEPT zero-residual after 3 doc fixes) + Owner GPG 0000000000000000000000000000000000000000 on the commit bearing this change (signed at commit time). AC-D0 organic-soak prerequisite Owner-overridden per ADR-095 doctrine (vote-trigger leg-b independently MET — 8 rotation markers strictly post-v1.39.4-ship-commit 2026-05-21T15:19:54Z, ≥ the required 5; live chain verifies intact post-WS-E+rotation; both historical root causes fixed + class-guarded; precedent S179 AC-C0)."
+owner: security-engineer
+plan: PLAN-112-FOLLOWUP-hmac-tamper-fix
+amends: ADR-055
+related: [ADR-055, ADR-055-AMEND-1, ADR-010]
+vote_trigger_data_volume: "post-v1.39.4 ship + 30 days production rotation traffic OR 5 rotation events post-ship (whichever first)"
+---
+
+# ADR-055-AMEND-2 — chain_reset_marker + rotation-manifest sidecar
+
+**Status:** ACCEPTED (S181, 2026-05-28)
+**Enforcement commit:** `8952915` (PLAN-112-FOLLOWUP-hmac-tamper-fix Wave B.3 — `_emit_chain_reset_marker_under_lock` + rotation-manifest sidecar + verifier marker-required mode; shipped v1.39.4 `3e27c1d`). PLAN-118 hardening: AC-B4 producer-pollution chokepoints (`d89ec76`, S179) + WS-E float-leak class-closure (`09e9c51`, S181).
+
+## Context
+
+PLAN-112-FOLLOWUP-hmac-tamper-fix Wave A R1 debate (4 archetypes ADJUST_PROCEED) + Codex pair-rail R2 iter-4 ACCEPT identified that ADR-055 §2 ("Chain resets ONLY on file boundary") combined with spool drain Phase 4↔Phase 5 intra-lock ordering created an integrity gap: producer chained line 1 of new file from rotated archive's last_hmac while verifier (per ADR-055 §2) treated line 1 as genesis-anchored. Result: STATUS_TAMPER on live audit-log.jsonl after every spool-drain-triggered rotation. F-7.7 (PLAN-112).
+
+Wave B.1 (hoist rotation probe to Phase 4 start in spool_writer.py) closes the immediate bug. This amendment introduces defense-in-depth:
+
+1. **chain_reset_marker synthetic genesis entry** as line 1 of every rotation-created fresh audit-log.jsonl
+2. **audit-log.rotation-manifest.json sidecar** as local boundary scoping verifier marker enforcement
+
+## Decision
+
+### Producer requirement
+
+When `_rotate_if_needed_safe(log_path)` returns non-None `rotated_to`, producer MUST emit chain_reset_marker as line 1 of new audit-log.jsonl, atomically under canonical FileLock, BEFORE releasing lock.
+
+Marker fields:
+- `action: "chain_reset_marker"`
+- `previous_archive_path: <relative path>`
+- `previous_archive_last_hmac: <hex; "" if unrecoverable>`
+- `rotation_ts: <ISO-8601 UTC>`
+- `rotation_trigger: "size_threshold" | "manual" | "owner_rotation" | "quarantine_pre_fix"`
+- Standard event_schema v2 fields
+
+HMAC anchored at GENESIS_PREV (marker IS new chain genesis).
+
+Post-marker under same FileLock:
+1. `audit-log.last-hmac` ← marker HMAC
+2. `audit-log.chain-length` ← 1
+3. `audit-log.rotation-manifest.json` ← `{schema_version, rotated_at, previous_archive_filename, marker_line_count: 1}`
+
+### Verifier behavior
+
+`audit-verify-chain.py` MUST:
+1. Read `audit-log.rotation-manifest.json` from SAME directory as audit-log being verified (NOT _audit_dir_from_env — avoids test envs inheriting production state)
+2. Absent sidecar → legacy mode (ADR-055 §2 unchanged; first-install logs work as before)
+3. Present sidecar → marker-required: line 1 MUST have `action == "chain_reset_marker"`; else STATUS_TAMPER
+
+Verifier explicitly does NOT walk rotation archives (preserves ADR-055 §Non-goals "log = source of truth").
+
+## Backwards compatibility
+
+| Log shape | Manifest | Verifier mode |
+|---|---|---|
+| Pre-v1.39.4 | absent | legacy |
+| v1.39.4+ first-install (no rotation yet) | absent | legacy |
+| v1.39.4+ post-rotation | present | marker-required |
+| Quarantine ceremony | present | marker-required (rotation_trigger=quarantine_pre_fix) |
+| Manual rename without ceremony | absent | legacy (intentional gap) |
+
+## Vote trigger (ADR-095 no-calendar-gates)
+
+Data-volume gate. PROPOSED → ACCEPTED after:
+- (a) 30 days production rotation traffic post-v1.39.4 ship, OR
+- (b) 5 rotation events post-ship (whichever first)
+
+## Implementation refs
+
+- `_lib.audit_emit._emit_chain_reset_marker_under_lock()` — marker write + manifest + sidecars
+- `_lib.audit_emit.emit_chain_reset_marker()` — public typed wrapper
+- `_lib.audit_hmac.write_rotation_manifest()` / `read_rotation_manifest()` / `delete_rotation_manifest()` + `ROTATION_MANIFEST_FILENAME` constant
+- `audit-verify-chain.py::verify(enforce_marker_if_manifest, log_dir)` extension
+- `.claude/plans/PLAN-112-FOLLOWUP-hmac-tamper-fix/scripts/quarantine_pre_fix_log.py` — Wave B.2 ceremony
+
+## Threat-model delta vs ADR-055
+
+**Defends additionally**: silent rotation-during-tamper (attacker can no longer silently rotate to "clean" chain — marker absence = TAMPER under marker-required mode)
+
+**Does NOT defend**:
+- Manifest deletion: attacker with FS write deletes manifest → verifier falls back to legacy mode. Mitigation: external anchor per ADR-055 §Out-of-scope
+- Marker forgery: attacker with key access can forge valid marker. Same residual as ADR-055 §Threat model "Key theft"
+
+## Residual-monitoring (PLAN-118 WS-D, S181 — identity-trust-architect ADJUST)
+
+- **Manifest-deletion is detectable by a sidecar-divergence check.** If
+  `audit-log.last-hmac` is non-zero AND `audit-log.chain-length` ≥ 1 AND
+  the rotation-manifest is absent, that is a forensic inconsistency: a
+  clean genesis would have zeroed both sidecars. A future observability
+  follow-up SHOULD surface this divergence as a tamper signal (the
+  manifest-deletion → legacy-mode fallback is otherwise silent). Documented
+  here for honesty about a detection vector the §Threat-model delta left
+  implicit.
+- **`previous_archive_last_hmac` is attestation-only, not re-verified.** Per
+  §Verifier behavior the verifier does NOT walk archives (preserves ADR-055
+  §Non-goals "log = source of truth"); the same audit key signs both the
+  archive tail and the new marker, so the key-lifecycle anchor is preserved
+  across rotations, but the bridge field is producer attestation. An OPTIONAL
+  `--verify-archive-bridge` verifier flag (default-off; opt-in forensic
+  deep-verify) is a candidate future amendment — out of scope here.
+
+## Soak-substitution doctrine (PLAN-118 WS-D AC-D0 Owner-override, S181)
+
+The PLAN-118 AC-D0 prerequisite (≥2 ORGANIC rotations soak per ADR-095) was
+Owner-overridden for this promotion. The override is a legitimate evidence
+substitution, not erosion, because the WS-A/B/C chokepoint architecture
+changed the proof model from **probabilistic** ("watch the producer not break
+under organic load") to **mechanical** ("the producer-pollution failure mode
+raises `AuditProducerPathPollutionError` at the emit chokepoints — structurally
+impossible to emit a polluted marker"), and WS-E added a class-closure guard
+(`BuildEntryCanonicalEncodeGuardTest`) for the float-in-HMAC root cause that
+the S164 closure missed. Combined with: the ADR's own vote-trigger leg-b
+independently MET (8 rotation markers strictly post-v1.39.4-ship-commit
+2026-05-21T15:19:54Z, ≥ the required 5); the live chain
+verifying `intact` under `--strict-against-counter` post-fix+rotation; and the
+forensic archives preserving every pre-fix byte verbatim — the substitution is
+auditable and reusable. Precedent: S179 AC-C0 override
+([[feedback-owner-override-ac-c0-stale-producer-evidence]]).