safeword 0.82.3 → 0.82.4

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

@@ -1,6 +1,6 @@
 {
   "name": "safeword",
-  "version": "0.82.3",
+  "version": "0.82.4",
   "description": "Safeword workflow guidance and gates for Codex.",
   "author": {
     "name": "Arcade AI"

package/codex-plugin/package.json

@@ -1,5 +1,5 @@
 {
   "name": "safeword-codex-plugin",
-  "version": "0.82.3",
+  "version": "0.82.4",
   "type": "module"
 }

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

@@ -561,7 +561,7 @@ Changed project learnings in the resolved namespace root's `learnings/*.md` must
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2> /dev/null || pwd)}"
 source "$PROJECT_DIR/.safeword/hooks/lib/audit-scope.sh"
 audit_scope_initialize "$PROJECT_DIR" || exit $?
-NS_ROOT="$(bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project namespace-root --cwd "$PROJECT_DIR")"
+NS_ROOT="$(bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project namespace-root --cwd "$PROJECT_DIR")"
 
 learning_is_in_audit_scope() {
   [ "$AUDIT_SCOPE_MODE" = "repository" ] && return 0
@@ -721,13 +721,13 @@ audit_scope_initialize "$PROJECT_DIR" || exit $?
 
 # 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 "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project namespace-root --cwd "$PROJECT_DIR" 2> /dev/null)"
+NS_ROOT="$(bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project namespace-root --cwd "$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 "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project namespace-root --cwd "$PROJECT_DIR" --key personas 2> /dev/null)"
-SURFACES_FILE="$(bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project namespace-root --cwd "$PROJECT_DIR" --key surfaces 2> /dev/null)"
-GLOSSARY_FILE="$(bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project namespace-root --cwd "$PROJECT_DIR" --key glossary 2> /dev/null)"
+PERSONAS_FILE="$(bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project namespace-root --cwd "$PROJECT_DIR" --key personas 2> /dev/null)"
+SURFACES_FILE="$(bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project namespace-root --cwd "$PROJECT_DIR" --key surfaces 2> /dev/null)"
+GLOSSARY_FILE="$(bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project namespace-root --cwd "$PROJECT_DIR" --key glossary 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"

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

@@ -159,10 +159,10 @@ findings remain. Return findings through the typed reviewer result contract.
 
 ## Exit: review, then (optionally) the user
 
-1. **Independent review first.** At review time, run `bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project review-knowledge --json`. Resolve a review-capable Safeword CLI, then invoke the coordinator with the current files identified by the resolver:
+1. **Independent review first.** At review time, run `bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project review-knowledge --json`. Resolve a review-capable Safeword CLI, then invoke the coordinator with the current files identified by the resolver:
 
    ```bash
-   SAFEWORD_REVIEW_PROGRESS=1 bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" review run plan-implementation --agent-handoff --json --context spec.md ticket.md feature-file principles-file personas-file surfaces-file architecture-records -- impl-plan.md
+   SAFEWORD_REVIEW_PROGRESS=1 bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" review run plan-implementation --agent-handoff --json --context spec.md ticket.md feature-file principles-file personas-file surfaces-file architecture-records -- impl-plan.md
    ```
 
    The shared coordinator sends that bounded packet to the opposite headless agent when available; its typed verdict, failure classification, and independence level are authoritative. `impl-plan.md` is the work under review; all resolved feature and project artifacts are bounded context. Only when that typed result is `REVIEW_ROUTES_EXHAUSTED`, invoke `$safeword:finish-review` immediately with the original result and the same accepted targets; return every other result unchanged and do not substitute another private subagent. 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`.

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

@@ -196,7 +196,7 @@ Off by default. When `.safeword/config.json` sets `architectureReviewGate: true`
 2. **A fresh-context review.** Resolve a review-capable Safeword CLI, then run the shared coordinator with only the bounded design evidence:
 
    ```bash
-   SAFEWORD_REVIEW_PROGRESS=1 bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" review run plan-implementation impl-plan.md ticket-spec feature-file --agent-handoff --json
+   SAFEWORD_REVIEW_PROGRESS=1 bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" review run plan-implementation impl-plan.md ticket-spec feature-file --agent-handoff --json
    ```
 
    The shared coordinator prefers the opposite headless agent. Only when its typed result is `REVIEW_ROUTES_EXHAUSTED`, invoke `$safeword:finish-review` with the original result and the same accepted targets; return every other result unchanged. Degraded findings cannot satisfy a required independent-review gate. On an independent pass, stamp it:

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

@@ -39,7 +39,7 @@ Gather the durable trail safeword already keeps, then narrate it. Run:
 
 ```bash
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2> /dev/null || pwd)}"
-NS_ROOT="$(bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project namespace-root --cwd "$PROJECT_DIR")"
+NS_ROOT="$(bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project namespace-root --cwd "$PROJECT_DIR")"
 # What you're on now: the last re-entry line names the current ticket + Next
 tail -3 "$NS_ROOT/re-entry.md" 2> /dev/null
 # Fallback when re-entry is empty: in_progress tickets (not epics)

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

@@ -50,7 +50,7 @@ If in a BDD workflow, read the current ticket from `<namespace-root>/tickets/` a
 
 ### Project-principle challenge
 
-For a BDD ticket, run `bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project review-knowledge --json` at the
+For a BDD ticket, run `bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project review-knowledge --json` 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.
@@ -212,7 +212,7 @@ Each pass:
    guarantee a bare `safeword` on `PATH`:
 
    ```bash
-   SAFEWORD_REVIEW_PROGRESS=1 bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" review run quality-review [--context path/to/evidence] --agent-handoff --json -- changed-file [more-changed-files...]
+   SAFEWORD_REVIEW_PROGRESS=1 bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" review run quality-review [--context path/to/evidence] --agent-handoff --json -- changed-file [more-changed-files...]
    ```
 
    A healthy deep review may return `REVIEW_PENDING` after its foreground

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

@@ -17,7 +17,7 @@ a caller-nominated path. The spool contains sanitized safeword findings for
 ## Procedure
 
 1. Before reading or making any tracker call, run
-   `bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project retro-drain "<spool-path>" --validated-jsonl`.
+   `bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project retro-drain "<spool-path>" --validated-jsonl`.
    Use only its JSONL stdout as the filing input. A nonzero exit means validation
    failed: make no search, comment, or create call, leave the spool unchanged,
    and report `retro-filer: cannot file - draft validation failed`. If its output
@@ -60,7 +60,7 @@ a caller-nominated path. The spool contains sanitized safeword findings for
    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 "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project retro-drain "<spool-path>"`; never rewrite or
+   `bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project retro-drain "<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

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

@@ -35,7 +35,7 @@ Adversarially review a ticket's scenarios: treat them as if you're trying to bre
 - **Manual re-run** — invoke `$safeword:review-spec` anytime after `define-behavior` (e.g., scenarios changed during implement and you want to re-validate). Allowed on a closed ticket too — a post-hoc audit is still readable.
 
 Read the active ticket's `.feature` source first. At review time, run
-`bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project review-knowledge --json` and read the current
+`bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project review-knowledge --json` and read the current
 `principles`, `personas`, and `surfaces` source paths and content it returns, so
 the review is grounded in project knowledge rather than labels or stale intake
 context. The resolver honors `paths.principles`, `paths.personas`, and
@@ -58,7 +58,7 @@ Resolve a review-capable Safeword CLI first; source checkouts do not guarantee
 a bare `safeword` on `PATH`:
 
 ```bash
-SAFEWORD_REVIEW_PROGRESS=1 bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" review run scenario-gate feature-file [legacy-test-definitions] --context ticket-spec [dimensions-file] principles-file personas-file surfaces-file --agent-handoff --json
+SAFEWORD_REVIEW_PROGRESS=1 bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" review run scenario-gate feature-file [legacy-test-definitions] --context ticket-spec [dimensions-file] principles-file personas-file surfaces-file --agent-handoff --json
 ```
 
 The coordinator's assigned/actual reviewer, failure classification, and

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

@@ -45,7 +45,7 @@ installed helper — report it to the user and resolve before retrying.
 ## Review the spec (do this now, with the stamp written)
 
 The stamp records that a review was invoked; the actual scrutiny is yours. At
-review time, run `bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.3/runtime/cli.js" project review-knowledge --json` and use its
+review time, run `bun "${CODEX_HOME:-$HOME/.codex}/plugins/cache/safeword/safeword/0.82.4/runtime/cli.js" project review-knowledge --json` and use its
 current `principles`, `personas`, and `surfaces` source paths and content—not
 labels remembered from intake. These resolve from `paths.principles`,
 `paths.personas`, and `paths.surfaces` when configured. Read those sources with the active ticket's

package/codex-plugin/templates/SAFEWORD.md

@@ -0,0 +1,252 @@
+# SAFEWORD Agent Instructions
+
+The standing operating model for this project. Read at session start; re-scan by topic as situations arise. Project-specific rules live in `./CLAUDE.md`. Triggered playbooks live in `./.safeword/guides/`.
+
+Project knowledge (tickets, learnings, principles, personas, glossary, surfaces) lives under the **project namespace root**: configurable via `paths.projectRoot` in `.safeword/config.json`, `.project/` by default, with legacy `.safeword-project/` honored only when that directory already exists. Paths below use `<namespace-root>` for the resolved directory.
+
+---
+
+## Workflow
+
+A safeword session runs through these phases in order. Each phase has an exit criterion — meet it before advancing.
+
+### 1. Clarify (Propose-and-Converge)
+
+Understand what the user is asking before classifying or building. **Propose-and-Converge** means: lead with a perspective, then surface open questions _inside_ that proposal. Don't ask first — propose first.
+
+Each turn, restate what you heard, contribute a perspective/sketch/reframe, and surface the remaining open questions inside that contribution. Incorporate what the user confirms to narrow the open set; advance once none remain and the user accepts.
+
+Research before proposing anything significant — and the order is load-bearing:
+
+1. **Frame** the problem and its hard constraints: prior tickets, the data model, non-negotiable framework idioms. Don't read the soft conventions yet.
+2. **Design the ideal.** Run `$safeword:figure-it-out` to weigh 2-3 options on correctness, simplicity, and no-bloat, and pick the best architecture _as if the codebase didn't exist_. Computing this first gives the next step a yardstick.
+3. **Survey the existing patterns** in the area you're about to touch — now, not before. Surveying earlier anchors the design to the status quo and quietly shrinks it to match.
+4. **Reconcile.** Conform to the existing pattern by default — deviate only when the ideal is a real improvement, not taste. When your ideal diverges from what exists, record the call: to deviate, name a concrete defect of the existing pattern the ideal fixes, the call-site count you're splitting, a one-line pre-mortem ("assume this was wrong — what broke?"), and the follow-up ticket to uplevel the rest. Reversible and local → a few lines in the ticket; irreversible or cross-cutting (data model, public API) → promote to an ADR. See `./.safeword/guides/architecture-guide.md`.
+
+Depth scales with ambiguity. Clear request → 0 turns. One open question → 1 turn. Vague idea → 2-3 turns of increasingly specific proposals.
+
+If the user references a ticket ID/slug or says "resume" / "continue", skip Clarify and resume at the ticket's current phase.
+
+**Replan on resume.** The plan may be stale: a `Resume check: N commit(s)…` line means someone else's commits touched files this ticket references since you last worked on it. This is opt-in: if the user declines or just proceeds, investigate nothing. If the user accepts ("check the plan"), spawn a fresh sub-agent (`isolation: worktree`) to judge whether scope still holds and report back **in chat only** — proposing one of still-good / change-scope / cancel / split / merge, with rationale. If the verdict is change-scope or split, run `$safeword:figure-it-out` before proposing a new approach — scope changed because the world changed, which is exactly when re-deciding from memory is most dangerous. Never edit the ticket without explicit approval. If the sub-agent errors or times out, note it in one line and proceed with the work — don't retry in a loop (the heads-up won't re-fire until new commits land).
+
+**Contribution techniques** to weave into proposals (pick the one that fits the gap):
+
+- Failure modes — when reliability or error handling is unclear.
+- Boundaries — when scope could expand indefinitely.
+- Scenario walkthrough — when the description is abstract.
+- Regret test — when deciding what stays in or out of scope.
+- User experience — when success criteria aren't described.
+
+Before proceeding, run the **specificity self-test**: can you describe the behavior that changes, the behavior that stays the same, and an observable "done" state? Any "no" means open questions remain — surface them.
+
+**Readiness triage.** The five-dimension check the prompt pointer abbreviates:
+
+- **Intent** — why, and for whom.
+- **Done** — a measurable end-state.
+- **Constraints** — what must not break, reversibility.
+- **Riskiest assumption** — and the cheapest way to test it before building.
+- **Request shape** — is this the problem, or someone's guess at the fix?
+
+Scale depth by blast radius — reversible, local work proceeds; irreversible or high-blast work resolves the open unknowns first. You're ready when your remaining questions are about edge-cases and trade-offs, not basics. For one-way-door (irreversible) features, intake offers a deeper **cold-start executability check** at exit (`.safeword/guides/cold-start-check.md`) — a context-free agent attempts to plan the work from the captured spec alone, surfacing what it couldn't reconstruct; runnable on demand too.
+
+**PM-grade intake** is the name for how these fit together, scaled by blast radius — one protocol, not three disconnected mechanisms:
+
+- The readiness pointer nudges every turn.
+- The Intake Brief (who asked · cost of inaction · reversibility) is authored for features.
+- The cold-start executability check fires only for one-way-door work.
+- `$safeword:elicit`, `$safeword:brainstorm`, and `$safeword:figure-it-out` get pulled in as the gaps demand (unknown intent · empty option space · options to weigh).
+
+**Project principles.** Before choosing scope or design, read the configured
+principles file (`paths.principles`, default `<namespace-root>/principles.md`)
+when it exists. Apply it as a decision lens, not a checklist: a principle pays
+rent only when it changes behavior, design, proof, or a deliberate deviation.
+Features record applicable principles in `impl-plan.md`'s Design alignment as
+**principle → concrete consequence → proof**. Tasks note a principle only when
+it materially changes the task; patches apply it silently unless they need an
+explicit exception. Never claim an experiential principle is proven by tests
+alone — tests prove observable mechanics; user evidence proves the experience.
+
+If the conversation feels circular, make a best-guess proposal: "Here's my best read — should I build this, or is something off?"
+
+Exit: user accepts your proposal. For features, intake builds its artifacts in order, each anchoring the next:
+
+1. Load personas, glossary, and surfaces from the configured project-knowledge files.
+2. Open with a short **Intake Brief** in `spec.md` (who asked · cost of inaction · reversibility) — the framing for the decision to build, which also triages whether this is a feature or a leaner task.
+3. Author the Jobs To Be Done in `spec.md` — one persona from the configured personas file per job, in the "When I…, I want…, so I can…" form. Jobs are outcomes the persona wants to be true; never drop or narrow one because of how it would be built. Feasibility, state, and which layer serves it are plan-implementation questions.
+4. Decompose each job into numbered Rules — one testable invariant per `#### <jtbd-id>.R<n>`, the level that define-behavior scenarios later prove against. (Acceptance Criteria — `#### <jtbd-id>.AC<n>` — is the still-supported legacy alternative; one criteria kind per job, never both.)
+5. Let jobs-and-rules anchor the engineering scope you write to ticket frontmatter — every resolved question produces scope (accepted choice = in scope, rejected alternative = out of scope):
+
+- **`scope`** — what you're building (derived from accepted choices).
+- **`out_of_scope`** — what you're not building (rejected alternatives + domain-knowledge exclusions).
+- **`done_when`** — observable outcomes.
+
+In define-behavior, each scenario carries its lineage `<jtbd-id>.R<#>.<scenario_name>` (snake_case; `.AC<#>` on the legacy path) so `safeword doctor` flags coverage gaps — uncovered rules, orphan scenarios. The bdd skill's DISCOVERY.md walks these sub-steps end to end with a worked example; SCENARIOS.md covers the numbering.
+
+If the user is exploring without intent to build, follow their lead — not every conversation produces a ticket.
+
+### 2. Classify (Sizing)
+
+Pick the work level internally. Don't announce it as a label ("Feature detected!"); state your scope read as part of your proposal.
+
+Three questions:
+
+1. How many files will this touch?
+2. Does this introduce new persistent state?
+3. Are there multiple user flows?
+
+```text
+All no or 1 file                          → patch    (fix directly)
+1-2 files, one testable behavior          → task     (TDD)
+3+ files OR new state OR multiple flows   → feature  (write scenarios first)
+```
+
+Fallback: task. User can `$safeword:bdd` to override.
+
+Sizing reads the jobs; it never edits them. A job that implies new state or a new flow makes the work **bigger** — that is a signal to split into an epic, never to drop the job so the work fits a smaller box. If you find yourself pruning jobs and the size falls, you sized the proposal instead of the work.
+
+Calibration the rules don't capture:
+
+- "Change button color to red" → task (1 file but real behavior change).
+- "Add dark mode toggle" → feature (3+ files, new state).
+- "Implement the fix for bug #123" → task (bug fix, despite "implement").
+- "Build the Docker image" → patch (infrastructure, not product).
+- "Clear pre-existing lint debt across 17 files" → task (mechanical cleanup — no behavior to discover, so the file count is noise).
+
+### 3. Build
+
+- **patch:** restate what you're fixing, fix it. `$safeword:bdd` to override.
+- **task:** restate scope, run TDD (RED → GREEN → REFACTOR). `$safeword:bdd` to override.
+- **feature:** include sizing in the proposal ("this touches N components with new state — I'd write scenarios"). Run `$safeword:bdd`; skip straight to TDD to override.
+
+### 4. Verify
+
+Never ask the user to test what you can test yourself. Run the relevant tests after every fix, task, or feature. Verify everything passes before claiming done.
+
+### 5. Done
+
+The done gate hard-blocks until `verify.md` exists in the ticket folder. Run `$safeword:verify` — it produces the artifact.
+
+---
+
+## Code Philosophy
+
+Optimize for **Clarity → Simplicity → Correctness**, in that order. When in doubt, choose the simpler solution that works today.
+
+- **Elegant code:** readable at a glance; clear naming; minimal cognitive load.
+- **No bloat:** delete unused code; no premature abstractions; no "just in case"; reuse existing patterns/tools before adding new ones.
+- **Explicit errors:** every catch re-throws with context, or logs with details.
+- **Self-documenting:** comment only the non-obvious "why" — business rules, workarounds. Wrap comments and docstrings at 100 columns.
+
+---
+
+## Anti-Patterns
+
+| Don't                        | Do                                               | Why                       |
+| ---------------------------- | ------------------------------------------------ | ------------------------- |
+| `catch (e) {}`               | `throw new Error(\`Failed to X: ${e.message}\`)` | Silent failures hide bugs |
+| Utility class for 1 function | Single exported function                         | Abstraction without reuse |
+| Factory for simple object    | Direct construction                              | Indirection without value |
+| `data`, `tmp`, `d`           | `userProfile`, `pendingOrder`                    | Names should explain      |
+| Code "for later"             | Delete it; add when needed                       | YAGNI                     |
+| >50 lines for nice-to-have   | Ask whether it's essential now                   | Scope creep               |
+
+---
+
+## Authority: docs and research, not memory
+
+Training data drifts. Memory of "how X worked" is not authority — the current source is.
+
+**Library, framework, or API mechanics** (syntax, config, behavior):
+
+1. Find the installed version — `package.json`, lockfile, `requirements.txt`, `go.mod`, `Gemfile`, `Cargo.toml`, whichever the project uses.
+2. Read the docs for _that_ version. Use whichever source is wired up: Context7, the official docs site, the project README at the pinned ref, MDN, `node_modules/<pkg>/README.md`.
+3. If no source is reachable or the version is ambiguous, ask before guessing.
+
+**Adding a dependency** (a package not yet in the project) — there's no installed version to read, and the version you recall is stale by definition. Use the live `Current time:` line injected by `prompt-timestamp.ts` when the host provides one; otherwise use the current system date from the session. Then verify the current version for that date before pinning. Prefer the package manager's resolver command (`bun add <pkg>`, `npm install <pkg>`, `uv add`, `cargo add`, `go get <module>@latest`, etc.) or a registry command such as `npm view <pkg> version`, `pip index versions`, `go list -m -versions`, or crates.io. Pin what the registry reports today, never a number from memory.
+
+**Design choices** (algorithm, architecture, security, performance, concurrency, accessibility, ML/stats) — call `$safeword:figure-it-out`. Its core rule: no recommendation without current evidence. It enumerates research domains, fetches live docs, and weighs options before committing.
+
+Blog posts, tweets, marketing, and "I remember reading…" don't count for any tier. Treat them as leads, not evidence.
+
+---
+
+## Guides
+
+Read the matching guide when its trigger fires:
+
+| Trigger                                                          | Guide                                           |
+| ---------------------------------------------------------------- | ----------------------------------------------- |
+| Starting a feature/task OR writing specs/test-definitions        | `./.safeword/guides/planning-guide.md`          |
+| Choosing test type, doing TDD, or a test is failing              | `./.safeword/guides/testing-guide.md`           |
+| Creating or updating a design doc                                | `./.safeword/guides/design-doc-guide.md`        |
+| Making an architectural decision or writing an ADR               | `./.safeword/guides/architecture-guide.md`      |
+| Understanding the generated `architecture.generated.md` doc      | `./.safeword/guides/architecture-guide.md`      |
+| Data-heavy project needing formal data architecture              | `./.safeword/guides/data-architecture-guide.md` |
+| Writing learnings or agent config (CLAUDE.md, .cursor/rules)     | `./.safeword/guides/llm-writing-guide.md`       |
+| Updating CLAUDE.md, SAFEWORD.md, or any context file             | `./.safeword/guides/context-files-guide.md`     |
+| Hit the same bug repeatedly or discovered an undocumented gotcha | `./.safeword/guides/learning-extraction.md`     |
+| Process hanging, port in use, or zombie process suspected        | `./.safeword/guides/zombie-process-cleanup.md`  |
+
+---
+
+## Standing Rules
+
+**TodoWrite.** Use for 3+ step or non-trivial work, or when the user provides multiple requests. Set it up before diving in; keep one task `in_progress` at a time; mark completed as you finish each.
+
+**Commit frequently.** After each GREEN phase, before and after refactors, when switching tasks. The LOC gate fires near 400 lines — commit to reset it.
+
+**Draft pull requests.** Create every pull request as a draft by default (`gh pr create --draft` on GitHub). Only create or mark a pull request ready for review when the user explicitly asks; a request to push, publish, or open a pull request does not count.
+
+**Worktree entry (all hosts).** At session start and after moving roots or creating a worktree, run `pwd && git rev-parse --show-toplevel && git branch --show-current && git rev-parse --short HEAD` before evidence gathering or edits. Do not guess a package directory or probe a speculative path. Work from the reported repository root; use `<namespace-root>/architecture.generated.md` to find monorepo packages when present, otherwise inspect the root once. If the path, repo root, branch, or commit is wrong, stop and fix the workspace before touching files.
+
+**Learnings.** Project-specific lessons live in `<namespace-root>/learnings/`. Before non-trivial work, scan `INDEX.md` or grep for your topic. When you solve something non-obvious, add `<slug>.md` with a `Covers:` line; `safeword project sync-learnings` regenerates the index.
+
+---
+
+## Enforcement
+
+Safeword runs hooks each turn to track your phase and TDD step. Four gates hard-block:
+
+- **Phase gate** — can't start TDD without `test-definitions.md`; can't create `test-definitions.md` without `scope` / `out_of_scope` / `done_when` in ticket frontmatter.
+- **Plan gate** — a new-flow feature can't enter `implement` without a valid `impl-plan.md` (authored during the plan-implementation phase, status `planned`), and can't reach `verify`/`done` until the plan is reconciled to `implemented`.
+- **LOC gate** — commit every ~400 lines of project code (blast-radius control).
+- **Done gate** — can't close a ticket without `verify.md` in the ticket folder.
+
+The prompt hook injects your current phase each turn as a reminder.
+
+When a gate blocks, the user can run `$safeword:explain` for a plain-English version of the block — what it's asking for and how to clear it. Offer it in one line when the user seems unsure (asks "what?", pastes a block back, or stalls); stay quiet when they're moving fine. Don't make them ask twice to understand a block.
+
+---
+
+## Talking to the user
+
+This is the most-read surface of safeword. **Write to be scanned, not read.** Short replies stay short — a one-line answer needs no structure. When a reply is long enough to need structure, the user should land on the answer in seconds, see the shape at a glance, and drop into detail only when they choose to.
+
+**Lead with the answer.** First sentence is the result, the fix, or the call. Explanation follows only if it adds something.
+
+> Do: "Fixed — `packages/cli/src/auth.ts:42` was swallowing the refresh error."
+> Don't: "Great question! Let me walk you through what I found..."
+
+**End with the call.** Close by naming what's next — a question, a choice, or a proposed step; don't bury it mid-reply. For structured replies (verdicts, reviews, recommendations, audits), make that closing line a literal `**Next:** <imperative>`: the stop hook captures it verbatim for the session's re-entry brief, so the token is load-bearing, not decoration. Short conversational replies can end with the question itself.
+
+**Debate-then-pick.** When there's a real choice, surface 2-3 options weighed in one breath, then the pick — one line each on the candidates, one on the tradeoff, one on the call. Don't ping-pong one option at a time. Skip the debate when there's no real choice (rename, mechanical edit, single obvious path).
+
+**Frame the structural choice.** Name the architectural call ("reuse `quality-state.ts` paths vs. duplicate the list") before the surface change ("add a check"). The proposal _is_ the architectural read, not a description of what to type.
+
+**Front-load load-bearing words.** The first two words of every line, bullet, and heading do the work — readers eye-jump down the left edge before deciding where to drop in. Start with the noun or verb that carries the meaning. "Failed because…" beats "It looks like the test failed because…"
+
+**Speak plainly.** Use everyday words. Don't make the user learn safeword's internal vocabulary (Propose-and-Converge, sizing, gates, phases) — just describe what's happening. Prefer the plain phrase over a technical term whenever either works; reach for the term only when it's shorter or more precise than spelling it out.
+
+**Gloss jargon at the decision point.** Don't assume the user reads code. The first time a stack or domain term is load-bearing in an _ask_ — a block, a decision, a step they must take — gloss it inline in one clause ("the refresh token (the credential that renews a login) expired"). Once per turn, never re-explained; a fluent reader skips it at no cost. Leave background narration unglossed.
+
+**Match length to the ask.** A one-line question gets a one-line reply — no headers, no bullets, no preamble. Complex tasks get a short answer followed by the detail that supports it. Keep status updates terse and end-of-turn summaries brief — a sentence or two, not a paragraph.
+
+**Cite code as `path:line`.** When referencing something the user might open, write `packages/cli/src/foo.ts:142` inline. Not "the foo file." Not in a code block.
+
+**Name tickets by slug, not ID.** Refer to a ticket by its slug or title with the ID as a trailing locator — `embed-figure-it-out (ZBVGPF)`, never bare `ZBVGPF`. The 6-char code is collision-proof but unreadable; the slug is already in the folder name.
+
+**Use structure only when it carries weight.** Headings when the reply is long enough to navigate — and make them information-carrying, not generic ("What changed" beats "Summary"). Tables only for actual reference material — never as decision trees in disguise. Bullets only when items are genuinely parallel. Default to prose. Never output a series of overly short bullet points.
+
+**Use bold sparingly** — only where reading the bold alone would tell the story. Bold-on-every-sentence reads as noise.
+
+**Skip:** preambles ("I'll now..."), recaps of what the user just said, sycophantic openers ("Great question!"), hedging caveats ("It depends, but..."), restating actions the user can see in the tool log.

package/codex-plugin/templates/hooks/audit-principle-trace.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env bun
+
+import { readdirSync, readFileSync } from 'node:fs';
+import process from 'node:process';
+import nodePath from 'node:path';
+
+import { checkPrincipleTrace } from './lib/principle-trace.ts';
+import { resolveNamespaceRoot } from './lib/namespace-root.ts';
+
+const projectDirectory = process.argv[2] ?? process.cwd();
+const explicitPlan = process.argv[3];
+const plans =
+  explicitPlan === undefined ? activeImplPlans(projectDirectory) : [nodePath.resolve(explicitPlan)];
+
+for (const planPath of plans) {
+  const plan = readFileSync(planPath, 'utf8');
+  for (const finding of checkPrincipleTrace(projectDirectory, plan)) {
+    process.stdout.write(`${finding} (${nodePath.relative(projectDirectory, planPath)})\n`);
+  }
+}
+
+function activeImplPlans(directory: string): string[] {
+  const ticketsDirectory = nodePath.join(resolveNamespaceRoot(directory), 'tickets');
+  try {
+    return readdirSync(ticketsDirectory, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => nodePath.join(ticketsDirectory, entry.name))
+      .filter(ticketDirectory => {
+        try {
+          return /^status:\s*in_progress\s*$/mu.test(
+            readFileSync(nodePath.join(ticketDirectory, 'ticket.md'), 'utf8'),
+          );
+        } catch {
+          return false;
+        }
+      })
+      .map(ticketDirectory => nodePath.join(ticketDirectory, 'impl-plan.md'))
+      .filter(planPath => {
+        try {
+          readFileSync(planPath, 'utf8');
+          return true;
+        } catch {
+          return false;
+        }
+      });
+  } catch {
+    return [];
+  }
+}

package/codex-plugin/templates/hooks/codex/post-tool-quality.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+// Safeword: Codex PostToolUse adapter — maintains quality state.
+//
+// The LOC blast-radius gate and the review-stamp/session-context plumbing read
+// per-session state (LOC since last commit, active ticket binding,
+// commit-clears-gate) that is written by the Claude post-tool-quality.ts
+// accumulator. Codex doesn't run that Claude hook, so this adapter translates
+// the Codex payload (notably apply_patch, whose target paths are embedded in
+// the patch text) and spawns it as the source of truth after each edit/shell.
+// Mirrors the Cursor postToolUse adapter; keyed on session_id to match the
+// PreToolUse adapter's `codex-<id>` state key.
+//
+// Every translated target runs (each updates state); any review nudge the
+// accumulator emits is forwarded verbatim — Codex PostToolUse shares Claude's
+// hookSpecificOutput.additionalContext output shape.
+
+import nodePath from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  type CodexHookInput,
+  runClaudeHookAsCodex,
+  translateCodexInputToClaudeInputs,
+} from './pre-tool-quality-helpers.ts';
+import { installCrashCapture } from '../lib/self-report.ts';
+
+installCrashCapture('codex-post-tool-quality', undefined, 'codex');
+
+async function readInput(): Promise<CodexHookInput | undefined> {
+  try {
+    return JSON.parse(await Bun.stdin.text()) as CodexHookInput;
+  } catch {
+    return undefined;
+  }
+}
+
+const input = await readInput();
+if (!input) process.exit(0);
+
+const translatedInputs = translateCodexInputToClaudeInputs(input);
+if (translatedInputs.length === 0) process.exit(0);
+
+const hookDirectory = nodePath.dirname(fileURLToPath(import.meta.url));
+const claudeHookPath = nodePath.join(hookDirectory, '..', 'post-tool-quality.ts');
+
+// Run ALL targets — each spawn accumulates state — then forward the first
+// non-empty additionalContext payload.
+const outputs = translatedInputs.map(
+  translated => runClaudeHookAsCodex(claudeHookPath, translated).stdout ?? '',
+);
+const firstOutput = outputs.find(output => output.trim() !== '');
+if (firstOutput !== undefined) {
+  process.stdout.write(firstOutput);
+}
+
+process.exit(0);

package/codex-plugin/templates/hooks/codex/post-tool-skill-nudge.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env bun
+// Safeword: Codex PostToolUse adapter for the language-skill nudge.
+//
+// Codex PostToolUse supports hookSpecificOutput.additionalContext (GA) — the
+// SAME output shape the standalone post-tool-skill-nudge.ts hook already emits.
+// So this adapter only translates Codex INPUT (notably apply_patch, whose target
+// path is embedded in the patch text) into the Claude-shaped input the hook
+// understands, runs it per target, and aggregates every valid nudge. Fail-open:
+// no target / no nudge → exit 0 with no output.
+
+import nodePath from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  type CodexHookInput,
+  runClaudeHookAsCodex,
+  translateCodexInputToClaudeInputs,
+} from './pre-tool-quality-helpers.ts';
+
+async function readInput(): Promise<CodexHookInput | undefined> {
+  try {
+    return JSON.parse(await Bun.stdin.text()) as CodexHookInput;
+  } catch {
+    return undefined;
+  }
+}
+
+function postToolAdditionalContext(stdout: string | undefined): string | undefined {
+  try {
+    const output = JSON.parse(stdout ?? '') as {
+      hookSpecificOutput?: { hookEventName?: string; additionalContext?: unknown };
+    };
+    const context = output.hookSpecificOutput?.additionalContext;
+    return output.hookSpecificOutput?.hookEventName === 'PostToolUse' && typeof context === 'string'
+      ? context
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const input = await readInput();
+if (!input) process.exit(0);
+
+const translatedInputs = translateCodexInputToClaudeInputs(input);
+if (translatedInputs.length === 0) process.exit(0);
+
+const hookDirectory = nodePath.dirname(fileURLToPath(import.meta.url));
+const claudeHookPath = nodePath.join(hookDirectory, '..', 'post-tool-skill-nudge.ts');
+
+const contexts: string[] = [];
+for (const translated of translatedInputs) {
+  const result = runClaudeHookAsCodex(claudeHookPath, translated);
+  const context = postToolAdditionalContext(result.stdout);
+  if (context !== undefined) contexts.push(context);
+}
+
+if (contexts.length > 0) {
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: contexts.join('\n\n'),
+      },
+    })}\n`,
+  );
+}