devrites 2.6.1 → 3.0.0

package/pack/generated/codex/skills/rite-seal/reference/phase-contract.md

@@ -0,0 +1,211 @@
+# rite-seal phase contract
+
+## Execution spine
+
+Run the engine gates at these moments:
+
+```bash
+devrites-engine preamble
+
+devrites-engine spec-validate .devrites/work/<slug>; echo "spec-validate rc=$?"
+devrites-engine check-acceptance .devrites/work/<slug>; echo "check-acceptance rc=$?"
+devrites-engine evidence-fresh <slug>; echo "evidence-fresh rc=$?"
+devrites-engine doubt-coverage <slug>; echo "doubt-coverage rc=$?"
+
+devrites-engine footprint log <slug> reviewer devrites-<x>-reviewer
+devrites-engine footprint log <slug> skip devrites-<x>-reviewer
+devrites-engine footprint roster <slug>; echo "roster rc=$?"
+devrites-engine review-integrity <slug>; echo "review-integrity rc=$?"
+devrites-engine review-fingerprints --write <slug>
+
+devrites-engine footprint render <slug>
+devrites-engine learnings add "<slug>" "<dismissed-as-intentional class or dead-end>" dismiss
+devrites-engine health record <0..10> "<GO|NO-GO evidence summary>" --note "<top blocker or green proof>"
+devrites-engine timeline log completed --skill rite-seal --slug <slug> --outcome "<go|no-go>" --decision "<verdict>"
+
+devrites-engine progress
+```
+
+Conditional calls still obey the detailed rules below: reviewer and skip
+footprints must account for the whole roster; learnings run only on GO; progress
+is rendered before the final response from [`output.md`](output.md). Seal decides
+only; `$rite-ship` owns irreversible git/publish/deploy actions.
+
+1. **Run the shared orientation preamble** — it prints `state.md`, the artifacts present,
+   the run mode (HITL/AFK), and the open-question tally by gate, so you orient deterministically
+   instead of re-deriving state from raw Markdown:
+   ```bash
+   devrites-engine preamble
+   ```
+   Then read all artifacts: `brief.md`, `spec.md`, `plan.md`, `tasks.md`, `state.md`,
+   `decisions.md`, `assumptions.md`, `questions.md`, `drift.md`, `evidence.md`,
+   `browser-evidence.md`, `polish-report.md`, `review.md`, `design-brief.md` (if UI),
+   `devex.md` (if a developer-facing surface), `strategy.md` (if present), and the **final diff**. If a code-intelligence index is available
+   (see `.agents/skills/devrites-lib/reference/standards/tooling.md`), use it for
+   blast-radius checks on the final diff in step 5; context7 if available can confirm a current
+   external-API signature a reviewer flags.
+2. Check **acceptance criteria one by one** — first run `devrites-engine spec-validate .devrites/work/<slug>`;
+   unresolved or unproven `resolved/test` prohibitions are a NO-GO until the linked evidence exists.
+   Then use [final-evidence](final-evidence.md).
+   Each gets a checkbox + the evidence that proves it (or "unproven"). Verify each criterion
+   **independently against the evidence artifact** — the slice report or the build narrative is not
+   proof; the `devrites-spec-reviewer` + `devrites-test-analyst` fan-out in step 7 is the
+   independent cross-check (a verifier that never saw the optimistic narrative).
+3. Verify tests, build/typecheck/lint, and browser proof are present and green for the
+   scope. Re-run if cheap and in doubt. **For a UI feature with a `design-brief.md`**, read the
+   `## Visual Verdict` table in `browser-evidence.md`: a `FAIL` on an **acceptance-mapped**
+   criterion is an unmet acceptance criterion (NO-GO, per the severity gate), a declared-state
+   `FAIL` is **Important**, and a UI build whose brief exists but whose verdict is **absent** is an
+   Important evidence gap (the scorecard should have been emitted at browser-proof).
+4. Check unresolved **questions** and **drift** — any open item that changes product
+   behavior blocks. **Any `questions.md` entry with `gate: validating` and `status: open`
+   is a NO-GO regardless of behavior impact** (an open validating gate is merge-blocking by
+   definition); a slice marked `built (pending review)` is not done.
+4a. **Doubt coverage — every stood decision was independently doubted.** Run the deterministic
+   check, then judge it against `decisions.md`:
+   ```bash
+   devrites-engine doubt-coverage <slug>; echo "doubt-coverage rc=$?"
+   ```
+   The script reads two records `$rite-build` writes — the `## Decisions stood` ledger in
+   `decisions.md` (each entry ends `— doubt: <accept | reject-resolved | MISSING>`) and the `doubt`
+   footprint. Read the exit code:
+   - **rc=3** — the ledger records a stood decision with `doubt: MISSING`: doubt was definitively
+     skipped for a decision on record. **Important**; **NO-GO** when that decision is irreversible-risk
+     (auth / public-API / migration). This is the per-slice skip the footprint count alone can't catch.
+   - **rc=1** — zero doubt dispatched across the build. A **prompt to verify, not a finding**: confirm
+     against the ledger — an every-slice-trivial feature (`- none`) is a valid pass; a stood triggering
+     decision (boundary / data-model / auth / public-API / migration / branching) with no verdict is
+     the finding, same severity as rc=3.
+   - **rc=0** — covered, or not assessable (an inline build logs no dispatch — verify the ledger's
+     verdicts by hand).
+   Either way, walk the `## Decisions stood` ledger yourself: severity rides the unverified
+   **decision**, never the exit code alone.
+5. Check **security, data, migration, rollback** risk —
+   [risk-and-rollback](risk-and-rollback.md). If `strategy.md` exists (from
+   `$rite-temper`), confirm its **top pre-mortem risks are mitigated** in the diff/evidence and
+   that no **Non-goal / deferred item crept into the diff** (scope creep) — either is a finding
+   (an unmitigated top risk or smuggled-in out-of-scope work).
+   - **Principles** (`principles.md`): score the final diff against each declared invariant in
+     `.devrites/principles.md`. A violation with no matching, human-approved exception in the
+     register is a **Critical** finding and a NO-GO; an exception that is stale (past its review
+     trigger) or wider than its stated scope is itself a finding. No file / no principles → skip.
+   - **Observability** (`observability.md`): if the diff added a runtime surface (endpoint,
+     job, integration, user flow, error path), a feature shipping with no way to debug it in
+     prod is an **Important** finding, not a pass — `evidence.md` should show telemetry observed
+     to emit (`$rite-prove` step 5b).
+   - **Developer experience** (`developer-experience.md`): if the diff ships a developer-facing
+     surface, reconcile `devex.md` (the `$rite-vet` predicted scorecard vs the `$rite-prove`
+     measured one — the boomerang). A broken public dev contract (a documented command that errors,
+     a getting-started flow that can't complete) or an unexplained measured DX regression is
+     **Important** — **Critical** on a frozen public surface (`principles.md`). No surface → skip.
+   - **Removal / migration** (`deprecation.md`): if the diff deletes or migrates code, an API,
+     or data, confirm it followed expand→contract, proved the old path unused before removing it,
+     and carries a rollback for every destructive step. A surprise deletion or a one-shot
+     breaking migration is a finding (and trips the irreversible-risk gate, `afk-hitl.md`).
+6. Check **frontend polish** if UI is involved (states, a11y, responsive, design-system,
+   browser evidence).
+7. **Independent review** — seal is the final gate, not a re-run of `$rite-review`.
+   It **always re-spawns** the axes `$rite-review` did not cover: `devrites-test-analyst`,
+   `devrites-security-auditor`, `devrites-performance-reviewer`, and
+   `devrites-frontend-reviewer` (UI). It **only re-runs the Spec and Code-review axes**
+   (`devrites-spec-reviewer`, `devrites-code-reviewer`) when the diff changed since
+   `$rite-review` ran (compare against `review.md`); if the diff is unchanged, carry
+   review's verdicts on those axes forward rather than re-litigating them.
+   If subagents are available, fan out **in parallel** (one `Task` block, multiple tool
+   calls) to the **roster** — the seven reviewers and their checkable triggers are the single
+   source in [`parallel-dispatch.md`](../../devrites-lib/reference/parallel-dispatch.md) (dispatch
+   shape + reconciliation there too; `.agents/skills/devrites-lib/reference/standards/agents.md` — "Run independent reviewers in
+   parallel"). Dispatch every always-on reviewer and every conditional whose trigger the diff
+   meets; `devrites-devex-reviewer` runs in **measure mode** — grade the measured DX scorecard
+   and reconcile the boomerang against the `$rite-vet` prediction. Give each the workspace path +
+   diff *without the author's reasoning*. If subagents are unavailable, run the equivalent
+   reviews sequentially yourself and flag each as a fallback.
+   The reviewer **AGENTS** here (fresh context, no author reasoning) are the seal
+   GATE; `devrites-audit` is the inline single-axis pass run during build/polish.
+   The two paths are intentional, not divergent — the inline audit catches issues
+   early; the fresh-context agents are the independent gate before ship.
+   **Footprint — account for the whole roster.** For each reviewer you dispatch, append
+   `devrites-engine footprint log <slug> reviewer devrites-<x>-reviewer` (the reviewer's **exact agent name** —
+   the roster gate matches on it, so a freehand label like `spec` will read as unaccounted); for
+   each roster reviewer you consciously do **not** dispatch, append
+   `devrites-engine footprint log <slug> skip devrites-<x>-reviewer` and note the one-line reason in `seal.md`.
+   A conditional reviewer that does not apply is a *recorded skip*, never a silent omission — step 7b
+   proves the roster complete before the verdict.
+7a. **Reconcile findings — confidence over volume.** Band each reviewer finding by confidence
+   (1–10); a low-confidence (≤4) finding that can't be verified against the diff is **suppressed**
+   to a `Suppressed (low-confidence): n` line, not a blocker. Every Critical/Important must cite
+   the `file:line` (or spec line) that proves it. Surface genuine cross-reviewer disagreement
+   **explicitly** rather than averaging it away, and don't let a pile of low-confidence nits
+   inflate the verdict — the gate is `Critical == 0` + acceptance + drift, not "few findings".
+   (A seal that fires noise teaches the next one to be ignored.)
+7b. **Account for the roster — no reviewer silently skipped.** Before the verdict, prove every
+   roster reviewer carries a decision (dispatched or skip-recorded in step 7's footprint):
+   ```bash
+   devrites-engine footprint roster <slug>; echo "roster rc=$?"
+   ```
+   - **rc=3** — a roster reviewer was neither dispatched nor skip-recorded: the silent omission
+     this gate exists to catch. **NO-GO** on the review's *completeness* (not the diff) — dispatch
+     the missing reviewer or record a justified skip, then re-run. Same standing as an unproven
+     criterion (severity gate).
+   - **rc=1** — an always-on axis (Spec / Code-review) was skip-recorded: legitimate **only** as a
+     carry-forward of `$rite-review`'s verdict on an **unchanged** diff (step 7). Confirm that;
+     otherwise dispatch it.
+   - **rc=0** — every reviewer accounted for; proceed.
+7c. **No silent reviewer — a zero-findings axis is justified, not assumed.** Confirm no adversarial
+   axis rubber-stamped: an axis that reported nothing must carry a `No-findings:` justification.
+   ```bash
+   devrites-engine review-integrity <slug>; echo "review-integrity rc=$?"
+   ```
+   - **rc=1** — an axis in `review.md` is silent (no finding, no justification): **Important** on the
+     review's completeness. Re-run that axis or record its `No-findings:` account, then re-seal.
+   - **rc=0** — every axis has findings or a justified clean bill; proceed. (No `review.md`, or a
+     freeform one, is a clean pass — the gate keys on per-axis sections.)
+   Then write stable finding IDs for learning and recurring-dismissal correlation:
+   ```bash
+   devrites-engine review-fingerprints --write <slug>
+   ```
+8. Decide GO / NO-GO — [go-no-go](go-no-go.md) — and write `seal.md`. Then render the
+   **fan-out footprint** into `seal.md` and the output — deterministic run-weight (subagents
+   dispatched · slices · wall-clock), **never a token or dollar figure** (DevRites can't
+   truthfully source one):
+   ```bash
+   devrites-engine footprint render <slug>
+   ```
+   Also emit a machine-readable verdict block into `seal.md` (so `$rite-autocomplete` can gate
+   without parsing prose):
+   ```json
+   { "feature": "<slug>", "verdict": "GO | NO-GO | CONDITIONAL-GO", "criticals": 0, "important": 0,
+     "acceptance": "<proven>/<total>", "test_integrity": "ok | weakened", "mutation": "<score | n/a>",
+     "blockers": ["<one line each, empty on GO>"] }
+   ```
+9. **On GO only — record proven conventions** to the local ledger
+   (`.devrites/conventions.md`) so later slices stop re-deriving this project's idioms:
+   the durable, *evidence-proven* commands / idioms / placement / gotchas this feature
+   established. Evidence-gated like the seal itself; the band is earned, not guessed; the
+   step degrades gracefully when unavailable. Full contract + command:
+   [conventions-ledger](conventions-ledger.md). (Skip entirely on NO-GO.)
+9a. **On GO only — auto-capture learnings** (`.devrites/learnings.md`). Learning is automatic, not a
+   command anyone must remember: append this feature's durable signal so the **next** feature's
+   review starts warmer — (a) any reviewer finding the gate **dismissed as intentional here** (a
+   "don't re-flag X in this project" class, tag `dismiss`); (b) a recurring correction or dead-end
+   worth not repeating (tag `note`). The review skills load this ledger **before** they fan out, so a
+   dismissed-finding class stops recurring. It is an untrusted prior — live code always overrides
+   (`.agents/skills/devrites-lib/reference/standards/security.md`). Promotion of a recurring lesson to a *project rule* stays the
+   human's call (`$rite-learn` — propose, don't impose). Skip on NO-GO.
+   ```bash
+   devrites-engine learnings add "<slug>" "<dismissed-as-intentional class or dead-end>" dismiss
+   ```
+10. **Record the durable phase traces.** Before the final output, record the health signal and
+    verdict event. The score is evidence-backed, not decorative: high for GO with green proof,
+    lower for NO-GO or unresolved blockers.
+    ```bash
+    devrites-engine health record <0..10> "<GO|NO-GO evidence summary>" --note "<top blocker or green proof>"
+    devrites-engine timeline log completed --skill rite-seal --slug <slug> --outcome "<go|no-go>" --decision "<verdict>"
+    ```
+
+## `seal.md` template
+
+Loaded on demand from [`seal-template.md`](seal-template.md). Fill in
+each section + write to `.devrites/work/<slug>/seal.md` as the durable record.
+
+> **Mid-flight discipline.** When tempted to round NO-GO up to GO, bypass the y/N prompt, average reviewer disagreements, or seal with unresolved drift — see [`anti-patterns`](anti-patterns.md). Load it the moment you reach for the excuse.

package/pack/generated/codex/skills/rite-seal/reference/risk-and-rollback.md

@@ -0,0 +1,30 @@
+# Risk & rollback
+
+Before GO, know how to undo the change and what could go wrong in production.
+
+## Risk scan
+Rank risks; for each, note likelihood × impact and any mitigation:
+- **Data**: schema changes, data migration, destructive operations, backfills.
+- **Security**: new trust boundaries, auth/authz changes, secret handling, new deps.
+- **Compatibility**: API contract changes, breaking changes for existing clients,
+  feature interactions.
+- **Operational**: new external dependency, config/env requirements, rate limits.
+- **UX**: changed flows users rely on; unverified UI.
+
+## Rollback plan (required for risky changes)
+For each risky step, state how to back it out:
+- **Migrations**: is there a reversible `down` / a documented manual revert? Is data
+  loss possible on rollback?
+- **Feature flag**: can it be disabled without a deploy?
+- **Revert boundary**: can the change be `git revert`-ed cleanly, or does it entangle
+  with other work?
+- **Data**: is there a backup / a way to restore prior state?
+
+## Blocking rules
+- A **destructive or data-migration change with no rollback plan** is a **NO-GO**.
+- A new external dependency with no failure handling is at least **Important**.
+- Record the chosen rollback path in `seal.md` → "Rollback / Recovery".
+
+## Destructive operations
+Confirm any destructive step with the user before shipping. Verify backups exist where
+relevant. Never treat an irreversible action as routine.

package/pack/generated/codex/skills/rite-seal/reference/seal-template.md

@@ -0,0 +1,36 @@
+# `seal.md` template
+
+Loaded on demand by `$rite-seal`. The seal writes this template (filled in) to `.devrites/work/<slug>/seal.md` as the durable record of the GO / NO-GO verdict.
+
+```markdown
+# Seal: <Feature>
+
+Verdict: GO / NO-GO
+
+## Acceptance Criteria
+- [ ] <criterion> — evidence: <...>
+
+## Verification Evidence
+<tests / build / lint summary>
+
+## Browser Evidence
+<summary | n/a>
+
+## Risks
+<ranked>
+
+## Blockers
+<must-fix before ship>
+
+## Non-blocking Follow-ups
+<deferred items>
+
+## Rollback / Recovery
+<how to back this out>
+
+## Final Decision
+<one paragraph: verdict + why>
+
+## Footprint
+<deterministic fan-out from devrites-engine footprint — subagents · slices · wall-clock; never tokens/cost>
+```

package/pack/generated/codex/skills/rite-ship/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: rite-ship
+description: Ship the sealed feature: commit, push, tag, archive, close. Use when the user says "ship it", "push the branch", "tag the release", or "close the task" after $rite-seal GO. Not for GO/NO-GO readiness.
+argument-hint: "[feature-slug]"
+user-invocable: true
+---
+
+## Codex compatibility
+
+This is the Codex mirror of a DevRites skill. In Codex:
+
+- Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
+- Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
+- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here — Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
+- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review** — an inline pass shares the calling context and is weaker evidence.
+- Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
+- When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers — NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
+
+
+# $rite-ship — ship + close the task
+
+The final phase. `$rite-seal` **decides** GO/NO-GO; `$rite-ship` **executes** the
+irreversible git actions and **closes** the feature. **Read the active workspace
+first**; if none, tell the user to run `$rite-spec <feature>`.
+
+Refuses to ship unless `seal.md` records a **GO** verdict.
+
+## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
+**Step 0:** Read `.agents/skills/devrites-lib/reference/standards/core.md` first. Then pull on demand:
+- `git-workflow.md` — Conventional Commits, atomic commits, the never-commit list.
+- `afk-hitl.md` — type-GO is the irreversible-action gate.
+- `definition-of-done.md` — final acceptance, evidence, drift, rollback, and documentation bar.
+- [`release/ship-checklist.md`](../devrites-lib/reference/standards/release/ship-checklist.md) — compact final ship and archive pass/fail sweep.
+
+## Operating rules
+- **Seal GO is a precondition.** No GO in `seal.md` → stop, point at `$rite-seal`.
+- **Evidence must be fresh.** If any file in `touched-files.md` changed after
+  `evidence.md` was written, the proof is stale → stop, point at `$rite-prove`. Enforced
+  deterministically by `devrites-engine evidence-fresh` in step 1 (exit 3 = STALE), not by eyeballing
+  mtimes (see `.agents/skills/devrites-lib/reference/standards/development-workflow.md`).
+- **type-GO before anything irreversible.** Render the prompt verbatim and wait for
+  the literal `GO`. Last safety net — render it every time, even under auto-trigger.
+- **Never delete the audit trail.** Closing *archives* the workspace; it never erases
+  the `.md` files.
+
+## Workflow
+1. **Orient.** Run `devrites-engine preamble` for deterministic workspace orientation.
+   Then read `seal.md`, `state.md`, `spec.md`, `touched-files.md`, `evidence.md`, and
+   `design-brief.md` (if the feature is UI — the design-memory rollup in step 2a reads it).
+   Confirm the verdict is **GO**, then run the deterministic evidence-freshness gate rather than
+   eyeballing mtimes (mirrors `$rite-seal`):
+   ```bash
+   devrites-engine evidence-fresh; echo "evidence-fresh rc=$?"
+   ```
+   **Exit 3 → STALE proof: STOP**, point at `$rite-prove` (a polish/review edit made after
+   `$rite-prove` invalidates the proof). Not GO → stop with the single resume command.
+1a. **Health re-check (advisory).** Run the DevRites doctor before the irreversible ladder —
+   a stale `ACTIVE` or corrupt workspace here risks shipping or closing the wrong feature.
+   Advisory: surface issues, don't block.
+   ```bash
+   devrites-engine doctor; echo "doctor rc=$?"
+   ```
+   If it flags the active feature, confirm you're shipping the intended slug before proceeding.
+2. Build the git plan from `git-workflow.md` + the project's own convention: the
+   Conventional-Commit message(s), commit trailers for non-trivial work, the target branch, and
+   whether a tag / PR applies. Derive trailers from `decisions.md`, `assumptions.md`, `seal.md`,
+   and `evidence.md`: `Constraint`, `Rejected`, `Confidence`, `Scope-risk`, `Not-tested` when
+   present; skip trailers for trivial typo/formatting commits. Scope the commit to
+   `touched-files.md`; never stage secrets or out-of-scope files.
+   **Completion:** message, trailers, target branch, tag/PR choice, and exact staged scope are explicit.
+2a. **Design memory (UI only).** Follow
+   [`reference/design-memory.md`](reference/design-memory.md). Completion: the confirmed
+   outcome is recorded, and any `DESIGN.md` edit is in `touched-files.md`; non-UI skips.
+2b. **Capability ledger sync.** Follow [`reference/ledger.md`](reference/ledger.md).
+   Completion: proven capability deltas are previewed, the confirmed outcome is recorded,
+   and every synced ledger file is in `touched-files.md`.
+2c. **Credential guard (blocking for HIGH).** Before the irreversible type-GO prompt, scan staged
+   and touched files plus any PR body draft. HIGH blocks ship and tells the user to rotate/redact;
+   MEDIUM asks for confirmation and records the exception in `ship.md`; LOW is FYI.
+   ```bash
+   devrites-engine secret-scan --staged; echo "secret-scan rc=$?"
+   ```
+   **rc=3 → STOP**: do not type-GO, commit, push, or archive.
+3. **Render the type-GO prompt** ([reference/git-ship.md](reference/git-ship.md)) and
+   wait. Only the literal `GO` proceeds; anything else cancels — record the cancel in
+   `ship.md` and stop (do not retry without the user asking).
+4. On `GO`: run the git ladder — commit → push → tag / PR as applicable
+   ([reference/git-ship.md](reference/git-ship.md)). Capture the commit SHA(s),
+   branch, and tag/PR URL.
+4a. **PR branch only.** Render the structured body from
+   [`reference/git-ship.md`](reference/git-ship.md#pull-request-body); omit empty sections.
+4b. **Durable architecture decisions only.** Apply
+   [`reference/adr-promotion.md`](reference/adr-promotion.md); slice-local decisions stay in
+   the archived workspace.
+5. Write `ship.md` ([reference/ship-template.md](reference/ship-template.md)): what
+   shipped, SHA(s), branch, tag/PR, acceptance summary (n/total), link to `seal.md`,
+   follow-ups.
+6. **Close the task** ([reference/close-out.md](reference/close-out.md)): set
+   `state.md` phase `done`, then run
+   `devrites-engine close-out <slug>` to archive
+   `.devrites/work/<slug>/` → `.devrites/archive/<slug>/` and clear `.devrites/ACTIVE`.
+   Every `.md` is preserved in the archive. Then refresh any managed project context block so
+   `AGENTS.md` / `CLAUDE.md` no longer advertise a closed active workspace:
+   ```bash
+   devrites-engine context sync || true
+   ```
+6a. **Cross-feature retro.** Run the cadence-gated advisory branch in
+   [`reference/close-out.md`](reference/close-out.md#cross-feature-retro). Completion: a
+   silent nudge does nothing; a real recurrence is appended to `.devrites/retro.md` and
+   surfaced to `$rite-learn`, never auto-promoted.
+
+> **Mid-flight discipline.** When tempted to ship without a GO seal, skip the type-GO,
+> stage files outside `touched-files.md`, or delete the workspace instead of archiving
+> it — stop. See [`anti-patterns`](reference/anti-patterns.md); the gate exists for the
+> failure mode the ask misses.
+
+## Output
+
+**Progress first** — run `devrites-engine progress`, then use the Shipped typed template from
+the shared completion reply contract
+([`reply-contract.md` § Shipped](../devrites-lib/reference/reply-contract.md#shipped)).
+If the user declined type-GO: state that nothing shipped, the seal still reads GO, and
+the resume command (`$rite-ship`).

package/pack/generated/codex/skills/rite-ship/reference/adr-promotion.md

@@ -0,0 +1,9 @@
+# ADR promotion
+
+Promote only durable architecture or interface decisions from `decisions.md`; slice-local
+calls remain in the archived workspace. If the project has no `docs/adr/`, ask before
+creating that convention.
+
+Write the next append-only `docs/adr/ADR-NNN.md` with Context, Decision, Status
+`accepted`, and Consequences. Never rewrite an accepted ADR; supersede it with a new ADR
+that links the old one. Add every promoted ADR to `touched-files.md` before shipping.

package/pack/generated/codex/skills/rite-ship/reference/anti-patterns.md

@@ -0,0 +1,25 @@
+# rite-ship — anti-patterns
+
+Load this before any irreversible action — `git commit`, `push`, `tag`, publish, deploy
+— or when tempted to skip the close-out.
+
+Pack-wide rationalizations + red flags: see
+[standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "Seal said GO, so I can just push." | A GO verdict is a decision, not authorization. **Render the type-GO prompt every time** and wait for the literal `GO`. |
+| "I'll push the tag now; type-GO is a formality." | Type-GO is the last safety net before an irreversible action. Always render it — even under auto-trigger. |
+| "`git add -A` is faster than listing touched files." | Stage only what's in `touched-files.md`. `-A` sweeps secrets, scratch files, and out-of-scope edits into the ship. |
+| "The evidence is probably still good." | If any touched file changed after `evidence.md`, the proof is stale — stop and re-prove. Ship on fresh evidence only. |
+| "Delete the workspace, the feature's done." | Closing **archives** the workspace (`.devrites/archive/<slug>/`); it never deletes the audit trail. |
+
+## Red Flags
+
+- About to run `git push` / `git tag` without rendering the type-GO prompt.
+- Shipping without a `GO` verdict recorded in `seal.md`.
+- Staging files not listed in `touched-files.md`, or any secret / `.env`.
+- `rm`-ing `.devrites/work/<slug>/` instead of archiving it.
+- Marking the feature `done` but leaving `.devrites/ACTIVE` pointing at it.

package/pack/generated/codex/skills/rite-ship/reference/close-out.md

@@ -0,0 +1,42 @@
+# Close-out — archive the workspace, free the active slot
+
+Closing a feature means it stops being the *active* work, not that its record is
+deleted. DevRites keeps the full audit trail; it just moves out of the live path.
+
+## What close-out does
+
+1. **Mark done.** Set `state.md` → `Phase: done`, `Status: done`, and a `Next step`
+   of `$rite-spec <next feature>`.
+2. **Archive.** Run the deterministic script:
+   ```bash
+   devrites-engine close-out <slug>
+   ```
+   It moves `.devrites/work/<slug>/` → `.devrites/archive/<slug>/` (every `.md`
+   intact) and clears `.devrites/ACTIVE` **only if** ACTIVE still points at `<slug>`.
+   It refuses to clobber an existing `.devrites/archive/<slug>/` (exit 5).
+3. **Confirm.** ACTIVE is now empty, so the next `$rite-spec` starts a clean feature
+   and `$rite-status` reports "no active feature".
+
+## Why archive, not delete
+
+- The `.md` files (`spec`, `decisions`, `assumptions`, `evidence`, `seal`, `ship`, …)
+  are the project's record of *why* the feature is the way it is. A future
+  `$rite-zoom-out` or incident review reads them.
+- Deleting them would make the workflow's own "evidence over confidence" rule a lie.
+
+## Re-opening an archived feature
+
+To resume archived work, move it back:
+`mv .devrites/archive/<slug> .devrites/work/<slug>` and write `<slug>` into
+`.devrites/ACTIVE`. Nothing is lost — close-out is reversible by design.
+
+## Cross-feature retro
+
+After archive, run `devrites-engine learnings nudge`. It stays silent until a
+finding/drift class recurs across at least two shipped features with new signal.
+
+When it emits, dispatch the read-only `devrites-retrospector` over
+`.devrites/archive/`, append its dated digest to `.devrites/retro.md`, and surface
+graduation candidates to `$rite-learn`. The retro proposes; only `$rite-learn` may
+promote a rule, principle, or convention. Mark `.devrites/.learnings-reviewed` only
+after the human acts there.

package/pack/generated/codex/skills/rite-ship/reference/design-memory.md

@@ -0,0 +1,120 @@
+# Design memory — roll proven design language into project `DESIGN.md`
+
+Optional, UI-only step at `$rite-ship`. A feature's design decisions live in its
+feature-scoped `design-brief.md` and are thrown away when the workspace archives. **Design
+memory** is the deliberate exception: when a UI feature ships, roll the design language it
+*proved* up into a project-level `DESIGN.md`, so the next feature's `devrites-ux-shape`
+inherits the system instead of re-discovering it.
+
+The consumers already exist — `devrites-ux-shape` §1 and
+`devrites-frontend-craft/reference/design-references.md` both read `DESIGN.md` when present.
+This step is the missing **producer**. It closes the loop: feature N seals its design
+language → feature N+1 builds to it.
+
+## When it runs
+- **UI features only.** No UI in the diff → skip silently.
+- **At ship, GO sealed, after the git plan, before type-GO** (step 2a) — so the user sees
+  the full staged change set (code + `DESIGN.md`) under the single type-GO that ships it.
+- **Opt-in and confirmed.** Persisting to a project-wide artifact is outside feature scope
+  (`standards/core.md` rule 7) — so it is *never silent*. Present a ranked option set
+  (`standards/afk-hitl.md` — Option set); **default is skip**. The user opts to persist.
+- **AFK**: first-time `DESIGN.md` *creation* is treated as a `validating` gate (a new
+  persistent project artifact) — propose + queue, don't auto-create. An *append* to an
+  existing `DESIGN.md` is `advisory` and may auto-proceed when `allow_gates` permits, since
+  it only adds evidence-proven entries.
+
+## Inputs (proven only)
+- `design-brief.md` — direction, color strategy, **calibration** (density / motion), key
+  states, named anchors, and the per-slice **Build-time refinements**.
+- The **final diff** + `touched-files.md` — what tokens / components / states *actually
+  shipped* (the evidence). Roll up only what the diff proves, not what the brief intended.
+- Existing `DESIGN.md` if present — the merge target.
+
+## What to roll up — the project's *converged* system, evidence-gated
+Only entries the shipped, proven feature establishes. Each is durable, cross-feature design
+language — not this feature's one-off choices.
+- **Tokens introduced + used** — new color roles / spacing steps / type steps / elevation
+  / radius that shipped and are reusable. Names and values, mirrored from the code.
+- **Color strategy + calibration baseline** — the strategy (Restrained / Committed / …) and
+  density / motion the project keeps landing on; note a deviation as a deviation, not a new
+  default.
+- **Type & spacing scales** in actual use; **motion** classes + easing; **materiality**
+  (elevation set, hairline usage, glass / texture policy).
+- **Component behaviors** — for each shared component this feature established or extended:
+  the states it ships and its interaction model. Grows one feature at a time.
+- **Named-anchor lineage** — the anchors features steered toward, so later work stays
+  coherent with what's already built.
+- **Anti-slop exceptions** — any banned default the project *intentionally* uses (with the
+  why), so build / polish don't "correct" a deliberate choice.
+
+## Merge discipline
+- **Append, don't overwrite.** Add proven entries; never silently rewrite an existing one.
+- **Conflict is a question, not an edit.** A new token / font / strategy that contradicts an
+  existing `DESIGN.md` entry → surface it to the user (the option set), don't resolve it
+  yourself. One design system per project.
+- **Never invent.** If the feature didn't prove it, it doesn't go in. `DESIGN.md` is design
+  *memory*, not design *aspiration*.
+- **Attribute + keep lean.** Tag each new entry with the feature slug so the lineage is
+  legible; one good line beats a paragraph. The file is read every future spec — keep it
+  scannable.
+
+## How it commits
+`DESIGN.md` is a tracked project artifact, so it ships **in the feature commit**:
+1. Write / update `<project-root>/DESIGN.md` from the template below.
+2. **Append `DESIGN.md` to `touched-files.md`** so the existing ship commit-scoping (SKILL
+   steps 2 + 4) stages it — the design-memory write rides the same commit and the same
+   type-GO, no second commit.
+3. Note the rollup in `ship.md` (what was added, or "design-memory: skipped by user").
+
+## `DESIGN.md` template (project-level, stack-agnostic)
+```markdown
+# DESIGN.md — <project> design memory
+
+> Rolled up from shipped features by `$rite-ship` (design memory). Read by
+> `devrites-ux-shape` and `devrites-frontend-craft` as the inherited system. Evidence-only:
+> every entry shipped and was proven. Edit through a feature's ship, not by hand.
+
+## Register & direction
+Default register per surface (brand / product) and the scene-derived direction the product
+keeps converging on.
+
+## Color
+Strategy baseline (Restrained | Committed | Multi-role | Saturated). Token roles
+(surface / text / accent / border / danger / …) with values or token names. Dark-mode approach.
+
+## Calibration
+Density baseline (Airy | Balanced | Dense) · Motion baseline (Minimal | Standard | Expressive).
+Surfaces that deviate + why.
+
+## Typography
+Families; the scale in use (fixed rem / fluid clamp); heading↔body ratio; weights.
+
+## Spacing
+The scale (4 pt multiples) and section rhythm in use.
+
+## Motion
+Classes in use, easing, `prefers-reduced-motion` handling.
+
+## Materiality
+Elevation token set, hairline usage, glass policy, texture / asset approach.
+
+## Components (proven behaviors)
+| Component | States shipped | Interaction model | First proven by |
+|---|---|---|---|
+| <name> | default/hover/focus/loading/empty/error/… | inline / navigated / modal · feedback | <slug> |
+
+## Named-anchor lineage
+The anchors features steered toward (keeps new work coherent).
+
+## Anti-slop — project exceptions
+Banned defaults this project *intentionally* uses, with the why (so build/polish don't undo them).
+```
+
+## NEVER (design memory)
+- Never roll up unattended on first creation — a new persistent project artifact is a
+  confirmed step, never an AFK silent write.
+- Never write an entry the feature didn't *prove* shipped — no aspirational tokens.
+- Never overwrite or silently reconcile a conflicting existing entry — surface it.
+- Never persist a feature-only one-off as if it were the project default.
+- Never add `DESIGN.md` to the commit without appending it to `touched-files.md` first
+  (it would fall outside the ship's commit scope).