ceo-orchestration 1.0.0

package/.claude/adr/ADR-030-llm-as-judge-methodology.md

@@ -0,0 +1,336 @@
+# ADR-030: LLM-as-Judge Methodology (hybrid with deterministic fallback)
+
+**Status:** ACCEPTED
+**Date:** 2026-04-14
+**Sprint:** 11 (PLAN-011 Phase 3)
+**Blast radius:** L2 — two new scripts, one schema file, two documentation
+artifacts, amendments to `run-skill-benchmark.py` and
+`SPEC/v1/benchmarks.schema.md`. No existing hook is modified.
+**Related:** ADR-015 (Reflexion v2 outcome loop), ADR-027 (unified state
+backend — audit redaction precedent), ADR-035 (OTEL export — advisory →
+gate lifecycle precedent), SPEC/v1/judge-payload.schema.md,
+SPEC/v1/benchmarks.schema.md.
+**Supersedes:** none.
+
+## Context
+
+Benchmarks in Sprints 1–10 scored skills via **fixture-based** scoring:
+pattern-match against `must_flag_tags` and `must_suggest_keywords`
+defined in the scenario YAML. This produces determinism (temperature=0,
+same inputs ⇒ same output) and local reproducibility, but captures
+only what the authoring team thought to enumerate. Nuances like
+"correct diagnosis but wrong suggestion vocabulary" or "correct
+suggestion but overstated severity" slip through.
+
+PLAN-011 Phase 3 introduces an **LLM-as-judge** mode so that skill
+evaluations can measure response quality the way a skilled reviewer
+would — against the intent of the rubric, not only its keyword
+shadow. Debate round-1 raised three HIGH-severity findings that shape
+the decision:
+
+- **§H5 (AI + QA, HIGH):** "Phase 3 judge methodology under-spec."
+  Require a committed prompt, two-pass (position bias), κ ≥ 0.7 on
+  N ≥ 50 calibration samples, provider rotation, and a golden-prompt
+  test.
+- **§H6 (Security, HIGH):** "Phase 3 judge sees everything."
+  Default-deny payload: rubric + redacted response + minimal task
+  context. Nothing else.
+- **§H7 (VPE, HIGH):** "Phase 3 judge provider SPOF." Ship a
+  deterministic fallback scorer; block closeout only when BOTH fail.
+
+Acting on these without discipline produces a judge that is worse than
+fixture-only: a single-provider oracle that silently drifts with model
+updates and sees Owner source whenever the response is echoed.
+
+## Decision Drivers
+
+- **Separation of rater and ratee.** A judge run by the same provider
+  as the judged model is a coauthor in disguise. Cross-provider is a
+  methodological invariant, not folklore.
+- **Payload minimisation.** Every extra field in the judge payload is
+  an exfil channel. Default-deny > default-allow.
+- **Deterministic fallback availability.** The judge MUST NOT be on
+  the critical path; an unreachable judge must degrade to a
+  deterministic grade that keeps CI green.
+- **Advisory now, gate later.** Same lifecycle precedent as ADR-023,
+  ADR-024, ADR-035: ship the machinery, measure, flip after evidence.
+- **Stdlib-only.** ADR-002 constraint. JSON-twin rubrics instead of
+  YAML parsing.
+
+## Options Considered
+
+### Option A — Fixture-only forever
+
+Keep the existing keyword-pattern scoring. Never introduce an LLM
+judge.
+
+**Pros:** zero new surface; fully deterministic.
+**Cons:** Ignores the core Phase 3 brief ("model-graded evaluation").
+Evaluations remain as good as the YAML authoring; blind to semantic
+quality.
+
+**Rejected.**
+
+### Option B — LLM-only (no fallback)
+
+Ship the judge and make it the sole grading path for `--judge-mode=llm`.
+
+**Pros:** simplest code path once the adapter is wired.
+**Cons:** any provider outage or rate-limit hits blocks CI. Single
+point of failure (§H7). No deterministic reproduction path.
+
+**Rejected.**
+
+### Option C — Hybrid with deterministic fallback (CHOSEN)
+
+Ship three modes behind `--judge-mode`:
+
+1. `fixture` (default; current behaviour preserved)
+2. `llm` (LLM judge with cross-provider guard; unreachable → None)
+3. `both` (fixture AND judge; disagreement emits veto)
+4. `fallback` (deterministic keyword-match baseline)
+
+When `mode=llm` and the adapter is unreachable, the RUNNER degrades
+silently — the fixture score still lands in the audit log with
+`judge_mode="llm"` and no judge fields. Operators who want the
+deterministic number use `--judge-mode=fallback` explicitly OR
+`--judge-mode=both` (which captures both).
+
+**Pros:** every decision path has a deterministic answer; cross-
+provider is enforced; disagreement becomes a queryable audit event;
+ADR-030 can flip to enforcement once κ ≥ 0.7.
+**Cons:** 3 new files + schema surface. Acceptable.
+
+**Chosen.**
+
+## Decision
+
+### 1. Committed prompt + golden hash
+
+The judge prompt lives at `.claude/benchmarks/_schemas/judge-prompt.md`.
+Its SHA-256 is:
+
+```
+297eabeffb4f0eec8c1ab5bc67f18627c563c72003151931317ce41a5ef0b1a1
+```
+
+This is the **golden prompt hash**. The test
+`test_benchmark_judge.TestGoldenPromptHash.test_committed_hash_matches`
+asserts the current file hashes to this value. Any intentional change
+REQUIRES:
+
+1. Updating the prompt file.
+2. Updating `GOLDEN_PROMPT_SHA256` in the test.
+3. Updating this hash line in the ADR.
+4. A commit message explaining the semantic change, not just the hash.
+
+Drift without all four is a regression.
+
+### 2. Default-deny payload
+
+The judge sees ONLY three top-level keys:
+
+```json
+{
+  "task_context": "<redacted, <=4000 chars>",
+  "rubric":       {<JSON rubric>},
+  "response":     "<redacted via redact_secrets, <=8000 chars>"
+}
+```
+
+Any fourth key raises `ValueError` at `validate_payload` time. See
+`SPEC/v1/judge-payload.schema.md` for the full contract. Six unit
+tests lock this down (`TestPayloadDefaultDeny.*`).
+
+### 3. Two-pass position-bias control
+
+Every judge invocation runs two passes:
+
+- **Forward:** task → rubric → response.
+- **Reverse:** task → response → rubric. The prompt is rendered with
+  the two sections swapped; the three-key payload is unchanged (the
+  reverse-pass bit is carried as a `[REVERSE-PASS] ` prefix inside
+  `task_context`, NOT a new key).
+
+Both scores are reported; `|forward - reverse| > 0.5` sets
+`recommend_human_review=true` in the output.
+
+### 4. Cross-provider guard
+
+`benchmark-judge.py --judge-adapter=<x>` rejects `<x>` equal to
+`CEO_HOOK_ADAPTER` (the main adapter). Exit code 3, reason code
+`cross-provider-collision`. Empty main adapter is allowed (stand-
+alone judge invocation).
+
+### 5. Deterministic fallback (§H7)
+
+`benchmark-fallback-scorer.py` is a keyword-match scorer with the
+same JSON output shape as `benchmark-judge.py`. For each rubric item,
+it tokenises the description (minus stopwords), counts matches in the
+response, and scores as `(matched / total_keywords) * weight`.
+
+Used:
+- Explicitly via `--judge-mode=fallback`.
+- Implicitly when `--judge-mode=llm|both` + judge unreachable
+  (silent degradation, audit shows `judge_mode` but no judge scores).
+
+Closeout is blocked ONLY when BOTH fixture AND fallback fail.
+
+### 6. Provider rotation
+
+`.claude/benchmarks/judge-rotation-schedule.md` documents the weekly
+rotation:
+
+| Week | Judge | Role |
+|---|---|---|
+| W1 | gemini | primary |
+| W2 | openai | primary |
+| W3 | local | offline control |
+| W4 | gemini (fixed-seed replay W1) | drift detection |
+
+Enforced operationally (by the weekly `--judge-adapter` value), NOT
+at code-review time. Cross-provider collision is enforced at runtime.
+
+### 7. κ calibration
+
+`.claude/benchmarks/human-sample-calibration.md` is the living
+protocol. Sample N = 50 paired grades across domains; compute Cohen's
+linear-weighted κ. Current state: **TBD (no grades yet)**. The file
+is append-only; corrections are new rows.
+
+### 8. Three-state lifecycle
+
+```
+    Sprint 11               Sprint 12+                Sprint 13+
+┌────────────────┐    ┌────────────────┐    ┌────────────────┐
+│  State 0       │───▶│  State 1       │───▶│  State 2       │
+│  advisory      │    │  gated         │    │  enforced      │
+│  both-score    │    │  disagreement  │    │  |delta|>0.2   │
+│  audit event   │    │  veto blocks   │    │  fails         │
+│  (no block)    │    │  PR until      │    │  benchmark run │
+│                │    │  resolved      │    │                │
+│ κ = TBD        │    │ κ ≥ 0.7        │    │ κ ≥ 0.8        │
+│                │    │ (N=50 sample)  │    │ (N=100+)       │
+└────────────────┘    └────────────────┘    └────────────────┘
+```
+
+Sprint 11 ships **State 0**. No existing benchmark is blocked by
+judge score.
+
+### 9. Flip criteria
+
+| From | To | Criterion | Window | Owner |
+|---|---|---|---|---|
+| State 0 | State 1 | `κ ≥ 0.7 on N ≥ 50 paired grades` AND `disagreement rate ≤ 15% over 30 days` | 14d avg | QA lead |
+| State 1 | State 2 | `κ ≥ 0.8 on N ≥ 100 paired grades` AND `judge unreachable events ≤ 1/week` | 30d avg | QA + VPE |
+
+A PR that proposes the flip MUST include an `audit-query.py
+benchmark-disagreements --since 30d` report and the κ calculation
+output (with 95% bootstrap CI when N allows). Without that data the
+flip PR is not approved.
+
+### 10. Non-goals
+
+- **Active learning of the rubric.** The rubric is a human-authored
+  artefact. The judge does not propose rubric edits; that would
+  collapse the rater/ratee separation.
+- **Aggregating judges (ensemble).** A single judge per invocation.
+  Ensembling is tempting but introduces another layer of bias that
+  the rotation schedule already mitigates.
+- **Real-time judging in hook context.** The judge is a batch /
+  benchmark tool; it does NOT run inside a PreToolUse or PostToolUse
+  hook. Those paths stay fixture-only.
+- **OPENAI / LOCAL real-wire invocation.** Phase 3 ships the
+  adapter-invocation seam (`invoke_adapter()`) with a mock path; the
+  real provider-wire implementation is provisional pending per-
+  provider SDK + credential handling. Unreachable mode is tested;
+  reachable is mock-only.
+
+### 11. Environment variables
+
+| Var | Default | Effect |
+|---|---|---|
+| `CEO_HOOK_ADAPTER` | `claude` | Main adapter; judge MUST differ. |
+| `CEO_SOTA_DISABLE` | unset | When `1`, judge mode becomes a no-op (WARNING on stderr, `fixture` is used). Mirrors the ADR-035 escape hatch. |
+
+## Consequences
+
+### Positive
+
+- Evaluations capture semantic quality, not just keyword coverage.
+- Payload default-deny is enforced at the code level; reviewers
+  cannot casually "sneak in" a source-code field.
+- Cross-provider guard prevents silent coauthor regressions.
+- Every judge result lands in the audit log with a parseable
+  envelope (`judge_mode`, `judge_score_forward`, `judge_delta`).
+- Disagreement vetoes become a first-class audit signal usable by
+  Sprint 12 calibration work.
+
+### Negative
+
+- Two new scripts to maintain (`benchmark-judge.py`,
+  `benchmark-fallback-scorer.py`) plus the one-schema expansion.
+- Human calibration is an ongoing obligation; if the team never
+  reaches N = 50 grades, the gate never flips — sunsetting is
+  explicit in §7 of `human-sample-calibration.md`.
+- Mock judge is deterministic by hash, which is enough for unit
+  tests but NOT enough to simulate realistic drift. Live provider
+  runs are required for W1–W4 rotation evidence.
+
+### Neutral
+
+- `run-skill-benchmark.py` grows a handful of flags (`--judge-mode`,
+  `--judge-adapter`, `--judge-mock`, `--judge-rubric-file`). Default
+  `--judge-mode=fixture` keeps current CI contracts unchanged.
+- Rubric public doc is YAML; code reads the JSON twin. Both are
+  committed; drift check is left to human review (a rubric-drift
+  test may be added in Sprint 12 if churn warrants).
+
+## Blast Radius
+
+**L2** — Cross-module contract change affecting:
+
+- `.claude/scripts/run-skill-benchmark.py` (AMEND — 4 new flags,
+  judge dispatcher, extended audit-emit path)
+- `.claude/scripts/benchmark-judge.py` (NEW)
+- `.claude/scripts/benchmark-fallback-scorer.py` (NEW)
+- `.claude/scripts/tests/test_benchmark_judge.py` (NEW)
+- `.claude/scripts/tests/test_benchmark_fallback_scorer.py` (NEW)
+- `.claude/scripts/tests/test_run_skill_benchmark_judge_mode.py` (NEW)
+- `.claude/benchmarks/_schemas/judge-prompt.md` (NEW)
+- `.claude/benchmarks/_schemas/judge-rubric.yaml` (NEW — public doc)
+- `.claude/benchmarks/_schemas/judge-rubric-example.json` (NEW — JSON
+  twin consumed by code)
+- `.claude/benchmarks/human-sample-calibration.md` (NEW — living doc)
+- `.claude/benchmarks/judge-rotation-schedule.md` (NEW)
+- `SPEC/v1/judge-payload.schema.md` (NEW)
+- `SPEC/v1/benchmarks.schema.md` (AMEND — additive judge-mode fields)
+
+**Reversibility:** HIGH. Rolling back to pre-Phase 3:
+
+1. Revert the `run-skill-benchmark.py` diff (flag/handler removal).
+2. Delete the two new scripts + their tests.
+3. Delete the two new schema files + two benchmark docs + two schema
+   artifacts.
+4. Revert `SPEC/v1/benchmarks.schema.md` to 1.0.0-rc.1.
+
+No migration path touches existing benchmarks (fixture-mode is the
+default and stable).
+
+## References
+
+- PLAN-011 Phase 3 — this commit
+- PLAN-011/debate/round-1/consensus.md §H5, §H6, §H7
+- `SPEC/v1/judge-payload.schema.md`
+- `SPEC/v1/benchmarks.schema.md` (judge-mode fields section)
+- `.claude/benchmarks/_schemas/judge-prompt.md` (golden prompt)
+- `.claude/benchmarks/human-sample-calibration.md` (κ protocol)
+- `.claude/benchmarks/judge-rotation-schedule.md` (provider rotation)
+- ADR-015 (Reflexion v2 outcome loop)
+- ADR-023 (docs-freshness lifecycle precedent)
+- ADR-024 (perf-baseline lifecycle precedent)
+- ADR-035 (OTEL advisory → gate lifecycle precedent)
+
+## Enforcement commit
+
+`61c1f2876fe1` (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-031-self-improving-skills.md

@@ -0,0 +1,221 @@
+# ADR-031: Self-improving skills (Owner-gated, shadow-mode)
+
+**Status:** ACCEPTED
+**Date:** 2026-04-14
+**Sprint:** 11 Phase 4
+**Related:** ADR-010 (canonical-edit sentinel), ADR-011 (injection_flag
+advisory), ADR-018 (claim grammar / confidence gate), ADR-019 (confidence
+gate enforcement lifecycle), PLAN-011 debate round 1 **CR1** (CRITICAL)
+
+## Context
+
+PLAN-011 Phase 4 introduces a feedback loop: **agent-authored lessons →
+candidate SKILL.md patch → Owner review → shadow apply → promote**.
+Lessons accrete under `.claude/lessons/` whenever a benchmark fails or a
+debate adjustment is captured. Over time the best-scoring lessons
+represent compressed institutional memory. A manual CEO would fold that
+institutional memory back into the relevant `SKILL.md` so every future
+spawn benefits from the lesson — but a manual fold is slow, inconsistent,
+and doesn't scale as the skill library grows past the current 48.
+
+The naive pipeline is **CRITICAL-unsafe**. A compromised lesson — or a
+crafted one planted by a prompt-injected Read — becomes a skill patch
+proposal, which an Owner-on-autopilot visually approves, which then
+mutates `SKILL.md`. Every subsequent spawn reads the compromised skill.
+The amplification factor is the full spawn count for that skill across
+the entire project lifetime. **This is the single highest blast radius
+in the framework.**
+
+The attack surface enumerated in debate round 1 CR1:
+
+1. Unicode bidirectional override (U+202E) hiding hostile tokens
+2. Zero-width joiners / spaces (U+200B–U+200F) hiding tokens
+3. Homoglyph substitution (Cyrillic `а` for Latin `a` in `api_key`)
+4. Long-line truncation — hostile payload past the 80/120 col visual cutoff
+5. Injection patterns (scan-injection.py hits) embedded in rationale
+6. Fenced executable code (```python) that looks like documentation but
+   will be read/interpreted by future agents
+7. Diff-size bloat — 10k-line diff that no human reviews exhaustively
+8. Frontmatter approval spoofing — `approved_by:` is untrustworthy without
+   cryptographic signature
+
+Doing nothing is not an option — the Owner asked for auto-skills. Doing
+it without the **10-point mitigation bundle** below would ship a backdoor.
+
+## Decision drivers
+
+- **Unacceptable worst case** — the cost of a single successful attack
+  is "every spawn of compromised skill reads malicious content". Err on
+  the side of false-negative rejection.
+- **Fail-closed default** — no proposal applies unless every mitigation
+  layer explicitly passes.
+- **Stdlib-only** — GPG via subprocess; no new runtime dependency.
+- **Shadow-first** — real `SKILL.md` is never written in the propose/apply
+  flow. Promotion is a separate, delayed, explicit step.
+- **Dogfood the sentinel** — the existing `check_canonical_edit.py`
+  (ADR-010) already blocks `SKILL.md` edits without an Owner-signed
+  sentinel. Skill-patch flow issues its OWN sentinel companion
+  (`check_skill_patch_sentinel.py`) with a stricter contract.
+- **Audit-first** — every stage (propose, apply, promote) emits an audit
+  event. Silent mutations are forbidden.
+
+## Decision
+
+Ship **Owner-gated, 7-day shadow-mode** self-improving skills.
+
+### Moving parts
+
+1. **`.claude/scripts/skill-patch-propose.py`** — drafts an `SP-NNN.md`
+   proposal from one or more lessons. Fail-closed on every attack
+   vector in the CR1 table below.
+2. **`.claude/scripts/skill-patch-apply.py`** — verifies GPG detached
+   signature + Owner `--confirm` phrase. Default mode writes
+   `<SKILL.md>.shadow.md` (never the real file). `--promote` mode is
+   only valid after 7 days AND requires re-verification of the proposal
+   + signature.
+3. **`.claude/hooks/check_skill_patch_sentinel.py`** — PreToolUse
+   `Edit|Write|MultiEdit` hook. If the target is a `SKILL.md` file,
+   blocks unless a matching approved `SP-NNN` proposal exists AND the
+   session env var `CEO_SKILL_PATCH_SHA` matches the diff hash recorded
+   in the proposal. Fail-open on infra errors (ADR-005).
+4. **`.claude/commands/skill-review.md`** — slash command for Owner
+   review / approval / rejection.
+5. **`.claude/proposals/`** — on-disk directory for SP-NNN proposals.
+   Gitignored by default in target repos; present in this repo only via
+   `.gitkeep` + `README.md` so the sentinel has something to scan.
+6. **`SPEC/v1/skill-proposals.schema.md`** — normative contract for
+   proposal frontmatter + status lifecycle + hash trailer format.
+
+### 10-point CR1 mitigation bundle — evidence table
+
+| # | Mitigation | Enforced by | Evidence (file:test) |
+|---|---|---|---|
+| 1 | `scan-injection.py` pre-draft | `skill-patch-propose.py::_scan_lesson` | `test_skill_patch_propose.py::test_rejects_injection_pattern` |
+| 2 | Bidi / zero-width / control-char strip in preview | `skill-patch-propose.py::_normalize_preview` | `test_skill_patch_propose.py::test_rejects_bidi_override` + `test_rejects_zero_width` |
+| 3 | AST-validate no fenced executable code without second-stage review | `skill-patch-propose.py::_detect_fenced_code` | `test_skill_patch_propose.py::test_rejects_fenced_python` + `test_allows_fenced_python_with_flag` |
+| 4 | Diff size < 200 lines | `skill-patch-propose.py::_check_diff_size` | `test_skill_patch_propose.py::test_rejects_oversized_diff` |
+| 5 | Re-run touched benchmarks in CI post-apply (shadow branch) | STUB in Sprint 11 — `skill-patch-apply.py` writes `.shadow.md` + `--skip-ci-rerun` sentinel log line (see §Open questions) | `test_skill_patch_apply.py::test_writes_shadow_on_apply` |
+| 6 | `SP-NNN.md` requires Owner GPG detached signature | `skill-patch-apply.py::_verify_signature` | `test_skill_patch_apply.py::test_missing_signature_exits_2` + `test_invalid_signature_exits_2` |
+| 7 | Hash of approved diff in commit trailer — verified by `check_canonical_edit.py` + `check_skill_patch_sentinel.py` | `check_skill_patch_sentinel.py::_verify_commit_trailer` via `CEO_SKILL_PATCH_SHA` env | `test_check_skill_patch_sentinel.py::test_allows_with_valid_trailer` + `test_blocks_on_trailer_mismatch` |
+| 8 | 7-day shadow mode | `skill-patch-apply.py::_check_shadow_age` | `test_skill_patch_apply.py::test_promote_before_seven_days_exits_4` + `test_promote_after_seven_days_merges` |
+| 9 | Confidence-gate extension (ADR-018 amendment) covers skill-patch proposals — declared as a rationale field, not a code change here | `skill-patch-propose.py` emits `claims_declared: bool` frontmatter field (Sprint 12 wires to confidence gate) | `test_skill_patch_propose.py::test_frontmatter_schema` |
+| 10 | Owner approval phrase `--confirm "I have read SP-NNN"` literal | `skill-patch-apply.py::_verify_confirm_phrase` | `test_skill_patch_apply.py::test_wrong_confirm_phrase_exits_3` |
+
+### 7-day shadow protocol
+
+```
+t=0   skill-patch-propose.py  → SP-042-core-security-2026-04-14.md (status: draft)
+                                 diff committed to proposals/, no SKILL.md write
+t=t0  Owner reviews, creates detached GPG signature SP-042.md.asc
+t=t0  skill-patch-apply.py --proposal SP-042 --signature SP-042.md.asc \
+        --confirm "I have read SP-042"
+      → writes .claude/skills/core/security-and-auth/SKILL.md.shadow.md
+        status: shadow, applied_at: 2026-04-14T12:00:00Z
+        emits skill_patch_applied(shadow_mode=True)
+t+7d  Owner runs benchmarks against the shadow file. No regression.
+      skill-patch-apply.py --proposal SP-042 --signature ... \
+        --confirm "I have read SP-042" --promote
+      → verifies proposed_at >= 7d old
+        merges SKILL.md.shadow.md → SKILL.md (printing commit message
+        with `Skill-Patch-SHA: <hex>` trailer for CEO to commit)
+        status: promoted, shadow_mode=False event emitted
+t+8d  CEO commits with the trailer. check_canonical_edit.py verifies
+      sentinel. check_skill_patch_sentinel.py verifies trailer hash
+      matches proposal's recorded sha256_of_diff.
+```
+
+`CEO_SOTA_DISABLE=1` → `propose.py` and `apply.py` exit 0 no-op.
+`check_skill_patch_sentinel.py` ignores `CEO_SOTA_DISABLE` — the sentinel
+is a safety surface, not a feature flag.
+
+## Non-goals (Sprint 11)
+
+- **Auto-apply without Owner approval** — explicitly out of scope. The
+  attack surface is too high.
+- **Cross-skill proposals in one SP-NNN** — each proposal targets exactly
+  one `SKILL.md`. Multi-skill refactors still need a hand-crafted plan.
+- **Auto-revocation** — if a promoted skill turns out bad, the Owner
+  reverts via normal `git revert` + new SP-NNN. No magic rollback.
+- **Real shadow CI wiring** — Sprint 11 ships measure-only: the `.shadow.md`
+  file exists, but the benchmarks re-run workflow is a separate ADR
+  (Sprint 12 ADR-037 candidate per CR1 row #5).
+- **Embedding-based lesson ranking for patch selection** — out of scope.
+  The propose flow is CLI-driven: Owner picks the lessons.
+
+## Blast radius: **L3**
+
+Every `SKILL.md` consumer — every spawn across every squad — reads the
+output of this flow (eventually). A misconfigured promote or bypassed
+sentinel compromises the governance contract.
+
+## Open questions (Sprint 12)
+
+1. **Shadow CI orchestration.** Sprint 11 writes `.shadow.md` but does
+   not automate benchmark re-runs against it. Sprint 12 ADR-037 wires
+   `.github/workflows/skill-patch-shadow.yml` that runs the per-skill
+   benchmark corpus against the shadow file and reports pass-rate delta.
+2. **Signer fingerprint allowlist.** Sprint 11 accepts any valid GPG
+   signature (GPG's WOT is used). Sprint 12 may add an explicit Owner
+   fingerprint pin in `settings.json` — e.g. `skill_patch_signer_fpr:
+   "ABCD 1234 ..."` — to defend against a compromised keyring.
+3. **ADR-018 amendment wire-up.** CR1 row #9 says the confidence gate
+   extension covers skill-patch proposals. Today this is declarative
+   (frontmatter field). Sprint 12 actually invokes `check_confidence_gate.py`
+   on the rationale section.
+4. **Multi-signer policy.** Some orgs will want 2-of-N Owner signatures
+   (e.g. CEO + Security). Deferred.
+
+## Alternatives considered
+
+- **Frontmatter `approved_by: @owner` + no GPG.** Rejected — one
+  compromised YAML parse away from backdoor. Cryptographic signature is
+  the defensible minimum.
+- **Auto-apply with synchronous benchmark gate.** Rejected — benchmarks
+  take minutes, and a benchmark suite crafted to avoid the injected
+  content is trivially constructible by the attacker.
+- **Skip shadow entirely.** Rejected — 7-day soak is the cheapest
+  independent observation of the mutation before it amplifies.
+- **Owner edits `SKILL.md` directly via canonical-edit sentinel (ADR-010).**
+  Still available; the skill-patch flow is purely additive. If an Owner
+  prefers the manual flow, ADR-010 still works.
+
+## Back-compat
+
+- `event_schema` remains `v2` (additive — `skill_patch_applied` is a new
+  action, per the same additivity discipline as ADR-011 injection_flag).
+- `check_canonical_edit.py` is unchanged. `check_skill_patch_sentinel.py`
+  is a NEW hook registered alongside it; both fire on the same matcher
+  (`Edit|Write|MultiEdit`).
+- `CEO_SOTA_DISABLE` is the single kill-switch for the propose/apply
+  feature. The sentinel remains active even when disabled.
+
+## References
+
+- PLAN-011 debate round 1 `consensus.md` §CR1 (this ADR addresses in full)
+- ADR-010 (canonical-edit sentinel — the pattern we extend)
+- ADR-011 (injection_flag advisory — observability pattern we dogfood)
+- ADR-018 / ADR-019 (claim grammar / confidence gate — CR1 row #9)
+- `SPEC/v1/skill-proposals.schema.md` (normative proposal format)
+
+## Amendment 1 — Skill bootstrap bypass (ADR-059, 2026-04-19)
+
+ADR-031 was designed for PATCHES over existing SKILL.md files via the
+SP-NNN proposal + sha256 trailer + 7-day shadow-apply flow. It
+inadvertently blocked NEW skill creation because the hook
+`check_skill_patch_sentinel.py` applies the same gate to bootstrap
+writes (target SKILL.md does not yet exist). Post-Sprint-11, every
+attempt to create a new skill hit this wall; PLAN-031 (brainstorm
+gate skill creation) surfaced the gap operationally.
+
+**Bootstrap bypass mechanism:** two-factor env-var pattern
+(`CEO_SKILL_BOOTSTRAP=<slug>` + `CEO_SKILL_BOOTSTRAP_ACK=I-ACCEPT`)
+parallel to `CEO_KERNEL_OVERRIDE` / `_ACK` from `check_arbitration_kernel.py`.
+Bootstrap-only (target must NOT already exist); existing SKILL.md
+patches continue through the SP-NNN flow.
+
+See `ADR-059-skill-bootstrap-env-knob.md` for the full rationale,
+compensating controls, and revisit triggers.
+
+## Enforcement commit
+
+`78db946a3279` (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.)