devrites 2.6.1 → 3.0.1

package/pack/.claude/skills/rite-explain/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: rite-explain
+description: User-invoked explainer that teaches one concept, diff, idea, or recent-work recap with an optional retrieval check-in.
+argument-hint: "[a concept | a diff ref | an idea | \"what did I do this week?\"] — or bare to be asked"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# /rite-explain — the human half of the learning loop
+
+Agent-driven development removed the learning that writing code by hand used to give the
+developer. When the agent writes the code, the human stops absorbing the codebase. `/rite-explain`
+is the replacement: it teaches the developer **one** thing well — a concept, a change, an idea, or
+a window of their own recent work — so they keep learning while the agents do the writing. For a
+specific change, it can instead write a **walkthrough**: a human review guide organized by concern,
+risk stops, and manual observations.
+
+This is the **complement of [`/rite-learn`](../rite-learn/SKILL.md)**, and the two together are
+the whole compounding story. `/rite-learn` teaches the **repo** — it promotes recurring lessons
+into rules and principles the next feature reads. `/rite-explain` teaches the **person** — the
+mental model the next feature needs a human to actually hold. A team that only runs `/rite-learn`
+compounds a codebase whose own maintainers understand it less each week. Run both.
+
+Read-only against source. It reads artifacts and code; it writes exactly one explainer file to
+`.devrites/explainers/` and never edits source, specs, or rules.
+
+## Who the explainer is for
+
+The developer, personally. Dense, technical, one voice — no audience adaptation, no "for
+beginners" softening, no executive summary. It is a display artifact: no embedded quizzes or
+widgets — the check-in (below) happens live in the session, where an answer can actually be
+graded. If the user asked for prep for a meeting or a teammate, it preps **them** to explain the
+thing; it does not produce the deck.
+
+## Model tiers
+
+Dispatch by task shape, per [`devrites-lib/reference/model-tiers.md`](../devrites-lib/reference/model-tiers.md):
+
+- **extraction tier** — the work-recap scout and any repo-profiling: search-and-quote, run under a
+  read budget, write findings to the run's scratch dossier, return only a gist.
+- **ceiling tier** — the explainer composition and the check-in reasoning. These run inline in the
+  orchestrator's own model; nothing is dispatched down. Teaching quality is the whole product — do
+  not cheapen it.
+
+The degradation rule in that file applies: no per-agent model control → run the scout inline under
+the same budget.
+
+## Workflow
+
+### 1. Classify the input — load the intake reference
+
+The four input shapes (concept · diff · idea · work-recap) each ground and compose differently,
+and each drives a different check-in. Diff inputs also branch into explainer vs walkthrough
+composition. Getting the shape wrong wastes the whole artifact.
+
+**Load [`reference/intake.md`](reference/intake.md) now** — it owns the classification rules, the
+`diff:` / `since:` / `output:` token table, the concept-vs-diff tiebreak, and the check-in
+mechanics per shape. Do not improvise classification from this file; the detail lives there so this
+one stays legible, and skipping it means guessing the shape.
+
+**Bare invocation** (no input): ask **one** blocking question (`AskUserQuestion` when the harness
+has it, else the harness's blocking-question tool — `request_user_input` on Codex) — "What should I
+explain?" — offering "a recap of my recent work in this repo" as a shortcut option alongside free
+text. Never emit a default explainer unprompted.
+
+### 2. Ground
+
+Match grounding to the shape (full rules in the intake reference). DevRites gives you grounding for
+free — prefer it over re-deriving:
+
+- A **diff** or **recap** → the workspace and archive: `seal.md`, `evidence.md`, `decisions.md`,
+  `traceability.md`, the shipped `.devrites/archive/<slug>/`, and `git log` / `git diff`.
+- A **concept** with footprint in this repo → the live code (codegraph / graphify first), plus any
+  `.devrites/principles.md` or ADRs that already take a position on it.
+- An **idea** or a concept with no repo footprint → the user's framing plus, only if it sharpens
+  the teaching, current external sources (weight by date; the year is 2026).
+
+Create the run directory before composing so scout dossiers have a home:
+
+```bash
+RUN_DIR=".devrites/explainers/$(date +%Y%m%d)-<slug>"; mkdir -p "$RUN_DIR"
+```
+
+### 3. Compose the explainer
+
+For diff inputs that ask for `walkthrough:<ref>`, "checkpoint", "walk me through", or human review,
+write `$RUN_DIR/walkthrough.md` using the walkthrough composition in `reference/intake.md`, then skip
+the active-recall check-in unless the user asks for teaching too.
+
+Otherwise write one dense artifact at `$RUN_DIR/explainer.md`. It must **teach**, not summarize:
+
+1. **One thing.** A single clear takeaway named in the first two lines. If the input sprawls,
+   teach the highest-leverage slice and say what you cut.
+   **Completion:** the first two lines state one takeaway and any deferred topics.
+2. **Build the model, don't list facts.** Start from what the developer already knows in *this*
+   codebase and move to the new thing. Concrete before abstract — a real symbol, file, or line
+   from the grounding beats a generic example every time.
+   **Completion:** the explanation connects a known project anchor to the new model without a fact dump.
+3. **Show the load-bearing detail.** Quote the actual diff hunk, the real function, the specific
+   config — with `file:line` pointers so the developer can go read it.
+4. **Visual where it earns it.** A small diagram, a before/after, or a worked trace when the shape
+   is spatial or sequential. Not decoration — only when it carries the idea faster than prose.
+   **Completion:** the visual carries a named relationship faster than prose, or this branch is explicitly skipped.
+5. **Human voice.** Follow [`prose-style.md`](../devrites-lib/reference/standards/prose-style.md):
+   no throat-clearing, no false-binary contrast, no marketing adjectives. One senior engineer
+   explaining to another.
+
+### 4. Offer the check-in (optional, active recall)
+
+Retention comes from *retrieving*, not re-reading. After the explainer, offer one check-in via the
+harness's blocking-question tool (`AskUserQuestion`, or `request_user_input` on Codex) — the user
+answers **first**, then you confirm or correct. The shape sets the
+form (mechanics in the intake reference):
+
+- **diff / recap** → **predict-then-reveal**: ask what a specific hunk changes or why a decision
+  was made *before* showing the reveal.
+- **concept / idea** → a **checked exercise**: one small problem the developer solves, then you
+  grade it against the model you just taught.
+
+Skippable when the material does not warrant retention work (a one-off, or the user declines). Do
+not force it; offer once.
+
+## Gotchas
+
+- **Teach one thing.** An explainer that covers five things teaches none. Cut ruthlessly; queue the
+  rest as "next time".
+- **Ground it or don't claim it.** A concept explainer with no `file:line` or real example is a
+  Wikipedia paragraph. If it has footprint in this repo, quote the repo.
+- **Not a review.** `/rite-explain` never judges the code or files findings — that is `/rite-review`.
+  It explains what *is*, adversarially neutral.
+- **Not `/rite-learn`.** It writes to `.devrites/explainers/`, never to `learnings.md`,
+  `principles.md`, or any rule file. Teaching the human is not promoting a repo rule.
+
+## Output
+
+Reply-contract exception: cross-feature learning utility; may run with no active feature, so it
+skips `devrites-engine progress` when no workspace exists. Otherwise follows
+[`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md).
+
+```
+Done: explained <the one thing> as a <concept|diff|idea|recap> explainer OR walked through <change> for human review.
+Changed: .devrites/explainers/<date>-<slug>/<explainer.md|walkthrough.md>
+Evidence: grounded in <artifacts/files quoted>; check-in <offered+result | skipped>; walkthrough stops <count>
+Open: <none | next-time topics deferred | check-in awaiting the user>
+Next: <single command — usually back to the calling phase, or /rite-learn if a repo rule surfaced>
+Record: .devrites/explainers/<date>-<slug>/explainer.md
+↻ Hygiene: /clear after reading; the explainer is on disk
+```

package/pack/.claude/skills/rite-explain/reference/intake.md

@@ -0,0 +1,79 @@
+# rite-explain intake — classify the input, then ground and check-in by shape
+
+Owned by `/rite-explain`. Loaded at Phase 1 because the four input shapes ground, compose, and
+check-in differently, and this detail would bloat the SKILL if inlined. This file is the single
+source for classification; the SKILL improvises none of it.
+
+## The four shapes
+
+| Shape | The input is… | Grounds in | Composes as | Check-in |
+|---|---|---|---|---|
+| **concept** | a named idea / pattern / technology ("explain optimistic locking", "how does our gate engine work") | this repo's footprint of the concept (codegraph first) + external sources only if they sharpen it | build the mental model from a known part of *this* codebase outward | **checked exercise** |
+| **diff** | a specific change — a ref, a slice, a PR, "this diff" | `git diff` / the hunks + `decisions.md` + `seal.md` for the *why* + `touched-files.md` `Review trail` when present | explainer, or **walkthrough** when the user asks to review/approve/checkpoint the change | **predict-then-reveal** |
+| **idea** | a hypothesis or "what if" with no code yet | the user's framing + prior art (external, date-weighted; year is 2026) | steelman the idea, name its hinge and its failure mode | **checked exercise** |
+| **recap** | a time window of the user's own work ("what did I ship this week") | the shipped archive + `git log`/`git diff` over the window + `evidence.md` | narrate what changed and what was learned, ranked by leverage | **predict-then-reveal** |
+
+## Token overrides — explicit beats inferred
+
+If the user's input carries any of these tokens, they **override** shape inference:
+
+| Token | Meaning |
+|---|---|
+| `diff:<ref>` | force the **diff** shape against `<ref>` (a commit, range, or slug) |
+| `walkthrough:<ref>` | force the **diff** shape and compose a human review walkthrough instead of a teaching explainer |
+| `since:<when>` | force the **recap** shape over the window (`since:1w`, `since:last-ship`, an ISO date) |
+| `output:<path>` | write the explainer to `<path>` instead of the default `.devrites/explainers/<date>-<slug>/` |
+
+No token → infer the shape from the phrasing and the referenced object. If the phrasing says
+"walk me through", "checkpoint", "human review", "help me approve", or "review this change",
+use the diff shape with walkthrough composition.
+
+## Tiebreaks
+
+- **concept vs diff** — if the input names both a concept *and* a specific change ("explain how
+  this diff does optimistic locking"), it is a **diff** explainer that teaches the concept through
+  the change. Ground in the diff; use the concept as the model to build.
+- **idea vs concept** — if the thing exists in the codebase or the wider world already, it is a
+  **concept** (teach what is). If it is a proposal not yet built, it is an **idea** (teach whether
+  it holds).
+- **conflict** — a token and the prose disagree (`diff:` set but the text asks to explain a
+  concept) → the token wins for shape; honor the prose for emphasis. State the resolution in one
+  line at the top of the explainer.
+
+## Check-in mechanics
+
+Retention comes from retrieval. Offer exactly one check-in via the harness's blocking-question tool
+(`AskUserQuestion`, or `request_user_input` on Codex); the user answers **before** any reveal. Grade honestly — a wrong prediction that gets corrected teaches more than a
+confirmed one, so do not lead the witness.
+
+## Walkthrough composition (diff only)
+
+A walkthrough is for human review, not retention. Write it under the normal run directory as
+`walkthrough.md` and include:
+
+1. **Intent** — one sentence naming what the change is for, grounded in `spec.md` / `decisions.md` when available.
+2. **Scope** — files changed, modules touched, and boundary crossings.
+3. **Concern walkthrough** — group `path:line` stops by design intent, not file order. Prefer the existing `touched-files.md` `Review trail`; generate one from the diff only when absent.
+4. **Risk stops** — 2–5 highest-blast-radius places to inspect, tagged `[auth]`, `[data]`, `[schema]`, `[public API]`, `[migration]`, `[ui]`, `[perf]`, or `[test]` where relevant.
+5. **Manual observations** — 2–5 concrete ways a human can observe the change working. If there is no user-visible behavior, say so and name the automated evidence instead.
+6. **Decision options** — approve / rework / ask for a targeted review, each with the next command.
+
+Completion criterion: every concern has at least one clickable repo-relative `path:line` stop, or the walkthrough states why the change has no source stops.
+
+### Predict-then-reveal (diff / recap)
+
+1. Pick the single most load-bearing hunk or decision in the explainer.
+2. Ask the user to predict: "what does this change do?" / "why was `<decision>` made here?" —
+   offer 2–4 plausible options where one is the real answer and the distractors are *reasonable*
+   (a distractor no one would pick teaches nothing).
+3. On answer, reveal: confirm or correct, pointing at the exact `file:line` that settles it.
+
+### Checked exercise (concept / idea)
+
+1. Pose one small problem the developer solves using the model just taught — "given `<situation>`,
+   what would `<mechanism>` do?" or "where would this break?".
+2. Let them answer, then grade against the taught model: name what they got right, correct what
+   they missed, and cite the part of the explainer (or the repo) that covers it.
+
+Skip the check-in entirely when the material is a genuine one-off with nothing worth retaining, or
+the user declines. Offer once; never nag.

package/pack/.claude/skills/rite-frame/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rite-frame
-description: Frame an ad-hoc ask into a falsifiable success criterion before coding, then audit the diff against the four classic LLM failure modes — silent assumption, overcomplication, out-of-scope edit, unverifiable goal. Use to reframe an underspecified imperative ask, to self-audit a raw diff, or at the top of `/rite-quick`. Not a replacement for the lifecycle gates (`/rite-seal`, `/rite-review`), the adversarial pre-mortem (`devrites-doubt`), or the fresh-context axis audit (`devrites-audit`) — it is the lightweight inline reflex for work that skips those.
+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
 ---
@@ -10,7 +10,7 @@ user-invocable: true
 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` + `reconcile.sh`, `/rite-seal`). But the express lane and plain
+`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:
@@ -103,19 +103,18 @@ ask into unreviewed work.
 - 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).
+
 ```
-FRAME
-  Criterion: Done WHEN <falsifiable check>.
-  Verify:    <exact command / observation>
-  Boundary:  <files/areas NOT touched>
-
-AUDIT (post-change)
-  1 assumption    : <clean | finding → cure>
-  2 simplicity    : <clean | finding → cure>
-  3 scope         : <clean | finding → cure>
-  4 verifiable    : <command → result, or finding>
-Verdict: framed & clean  |  N findings (acted | escalated to /rite-spec)
+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
 ```
 
-↻ Hygiene: rite-frame adds no workspace state — nothing to persist. If it routed you to
-`/rite-spec`, that phase owns the handoff from here.
+If it routes to `/rite-spec`, that phase owns the durable workspace from there.

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

@@ -11,7 +11,7 @@ reaches the gates where those cures normally fire.
 |---|---|---|---|
 | 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), `reconcile.sh` (hard-stops a source file changed outside the claimed set), the "it's only a small refactor" 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

package/pack/.claude/skills/rite-handoff/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: rite-handoff
-description: Compact the current chat into a handoff doc a fresh agent can pick up cold — syncs chat-only context into the canonical `.devrites/` files, references artifacts by path. Use when the user says "handoff", "prep for tomorrow", or "summarize for the next agent". Not for routine `/clear` between phases.
+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]"
 ---
 
@@ -12,18 +13,10 @@ persist (spec, plan, tasks, decisions, evidence, drift, review). This skill capt
 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 `.claude/rules/core.md` first — its "Persistence before stopping" discipline is
+Read `.claude/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 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
-P=.claude/skills/devrites-lib/scripts/preamble.sh
-[ -f "$P" ] || P="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/preamble.sh"
-[ -f "$P" ] || P=pack/.claude/skills/devrites-lib/scripts/preamble.sh
-[ -f "$P" ] && bash "$P" || echo "(orientation preamble unavailable on this install — read state.md directly to orient)"
-```
+Then run `devrites-engine preamble` for deterministic workspace orientation.
 
 ## Where to write
 
@@ -80,16 +73,25 @@ themselves. The workspace is the canonical store; the handoff is the chat-only d
 ## Output template
 
 Loaded on demand from [`reference/handoff-template.md`](reference/handoff-template.md).
-Fill in each section + write to `.devrites/work/<slug>/handoff.md` (or to a temp file
-when no active feature).
+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
+```
 
-After writing, **print the absolute path** of the handoff file so the user (or the next
-agent) can open it without searching.
+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 — handoff written; all chat-only context is now on disk, safe to /clear
-or close the session. Resume next session with: <the single next command from state.md>
+↻ Hygiene: /clear
 ```

package/pack/.claude/skills/rite-handoff/reference/handoff-template.md

@@ -6,12 +6,22 @@ Loaded on demand by `/rite-handoff`. Write the filled-in template to
 ```
 # Handoff — <feature slug | "no active feature"> — <ISO date>
 
-## Suggested next action
-<one command, no options>
+## Resume
+Current objective: <one sentence>
+Last completed slice: <SLICE-### | none>
+Blockers: <none | Q-### / DRIFT-###>
 
-## What just happened (this chat)
-- ...
-- ...
+## 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>
@@ -30,5 +40,5 @@ Loaded on demand by `/rite-handoff`. Write the filled-in template to
 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 suggested next action above.
+4. Continue with the `Next action` above.
 ```

package/pack/.claude/skills/rite-learn/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rite-learn
-description: Review the auto-captured learning ledger and promote recurring lessons to project rules or principles — the human-gated half of the cross-feature learning loop. Not for the install (`/rite-doctor`), feature status (`/rite-status`), onboarding (`/rite-adopt`), or a diff review (`/rite-review`).
+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
@@ -8,10 +8,12 @@ disable-model-invocation: true
 
 # /rite-learn — the cross-feature learning loop
 
-Recurring corrections, dismissed review findings, and dead-ends are durable signal. **Capture is
-automatic** — `/rite-seal` appends them to `.devrites/learnings.md` on every GO (step 9a), and the
-review skills load that 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.
+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,
@@ -19,7 +21,7 @@ never impose** — promotion is the human's call, which is why it stays a delibe
 than firing on its own.
 
 Read-mostly. It reads the auto-populated ledger + the archive; it writes only `.devrites/learnings.md`
-(consolidation, via `learnings.sh`) and drafts proposed rule/ledger edits for the user to confirm —
+(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
@@ -30,48 +32,63 @@ it never edits source or rule files on its own.
 ## 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 `learnings.sh mine` over the archive (resolve via
-   the standard 3-path snippet; it clusters repeated finding / decision / drift phrases across shipped
+   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
-   L=.claude/skills/devrites-lib/scripts/learnings.sh
-   [ -f "$L" ] || L="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/learnings.sh"
-   [ -f "$L" ] || L=pack/.claude/skills/devrites-lib/scripts/learnings.sh
-   [ -f "$L" ] && bash "$L" mine || echo "(learnings.sh unavailable — scan .devrites/archive/*/{decisions,drift,review}.md by hand)"
+   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 `.claude/rules/*` file or `CLAUDE.md`.
+   - **project rule** — a craft/standard that belongs in a `.claude/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`](../../rules/principles.md)). This is the **trusted, gating** layer — higher
+     ([`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.
-5. **Record the accepted.** For each the user accepts, append it with `learnings.sh add <slug>
+   **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. Then `touch .devrites/.learnings-reviewed`
+   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 ledger is an **untrusted prior** — a fresh observation of the
-live code always overrides a ledger entry (see `.claude/rules/security.md`). Confidence in a
+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 `.claude/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,
@@ -85,11 +102,16 @@ That asymmetry is why principle promotion is human-confirmed and dated, never au
 - The ledger records *what was learned*; it does not re-open shipped features or edit their archives.
 
 ## Output
-```
-Mined: <n> features · <n> recurring patterns
-Candidates: <n> (rule: a · convention: b · dismiss: c · dropped: d)
-Promoted: <n> → .devrites/learnings.md  (+ <n> rule/ledger edits drafted for your confirm)
+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).
 
-Session hygiene: /clear (recommended) — the ledger is on disk; the proposals are listed above.
-Resume next session with: <the single next command, e.g. the drafted rule edit, or /rite-status>
+```
+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
 ```