safeword 0.71.0 → 0.72.0

package/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "safeword",
-  "version": "0.71.0",
+  "version": "0.72.0",
   "description": "Safe Word workflow guidance and gates for Codex.",
   "author": {
     "name": "Arcade AI"

package/codex-plugin/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bunx --bun safeword@0.71.0 hook codex session-start --plugin-hook",
+            "command": "bunx --bun safeword@0.72.0 hook codex session-start --plugin-hook",
             "timeout": 120,
             "statusMessage": "Loading Safe Word standing instructions"
           }
@@ -19,7 +19,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bunx --bun safeword@0.71.0 hook codex pre-tool-use --plugin-hook",
+            "command": "bunx --bun safeword@0.72.0 hook codex pre-tool-use --plugin-hook",
             "timeout": 30,
             "statusMessage": "Checking Safe Word edit gates"
           }
@@ -32,7 +32,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bunx --bun safeword@0.71.0 hook codex post-tool-use --plugin-hook",
+            "command": "bunx --bun safeword@0.72.0 hook codex post-tool-use --plugin-hook",
             "timeout": 30,
             "statusMessage": "Surfacing Safe Word post-tool context"
           }
@@ -45,7 +45,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bunx --bun safeword@0.71.0 hook codex user-prompt-submit --plugin-hook",
+            "command": "bunx --bun safeword@0.72.0 hook codex user-prompt-submit --plugin-hook",
             "timeout": 30,
             "statusMessage": "Checking queued Safe Word prompt context"
           }
@@ -58,7 +58,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bunx --bun safeword@0.71.0 hook codex stop --plugin-hook",
+            "command": "bunx --bun safeword@0.72.0 hook codex stop --plugin-hook",
             "timeout": 600,
             "statusMessage": "Checking Safe Word stop continuation"
           }

package/codex-plugin/skills/audit/SKILL.md

@@ -670,7 +670,35 @@ Test Quality:
 
 Review the changed area from the printed scope. For each significantly changed area, check if related docs, readmes, or guides need updating. Flag stale, missing, or contradictory impacted documentation as errors. Documentation drift is never a warning; date-only staleness with no changed-code contradiction is repository-audit context, not a diff finding.
 
-### 6. Namespace Domain Docs
+### 6. Principle Trace Integrity
+
+For the active ticket, when `impl-plan.md` declares project-principle alignment,
+resolve the source using `paths.principles` (default
+`<namespace-root>/principles.md`) and check the principle trace as **observable
+facts only**:
+
+- The named principle exists in the configured source.
+- The trace contains a non-empty concrete consequence and proof.
+- The proof reference resolves to recorded test, verification, or manual
+  evidence; an intentional conflict is named in Known deviations.
+
+Report a missing source entry, incomplete mapping, dead evidence reference, or
+unrecorded conflict as `[E010] Broken principle trace`. Do not judge whether a
+principle was applicable, whether the consequence was a wise interpretation,
+or whether an experience was genuinely delightful—those are adversarial
+`quality-review` judgments. A plan with no declared applicable principle is not
+an audit finding.
+
+Run the factual checker below verbatim. Its sentinel keeps the executable audit
+contract testable without turning semantic review into shell heuristics.
+
+```bash
+# principle-trace-check — E010 objective trace integrity only.
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2> /dev/null || pwd)}"
+bun "$PROJECT_DIR/.safeword/hooks/audit-principle-trace.ts" "$PROJECT_DIR"
+```
+
+### 7. Namespace Domain Docs
 
 When a changed feature/spec or changed domain doc references them, reconcile the
 three namespace domain docs — `personas.md`, `surfaces.md`, `glossary.md` —
@@ -687,20 +715,29 @@ PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2> /dev/null
 source "$PROJECT_DIR/.safeword/hooks/lib/audit-scope.sh"
 audit_scope_initialize "$PROJECT_DIR"
 
-# A branch audit skips unrelated domain-doc corpus drift. Deleted and
-# type-changed feature/spec/domain files remain in reference review scope, so
-# they still trigger this check for broken-reference review. A repository audit
-# deliberately checks every domain doc and every discovered feature/spec.
-if [ "$AUDIT_SCOPE_MODE" = "diff" ] && ! audit_scope_has_review_path_matching '(^|/)(personas|surfaces|glossary)\.md$|\.feature$|(^|/)spec\.md$'; then
-  exit 0
-fi
-
 # Resolve the namespace root (honors config paths.projectRoot in real runs).
 # Fall back on directory existence — robust when the resolver hook is absent.
 NS_ROOT="$(bun "$PROJECT_DIR/.safeword/hooks/resolve-namespace-root.ts" "$PROJECT_DIR" 2> /dev/null)"
 [ -d "$NS_ROOT" ] || {
   if [ -d "$PROJECT_DIR/.project" ]; then NS_ROOT="$PROJECT_DIR/.project"; else NS_ROOT="$PROJECT_DIR/.safeword-project"; fi
 }
+PERSONAS_FILE="$(bun "$PROJECT_DIR/.safeword/hooks/resolve-namespace-root.ts" "$PROJECT_DIR" personas personas.md 2> /dev/null)"
+SURFACES_FILE="$(bun "$PROJECT_DIR/.safeword/hooks/resolve-namespace-root.ts" "$PROJECT_DIR" surfaces surfaces.md 2> /dev/null)"
+GLOSSARY_FILE="$(bun "$PROJECT_DIR/.safeword/hooks/resolve-namespace-root.ts" "$PROJECT_DIR" glossary glossary.md 2> /dev/null)"
+[ -n "$PERSONAS_FILE" ] || PERSONAS_FILE="$NS_ROOT/personas.md"
+[ -n "$SURFACES_FILE" ] || SURFACES_FILE="$NS_ROOT/surfaces.md"
+[ -n "$GLOSSARY_FILE" ] || GLOSSARY_FILE="$NS_ROOT/glossary.md"
+
+# A branch audit skips unrelated domain-doc corpus drift. Include configured
+# domain paths, whose basenames need not be personas.md/surfaces.md/glossary.md.
+if [ "$AUDIT_SCOPE_MODE" = "diff" ] && ! audit_scope_has_review_path_matching '(^|/)(personas|surfaces|glossary)\.md$|\.feature$|(^|/)spec\.md$'; then
+  domain_path_changed=false
+  for configured_domain_file in "$PERSONAS_FILE" "$SURFACES_FILE" "$GLOSSARY_FILE"; do
+    configured_domain_path="${configured_domain_file#"$PROJECT_DIR"/}"
+    audit_scope_path_changed "$configured_domain_path" && domain_path_changed=true
+  done
+  [ "$domain_path_changed" = true ] || exit 0
+fi
 
 # Single-source the HTML-comment strip used by every check below. Strips
 # same-line comments FIRST (`s/<!--.*-->//g`) then deletes multi-line comment
@@ -724,7 +761,11 @@ domain_docs_entry_count() {
 # In a diff audit, report only a changed domain doc. An unchanged empty scaffold
 # is existing debt, not a finding caused by an unrelated feature or spec change.
 for doc in personas surfaces glossary; do
-  dd_file="$NS_ROOT/$doc.md"
+  case "$doc" in
+    personas) dd_file="$PERSONAS_FILE" ;;
+    surfaces) dd_file="$SURFACES_FILE" ;;
+    glossary) dd_file="$GLOSSARY_FILE" ;;
+  esac
   [ -f "$dd_file" ] || continue
   domain_doc_path="${dd_file#"$PROJECT_DIR"/}"
   [ "$AUDIT_SCOPE_MODE" = "repository" ] || audit_scope_path_changed "$domain_doc_path" || continue
@@ -749,7 +790,7 @@ feature_directories() {
     return 127
   fi
 }
-surfaces_file="$NS_ROOT/surfaces.md"
+surfaces_file="$SURFACES_FILE"
 dd_file="$surfaces_file"
 surfaces_path="${surfaces_file#"$PROJECT_DIR"/}"
 if [ "$AUDIT_SCOPE_MODE" = "repository" ] || audit_scope_path_changed "$surfaces_path"; then
@@ -785,7 +826,7 @@ fi
 # --- Persona drift (E009): spec **Persona:** code referenced but undefined ---
 # Spec lines only, comment-stripped (feature lineage tags carry ticket-ids, not
 # personas). Suppressed when personas.md is empty/absent.
-personas_file="$NS_ROOT/personas.md"
+personas_file="$PERSONAS_FILE"
 tickets_dir="$NS_ROOT/tickets"
 dd_file="$personas_file"
 personas_path="${personas_file#"$PROJECT_DIR"/}"
@@ -923,7 +964,7 @@ fi
 
 **Empty-doc offer (W008):** report the empty doc and point the user to its template — do **not** draft entries or write the file during the audit pass (read-only). Filling it is a follow-up the user approves.
 
-**Coverage limitation:** the block reads the default namespace-root locations; per-file `paths.personas` / `paths.surfaces` / `paths.glossary` overrides are validated by `safeword doctor` (structure), not here. If the safeword feature-directory resolver is unavailable, W009 says E008 fell back to root `features/` only. Persona drift reads spec `**Persona:**` lines only — feature lineage tags are not a reliable persona source.
+**Coverage limitation:** configured `paths.personas`, `paths.surfaces`, and `paths.glossary` are resolved before reconciliation. `safeword doctor` separately reports missing configured files and orphaned defaults. If the safeword feature-directory resolver is unavailable, W009 says E008 fell back to root `features/` only. Persona drift reads spec `**Persona:**` lines only — feature lineage tags are not a reliable persona source.
 
 ---
 
@@ -941,6 +982,7 @@ Report findings by severity with codes:
 - [E007] Drifted layer→dir: `ARCHITECTURE.md` maps `domain` → `src/core/` but no such module path is in `architecture.generated.md`
 - [E008] Surface drift: `@surface.safeword-cli` is referenced in `features/` but has no matching entry in `surfaces.md`
 - [E009] Persona drift: persona code `DEV` is named in a spec `**Persona:**` line but has no matching entry in `personas.md`
+- [E010] Broken principle trace: `Delight the user` points to `verify.md#persona-walkthrough`, but that evidence record does not exist
 
 ### Warnings (should review)
 

package/codex-plugin/skills/bdd/SKILL.md

@@ -48,18 +48,21 @@ phase: implement # intake | define-behavior | scenario-gate | plan-implementatio
 
 The **scenario-gate exit requires** an independent review of the scenarios — not
 your own pass. (Your own inline pass is Tier 1: `$safeword:self-review`, per asset, as you
-author.) Run it as a _fresh reviewer with no conversation history_ so the author
-can't grade their own work: a forked subagent — a skill with `context: fork`, or
-an explicit subagent — handed only the phase's artifacts and the ticket's scope,
-applying the `$safeword:review-spec` procedure; **its** verdict decides. When
-`crossModelReview` is on, that reviewer must be a **different model than the
-author** — a same-model reviewer shares the author's blind spots. Prefer one of
-comparable-or-better capability; never weaker. If you can't run a different
-model, log a deliberate skip (`--skip "<reason>"`) rather than stamping a
-same-model review. On a pass, record the stamp:
+author.) Invoke the shared host-owned coordinator with only the phase artifacts
+and ticket scope; its typed verdict decides:
 
 ```bash
-bun .safeword/hooks/write-review-stamp.ts --phase <phase you are leaving>
+safeword review run scenario-gate feature-file ticket-spec [legacy-test-definitions]
+```
+
+The coordinator prefers the opposite headless agent, labels a permitted
+same-agent fallback as degraded, and blocks with one recovery action when no
+safe route remains. Do not bypass it with a private subagent. On a result that
+satisfies the configured policy, record the returned provenance in the stamp
+(substitute the four values from `data` in the coordinator result):
+
+```bash
+bun .safeword/hooks/write-review-stamp.ts --author-agent "author-agent" --reviewer-agent "actual-reviewer" --independence "independence" --phase phase-name
 ```
 
 If the reviewer finds blocking issues, fix them and re-review — don't stamp.

package/codex-plugin/skills/bdd/references/DISCOVERY.md

@@ -4,18 +4,18 @@
 
 ## Sub-phase gates
 
-Intake advances through sub-phases (load personas/glossary/surfaces → JTBD → Rules → engineering scope). Each one ends with a **gate** — don't advance on your own momentum; present what you captured and get the user's signoff first. Three moves:
+Intake advances through sub-phases (load principles/personas/glossary/surfaces → JTBD → Rules → engineering scope). Each one ends with a **gate** — don't advance on your own momentum; present what you captured and get the user's signoff first. Three moves:
 
 1. **Present** the captured artifact verbatim — the JTBD list, the Rules list grouped by JTBD, or the Scope / Out of Scope / Done When block.
 2. **Ask** the sub-phase's closing question (below).
 3. **Wait** for confirmation. Any forward-moving reply advances — an explicit "looks good" / "proceed", or an amendment you fold in and re-present. A new concern loops back; you don't advance until it's resolved.
 
-| Sub-phase                      | Closing question                                                                                                                                                                             |
-| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Personas / glossary / surfaces | _"`<file>` is empty — add entries now, or proceed without?"_ (only when missing/empty)                                                                                                       |
-| Jobs To Be Done                | _"Here's who asked, the cost of not doing it, and how reversible it is — plus the jobs it serves. Given that, is this a feature, or a task? And do the jobs cover who this serves and why?"_ |
-| Rules                          | _"Does each job's criteria capture what 'done' means for the persona? Any to split, add, or drop?"_                                                                                          |
-| Engineering scope              | _"Here's the scope / out-of-scope / done-when — ready to proceed?"_                                                                                                                          |
+| Sub-phase                                   | Closing question                                                                                                                                                                             |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Principles / personas / glossary / surfaces | _"`<file>` is empty — add entries now, or proceed without?"_ (only when missing/empty)                                                                                                       |
+| Jobs To Be Done                             | _"Here's who asked, the cost of not doing it, and how reversible it is — plus the jobs it serves. Given that, is this a feature, or a task? And do the jobs cover who this serves and why?"_ |
+| Rules                                       | _"Does each job's criteria capture what 'done' means for the persona? Any to split, add, or drop?"_                                                                                          |
+| Engineering scope                           | _"Here's the scope / out-of-scope / done-when — ready to proceed?"_                                                                                                                          |
 
 **On resume** (picked up mid-sub-phase across sessions): re-present the captured artifact for re-confirmation rather than assuming the prior signoff still stands — context may have shifted.
 
@@ -23,6 +23,21 @@ Intake advances through sub-phases (load personas/glossary/surfaces → JTBD →
 
 These gates are conversational discipline the agent runs — not a hook block. (Hook-enforced sub-phase tracking is future work, coordinated with phase-step-enforcement epic 172.)
 
+## Load project principles
+
+At intake start, read the configured principles file (`paths.principles`,
+default `<namespace-root>/principles.md`). This is the project's source of truth
+for durable decision policy. Do not copy the catalogue into the ticket and do
+not force every principle to apply.
+
+- **Missing or empty:** ask whether to add principles now or proceed without.
+- **Applicable:** carry the principle forward only when it changes a Rule,
+  design choice, proof, or deliberate deviation.
+- **Experiential:** translate it into observable Rules and, when appropriate, a
+  Rave Moment; tests prove the mechanics, not the emotion itself.
+- **Technical:** keep product Rules technology-neutral and carry the principle
+  into plan-implementation, where alternatives and evidence belong.
+
 ## Load project personas
 
 At intake start, read the configured personas file (`paths.personas`, default `<namespace-root>/personas.md`). This file is the project's source of truth for who features serve; later phases (JTBD authoring, criteria validation, scenario numbering) reference its entries.

package/codex-plugin/skills/bdd/references/PLAN_IMPLEMENTATION.md

@@ -21,6 +21,16 @@ worktree. Never reuse the spike's experimental code or commits.
 2. **Then survey what exists** — after sketching the ideal, read the generated architecture state doc (`architecture.generated.md` — the machine-owned _what-is_) and the decision record (resolved from `paths.architecture`) for **reuse** candidates: components that already do the job, or do it better. Order matters: surveying first anchors the design to the status quo.
 3. **Reconcile without sunk-cost conformance.** Existing architecture is changeable with a recorded decision, not a constraint to conform to. Reuse what's better; change what's worse — deliberately, with the change recorded (ADR lifecycle below).
 
+## Apply project principles
+
+Re-read the configured principles file (`paths.principles`, default
+`<namespace-root>/principles.md`) so planning does not depend on intake context
+surviving. Identify only the **applicable project principles**—do not enumerate
+the catalogue as a checklist. For each applicable principle, record in Design
+alignment: **principle → concrete consequence → proof**. Put an intentional
+conflict in Known deviations with its reason. No applicable principle is a
+valid `skip:`; vague “complies with principles” prose is not.
+
 ## Environment fluency
 
 - **Map installed language skills and component skills to the scenarios** — for the languages the feature touches, check the installed skill packs (`.claude/skills/<lang>-*`) and note per-scenario which apply. Scope to the feature's touched code and surfaces: in a polyglot monorepo, surface only what's relevant, never the full inventory.
@@ -36,7 +46,7 @@ Scaffold from `.safeword/templates/impl-plan-template.md` (sibling to `ticket.md
 
 - **Approach** — open with the riskiest assumption and the cheapest scenario that proves it; then the proof plan: for each scenario the primary proof (`unit`, `integration`, `E2E`, or `eval` per `testing/SKILL.md`'s highest practical scope rule), supporting proofs, at least one wiring test per new entry point, and the build order with the load-bearing slice first. Cover each **affected surface** the spec lists — name the proof that covers it or a per-surface `skip: <reason>`.
 - **Decisions** — one row per significant technical choice: choice, alternatives, rejected-because, with the `$safeword:figure-it-out` evidence cited.
-- **Arch alignment** — consult the architecture record (resolve `paths.architecture` in `.safeword/config.json`; default `.project/architecture.md`; a directory holds one ADR per `.md`, README excluded) **before** filling this in. Records exist: list the decisions this design honors. None recorded yet: write `skip: no ADRs in this project yet` and offer to draft the first ADR (technology choices spanning features, data ownership, cross-service contracts).
+- **Design alignment** — record applicable project principles with their concrete consequence and proof, then consult the architecture record (resolve `paths.architecture` in `.safeword/config.json`; default `.project/architecture.md`; a directory holds one ADR per `.md`, README excluded). Records exist: list the decisions this design honors. With applicable principles but no records, write `None recorded yet` for the architecture sub-entry and offer to draft the first ADR for a significant decision. With neither applicable principles nor architecture records, write `skip: no applicable principles or ADRs` and offer to draft the first ADR for a significant decision (technology choices spanning features, data ownership, cross-service contracts).
 - **Known deviations** — where this deviates from guidance and why that's acceptable.
 - **Doc impact** — which configured `docs.sources` surfaces the customer-visible changes touch, folded into the build order as tasks; internal-only: `skip: <reason>`.
 - **Assessment triggers** — what would prompt revisiting these choices.
@@ -57,7 +67,7 @@ Scaffold from `.safeword/templates/impl-plan-template.md` (sibling to `ticket.md
 
 ## Exit: review, then (optionally) the user
 
-1. **Independent review first.** Spawn a fresh reviewer with no conversation history — handed only `impl-plan.md`, the ticket scope, and the `.feature` source — to refute the plan (wrong-direction design, missed scenarios, editorial padding via the deletion test). Fix findings, re-review, then stamp the exit (`write-review-stamp.ts --phase plan-implementation`, where the review gate is enabled). Human handoff happens **only after** this review passes — raw planning output is never presented for approval. Exception, any time: information only the user has (intent, priorities, constraints not in code or docs) routes to the user the moment the gap appears — `$safeword:elicit`.
+1. **Independent review first.** At review time, run `bun .safeword/hooks/resolve-project-knowledge.ts`, then run `safeword review run plan-implementation impl-plan.md spec.md ticket.md feature-file principles-file personas-file surfaces-file` with the current files identified by the resolver. The shared coordinator sends that bounded packet to the opposite headless agent when available; its typed verdict, failure classification, and independence level are authoritative, so do not substitute a private subagent. Give the reviewer the current `spec.md`, configured principles file, configured personas file, and configured surfaces file in that packet. The reviewer refutes the plan: challenge whether it selected the actually applicable principles, whether each concrete consequence follows from its principle, whether the proposed proof can prove that consequence, whether conflicts belong in Known deviations, whether the design fulfills each persona's JTBD, and whether any affected surface was omitted or lacks credible proof. Also check wrong-direction design, missed scenarios, and editorial padding via the deletion test. Fix findings, re-resolve the sources, re-review, then stamp the exit with the returned agent provenance (`write-review-stamp.ts --author-agent "author-agent" --reviewer-agent "actual-reviewer" --independence "independence" --phase plan-implementation`, where the review gate is enabled). Add `--model` only when the executed reviewer reports a verifiable model identifier; the coordinator never invents one. Human handoff happens **only after** this review passes — raw planning output is never presented for approval. Exception, any time: information only the user has (intent, priorities, constraints not in code or docs) routes to the user the moment the gap appears — `$safeword:elicit`.
 2. **`designApprovalGate`** (in `.safeword/config.json`): **absent or off** — the reviewed plan advances autonomously; do not ask. **Enabled** — present the reviewed plan (riskiest assumption, build order, decisions) and wait for user approval before `implement`.
 3. **Sessions without an interactive user** (cloud/headless — Claude Code on the Web, Codex Cloud, Cursor Cloud Agents): an enabled approval gate must not stall the container. Record the auto-decision as pending approval in the ticket work log and surface the reviewed plan in the session's reviewable output (PR description / session summary) — approval lands at PR review. Note: Cursor Cloud Agents run `preToolUse` hooks but not stop hooks, so enforcement rides the transition gate there, not stop-time nudges.
 4. **Update frontmatter:** `phase: implement`. The pre-tool transition gate verifies `impl-plan.md` parses valid with status `planned` — a missing or invalid plan blocks the move with the fix named. A `phase_skips` justification satisfies phase provenance only — a new-flow feature (spec.md present) still needs the valid plan to enter implement.

package/codex-plugin/skills/bdd/references/TDD.md

@@ -153,7 +153,7 @@ Then reconcile the plan.
 All scenarios complete → reconcile `impl-plan.md` against what actually shipped, **before** advancing to verify (the stop hook blocks `verify`/`done` while the plan still says `planned`):
 
 1. **Walk the Decisions table** — for each row ask "did we actually do this, or did we change our mind?" Update changed rows: new choice, new rationale, the abandoned choice moves into Alternatives considered.
-2. **Walk Arch alignment** — for each claim ask "did the implementation honor this?" Move anything that deviated into **Known deviations** with the reason.
+2. **Walk Design alignment** — for applicable project principles and architecture claims, ask "did the implementation honor each stated consequence, and does its proof pass?" Move anything that deviated into **Known deviations** with the reason.
 3. **Refresh Assessment triggers** — add triggers the implementation surfaced (e.g., "works at current scale, degrades past 10x").
 4. **Flip the status line** to `**Status:** implemented`. The phase hook stamps the transition with real time (Claude Code — on other harnesses add a short transition entry yourself); log the reconciliation outcome ({N} decisions updated, {M} deviations recorded) as a narrative work-log entry.
 
@@ -169,20 +169,20 @@ surfaces a real spec, scope, value, or risk decision.
 Off by default. When `.safeword/config.json` sets `architectureReviewGate: true`, the stop hook blocks `verify`/`done` for a new-flow feature until its `impl-plan.md` design has been **independently reviewed** — the same propose-then-challenge discipline the scenario-gate applies to scenarios, now applied to the design. Two requirements:
 
 1. **Cited evidence.** The Decisions section must carry a citation — a URL or a `[n]` source-reference marker — proving the choice was weighed against real evidence (the `$safeword:figure-it-out` trace), or an auditable `skip: <reason>`.
-2. **A fresh-context review.** Spawn a reviewer with **no conversation history**, handed only `impl-plan.md` and the ticket scope, to try to refute the design against its cited sources. On a pass, stamp it:
+2. **A fresh-context review.** Run `safeword review run plan-implementation impl-plan.md ticket-spec feature-file` so the shared coordinator gives only the bounded design evidence to the preferred opposite headless agent. Its typed result must satisfy the configured policy; a private subagent result cannot satisfy this gate. On a pass, stamp it:
 
    ```bash
-   bun .safeword/hooks/write-review-stamp.ts impl-plan
+   bun .safeword/hooks/write-review-stamp.ts --author-agent "author-agent" --reviewer-agent "actual-reviewer" --independence "independence" impl-plan
    ```
 
    The stamp binds to the plan's current content, so editing the design after review invalidates it — re-review and re-stamp.
 
-**Cross-model (`crossModelReview: true`).** The reviewer must run on a **different model than the author** — a same-model reviewer shares the author's blind spots (correlated errors). Prefer one of comparable-or-better capability; never weaker. This means an explicit different-model subagent — **not** a `context: fork`, which inherits the author's model. Record the model you assigned:
+**Cross-model (`crossModelReview: true`).** The reviewer must run on a **different model than the author** — a same-model reviewer shares the author's blind spots (correlated errors). Prefer one of comparable-or-better capability; never weaker. Record a model only when the executed reviewer reports a verifiable identifier; the cross-agent coordinator does not guess a default model:
 
 ```bash
-bun .safeword/hooks/write-review-stamp.ts --model "<reviewer-model-id>" impl-plan
+bun .safeword/hooks/write-review-stamp.ts --author-agent "author-agent" --reviewer-agent "actual-reviewer" --model "verified-model" --independence "independence" impl-plan
 ```
 
-The gate compares that tag against the author model (captured at SessionStart) and enforces **different only** — "comparable-or-better" is your judgment, not gate-checked. An absent tag fails closed. If you can't run a different model, log a deliberate skip (`--skip "<reason>"`) rather than stamping a same-model review. (This gate is stricter than quality-review's advisory loop, which accepts a fresh-context pass on your own model — here a genuinely different model, or an explicit `--skip`, is required.)
+The gate compares that tag against the author model (captured at SessionStart) and enforces **different only** — "comparable-or-better" is your judgment, not gate-checked. An absent tag fails closed. When `crossAgentReview` is `require`, degraded evidence and skips also fail closed; restore the opposite reviewer and rerun the coordinator. (This gate is stricter than quality-review's advisory loop, which may accept a labeled same-agent result under the default `prefer` policy.)
 
 **Avoid bloat.**

package/codex-plugin/skills/closeout/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: closeout
+description: Close a completed local delivery safely. Use when wrapping up a
+  finished coding session by verifying it, merging only with explicit authority,
+  running the mandatory retrospective, and cleaning the exact merged branch and
+  worktree. Do NOT use for cloud-agent tasks, unmerged work, or cleanup without
+  a pull request.
+---
+
+# Closeout
+
+Close a completed local GitHub delivery from observed state. Never compress the
+workflow into “merge succeeded, so we are done.”
+
+## 1. Prove delivery readiness
+
+Run `$safeword:verify` for the current pull request head. Then observe the pull request
+directly with structured `gh pr view --json` output. Require all of these before
+any merge:
+
+- local verification covers the current pull request head;
+- all required checks pass;
+- review requirements are satisfied; and
+- the pull request is not a draft.
+
+Collect and report every blocker. Missing, stale, failing, pending, unknown, or
+ambiguous evidence means **no merge or cleanup**. A merge command's exit status
+never proves that the pull request is merged.
+
+## 2. Respect merge authority
+
+Invocation alone grants no merge authority. Read authority only from the current user request;
+historical, implied, or previously consumed authority is not available to a
+resumed closeout.
+
+- **No authority:** report that the delivery is ready and stop before merging.
+- **Normal merge:** only an explicit current request for a normal merge permits a
+  policy-compliant `gh pr merge`. Never escalate a blocked normal merge.
+- **Administrative merge:** only an explicit current request to perform an
+  administrative merge or bypass repository requirements permits `--admin`.
+
+Merge authority is consumed when the merge action is attempted. Entering a merge
+queue or enabling auto-merge consumes it too; later runs observe that queued
+action and do not repeat it.
+
+## 3. Re-observe merge truth and resume
+
+After every merge command—success or error—re-observe the exact pull request:
+
+```sh
+gh pr view PR_NUMBER --json state,mergedAt,mergeCommit,headRefName,headRefOid
+```
+
+Continue only when `state` is exactly `MERGED` and the observed head still
+matches the recorded pull request head. Queued, automatic, pending, unknown, or
+unobservable results are not merge proof; report the recovery check and stop.
+
+If the command reported an error but fresh observation proves the expected head
+was merged, report that the remote merge succeeded, do not retry it, and proceed
+to the mandatory retrospective. On every invocation, re-observe durable state
+and continue only the unfinished suffix. Treat an absent cleanup target as
+complete only after proving it was the exact planned target. If the pull request
+is merged, its retrospective is complete, and its exact branch and worktree are
+already absent, report that the session is already closed.
+
+## 4. Complete the current session's retrospective
+
+After merge is independently confirmed, invoke the cleanup guard in preview
+mode. Its host hook supplies a short-lived, single-consumer binding to this exact
+session (and Cursor transcript). A missing or expired binding fails closed;
+there is no newest-session fallback and callers cannot nominate another receipt,
+session, transcript, or spool.
+
+The guard runs `safeword retro run --json` itself and accepts only a
+successful result whose `data.agent_filing_needed` is `false` and whose derived
+current session has an empty filing spool. Zero substantial findings and every
+finding successfully filed are both complete outcomes.
+
+Failed extraction, failed filing, pending drafts, malformed output, or an
+identity mismatch means no cleanup. Report every failure and its recovery
+action. A request to skip retro does not create a bypass: preserve the worktree
+and branches and explain that the retrospective is required before cleanup.
+
+## 5. Preview, confirm, and apply exact cleanup
+
+Run the guard from the delivery worktree; preview is the default:
+
+```sh
+bun .safeword/scripts/closeout-cleanup.ts --pr PR_NUMBER
+```
+
+The preview reruns the project's verification, build, typecheck, BDD, and
+dependency plans and binds the resulting repository state and exact PR identity
+to `PLAN_DIGEST`. Report the complete operation list and all blockers. Do not
+apply a blocked plan.
+
+With the user's cleanup intent already established by invoking closeout, apply
+only the unchanged preview:
+
+```sh
+bun .safeword/scripts/closeout-cleanup.ts --pr PR_NUMBER --yes --plan PLAN_DIGEST
+```
+
+The guard re-observes identity and executes only this order: worktree, remote
+branch, local branch. It never passes `--force` to `git worktree remove`; remote
+deletion uses an exact `--force-with-lease`, and squash/rebase-safe local deletion
+uses `git update-ref -d` with the recorded old OID. Never use merge-time branch
+deletion. Changed, dirty, locked, stale, protected, default, main, ambiguous, or
+other-worktree targets are preserved and reported with a recovery action.
+
+## 6. Report the durable result
+
+Claim the session complete only after fresh observation proves every state.
+Report:
+
+- verification and the exact verified head;
+- merged state and merge commit;
+- retrospective completion and filing result;
+- remote branch, local branch, and worktree state; and
+- unresolved items (explicitly `none` when empty).
+
+When blocked or partially complete, report every blocker and its recovery action,
+including simultaneous blockers. Never hide a successful remote merge behind a
+later local cleanup failure, and never describe a planned deletion as completed.

package/codex-plugin/skills/quality-review/SKILL.md

@@ -48,6 +48,56 @@ If in a BDD workflow, read the current ticket from `<namespace-root>/tickets/` a
 | verify              | Flaky-test & regression patterns, coverage gaps |
 | done                | CI/CD patterns, release checklists              |
 
+### Project-principle challenge
+
+For a BDD ticket, run `bun .safeword/hooks/resolve-project-knowledge.ts` at the
+start of each pass and read the current `principles`, `personas`, and `surfaces`
+paths and content it returns (including overrides such as `paths.principles`).
+Do not substitute labels or intake-era content.
+With `impl-plan.md`, read those sources alongside the plan and work-product.
+Treat the plan's
+**principle → concrete consequence → proof** entries as claims to refute, not a
+compliance checklist:
+
+- Challenge applicability, including a principle the plan may have omitted;
+  report only omissions that would materially change behavior, design, proof,
+  or a deliberate deviation.
+- Check that each consequence actually follows from the principle and appears
+  in the shipped work; check that the named proof demonstrates that consequence
+  rather than adjacent mechanics.
+- An experiential principle is not proven by tests alone. Require the
+  user-facing signal the plan named—such as a persona walkthrough, usability
+  observation, or Rave Moment check—and state any evidence limitation.
+- For sourcing or architecture principles, independently check current options,
+  extension boundaries, and compatibility claims against primary sources; do
+  not accept the plan's research summary as its own proof.
+- Treat an intentional conflict as valid only when Known deviations names it
+  and explains the trade-off.
+
+This is the judgment gate. `$safeword:audit` later checks trace integrity as observable
+facts only; it does not decide whether a principle was applicable or wise.
+
+### Persona and surface challenge
+
+For a BDD ticket, read `spec.md` plus the configured persona and surface
+inventories (`paths.personas` and `paths.surfaces`). Challenge whether the
+shipped behavior fulfills each persona's JTBD and Rules, rather than merely
+resolving a persona code. Then reconcile every affected surface against the
+plan, scenarios, and verification output:
+
+- Require one concrete proof result per affected surface, or a named `skip:`
+  with its limitation; an `@surface.*` tag alone is coverage intent, not surface
+  evidence.
+- Check the surface evidence used the real surface boundary or names why that
+  boundary could not run. A generic unit test does not prove runtime, client,
+  protocol, or deployment parity.
+- Challenge omitted personas or surfaces only when the source artifacts and
+  ticket scope make the omission material; do not turn either inventory into a
+  universal checklist.
+
+Persona fulfillment and proof fidelity are review judgments. `$safeword:audit` owns only
+unknown references, stale tags, and dead evidence links.
+
 ## 2. Research Angles
 
 Run each angle that applies — angle _diversity_ is the lever, not search volume: **source-currency** + **risk/security** (this section), **supersession** + **primary-source docs** (§3). If the user gave a focus or scope restriction, apply it to **every** angle — don't use it only for the first search.
@@ -119,17 +169,21 @@ Run the review in passes until **Critical issues** come back None. A couple of p
 
 Each pass:
 
-1. **Review with a fresh, independent reviewer.** A same-model, same-context
-   reviewer shares your blind spots, and ungrounded self-correction can
-   _degrade_ the work rather than improve it. Prefer a different model of
-   comparable-or-better capability; otherwise run a fresh-context pass on your
-   own model (the usual path, since most setups run one model) — never a
-   _weaker_ one. Hand the reviewer only the work-product and its scope, have it
-   apply §1–3, and return the Output Format above.
-   - Claude Code: Agent/Task tool. Codex: ask in your prompt — subagents never
-     auto-spawn, and `/agent` only switches existing threads. Cursor: subagents.
-     No sub-agent? Re-read in a fresh context — independence is the point, not
-     the mechanism.
+1. **Run the shared independent-review coordinator.** After gathering any
+   current-source evidence needed by §1–3, pass only the bounded work-product
+   and scope to the host-owned coordinator:
+
+   ```bash
+   safeword review run quality-review changed-file [more-changed-files...]
+   ```
+
+   Claude-authored work prefers headless Codex; Codex-authored work prefers
+   headless Claude. The coordinator uses a neutral snapshot, checks reviewer
+   provenance, preserves the exact preferred-route failure, and labels any
+   permitted same-agent fallback as degraded. Treat its typed result as the
+   review verdict. If it blocks, follow its one recovery action; do not invent
+   a private subagent route or mint passing evidence yourself.
+
 2. **Triage.** Fix every **Critical issue** this pass. Apply the **Suggested
    improvements** worth the change; list the rest — don't chase them.
 3. **Decide.** Stop when **Critical issues = None**; remaining suggestions are

package/codex-plugin/skills/retro-filer/SKILL.md

@@ -48,9 +48,14 @@ the host project.
 
 4. After every successful comment or create, append exactly one compact JSON ack
    `{"signature":"<signature>","issue":<number>}` to the sibling `.acks.jsonl`
-   file before removing that draft from the spool. Leave failed drafts in place.
-5. Create at most five new issues per run. Rewrite the spool with only unfiled
-   drafts, or delete it when none remain. If tracker write access is unavailable,
-   leave the spool unchanged and report `retro-filer: cannot file - <reason>`.
+   file, then re-read it and exact-match that signature and destination. Remove
+   the draft only when the append succeeded and the exact ack is visible. If the
+   append or verification fails, leave the draft in place.
+5. Create at most five new issues per run. Drain only by running
+   `bun .safeword/hooks/lib/drain-retro-spool.ts "<spool-path>"`; never rewrite or
+   delete the spool directly. The helper removes only drafts whose valid ack is
+   reader-visible, so unfiled or unacknowledged drafts remain. If tracker write
+   access is unavailable, leave the spool unchanged and report
+   `retro-filer: cannot file - <reason>`.
 
 Finish with one line of counts: `retro-filer: filed 2, commented 1, remaining 0`.