devrites 2.6.0 → 3.0.0

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

@@ -0,0 +1,116 @@
+---
+name: rite-adopt
+description: Adopt an existing or legacy codebase into DevRites by reverse-engineering current behavior, seeding conventions, and establishing the workflow. Use for inherited or live applications.
+argument-hint: "[path or area to adopt] [+ what you want to build next]"
+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-adopt — brownfield on-ramp
+
+The **reverse** of `$rite-spec`. `$rite-spec` goes idea → spec; `$rite-adopt` goes
+**existing code → spec + seeded conventions**, so an already-built project can enter the
+DevRites lifecycle without hand-writing a spec from nothing. It produces the same
+`spec.md` the rest of the lifecycle expects, plus a head start in the conventions ledger
+so the very first new slice already knows the project's idioms.
+
+Use it once, at the start, to onboard a repo (or a sub-area of one). After it, the normal
+lifecycle (`$rite-temper` → `$rite-define` → `$rite-build` …) takes over.
+
+> **Just want a map, not an onboarding?** `$rite-zoom-out` returns a structural map of
+> unfamiliar code without creating a workspace or ledger. `$rite-adopt` is the heavier move:
+> it *commits the project to the lifecycle*. Pick zoom-out to look, adopt to begin.
+
+## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
+Pull `documentation.md` when recording the adoption decisions (why-not-what) in
+`decisions.md`; pull `principles.md` when the code
+upholds invariants worth proposing as project principles (step 4a).
+
+## Operating rules (DevRites core)
+- No silent assumptions · prefer the project's existing conventions (you are *documenting*
+  them, not imposing new ones) · ask the human when the adoption scope or the next-build
+  objective is unclear.
+
+## Workflow
+0. **Read `.agents/skills/devrites-lib/reference/standards/core.md`**, then run
+   `devrites-engine preamble` for deterministic workspace orientation.
+1. **Scope the adoption** (`$ARGUMENTS`). Which repo or sub-area is being onboarded, and —
+   if stated — what the user wants to build *next* on top of it. If the next-build objective
+   is missing, ask once (it shapes the spec's acceptance); if the area is ambiguous, confirm
+   before investigating the whole tree.
+2. **Reverse-investigate the existing code** — the durable shape of the project. Use a
+   code-intelligence index if available — codebase-memory-mcp first (its `get_architecture`
+   gives a fast overview), cross-checked with codegraph + graphify, else standard methods
+   (LSP / Read/Grep/Glob); see `.agents/skills/devrites-lib/reference/standards/tooling.md` — for
+   structure, callers, and impact. Capture, per [adoption](reference/adoption.md): **current
+   behavior**, **architecture + placement** (layers, seams, where each kind of thing lives),
+   the **commands** (test / build / typecheck / lint), and the **idioms** (naming, layering,
+   error model, test style) + recurring **gotchas**. Read `PRODUCT.md` / `DESIGN.md` /
+   `CLAUDE.md` / `AGENTS.md` if present.
+3. **Write `spec.md`** via [rite-spec's spec template](../rite-spec/reference/spec-template.md)
+   and create the workspace + set `.devrites/ACTIVE`
+   ([state-workspace](../rite-spec/reference/state-workspace.md)). The spec records the
+   **current behavior as the baseline** and the **next objective** (what adoption is for) with
+   measurable acceptance. Also write `decisions.md`, `assumptions.md`, `questions.md`, and
+   `state.md` (phase: spec).
+3a. **Seed the capability ledger** from the baseline. If the reverse-derived `spec.md` carries
+   structured `### Requirement:` blocks, fold them into the living
+   `.devrites/specs/<capability>/spec.md` ledger so the project's *current* proven behavior is on
+   record before the first new feature — the ledger the next `$rite-spec` writes deltas against
+   ([ledger.md](../rite-ship/reference/ledger.md)). A flat baseline folds as all-ADDED into the
+   feature slug's capability; tag capabilities in the spec first if you want finer granularity.
+   ```bash
+   devrites-engine ledger diff .devrites/work/<slug>   # preview
+   devrites-engine ledger sync .devrites/work/<slug>   # seed
+   ```
+   Skip when the baseline records no structured requirements (nothing to seed).
+4. **Seed the conventions ledger** from what the investigation *observed* —
+   [adoption § seeding](reference/adoption.md). This is the deliberate bootstrap exception to
+   evidence-gated promotion: the seeds start at the base band and are provenance-tagged as
+   onboarding observations, not sealed-slice proofs, so real slices later corroborate or
+   (fresh-wins) contradict them.
+   **Completion:** every seed names observed evidence, provenance, and the base band.
+4a. **Propose candidate principles** (human-ratified; optional). Where the investigation found an
+   invariant the code *consistently and deliberately* upholds — money always in integer cents, PII
+   always redacted from logs, every v1 endpoint preserved — surface it as a **candidate
+   principle**, not a seeded convention. Principles are prescriptive and gating, so they are
+   **ratified by the human, never auto-seeded** the way conventions are: present the candidates via
+   `AskUserQuestion` with the evidence (where the code upholds it), and write the ones the human
+   ratifies to `.devrites/principles.md` with a dated Governance entry
+   ([`principles.md`](../devrites-lib/reference/standards/principles.md)). Propose, don't impose — an unratified candidate
+   stays a convention, not a gate. Skip cleanly when nothing rises to an invariant (common — a
+   fresh adopt may declare zero principles, and that's valid).
+5. **Hand off.** The project is now in the lifecycle with a spec and a head-start ledger.
+   Point the user at `$rite-temper` (big/risky) or `$rite-define` (straightforward) — do not
+   plan or build here.
+   **Completion:** one next rite is reported and no plan or application code was written.
+
+> **Mid-flight discipline.** Don't invent conventions the code doesn't actually follow, don't
+> seed an idiom you only assumed, and don't expand scope into a rewrite — adoption documents
+> what exists; the *next* feature changes it. See [`anti-patterns`](reference/anti-patterns.md).
+
+## Output
+
+**Progress first** — run `devrites-engine progress`, then use the shared completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)).
+Default success shape:
+```
+Done: adopted existing behavior into <slug>; baseline spec and placement recorded.
+Changed: spec.md, decisions.md, conventions ledger, principles proposals <updated|none>
+Evidence: not applicable; reverse-derived behavior is recorded for review
+Open: <none | adoption questions | Alternative: $rite-define for straightforward follow-up>
+Next: $rite-temper
+Record: .devrites/work/<slug>/spec.md
+↻ Hygiene: /clear before the next phase
+```

package/pack/generated/codex/skills/rite-adopt/reference/adoption.md

@@ -0,0 +1,55 @@
+# Adoption — reverse-investigate + seed (the on-ramp contract)
+
+Loaded on demand by `$rite-adopt`. Two jobs: document what the code already does (so the
+lifecycle has a spec), and seed the conventions ledger (so the first slice knows the idioms).
+
+## Reverse-investigation — what to capture
+
+Document the **durable shape** of the project, not a line-by-line tour:
+
+- **Current behavior** — what the adopted area does today, from the user's perspective.
+- **Architecture + placement** — the layers and seams; where each kind of thing lives
+  (where endpoints / components / models / migrations / tests go). Prefer a code-intelligence
+  index if available (see `../../devrites-lib/reference/standards/tooling.md`) for
+  structure, callers, and impact.
+- **Commands** — the real test / build / typecheck / lint commands (run or read them; don't
+  guess). Verify uncertain framework facts at the source.
+- **Idioms** — naming + casing, layering, the error model, the result/exception style, the
+  http/data-access pattern, the test framework + file layout.
+- **Gotchas** — non-obvious constraints the code encodes (ordering requirements, "don't call
+  X before Y", a framework quirk).
+
+This feeds `spec.md` (current behavior as the baseline + the next objective) and the ledger
+seeds below.
+
+## Seeding the conventions ledger
+
+The deliberate **bootstrap exception** to evidence-gated promotion. Normally a convention is
+promoted only when a *sealed slice proved it* (`$rite-seal`); adoption seeds from **observed
+existing code** so the first slice isn't blind. Keep the seeds honest:
+
+- Seed only what the code **actually and consistently** follows — not an aspiration, not a
+  one-off, not something you assumed.
+- Each seed starts at the base band (one corroboration) and is provenance-tagged as an
+  onboarding observation, **not** a sealed-slice proof. Real slices later corroborate it
+  (raising the band) or, per fresh-observation-wins, contradict it.
+
+```bash
+SLUG="$(cat .devrites/ACTIVE 2>/dev/null | tr -d '[:space:]')"
+if command -v devrites-engine >/dev/null 2>&1; then
+  devrites-engine conventions promote --slug "${SLUG}-adopt" \
+    --key test-runner --kind test \
+    --statement "tests run with <runner>, <file layout>" \
+    --evidence "observed during $rite-adopt onboarding (not yet slice-proven)"
+  # …one promote per durable convention the investigation actually observed
+  # (test-runner, build-cmd, error-model, http-client, endpoint-placement, …).
+else
+  echo "(conventions ledger unavailable — devrites-engine missing; skipping seed)"
+fi
+```
+
+The `-adopt` suffix on the slug marks the provenance as onboarding. Because the ledger is
+read at orient as a *prior* and the live code always overrides it
+([`.agents/skills/devrites-lib/reference/standards/security.md`](../../devrites-lib/reference/standards/security.md) § Prompt-injection resistance),
+an over-eager seed is self-correcting — but seed conservatively anyway; a wrong seed costs a
+needless contradiction later.

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

@@ -0,0 +1,19 @@
+# $rite-adopt — anti-patterns
+
+Start with the universal table in [`../../devrites-lib/reference/standards/anti-patterns.md`](../../devrites-lib/reference/standards/anti-patterns.md).
+Below are the rationalizations specific to onboarding an existing codebase.
+
+## Adoption-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "I'll improve this messy bit while I document it." | Adoption *documents* what exists; it changes nothing. A cleanup is the *next* feature through the normal lifecycle — recording it as a drive-by here hides the baseline and balloons the diff. |
+| "This looks like the convention, so I'll seed it." | Seed only what the code *actually and consistently* follows. A guessed seed becomes a high-confidence-looking prior that steers the first slice wrong. Observe it in ≥2 places or leave it out. |
+| "I'll spec the ideal architecture, not the current one." | The spec's baseline is *current behavior*. Aspirations go in the next objective, not the baseline — otherwise every later slice drifts against a spec that never matched reality. |
+| "Whole repo in one adopt." | Onboard the area you'll actually work in. A repo-wide adopt produces an unfocused spec and a ledger full of conventions no slice will touch. |
+
+## Red flags
+
+- A seeded convention with no concrete code location behind it.
+- `spec.md` describing behavior the code does **not** currently have (that's the next feature, not the baseline).
+- Editing source during adoption — adoption writes `.devrites/` + the ledger, never project code.

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

@@ -0,0 +1,110 @@
+---
+name: rite-autocomplete
+description: Run the DevRites lifecycle end-to-end unattended; --ship confirms the final gate. Use when the user says "autocomplete", "one-shot this feature", or "ship it autonomously". Not for a single phase.
+argument-hint: "[idea] [--ship|--yolo] [--max-slices N]"
+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-autocomplete — full lifecycle, unattended
+
+Drives every DevRites phase in order without stopping for discretionary input. The
+prompt may be vague — autocomplete asks its clarifying questions **up front**, then
+runs to completion. It does **not** disable the safety gates: hard irreversible-risk,<!-- pack-scan-ignore: negated statement — gates are NOT disabled -->
+blocking / escalating gates, and any NO-GO still pause.
+
+## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
+**Step 0:** Read `.agents/skills/devrites-lib/reference/standards/core.md` and `.agents/skills/devrites-lib/reference/standards/afk-hitl.md` first.
+
+## Operating rules
+- **One human window.** Clarifying questions are batched up front via
+  `devrites-interview`. After that, discretionary decisions are made automatically and
+  recorded in `decisions.md` — not asked. See [reference/decision-policy.md](reference/decision-policy.md).
+- **Safety gates are not bypassable.** AFK never auto-passes destructive migration /
+  auth-authz change / public-API break / external-contract change / red tests; blocking
+  and escalating gates and any open `gate: validating` always pause. `--ship` auto-confirms
+  the **final** type-GO only — nothing else. A change that violates a declared project
+  principle (`.devrites/principles.md`) with no recorded exception pauses too — autocomplete
+  never grants a principle exception on its own (`principles.md`: that's a human decision).
+- **Loop budget = the plan's own slice count, not a fixed number.** After `$rite-vet`
+  (not `$rite-define` — vet may split or add slices, so the count isn't final until then),
+  set the AFK budget to however many slices the plan has, so the loop builds exactly the
+  task's slices and stops when they're done. `--max-slices N` is an OPTIONAL *lower* safety
+  cap (partial / babysat run); omit it to run the whole plan. The budget is finite
+  (= planned slices), so a runaway is still bounded.
+- **Best option, recorded.** For each discretionary choice, pick the option the relevant
+  specialist / reviewer favours and record the rationale. Never silently coin-flip.
+- **Strategic review runs, but never auto-grows scope.** After `$rite-spec`, run `$rite-temper`
+  (significance-gated — it skips low-stakes specs in one line). Unattended it auto-applies only
+  `hold-rigor` + `reduce-to-MVP` (these never grow acceptance); **any `expand` is a blocking
+  pause**, and irreversible-risk findings always pause. Autocomplete hardens and may *prune* the
+  spec on its own; it never *expands* the build's scope without the human.
+- **Engineering review runs on every plan, but never auto-grows scope.** After `$rite-define`,
+  run `$rite-vet` on **every** feature (depth scales — a light pass on simple plans, full rigor on
+  big/risky; never skipped). Unattended it auto-applies only *hardening* findings — added test
+  requirements, error-handling / failure-mode coverage, tightened scope, reuse-over-rebuild,
+  ordering / parallel-lane fixes (these never grow acceptance); **any finding that grows scope,
+  adds a slice, or changes acceptance is a blocking pause**, and irreversible-risk findings always
+  pause. Cross-model is off unless `--cross-model` was armed.
+
+## Workflow
+1. **Orient + parse args.** Run `devrites-engine preamble` for deterministic workspace orientation.
+   The idea + flags: `--ship` / `--yolo` (auto-confirm the final
+   type-GO), `--max-slices N` (OPTIONAL *lower* safety cap for a partial run; default =
+   the plan's slice count, i.e. run all planned slices).
+2. **Clarify up front.** If the idea is underspecified, run `devrites-interview` to
+   ~95% confidence — the only interactive window. If already clear, skip.
+3. **Arm AFK.** Write `.devrites/AFK` with `allow_gates: [advisory]`; set the slice budget
+   from the plan's count after `$rite-vet` (the slice count is only final post-vet), or from
+   an explicit `--max-slices` ([reference/loop.md](reference/loop.md)). validating / blocking / escalating +
+   irreversible-risk still pause. Also `touch .devrites/CHECKPOINT` — an unattended run is the
+   case checkpoint mode earns its keep, so each proven slice is committed local-only as
+   crash-survivable `WIP` ([rite-build/reference/checkpoint.md](../rite-build/reference/checkpoint.md));
+   `$rite-ship` collapses them into the one feature commit.
+4. **Drive the phases** ([reference/loop.md](reference/loop.md)): `$rite-spec` →
+   **`$rite-temper`** → `$rite-define` → **`$rite-vet`** → `$rite-build` (loop until all slices
+   built; `devrites-engine tick-afk` each) → `$rite-prove` → `$rite-polish` → `$rite-review` → `$rite-seal`.
+   Run each by Reading its `SKILL.md` and executing its workflow; state is carried by the
+   workspace files, not chat.
+5. **Apply stop conditions at every gate** ([reference/stop-conditions.md](reference/stop-conditions.md)):
+   on hard-risk / blocking / escalating / NO-GO / budget-exhausted / still-low-confidence
+   → write `state.md` (`Status`, `Next step`), surface *why*, and **STOP**.
+6. **Seal GO → ship.** With `--ship`, proceed to `$rite-ship` and auto-confirm the
+   type-GO. Without it, render the type-GO prompt and stop for the human.
+
+> **Mid-flight discipline.** When tempted to auto-pass a blocking gate "to keep moving",
+> answer a material question yourself instead of pausing, or run past red tests — stop.
+> Autonomy is for the routine path; the gates exist for everything else.
+
+## Output
+A compact phase-by-phase log, then the final status. **Progress first for the final
+status** — run `devrites-engine progress`, then use the shared typed states from
+[`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md):
+`Shipped`, `Stopped`, `Awaiting human`, `NO-GO`, or `GO`.
+
+Keep the log terse:
+```
+Autocomplete: <slug>
+spec <done|stopped> · temper <done|skipped|stopped> · define <done|stopped> · vet <done|stopped> · build <n/N|stopped> · prove <done|stopped> · polish <done|stopped> · review <done|stopped> · seal <GO|NO-GO|stopped>
+```
+
+Final state examples: `Shipped: <feature>`, `Stopped: <reason>`, `Awaiting human:
+<qid> · <gate> · <slice/phase>`, `NO-GO: <verdict>`, or `GO: feature cleared to ship`.
+Do not write a narrative recap.
+
+## Clean baseline and checkpoint mode
+- Before an autonomous run, require a clean or explicitly accepted baseline: refuse unrelated dirty work and record expected planning artifacts.
+- Arm `.devrites/CHECKPOINT` for the run so each proven slice can be checkpointed local-only; `$rite-ship` owns collapsing those checkpoints.
+- Stop on risky steps, red gates, NO-GO, stale evidence, or budget exhaustion.
+- Autocomplete gets one approved pass through the lifecycle; `$rite-build` still builds exactly one slice per invocation.

package/pack/generated/codex/skills/rite-autocomplete/reference/decision-policy.md

@@ -0,0 +1,35 @@
+# Decision policy — how autocomplete "chooses the best option"
+
+Unattended ≠ careless. Every discretionary choice is made the way a senior engineer
+would, then **recorded** so the seal can audit it. The difference from interactive mode
+is only *who answers* a discretionary question — not whether it's reasoned.
+
+## The rule
+
+For each non-trivial choice, pick the option the **relevant specialist favours**, and
+write the choice + the one-line rationale to `decisions.md`. Do not coin-flip, and do
+not pick the option that's merely easiest to implement.
+
+| Choice type | Defer to | Then |
+|---|---|---|
+| Uncertain framework / library behaviour | `devrites-source-driven` (check the docs/source) | record the source in `evidence.md` |
+| Risky boundary / data-model / API decision | `devrites-doubt` (+ `devrites-doubt-reviewer`) | record the trade-off in `decisions.md` |
+| Cross-boundary contract (FE/BE split, API shape) | `devrites-api-interface` | contract-first slice |
+| UI surface / states / a11y | `devrites-frontend-craft` | shape before code |
+| Two reasonable designs, no clear winner | the simpler one that meets acceptance | note why in `decisions.md` |
+
+## Defaults autocomplete may assume (record them)
+
+- Follow the project's existing conventions, components, and test commands — always.
+- Prefer the smallest vertical slice that proves the acceptance criterion.
+- Reuse → extend → build new, in that order (`coding-style.md`).
+- When two options are equivalent on the evidence, choose the lower-risk / more
+  reversible one.
+
+## When a choice is NOT autocomplete's to make
+
+If a discretionary choice would change **product behaviour, scope, data model, security
+posture, or acceptance criteria**, it is no longer discretionary — it is a material
+question. Route it through the Spec Drift Guard / a `blocking` question and **stop**
+(see [stop-conditions.md](stop-conditions.md)). Autocomplete answers *how*, never
+*what to build* beyond what the up-front interview settled.

package/pack/generated/codex/skills/rite-autocomplete/reference/loop.md

@@ -0,0 +1,54 @@
+# The autocomplete loop — arm AFK, drive every phase
+
+Autocomplete is an orchestrator: it runs the existing `/rite-*` skills in order,
+exactly as a human would, but without stopping between them. It owns no workflow of
+its own — the phases do the work; autocomplete sequences them and enforces stops.
+
+## Arm AFK
+
+Arm the gate policy up front; set the slice budget once the plan's count is known:
+
+```yaml
+allow_gates: [advisory]        # only advisory auto-handles; validating+ pause
+# notify: "<cmd>"              # optional — fired on any awaiting_human pause
+# max_slices: <N>              # the slice BUDGET — set from the plan's count after
+# $rite-define (or an explicit --max-slices). NOT a target decomposition; it only
+# caps how many run unattended (default = all the plan's slices).
+```
+
+The budget is the plan's own slice count, not a fixed number — so the loop builds exactly
+the task's slices and stops when they're done; `--max-slices N` only *lowers* it for a
+partial run. Arm the gate policy at step 3; write `max_slices` / `AFK slices remaining`
+**after `$rite-vet`** (it runs before the build loop and may split or add a slice, so the
+count isn't final until then — vet runs on every plan here, so always set the budget after it).
+
+`allow_gates: [advisory]` is deliberate: an open `gate: validating` is merge-blocking
+at seal (`afk-hitl.md`), so autocomplete must *pause* on it rather than queue it and
+then hit NO-GO. Widen `allow_gates` only if the caller explicitly asked.
+
+## Drive the phases
+
+Run each by Reading its `SKILL.md` and executing that workflow. State flows through the
+workspace files (`state.md`, `tasks.md`, `evidence.md`, …), so each phase picks up where
+the last left off — there is nothing to thread through chat.
+
+| Step | Phase | Loop / gate |
+|---|---|---|
+| 1 | `$rite-spec` | feed the interview answers; write `spec.md` |
+| 2 | `$rite-temper` | significance-gated strategic review; harden spec + write `strategy.md`. Skip low-stakes specs in one line. AFK: `hold-rigor` / `reduce-to-MVP` auto-apply; **any `expand` pauses (blocking)**; irreversible-risk pauses |
+| 3 | `$rite-define` | reads `strategy.md`; `plan.md` + `tasks.md`; record `Plan approved` |
+| 4 | `$rite-vet` | engineering plan review on **every** plan (light pass on simple plans, full on big/risky; never skipped); harden `plan.md` / `tasks.md` + write `eng-review.md` + `test-plan.md`. AFK: hardening / coverage findings auto-apply; **any scope-growing / acceptance-changing finding pauses (blocking)**; irreversible-risk pauses. Set the slice budget after this (vet may split a slice) |
+| 5 | `$rite-build` ×N | **loop** while any slice is `pending`; build one (the slice-wright reads `test-plan.md` for coverage), then run `devrites-engine tick-afk state.md` — exit 3 (budget hit) ⇒ STOP |
+| 6 | `$rite-prove` | once all slices `built`; walks `test-plan.md`; on failure → `devrites-debug-recovery` within scope |
+| 7 | `$rite-polish` | re-verify after code edits (evidence must stay fresh) |
+| 8 | `$rite-review` | apply in-scope fixes; re-prove if code changed |
+| 9 | `$rite-seal` | GO/NO-GO decision (no git here) |
+| 10 | `$rite-ship` | only if seal GO; `--ship` auto-confirms type-GO, else stop for human |
+
+## Between phases
+
+- Re-read the active workspace before each phase (don't trust chat memory).
+- After a phase that edits code (build, polish, review), evidence may be stale — let
+  the next gate re-prove rather than carrying a stale pass (see
+  `.agents/skills/devrites-lib/reference/standards/development-workflow.md`).
+- Check [stop-conditions.md](stop-conditions.md) at every gate **before** advancing.

package/pack/generated/codex/skills/rite-autocomplete/reference/stop-conditions.md

@@ -0,0 +1,59 @@
+# Stop conditions — when autocomplete must pause for a human
+
+Autonomy covers the routine path. These are the cases where autocomplete writes
+`state.md` (`Status: awaiting_human` or `blocked`), surfaces *why* + the single resume
+command, fires `notify` if set, and **stops**. None are bypassable by `--ship`.
+
+## Always stop (irreversible-risk list — from `afk-hitl.md`)
+
+Regardless of `allow_gates` or `--ship`:
+- Destructive data migration (drop column/table, irreversible backfill).
+- Auth / authz boundary change.
+- Public-API break (response shape, removed endpoint, changed status semantics).
+- External-service contract change.
+- Filesystem destruction outside the workspace.
+- Red tests / types / lint at slice end (fail-on-red).
+
+## Stop on gate severity
+
+- `blocking` gate fires → synchronous pause.
+- `escalating` gate fires → pause, route to the specialist tag.
+- Any `questions.md` entry with `gate: validating` and `status: open` → pause (it is a
+  seal NO-GO by definition; don't sail into a guaranteed NO-GO).
+
+## Stop on strategic-review scope expansion (`$rite-temper`)
+
+- `$rite-temper` choosing scope mode `expand` — or otherwise **adding** any acceptance
+  criterion to `spec.md` — → synchronous pause, regardless of `allow_gates` / `--ship`.
+  Autocomplete may auto-apply only `hold-rigor` and `reduce-to-MVP` (they harden / prune and
+  never grow the build's scope); **growing scope unattended is never automatic**. A low-stakes
+  spec that temper skips, or a `hold-rigor` / `reduce-to-MVP` run, does **not** pause.
+
+## Stop on workflow state
+
+- **NO-GO at seal** → stop; surface every blocker with `file:line` and the fix
+  direction. Do not round NO-GO up to GO.
+- **Spec Drift Guard fires** (`$rite-build` finds the plan is wrong and the change
+  alters product behaviour) → stop; route through `$rite-plan repair`.
+- **Budget exhausted with slices still pending** — `devrites-engine tick-afk` exit 3 while `tasks.md`
+  still has unbuilt slices (only when an explicit `--max-slices` capped the run below the
+  plan's count) → stop; report slices remaining. Exhausting the default budget = all
+  planned slices built = normal completion → continue to `$rite-prove`, don't pause.
+- **Still low-confidence after the interview** — the idea can't be pinned to testable
+  acceptance criteria → stop and ask, rather than guessing the product.
+- **Repeated failure** — a phase fails, `devrites-debug-recovery` can't fix it within
+  scope after a bounded number of attempts → stop with the reproduction.
+
+## The final type-GO
+
+- Default: render the type-GO prompt at `$rite-ship` and **stop** for the human's
+  literal `GO`.
+- With `--ship` / `--yolo`: auto-confirm the type-GO (the *only* thing the flag changes).
+  Everything above still pauses.
+
+## How to stop well
+
+State must be enough for a fresh agent to resume cold:
+- `state.md`: `Status`, the blocking reason, and a single `Next step` command.
+- The relevant `questions.md` / `drift.md` / `seal.md` entry that explains the pause.
+- A one-line user-facing message: *what* stopped it and *what command* resumes.

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

@@ -0,0 +1,96 @@
+---
+name: rite-build
+description: Build one approved vertical slice, then stop with evidence. Use when the next planned slice should be implemented. Not for multiple slices.
+argument-hint: "[slice number or name]"
+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-build — one verified slice
+
+Build the next single slice, leave it working and proven, then **stop**. **Read the
+active workspace first**; if none, tell the user to run `$rite-spec <feature>`.
+
+This skill is the **orchestrator**: it owns the gates and the workspace; a fresh-context
+[`devrites-slice-wright`](.codex/agents/devrites-slice-wright.toml) owns the **writing**. You run
+pre-flight (readiness, slice select, HITL pause), dispatch the wright for the build core, then
+run the post-return gates (doubt, fail-on-red, record, stop). See
+[`reference/wright-dispatch.md`](reference/wright-dispatch.md).
+
+## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
+Read `.agents/skills/devrites-lib/reference/standards/core.md` first (workflow step 0). The
+following load on demand — **the wright reads them** (they are named in its contract) while it
+writes; read them yourself for the doubt/record gates or in the inline fallback:
+- `coding-style.md` — naming, function shape, guard clauses, comments, reuse-first.
+- `error-handling.md` — fail fast, no silent catches, fail closed.
+- `testing.md` — pyramid, behaviour over implementation, see-it-fail-first.
+- `patterns.md` — composition over inheritance, avoid premature abstraction.
+- `principles.md` — the project invariants (`.devrites/principles.md`) the slice must honor; the wright reads them as **binding**, not priors.
+- `security.md` — when the slice touches user input, auth, data, or external integrations.
+- `definition-of-done.md` — standing Done bar: acceptance mapped, fresh proof, no open hard gates, scoped edits, rollback/docs where needed.
+
+
+## Operating rules
+- **One slice at a time. DO NOT** start the next slice without the user asking.
+- Evidence over confidence. Prefer existing conventions. Feature scope only — no
+  drive-by refactors.
+- **Noticed, not touched.** An adjacent smell the wright sees outside `touched-files.md` is
+  recorded as an FYI follow-up in `decisions.md`, never fixed inline — the slice's change summary
+  states what it *deliberately left alone* ([`git-workflow.md`](../devrites-lib/reference/standards/git-workflow.md) "Things
+  I didn't touch"), so the reviewer reads a feature-scoped diff, not a renovation. The `devrites-engine reconcile`
+  gate (step 6) enforces this by exit code.
+- **Don't re-run an unchanged check.** Re-running the same build/test command on code that hasn't
+  changed since proves nothing new — it's motion, not evidence. Re-verify after an edit, not before.
+- Surface material assumptions; ask before adding dependencies or a second design
+  system. The [Spec Drift Guard](reference/spec-drift-guard.md) is active throughout.
+- **Avoid AI slop while writing.** `devrites-slice-wright` enforces the anti-slop charter **at
+  the source** — the canonical do-not list is `rite-polish/reference/anti-ai-slop.md` (the
+  wright reads it; don't restate it here). It writes the code the *project* would write, in its
+  idiom, reusing before building; **you verify the charter held on return** — you do not re-list
+  it and you do not fix slop by editing source. Polish catches what slips; build prevents.
+  The **prose you write yourself** — `evidence.md`, `decisions.md`, the slice report — follows
+  the human-voice charter (`.agents/skills/devrites-lib/reference/standards/prose-style.md`; depth in `devrites-prose-craft`): no
+  filler openers, no marketing adjectives, exact commands and identifiers kept verbatim.
+- **Honor declared project principles.** The wright reads `.devrites/principles.md` and treats
+  each invariant as **binding** (not a prior to weigh like a convention) — a slice it cannot build
+  without breaking one is an **Escalation**, not a silent violation. On return **you verify no
+  principle was broken**; a fresh violation is handled like any irreversible-risk item — a
+  human-approved, scoped exception in the register or a stop, never folded into the slice. No
+  `.devrites/principles.md` → none declared → nothing to honor.
+- **You never edit source — the wright is the only writer of code + tests.** You write only
+  `.devrites/` bookkeeping. On any red gate, doubt finding, or coverage gap your only remedies
+  are **continue the same wright once** (it fixes in its own context) or **stop + escalate** —
+  never patch the code yourself. The `devrites-engine reconcile` gate (step 6) enforces this by exit code:
+  any source file changed outside the wright's claimed set is a hard STOP.
+- **A `Forge: yes` slice competes candidates — one author still lands.** When `$rite-vet`
+  flagged the slice a genuine architecture fork, step 3 runs K=2–3 candidate wrights in
+  **isolated worktrees** and lands exactly one winner's diff; the single-writer invariant holds
+  because no tree ever has two authors and only the winner reaches the working tree. You still
+  never edit source, and reconcile runs against the winner's claimed set. The default slice is
+  single-path — forge is the rare exception ([`reference/forge.md`](reference/forge.md)).
+
+## Workflow
+
+Run the full execution contract in
+[`reference/phase-contract.md`](reference/phase-contract.md). It is not optional:
+it contains the gated one-slice workflow, including readiness, HITL/AFK handling,
+wright dispatch, forge, doubt, fail-on-red, record gates, and stop behavior.
+
+## Output
+
+Use the full output contract in [`reference/output.md`](reference/output.md).
+It preserves the progress-footer-first response shape, uses the shared completion
+reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)),
+and keeps the explicit stop after one slice.