devrites 2.6.0 → 3.0.0

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

@@ -0,0 +1,132 @@
+---
+name: rite-frame
+description: Frame an ad-hoc ask before coding, then audit the diff. Use for underspecified imperative asks, raw-diff self-audits, or `$rite-quick` setup. Not a lifecycle gate.
+argument-hint: "[task to frame | diff to audit]"
+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-frame — frame the goal, audit the diff
+
+LLMs reliably get four things wrong: they **assume** silently, **overcomplicate**, edit
+**out of scope**, and run on an **unverifiable** "make it work". The full DevRites
+lifecycle catches all four at its gates (spec readiness, the Spec Drift Guard,
+`touched-files.md` + `devrites-engine reconcile`, `$rite-seal`). But the express lane and plain
+"just do X" requests **skip those gates** — and a raw diff has no gate at all.
+
+`rite-frame` is the gate's reflex made portable. Two moves, no workspace required:
+
+- **FRAME** (before code) — turn the imperative ask into a falsifiable success criterion
+  and the command that proves it. *"Give it success criteria and watch it go."*
+- **AUDIT** (after the change) — read the diff against the four failure modes; route each
+  finding to the DevRites cure that already exists for it.
+
+It is a self-applied lens, not a subagent and not a phase. Light enough to run at the top
+of a one-line fix; the heavy guns (`devrites-doubt`, `devrites-audit`, the seal) stay where
+they are.
+
+## When to use
+At the top of `$rite-quick` · before a plain "just do X" / "quick fix" / "tiny tweak" edit
+that won't go through the lifecycle · to self-review a raw `git diff` before you commit ·
+any time you're about to act on an imperative without a written success criterion.
+
+**When not:** a real feature (use `$rite-spec`) · a single high-stakes decision that wants
+an adversarial second read (`devrites-doubt`) · a fresh-context axis review of an active
+feature (`devrites-audit <security|perf|simplify>`) · the final GO/NO-GO (`$rite-seal`).
+rite-frame is the *inline* reflex; those are the *gates*. Don't use it to dodge one.
+
+## FRAME — before you touch code
+
+Restate the ask as a check, not a chore. Convert the verb into a condition that can be
+**false**:
+
+| Imperative ask | Falsifiable success criterion |
+|---|---|
+| "Add validation" | "Inputs `{empty, oversize, wrong-type}` are rejected with a 4xx + message — a test asserts each, and fails today." |
+| "Fix the bug" | "A test reproduces the bug (red now), and turns green after the fix — nothing else changes." |
+| "Make it faster" | "Operation X drops from `<measured baseline>` to `<target>` on `<named benchmark>`." |
+| "Refactor X" | "The existing suite is green before and after; behavior is byte-identical." |
+| "Clean this up" | *(no falsifiable criterion → the ask is ambiguous → mode 1 → ask what "clean" means, or route to `$rite-spec`)* |
+
+Checklist (copy it):
+
+- [ ] **Criterion** — one sentence: *"Done WHEN `<observable, falsifiable check>`."* If you
+      can't write one that could be false, the ask is ambiguous — **stop, name it, ask** (that
+      is failure mode 1, surfaced early instead of after the diff).
+- [ ] **Verify command** — the exact test / build / runtime / screenshot that decides it.
+      No command → no proof → you're about to confidence-assert. Name it now.
+- [ ] **Scope boundary** — the files/areas you will **not** touch. Anything outside is mode 3.
+- [ ] **Loop** — with a falsifiable criterion you can iterate to green unattended; with a weak
+      one ("make it work") you'll need the user every few minutes. Sharpen the criterion until
+      it can drive the loop.
+
+## AUDIT — after the change
+
+Read the diff (or `$ARGUMENTS`) against the four modes. One line per finding, severity-tagged
+(`Critical / Important / Suggestion / Nit / FYI`), each routed to its existing cure. Full
+map + worked examples: [`reference/failure-modes.md`](reference/failure-modes.md).
+
+- [ ] **1 · Silent assumption** — did I pick one reading of an ambiguous ask and run with it?
+      Any value, contract, or behavior I *guessed*? → surface it; route material ones through
+      the Spec Drift Guard (`core.md` #2/#3).
+- [ ] **2 · Overcomplication** — an abstraction / flag / indirection nobody asked for? 200 lines
+      where 50 would do? A defensive check inside trusted code? → apply the **deletion test**;
+      simplify (`coding-style.md`, `patterns.md`, `devrites-audit simplify`).
+- [ ] **3 · Out-of-scope edit** — did I touch code, comments, or formatting outside the ask?
+      "While I'm here" refactors? → revert to the boundary; record the rest as an FYI follow-up
+      (`core.md` #7, `touched-files.md`).
+- [ ] **4 · Unverifiable goal** — is there a command that proves this, run, with output? Or am
+      I asserting "it works"? Tautological test that can't fail? → run the FRAME verify command;
+      record command + output (`testing.md`, evidence-over-confidence).
+- [ ] **Principle check** — if `.devrites/principles.md` exists, does the change break a declared
+      invariant? A violation with no recorded, human-approved exception is a **Critical** — the
+      express lane is not a way around a project gate; escalate it, don't ship it (`principles.md`).
+
+The test for each changed line: **it traces directly to the criterion, and the criterion can
+be proven false.** A line that fails either is a finding.
+
+## Escalation
+
+If FRAME can't produce a falsifiable criterion, or AUDIT surfaces a mode-1 / mode-3 issue that
+is actually a hidden design decision (new dependency, data model, second design system, an
+auth/migration/public-API touch), or a **declared-principle violation** with no recorded
+exception → **STOP and route to `$rite-spec`** (a needed exception is a human-approved decision,
+not an inline call). Same drift guard the express lane enforces — don't quietly grow an unframed
+ask into unreviewed work.
+
+## Rules
+- Self-applied and inline. No subagent, no `.devrites/` workspace required. For an adversarial
+  fresh-context read of one decision use `devrites-doubt`; for a fresh-context axis audit of an
+  active feature use `devrites-audit`.
+- FRAME before code, AUDIT after. Running AUDIT without having framed the criterion first means
+  mode 4 has nothing to check against.
+- A criterion that can't be false isn't a criterion — it's a wish. Rewrite it or ask.
+- Feature/ask scope only. Out-of-scope findings become FYI follow-ups, never silent fixes.
+
+## Output
+Reply-contract exception: ad-hoc utility. It may run outside a DevRites workspace, so
+it skips `devrites-engine progress`, but it follows the compact reply principles in
+[`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md).
+
+```
+Done: frame complete for <task>; criterion and boundary are explicit.
+Changed: workspace only
+Evidence: verify command <cmd | not run yet>; audit findings <none|n>
+Open: <none | assumptions | escalation reason>
+Next: <single recommended command>
+Record: <.devrites/work/<slug>/decisions.md | not applicable>
+↻ Hygiene: /clear if no workspace; otherwise follow the active phase hygiene
+```
+
+If it routes to `$rite-spec`, that phase owns the durable workspace from there.

package/pack/generated/codex/skills/rite-frame/reference/failure-modes.md

@@ -0,0 +1,68 @@
+# The four failure modes — mapped to their DevRites cure
+
+The lens behind `rite-frame`. Each mode is a thing LLMs reliably get wrong; each already
+has a cure somewhere in the pack. The value of naming them here is a **portable
+vocabulary** — a fast self-check you can run on ad-hoc or express-lane work that never
+reaches the gates where those cures normally fire.
+
+## The map
+
+| # | Failure mode | The tell in a diff / a reply | Cure already in the pack |
+|---|---|---|---|
+| 1 | **Silent assumption** | A value, contract, edge case, or interpretation was *guessed* and run with — no note, no question. The ask had two readings and one was picked silently. | `core.md` #2 (no silent assumptions) / #3 (no guessing through confusion); the Spec Drift Guard; `devrites-doubt` for a single high-stakes call; `devrites-interview` when the ask is underspecified. |
+| 2 | **Overcomplication** | An abstraction, flag, config knob, or indirection nobody asked for. 200 lines where 50 would do. A single-use factory. Defensive `try/catch` + null checks inside trusted code. A dependency added where an in-repo option exists. | `coding-style.md` (simplicity, reuse-first), `patterns.md` (avoid over-engineering), `devrites-audit simplify` (deletion test, Chesterton's Fence), the "over-defensive guarding is slop" anti-pattern. |
+| 3 | **Out-of-scope edit** | Touched code, comments, or formatting outside the ask. A "while I'm here" refactor. Renamed something orthogonal. Reflowed an import block. | `core.md` #7 (feature scope only), `touched-files.md` (the recorded diff boundary), `devrites-engine reconcile` (hard-stops a source file changed outside the claimed set), the "it's only a small refactor" anti-pattern. |
+| 4 | **Unverifiable goal** | "It works" with no command, no output, no test. A success criterion that can't be false ("make it better"). A tautological test that passes no matter what. | `rite-spec/reference/acceptance-criteria.md` (measurable acceptance), `core.md` #6 (evidence over confidence), `testing.md` (assertion strength, see it fail first), the TDD wright. |
+
+The first three are the **diseases** Karpathy named; the fourth is the **leverage** — a
+falsifiable criterion is what lets the model loop to done without a human in the loop every
+few minutes. FRAME front-loads mode 4 so the AUDIT of modes 1–3 has something to check
+against.
+
+## FRAME: the imperative → falsifiable reframe
+
+The move is to rewrite the *verb* as a *condition that can be false*. If you can't, the ask
+is ambiguous — that's mode 1, caught before the diff instead of after.
+
+| Imperative ask | Weak (still a wish) | Falsifiable criterion + verify |
+|---|---|---|
+| "Add validation" | "validate the inputs" | "`{empty, oversize, wrong-type}` → 4xx + message; a test asserts each and is red today." → `npm test path/to.spec` |
+| "Fix the bug" | "make the bug go away" | "Test reproducing the report is red now, green after, nothing else changes." → the repro test |
+| "Make it faster" | "improve performance" | "Endpoint X p95 `<baseline ms>` → `<target ms>` on `<named bench>`." → the benchmark cmd |
+| "Refactor X" | "clean up X" | "Existing suite green before and after; behavior byte-identical." → full suite, twice |
+| "Handle errors" | "add error handling" | "On `<failure F>` the system fails closed with `<observable>`; a test forces F." → that test |
+| "Improve the UX" | "make it nicer" | *(no falsifiable check → ambiguous → `devrites-ux-shape` / ask which states/flows)* |
+
+A criterion passes the bar when a reviewer could run the verify command and get a clear
+pass or fail without asking you what you meant. If they'd have to ask, sharpen it.
+
+## AUDIT: worked finding lines
+
+Findings read like the rest of the pack — one line, severity-tagged, cite `file:line`, route
+to the cure. Severity ladder is the pack standard (`Critical / Important / Suggestion / Nit /
+FYI`).
+
+```
+auth.ts:42  Important  mode 1 (assumption): assumes `role` is always present — unset on legacy rows. → validate at boundary or ask (core #2).
+cart.ts:88  Suggestion mode 2 (overcomplication): single-use `StrategyFactory` for one caller. → inline; deletion test fails it (devrites-audit simplify).
+utils.ts:5  FYI        mode 3 (scope): reflowed an unrelated import block. → revert to boundary; not in this ask (core #7).
+sum.spec:12 Important  mode 4 (unverifiable): test asserts `mock.called`, not the result — passes if the fn is empty. → assert the value; see it fail first (testing.md).
+```
+
+Clean lanes say so explicitly — `1 assumption: clean` — so the audit is a positive
+statement, not a silent skip.
+
+## How this differs from the heavier tools (so you don't reach past it)
+
+- **`devrites-doubt`** — adversarial *fresh-context subagent* pre-mortem on **one** decision.
+  Heavier, independent, anti-anchoring. rite-frame is *self-applied* and covers the four modes
+  broadly; escalate a single load-bearing claim to doubt.
+- **`devrites-audit <axis>`** — *fresh-context subagent* review of an **active feature's** diff
+  on one axis (security / perf / simplify). Needs a `.devrites/` workspace. rite-frame needs no
+  workspace and runs in your own context — cheaper, less independent.
+- **`$rite-review` · `$rite-seal`** — the **gates**: parallel reviewer fan-out, blocking
+  severities, written verdict. rite-frame is the inline reflex for work that never reaches a
+  gate; it does not replace one. If the work is a real feature, the gate is the answer.
+
+The point is not redundancy — it's a tiered ladder. rite-frame is the cheapest rung: a lens
+you run yourself in seconds. Climb to doubt / audit / the gates as the stakes rise.

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

@@ -0,0 +1,109 @@
+---
+name: rite-handoff
+description: User-invoked handoff writer: sync chat-only context into `.devrites/` and write a fresh-agent handoff.
+user-invocable: true
+disable-model-invocation: true
+argument-hint: "[what the next session will focus on]"
+---
+
+## 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-handoff — chat-only context, into a fresh-agent doc
+
+DevRites' workspace `.devrites/work/<slug>/` already captures everything that *should*
+persist (spec, plan, tasks, decisions, evidence, drift, review). This skill captures
+what the **chat** is holding that is **not** in the workspace, so a fresh agent — or
+the same user after `/clear` — can pick the work up without re-reading the transcript.
+
+Read `.agents/skills/devrites-lib/reference/standards/core.md` first — its "Persistence before stopping" discipline is
+exactly what this skill executes. The other rule files load on demand.
+
+Then run `devrites-engine preamble` for deterministic workspace orientation.
+
+## Where to write
+
+- **Active feature exists** → `.devrites/work/<slug>/handoff.md` (overwrites the previous
+  handoff; the workspace is the canonical home for this slug).
+- **No active feature** → OS temp dir (`$TMPDIR` / `/tmp` / `%TEMP%`) as
+  `rite-handoff-<ISO-timestamp>.md`. Print the absolute path after writing.
+
+## Before you write — sync, don't duplicate
+
+For each of these, write the content into its **canonical home** first, then merely
+*note* in the handoff that the sync happened:
+
+- **Open mid-flight question** → append to `questions.md` (with best-guess attached if
+  possible).
+- **Decision discussed but not yet recorded** → append to `decisions.md` with the *why*,
+  not just the *what*.
+- **Assumption** about behaviour / API / user intent → append to `assumptions.md`.
+- **Drift event raised but not fully resolved** → update `drift.md` with the current
+  resolution status (open / asked-user / repaired).
+- **Files modified in chat not yet in `touched-files.md`** → append to
+  `touched-files.md`.
+
+The handoff doc itself then says "synced N entries into decisions.md", not the entries
+themselves. The workspace is the canonical store; the handoff is the chat-only delta.
+
+## What to include in the handoff
+
+1. **Suggested next action.** ONE command, not three options. If the active feature is
+   mid-phase, name the next `rite-*` command. If a question blocks progress, point at
+   it. If the user passed `[what the next session will focus on]`, tailor this section
+   to the named focus. Where you were mid-thought, **quote the most recent next-step
+   verbatim** from the chat (the exact sentence describing what to do next) so no nuance
+   is lost to paraphrase.
+2. **What just happened in this chat** (3–5 bullets). Distil — do not transcribe.
+3. **External references** that exist only in chat: URLs, Figma links, screenshot paths,
+   video timestamps the user pasted. List as references; do not embed.
+4. **Live assumptions the agent is acting on** that the workspace doesn't reflect yet
+   (after the sync above, this section should be near-empty — flag anything that
+   remains).
+5. **How to resume** — fixed boilerplate (see template below).
+
+## What NOT to include
+
+- Anything already in `spec.md`, `plan.md`, `tasks.md`, `state.md`, `decisions.md`,
+  `evidence.md`, `review.md` — link by path instead.
+- `git diff` output — the next agent runs `git diff` themselves.
+- The full conversation transcript — distil.
+- Secrets (API keys, tokens, PII, credentials). Redact aggressively.
+- **New ideas the user didn't confirm.** A handoff records what *happened* and what's *next*.
+  Leave out fresh suggestions, scope the user didn't agree to, and redesigns you thought of. Capture
+  the state, not your opinions about it.
+
+## Output template
+
+Loaded on demand from [`reference/handoff-template.md`](reference/handoff-template.md).
+Fill in each section and write to `.devrites/work/<slug>/handoff.md` (or to a temp
+file when no active feature). Then use the compact reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)):
+
+```
+Done: handoff written for <slug | session>.
+Changed: handoff.md plus synced workspace artifacts <n>
+Evidence: not applicable; chat-only context persisted
+Open: <none | unsynced caveats>
+Next: <single resume command>
+Record: <absolute path to handoff.md>
+↻ Hygiene: /clear
+```
+
+Print the absolute path in `Record:` so the user or next agent can open it without searching.
+
+## Session hygiene
+Close with the one-line hygiene advisory + the single resume command — this skill *is* the
+pre-`/clear` bridge, so it's where the advisory matters most (`context-hygiene.md`):
+```
+↻ Hygiene: /clear
+```

package/pack/generated/codex/skills/rite-handoff/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,44 @@
+# Handoff doc template
+
+Loaded on demand by `$rite-handoff`. Write the filled-in template to
+`.devrites/work/<slug>/handoff.md` (or to a `$TMPDIR` file when no active feature).
+
+```
+# Handoff — <feature slug | "no active feature"> — <ISO date>
+
+## Resume
+Current objective: <one sentence>
+Last completed slice: <SLICE-### | none>
+Blockers: <none | Q-### / DRIFT-###>
+
+## Read next
+1. `.devrites/work/<slug>/README.md` — workspace map.
+2. `.devrites/work/<slug>/state.md` — current cursor.
+3. `.devrites/work/<slug>/traceability.md` — acceptance coverage.
+4. <phase-specific source artifact; link, do not duplicate>.
+
+## Next action
+<one command or action, no option set>
+
+## What changed this turn
+- <short event; link to source artifact instead of copying full content>
+
+## External references (chat-only)
+- <URL / Figma / screenshot path / video timestamp>
+
+## Live assumptions (not yet in assumptions.md)
+- ...   (this section should be near-empty after the sync step)
+
+## Synced this turn
+- decisions.md: <N entries appended>
+- questions.md: <N appended>
+- assumptions.md: <N appended>
+- drift.md: <updated? yes/no>
+- touched-files.md: <N appended>
+
+## How to resume
+1. Read this file.
+2. Read `.devrites/work/<slug>/state.md` for the workspace cursor.
+3. Run `$rite-status` for the current phase / next action / open drift.
+4. Continue with the `Next action` above.
+```

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

@@ -0,0 +1,129 @@
+---
+name: rite-learn
+description: User-invoked review of the learning ledger; promotes recurring lessons to project rules or principles.
+argument-hint: "[--mine | \"<lesson to record>\"]"
+user-invocable: true
+disable-model-invocation: 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-learn — the cross-feature learning loop
+
+Recurring corrections, dismissed review findings, timeline decisions, and health dips are durable
+signal. **Capture is automatic** — `$rite-seal` appends lessons to `.devrites/learnings.md` on every
+GO (step 9a), while the engine can keep `.devrites/timeline.jsonl`,
+`.devrites/health-history.jsonl`, and per-feature review fingerprints as supporting evidence. The
+review skills load the learning ledger **before** a fan-out, so a dismissed-finding class stops
+being re-flagged without anyone running a command. The system learns as it ships.
+
+`$rite-learn` is the periodic **review + promote** pass on that auto-populated ledger: cluster the
+signal across features and decide which recurring lessons graduate into a project rule. **Propose,
+never impose** — promotion is the human's call, which is why it stays a deliberate command rather
+than firing on its own.
+
+Read-mostly. It reads the auto-populated ledger + the archive; it writes only `.devrites/learnings.md`
+(consolidation, via `devrites-engine learnings`) and drafts proposed rule/ledger edits for the user to confirm —
+it never edits source or rule files on its own.
+
+## Modes
+
+- `$rite-learn` or `$rite-learn --mine` — **mine + propose** (the default).
+- `$rite-learn "<lesson>"` — **record one lesson** directly to the ledger and stop.
+
+## Workflow (mine + propose)
+
+1. **Gather the signal.** Start from the **auto-populated ledger** `.devrites/learnings.md` (seal
+   appends to it on every GO — step 9a), then run `devrites-engine learnings mine` over the archive (it clusters
+   repeated finding / decision / drift phrases across shipped
+   features) to surface cross-feature patterns the per-feature entries don't show on their own:
+   ```bash
+   devrites-engine learnings mine
+   ```
+   Use `.devrites/timeline.jsonl`, `.devrites/health-history.jsonl`, and
+   `.devrites/work/*/review-fingerprints.jsonl` as supporting evidence when they exist; do not
+   promote from those traces without the same repeated-feature threshold.
+2. **Cluster + name.** Group the recurring corrections into candidate lessons. A candidate needs
+   **≥2 occurrences across distinct features** — one-offs are noise, not a pattern. Name the
+   pattern in one specific sentence (the specificity rule from `prose-style.md` applies: a lesson
+   you could swap onto any project says nothing).
+   **Completion:** every candidate cites two distinct features, except a single deliberate
+   rejected direction with its durable reason.
+3. **Classify each candidate** into its durable home:
+   - **project rule** — a craft/standard that belongs in a `.agents/skills/devrites-lib/reference/standards/*` file or `CLAUDE.md`.
+   - **project principle** — a recurring correction that is really a *non-negotiable invariant*
+     (not just an idiom or a craft standard): graduate it to `.devrites/principles.md`
+     ([`principles.md`](../devrites-lib/reference/standards/principles.md)). This is the **trusted, gating** layer — higher
+     stakes than a rule — so `$rite-learn` **drafts** the principle + a dated Governance entry for
+     the human to confirm; it never writes a principle silently.
+   - **conventions-ledger entry** — a proven project idiom for `.devrites/conventions.md`.
+   - **dismissed-finding class** — a pattern reviewers keep flagging that is *intentional here*;
+     recording it stops the recurring false positive (`learnings.md`, loaded pre-fan-out).
+   - **rejected direction** — an approach or product direction weighed and ruled out with a
+     reason that outlives one feature; recording it (tag `rejected-direction`) stops ideation
+     skills (`$rite-pressure-test`, `$rite-pov`) from re-proposing it. Exempt from the
+     ≥2-occurrence rule — one deliberate rejection is the whole pattern.
+   - **drop** — not durable; let it go.
+4. **Propose, don't impose.** Present the candidates with their evidence (which features, how many
+   times, the proposed home) via `AskUserQuestion` — the human picks which to promote. Never
+   promote a lesson to a rule silently; an unproven "lesson" hardened into a rule is its own slop.
+   **Completion:** every candidate is explicitly accepted, rejected, or deferred by the human.
+5. **Record the accepted.** For each the user accepts, append it with `devrites-engine learnings add <slug>
+   "<lesson>" <tag>` (`tag` ∈ `rule | convention | dismiss`). If the user approves a **rule**,
+   **principle**, or **ledger** promotion, draft the exact edit and let the user confirm it through
+   the normal flow — `$rite-learn` writes the ledger, not the rule or principle files. A
+   **principle** promotion is the highest-stakes of these: draft the `.devrites/principles.md` entry
+   **plus its dated Governance line**, and let the human confirm before it lands — a principle is a
+   gate, so it is amended deliberately, never auto-written. **Amendment ripple:** a confirmed
+   add/change/retire of a principle has a blast radius — grep its `P#` (and its key nouns) across
+   `.devrites/` and every open `.devrites/work/*/` workspace, and append to the same dated
+   Governance entry one line per referencing artifact: *still-aligned* or *needs-follow-up (what)*.
+   An open plan that bakes in the now-retired or now-tightened invariant is a `needs-follow-up`
+   the next `$rite-vet` or `$rite-plan repair` on that feature must clear; a ripple with zero
+   references is itself worth recording ("no live references"). Then `touch .devrites/.learnings-reviewed`
+   so the SessionStart learnings nudge snoozes until new signal accumulates.
+
+## How the ledger is used
+
+The review skills (`$rite-review`, `$rite-seal`) read `.devrites/learnings.md` before they fan
+out: a **dismissed-finding class** suppresses the recurring false positive; a **proven
+convention** raises the bar. The ideation skills (`$rite-pressure-test`, `$rite-pov`) read the
+**rejected-direction** entries before proposing, so a ruled-out direction returns only with new
+evidence against its recorded why. The ledger is an **untrusted prior** — a fresh observation of the
+live code always overrides a ledger entry (see `.agents/skills/devrites-lib/reference/standards/security.md`). Confidence in a
+recorded lesson never raises its authority.
+
+A **project principle** (`.devrites/principles.md`) is the opposite layer — prescriptive,
+trusted, and **gating**. Promoting a lesson there is a deliberate amendment, not a prior the next
+fan-out can override: a violation becomes a blocking finding, not a suppressed false positive.
+That asymmetry is why principle promotion is human-confirmed and dated, never auto-written.
+
+## Gotchas
+- Evidence first: a lesson without ≥2 real occurrences is speculation. Cite the features.
+- Don't pad the ledger. Five real lessons that change behaviour beat thirty rubber-stamped rows.
+- The ledger records *what was learned*; it does not re-open shipped features or edit their archives.
+
+## Output
+Reply-contract exception: cross-feature learning utility. It may run without an active
+feature, so it skips `devrites-engine progress`, but follows
+[`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md).
+
+```
+Done: learnings mined from <n> features; <n> recurring patterns found.
+Changed: .devrites/learnings.md <updated|unchanged>; rule/ledger drafts <n|none>
+Evidence: mined archive count <n>; candidates rule <a> / convention <b> / dismiss <c> / dropped <d>
+Open: <none | promotion confirmations>
+Next: <single recommended command>
+Record: .devrites/learnings.md
+↻ Hygiene: /clear; the ledger is on disk
+```

package/pack/generated/codex/skills/rite-learn/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,107 @@
+---
+name: rite-plan
+description: Re-plan existing work when reality invalidates the plan: reslice a slice that is too big, repair drift, reorder dependencies, split boundaries, or unblock work. Not first-pass decomposition.
+argument-hint: "[mode: decompose|reslice|repair|reorder|split|unblock|course-correct|revise]"
+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-plan — (re)plan an active feature
+
+Reshape the plan when reality and the plan disagree. **Read the active workspace
+first.** If `.devrites/ACTIVE` is empty or its workspace is missing, stop and tell the
+user to run `$rite-spec <feature>`. **Revise mode is artifact-only**: reconcile
+`spec.md` / `architecture.md` / `plan.md` / `tasks.md` / `traceability.md` without
+editing source code.
+
+## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
+Pull `development-workflow.md` via `Read` when reshaping slice cadence or DoD criteria.
+
+## Operating rules
+- Spec is living, not sacred — but never plan around a known-wrong assumption silently.
+- If a change alters product behavior, scope, architecture, data model, UX, security,
+  or migration risk → **ask the user first** (use the Spec Drift Guard question format).
+- Keep each slice small enough for one focused build → prove cycle.
+- **Slice count is derived, never dictated** — reslice when a slice fails the sizing rule
+  (multiple "and"s, can't build+prove in one cycle), not to hit a user-named tally. A
+  requested count is a hint at most; slice logically and explain if it differs. See
+  [`reference/slicing.md`](reference/slicing.md) ("How many slices?").
+- **Size by complexity, order by dependency.** A slice carries a `Complexity: N/5` score (from
+  `$rite-define`); a slice scoring **>3** is a reslice trigger unless its inline reason justifies
+  the irreducible complexity. Honor each slice's `depends_on:` — the next *buildable* slice is the
+  lowest pending one whose dependencies are all built (keeps one-slice-at-a-time correct, not parallel).
+
+## Workflow
+0. Read `.agents/skills/devrites-lib/reference/standards/core.md` (operating rules) before reshaping anything.
+   Then run `devrites-engine preamble` for deterministic workspace orientation.
+1. Read `spec.md`, `plan.md`, `tasks.md`, `state.md`, `drift.md`, and the current
+   `git diff` (if a repo). Read `decisions.md` and `assumptions.md`. If a code-intelligence
+   index is available — `codebase-memory-mcp` first, cross-checked with `codegraph`
+   (`.codegraph/` / `codegraph_*` tools) + `graphify` (`graphify-out/`), else standard methods
+   (LSP / `Read`/`Grep`/`Glob`); see `.agents/skills/devrites-lib/reference/standards/tooling.md` —
+   prefer it for structural questions (what calls X, what would
+   changing Y break) over reading whole files, to keep planning context lean. For an external
+   dependency's current API surface, consult context7 if available.
+2. **Pick the mode** (`$ARGUMENTS` or infer):
+   - **decompose** — first/again break the feature into vertical slices.
+   - **reslice** — a slice is too large; split into thinner end-to-end slices.
+   - **repair** — a Spec Drift Guard event; fold the resolution into plan + tasks.
+   - **reorder** — fix the dependency order.
+   - **split** — separate backend/frontend contracts (see `devrites-api-interface`).
+   - **unblock** — a verification failed; re-route around the blocker.
+   - **course-correct** — a deliberate mid-build *pivot* (the user changed their mind), distinct
+     from accidental drift: classify the change, assess its impact across the remaining slices,
+     decide rollback vs forward-fix, and update `spec.md` + `plan.md` + `tasks.md` + `decisions.md`
+     atomically. An acceptance/behavior change still goes through the user first. When the plan
+     names an `MVP cut`, offer it as the retreat option: falling back to the cut is a pre-agreed
+     scope, not a new negotiation.
+   - **revise** — apply a requested planning-artifact revision and reconcile existing artifacts in
+     any direction; propose the file edit set first, confirm each file before writing, and **never
+     edit source code**. **Gate first — revise or new?** Same intent? >50% of existing scope
+     survives? original *not* completable without this? Two "no"s → new work: recommend
+     sealing/shipping the current workspace (MVP cut if named) then `$rite-spec` for the new
+     intent, and stop. Revise preserves context; a new workspace provides clarity.
+   See [replan-and-repair](reference/replan-and-repair.md) for each mode's steps.
+3. Reason about dependencies — [dependency-graph](reference/dependency-graph.md).
+   **Completion:** the slice graph is cycle-free and every dependency names an existing slice.
+4. Re-slice using vertical-slice rules — [slicing](reference/slicing.md) and
+   [task-breakdown](reference/task-breakdown.md). Prefer thin, shippable, verifiable.
+   **Completion:** every slice is independently shippable/provable or carries an irreducibility reason.
+5. Update `plan.md`, `tasks.md`, `state.md`, and append rationale to `decisions.md`.
+   If you stopped for drift, mark the `drift.md` entry resolved.
+6. If product behavior/acceptance criteria change, confirm with the user before writing.
+   **Completion:** the change is classified, and every behavior/acceptance change has explicit
+   confirmation recorded before the artifacts are updated.
+7. **Done when** — every slice is sized (builds + proves in one cycle; no slice scoring >3
+   left unjustified), the dependency order is acyclic, every `drift.md` entry you stopped for
+   is marked resolved, revised artifacts agree with each other, no source files changed in
+   `revise` mode, and behavior-change-vs-not is confirmed (`no`, or asked + answered).
+   If any check fails, loop back — don't hand off a half-reshaped plan.
+
+> **Mid-flight discipline.** When tempted to change product behavior without asking, absorb drift silently, or skip the user — see [`anti-patterns`](reference/anti-patterns.md). Load it the moment you reach for the excuse.
+
+## 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: plan repaired for <slug> in <mode> mode.
+Changed: plan.md, tasks.md, traceability.md, decisions.md, state.md
+Evidence: not applicable; slice map now <n> slices and next slice is <name>
+Open: <none | behavior question answered | Alternative: $rite-prove if all built slices need re-verification>
+Next: <single next command: build, re-define, or prove depending on the revision>
+Record: .devrites/work/<slug>/plan.md
+↻ Hygiene: /clear if the repair was large; keep session for small reorder-only repairs
+```

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

@@ -0,0 +1,24 @@
+# rite-plan — anti-patterns
+
+Load this when standing a non-trivial re-plan decision, or when the agent
+feels reluctance toward asking the user before a behavior change.
+
+Pack-wide rationalizations + red flags: see [standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "User didn't ask for a re-plan." | A Spec Drift Guard event *is* a re-plan trigger — ask is courtesy, the route is automatic. |
+| "I can fix the slice mid-build, no need to update tasks." | `tasks.md` is the contract `$rite-build` reads. A fix that isn't there isn't visible to the next phase. |
+| "Reordering slices is cosmetic." | Dependency order controls risk discovery; risk-first wins because it surfaces blockers early. |
+| "This drift is small enough to absorb silently." | Silent drift = unrecorded decision = future "why does this work?" debugging session. |
+| "I can change product behavior to make the plan fit." | Behavior change always asks the user first, no exceptions. |
+
+## Red Flags
+
+- About to change product behavior, acceptance, or scope without asking the user.
+- `drift.md` entry unresolved while planning the next slice.
+- A "mode" invented that isn't one of `decompose / reslice / repair / reorder / split / unblock`.
+- Slices reordered without updating dependency notes — order changed, rationale didn't.
+- Repairing a drift event by silently widening the spec rather than narrowing the plan.