devrites 4.0.12 → 4.2.0

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

@@ -7,47 +7,37 @@ user-invocable: true
 
 # $rite-define: plan from the spec
 
-Turn the active feature's `spec.md` into a buildable workspace with architecture, an
-implementation approach, dependency-ordered **vertical slices**, traceability, and a
-state cursor. The spec defines what and why; this phase defines how. Keep spec,
-architecture, plan, tasks, and traceability in their phase-owned files. **Do not write
-code here.**
+Turn `spec.md` into architecture, vertical slices, traceability, and state. Spec owns
+what/why; Define owns how. **Do not write code.**
 
 ## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
 Pull these via `Read` when shaping the plan:
 - `development-workflow.md`: small batches, trunk-always-green, definition of done.
 - `principles.md`: the project invariants (`.devrites/principles.md`) the chosen approach must conform to.
 - `documentation.md`: record plan-time decisions and rationale.
+- `repository-topology.md`, `data-integrity.md`, and `integration-reliability.md`:
+  load only for matching `spec.md` applicability rows; each applicable owner is mandatory.
 - `../workspace-artifact-schema.md`: artifact purposes, budgets, IDs, and read triggers.
 
 ## Operating rules
-- **Requires a readied spec.** Read the active workspace first; if `.devrites/ACTIVE` is empty,
-  the workspace has no `spec.md`, its readiness gate hasn't passed, or any spec-quality
-  `checklists/<domain>.md` has an open CRITICAL → **STOP** and tell the user to run
-  `$rite-spec <feature>` first. A missing or non-`CLEAR` `decision-coverage.md` routes to
-  `$rite-clarify`. **DO NOT plan from a missing, unreadied, or unclarified spec.**
-- Apply `afk-hitl.md` decision ownership. Prefer conventions; source-check new dependencies or
-  design systems, asking only about licensing/cost/security or explicit policy.
-- **Author one section at a time.** Write `architecture.md` and `plan.md` section by
-  section, pausing after each. For an open design choice or uncertain estimate, use a
-  relevant technique from
-  [`elicitation.md`](../devrites-lib/reference/standards/elicitation.md) (Tournament for two viable
-  designs, Delphi for the estimate) before it hardens into slices.
+- **Requires a readied spec.** Missing workspace/spec/readiness or open CRITICAL checklist →
+  `$rite-spec`; missing/non-`CLEAR` decision coverage → `$rite-clarify`. Never plan it.
+- Apply `afk-hitl.md` ownership. Prefer conventions; source-check new dependencies/design
+  systems, asking only about licensing, cost, security, or policy.
+- Author one `architecture.md`/`plan.md` section at a time. Before slicing, use
+  [`elicitation.md`](../devrites-lib/reference/standards/elicitation.md) Tournament for open
+  designs and Delphi for uncertain estimates.
 - **Derive the slice count from the work.**
-  One per independently-shippable increment, sized by `slicing.md`, every acceptance
-  criterion mapped to ≥1 slice. A user-named count is a hint at most: slice logically and,
-  if your honest count differs, present it and why. Never pad or compress to hit a figure.
-  (`.devrites/AFK` `max_slices` is a separate AFK iteration budget, not the decomposition.)
-- **Complexity does not shrink accepted scope.** Split/reorder for context, size,
-  or dependencies; MUST NOT drop/defer approved REQ/AC. Reduction requires Spec
-  Drift Guard + recorded human decision; hard/large is a decomposition signal.
-- **Wide mechanical refactors slice expand → migrate → contract.** If one repeated change
-  crosses many files, don't fake vertical slices. Add a compatibility/adapter slice, migrate
-  small green batches, then remove the old path. If a batch cannot stay green, use an
-  integration branch plus a final verify slice.
-- **Root writes; drafter proposes.** Use the native bounded fresh-context contract in
-  [`agents.md`](../devrites-lib/reference/standards/agents.md). The root owns architecture
-  decisions, human questions, approval, and every canonical artifact write.
+  One per independently-shippable increment, sized by `slicing.md`; map every acceptance
+  criterion. User counts are hints: explain honest differences, never pad/compress.
+  `.devrites/AFK` `max_slices` is an iteration budget, not decomposition.
+- **Complexity does not shrink scope.** Split/reorder; never drop/defer approved REQ/AC.
+  Reduction needs Drift Guard + human decision; hard/large means decompose.
+- **Wide refactors use expand → migrate → contract.** Add compatibility, migrate green
+  batches, then remove the old path; if batches cannot stay green, use an integration branch
+  plus final verify.
+- **Root writes; drafter proposes** under bounded fresh context
+  ([`agents.md`](../devrites-lib/reference/standards/agents.md)); root owns choices and canonical files.
 
 ## Workflow
 0. **Read `.agents/skills/devrites-lib/reference/standards/core.md`:** the always-on operating rules and anti-rationalizations.
@@ -66,39 +56,41 @@ Pull these via `Read` when shaping the plan:
    **`design-brief.md` if the feature touches UI** (the UX/UI contract `$rite-spec` shaped:
    its key states, interaction model, and proof targets drive how UI slices are cut). If a blocking
    `[NEEDS CLARIFICATION]` remains, stop → `$rite-clarify`.
+   Reconcile every `Applicability map` row against live repository evidence. Load each
+   applicable standard; a false `not applicable` is a blocking spec gap, not a planning
+   shortcut.
 1a. **Draft from fresh context.** Freeze the planning inputs and dispatch
    `devrites-plan-drafter` in `define` mode for one atomic candidate bundle:
-   `architecture.md`, `plan.md`, `tasks.md`, and `traceability.md`, including proof mapping.
-   Wait for and validate its bounded result. The drafter does not write or ask; any human-owned
-   choice returns to this root context.
-2. **Reconcile and decide the architecture + approach** (the HOW the spec deliberately
-   omitted). Validate the candidate against live seams and the following rules; the root writes
-   accepted content at step 6. Shape
-   `architecture.md` for owning layer, boundaries, integration points, data/API/events,
-   dependencies, risks, and affected areas; write only the build strategy in `plan.md`.
-   Use a
-   code-intelligence index if available (see
-   `.agents/skills/devrites-lib/reference/standards/tooling.md`) for structure/impact; for the current API or behaviour of
-   an external library/framework the architecture will rely on, consult context7 if available.
-   Record significant options as `DEC-###`. For high-cost/hard-to-reverse boundaries, data
-   models, public contracts, or dependencies, compare ≥2 viable approaches by drivers,
-   trade-offs, and consequences. Specify cross-boundary interfaces for independent work:
+   `architecture.md`, `plan.md`, `tasks.md`, and `traceability.md` with proof mapping.
+   Validate its bounded result; it does not write/ask, and returns human choices to root.
+2. **Reconcile architecture + approach** against live seams; root writes at step 6.
+   `architecture.md` owns layers/boundaries/integrations/data/dependencies/risks/impact;
+   `plan.md` owns build strategy. Use the code index for structure/impact
+   ([`tooling.md`](../devrites-lib/reference/standards/tooling.md)) and source-check external behavior.
+   Record significant options as `DEC-###` only for non-obvious real trade-offs where
+   independently built lower units could choose incompatibly; leave other details to convention/
+   slice. Compare ≥2 viable approaches for hard-to-reverse boundaries, models, contracts, or
+   dependencies by drivers, trade-offs, and consequences. Specify cross-boundary interfaces for independent work:
    invariants, I/O, ordering/idempotency, errors, versioning, config, and relevant budgets.
+   Establish repository/deployable roots, state and contract ownership, shared mutable
+   resources, and deployment order under `repository-topology.md`. For applicable durable
+   data or integration rows, include the exact required plan table from `data-integrity.md`
+   or `integration-reliability.md`; do not replace it with "handle retries/migration" prose.
    For any changed provider/consumer boundary, complete `plan.md`'s canonical
    `Shared contract proof` table with one reused contract artifact and provider- and
    consumer-side asserting tests that both consume it. Otherwise record the exact justified
    no-impact statement. Missing, one-sided, duplicated-contract, vague, or non-consuming proof blocks.
-   **Deep-module check:** while sketching the major modules, look for opportunities
-   to extract a **deep module**: a small, stable interface that hides a meaningful chunk
-   of behavior and is independently testable. A *shallow* module whose interface is
-   nearly as complex as its implementation adds no value; deepen it or delete
-   it. Put independently testable deep-module behavior in the slice's `Tests/proof`;
-   `$rite-vet` confirms the level.
-2a. **Foreseeable-decision sweep.** Inspect questions, assumptions, architecture, dependencies,
-   proof prerequisites, and proposed checkpoints. Search facts and decide reversible technical
-   calls. New product/acceptance/policy/irreversible-risk gaps return to `$rite-clarify`; a build
-   checkpoint survives only for unavailable pre-code evidence or mandatory action-time approval.
-   **Completion:** no known implementation choice is postponed for build to ask later.
+   **Deep-module check:** prefer small, stable interfaces hiding meaningful, testable
+   behavior. Deepen/delete shallow modules whose interface matches implementation
+   complexity. Put their independent behavior in `Tests/proof`; `$rite-vet` confirms.
+2a. **Decision-horizon sweep.** Apply `reference/plan-template.md`'s classification to every
+   question, assumption, architecture/dependency/proof choice, and checkpoint. Resolve
+   planning items from source; only necessary executable evidence warrants a risk spike with
+   discriminating criteria/fallback branches. Human blockers route to `$rite-clarify`.
+   Implementation-local deferral needs owner slice, observable trigger, bounds/fallback,
+   and resolution proof; action checkpoints name their signal. Preserve entries until
+   evidence resolves/supersedes them. **Completion:** no blocker or unowned/unsupported
+   deferral; deferral is not “ask later.”
 3. **Create vertical tasks:** each delivers one independently verifiable, observable
    capability end to end; first is the thinnest useful path, ordered by dependency then
    risk. Apply the slice-count and broad-refactor rules above plus
@@ -113,12 +105,17 @@ Pull these via `Read` when shaping the plan:
    provenance inputs; `$rite-vet` preflights them. Write the portable repository command,
    never RTK/local wrappers, user-specific absolute paths, or temporary proof trees. When a
    shared contract changes, order its canonical artifact before both asserting tests and make
-   the provider/consumer slice dependencies explicit.
+   provider/consumer dependencies explicit. Each exact `Characterization:
+   characterize-before-modify` row is the first touching slice's prerequisite: observe and test
+   unchanged baseline green, perturb realistic behavior red, restore green, then modify. Never
+   expand this into repository-wide coverage.
 4. **Map coverage and wiring:** every `AC-###` spec acceptance criterion maps to ≥1 `SLICE-###`
    (`rite-spec/reference/acceptance-criteria.md`); no orphaned criteria, no slice without a
    criterion. Lift covered/backstop `Edge Coverage` rows and resolved `Prohibitions (must-NOT)`
    rows into `traceability.md` and `test-plan.md`; unresolved rows get a gate/owner. Each
    cross-slice boundary names producer, consumer, invariant, integration step, and proof.
+   Map each applicable topology/data/integration risk to a slice, failure/recovery path,
+   and discriminating proof; a risk cannot live only in the architecture narrative.
 4a. **Persist traceability natively.** The drafter proposes and root writes
    `traceability.md` (`AC/REQ ID → slice → proof → evidence ID → files → status`).
    Re-read spec, tasks, and proof fields: every ID must exist and every mapping
@@ -140,10 +137,11 @@ Pull these via `Read` when shaping the plan:
    buildable AC/REQ maps to an existing slice/proof, every slice maps to real
    acceptance, and names/prose agree. Missing, duplicate, contradictory, or
    meaning-changing mappings block.
-7. **Readiness gate** (plan-template): require CLEAR coverage, complete acceptance and
-   cross-slice wiring/proof, complete `Shared contract proof`, risk-first acyclic order,
-   justified deviations, rollback, and a
-   closed decision sweep. **Stop and confirm** before code. Render the review-before-code
+7. **Readiness gate** (`plan-template.md`): require CLEAR coverage; complete acceptance,
+   wiring, shared-contract proof, applicable outputs, and rollback; risk-first acyclic order;
+   justified deviations; and every horizon item present, with blockers resolved, planning
+   items resolved/validly spiked, and local/action entries bounded and owned.
+   **Stop and confirm** before code. Render the review-before-code
    digest first: `Intent` (one sentence from the spec), `Done means` (acceptance coverage x/y),
    `Plan sanity` (slice count + riskiest boundary/gate), `Expected build interruptions`
    (`none` or only justified action-time gates), and `Build exactly this?` (yes → approve;

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

@@ -1,119 +1,136 @@
 # `plan.md` template
 
-Write **how** to build what `spec.md` defines. Use `$rite-plan` when evidence requires
-an update. Technology choices belong here, not in the spec.
+Build plan for `spec.md`; tech choices live here, not in spec. `$rite-plan` revises on
+new evidence.
 
 ```markdown
 # Plan: <Feature>
 Spec: ./spec.md   Decision coverage: ./decision-coverage.md   Date: <date>
 
 ## Summary
-1–2 sentences: the primary requirement + the chosen approach.
+<primary requirement + chosen approach, 1–2 sentences>
 
 ## Technical context
-- Language / runtime + version: <e.g. TypeScript 5, Node 20>
-- Frameworks / libraries in play: <...>
-- Storage / data: <...>
-- Testing tools + commands: <from spec "Commands discovered">
-- Target / platform / constraints: <...>
-- Any product/constraint unknown that affects the approach routes to `$rite-clarify`;
-  do not carry `[NEEDS CLARIFICATION]` into an approvable plan.
+- Language/runtime/version: <...>
+- Frameworks/libraries: <...>
+- Storage/data: <...>
+- Test commands: <from spec Commands discovered>
+- Target/platform/constraints: <...>
+- Approach-affecting product/constraint unknowns route to `$rite-clarify`;
+  `[NEEDS CLARIFICATION]` blocks approval.
+
+## Applicability and system ownership
+
+Validate `spec.md` applicability against live evidence. Each `applies` row includes its
+owner's **Required plan output** here or in architecture:
+
+- topology → root/deployable/owner table;
+- data/migration/tenant/retention → invariant/recovery table;
+- API/webhook/queue/job/cache/service → boundary table;
+- security/UI/delivery → focused standard + proof owner.
+
+Record feature owner, failure/recovery, slice, and evidence. Changed `not applicable`
+uses Spec Drift Guard.
 
 ## Global constraints
-Project-wide requirements from the spec that every slice implicitly includes — version
-floors, dependency limits, naming/copy rules, platform requirements. One line each, exact
-values **verbatim from spec.md** (a paraphrased constraint drifts by the time slice 4 builds).
+Exact `spec.md` requirements inherited by every slice.
 
 ## Approach
-The strategy in a few sentences. Why this over the alternatives considered.
-For high-cost/hard-to-reverse boundaries, models, contracts, or dependencies compare ≥2
-viable `Option · Drivers · Trade-offs · Consequence`; skip theater for routine choices.
+State strategy and rationale. For costly/hard-to-reverse boundaries, models, contracts,
+or dependencies compare ≥2 `Option · Drivers · Trade-offs · Consequence`.
 
 ## Slice strategy
-How the feature is split into vertical `SLICE-###` increments, why the order is
-risk-first within dependency tiers, and which acceptance criteria each slice covers. For a
-wide mechanical refactor, use expand → migrate batches → contract; keep every migrate batch
-green, or name the integration branch + final verify slice.
+List vertical `SLICE-###` increments, AC coverage, and risk-first order within dependency
+tiers. Wide refactors use expand → green migrate batches → contract, or an integration
+branch + final verify slice.
 
 ## Architecture decisions
-Key decisions + rationale (mirror into decisions.md). New pattern vs reuse — prefer
-reuse of existing project conventions. Record architecture as invariants, not scaffolding:
-include a decision only when slices could choose incompatibly. Medium+ decisions include
-`Binds:` and `Prevents:`. Cross-boundary interfaces name invariants, I/O, ordering/idempotency,
-errors, versioning, config, and relevant budgets.
+Decisions + rationale (mirror to `decisions.md`). Prefer reuse and invariants over
+scaffolding. Medium+ entries add `Binds:`/`Prevents:`. Interfaces name invariants, I/O,
+ordering/idempotency, errors, versioning, config, and budgets.
+
+## Decision horizons
+
+Classify every known unresolved/action item. Keep `HZN-###` across replans; never delete
+silently. Resolution/supersession needs evidence.
+
+| Horizon | Includes | Required disposition |
+|---|---|---|
+| Human-owned blocker | Product, acceptance, policy, irreversible risk | `$rite-clarify`; unresolved blocks approval/readiness. |
+| Planning-owned | Architecture, boundary, dependency, sequence, proof | Resolve from source. If executable evidence is necessary, plan a bounded risk spike with discriminating criteria + fallback branches. |
+| Implementation-local | Reversible detail unknowable before code/tests: exact helper name, final query shape after live evidence, or a refactor that may disappear | Owner slice + observable trigger + bounds/fallback + resolution proof; never “ask later.” |
+| Action-time checkpoint | Approval/evidence mandatory when acting | Owner + gate/signal + bounds/fallback + proof; cannot hide an earlier decision. |
+
+Never local: public contracts, security/data invariants, acceptance, migration/rollback,
+dependency choice, cross-slice interfaces. Output per item: `HZN-### · item · horizon ·
+owner/slice · evidence · trigger/checkpoint · bounds/fallback/branches · resolution proof ·
+status`. Only a complete sweep may write `Decision horizons: none — <evidence>`.
 
 ## Shared contract proof
-When this feature changes an API, event, schema, or other provider/consumer boundary,
-include exactly one table and omit the no-impact statement:
+Changed provider/consumer boundary: one table:
 
 | Boundary | Canonical contract artifact | Provider-side asserting test | Consumer-side asserting test |
 |---|---|---|---|
 | <provider → consumer surface> | <existing schema/type/fixture path> | <test path + assertion> | <test path + assertion> |
 
-Both tests must consume the same artifact. Reuse an existing canonical schema, type, or
-fixture when one exists; do not create one for ceremony. If no provider/consumer boundary
-changes, omit the table and write exactly:
+Tests consume the same artifact. Reuse an existing canonical artifact; no ceremony-only
+artifact. Without boundary change write exactly:
 
 Shared contract impact: none — <specific justification>
 
 ## Dependency graph
-What must exist before what (text is fine):
-- SLICE-001 (no deps) → SLICE-002 (needs SLICE-001) → SLICE-004 (needs SLICE-002, SLICE-003)
-- SLICE-003 (independent / parallelizable)
+List slice prerequisites, non-code prerequisites, and deployable order:
+contract/schema/config → old/new app/worker → migration/backfill → exposure → removal.
+Name shared mutable resources that force serialization.
 
 ## Implementation order
-Ordered slice list + the reason for the order (risk-first within a dependency tier).
-`MVP cut: after SLICE-00N — <what ships if we stop here>` — the earliest prefix of the order
-that is a coherent, shippable feature on its own. This is the pre-agreed retreat position when
-the feature stalls or `$rite-plan` pivots: every acceptance criterion above the cut is proven by
-slices above the cut, and no slice above it depends on one below.
+Ordered slices + rationale (risk-first within dependency tiers).
+`MVP cut: after SLICE-00N — <what ships if we stop here>` — the earliest coherent,
+shippable prefix. Every acceptance criterion above it is proven there, with no dependency
+below it.
 
 ## Validation strategy
-After which slices to run tests / build / browser proof. For UI slices, name the visual
-acceptance targets from `design-brief.md`, not a generic "looks good" check.
-Each proof names exact command/cwd/signal, prerequisites, and mutable provenance inputs.
-Use portable repository commands; runtime wrappers and local absolute/temp paths do not
-belong in a durable plan.
-
-**Key links** — the wiring the assembled feature must exhibit, one row each:
-`<from> → <to> via <mechanism>` (route → handler via registration; producer → consumer via
-event). List only cross-slice links whose absence no single
-slice's tests would catch — `$rite-prove` walks each (step 5d). `Key links: none` is a
-deliberate single-slice call.
+Name test/build/browser proof points. UI uses `design-brief.md` targets. Each proof names
+portable command/cwd/signal, prerequisites, and mutable provenance inputs.
+
+**Key links** — assembled wiring, one row each:
+`<from> → <to> via <mechanism>`. List wiring no slice test catches; `$rite-prove` walks it.
+`Key links: none` is deliberate.
 
 ## Complexity & deviations gate
-List anything that deviates from DevRites defaults (prefer existing conventions, the
-simplest approach, feature scope only, no new deps/design system) and **justify it**.
-If you can't justify a deviation, simplify instead of recording it.
+Justify deviations from reuse, simplicity, scope, dependency/design-system rules;
+otherwise simplify.
 | Deviation | Why needed | Simpler option rejected because |
 |-----------|-----------|---------------------------------|
 | <e.g. new dependency X> | <reason> | <why the in-repo option won't work> |
 
 ## Rollback
-How to back out each risky step (migration down, feature flag, revert boundary, backup).
+Risky-step backout: migration/flag/revert/backup.
 
 ## Scope boundaries
-What this plan will NOT touch. Restate "Ask first" / "Never do" from the spec.
+Untouched scope; copy spec “Ask first”/“Never do.”
 
 ## Source docs needed
-Framework/library docs to consult (triggers devrites-source-driven). Record URLs in
-decisions.md / evidence.md when used.
+Framework/library sources (triggers source-driven).
 
 ## Readiness gate  *(must pass before $rite-build)*
 - [ ] `decision-coverage.md` says `Decision coverage: CLEAR`
-- [ ] Every spec acceptance criterion is covered by a slice
-- [ ] Dependency order is acyclic and risk-first
-- [ ] An `MVP cut` is named, self-contained (ACs above the cut proven above the cut, no dependency reaching below), and marks a genuinely shippable scope
-- [ ] No unjustified deviation remains in the complexity gate
-- [ ] Rollback exists for every destructive / migration step
-- [ ] Every `Mode: HITL` slice has `Gate`, `SLA`, and `Checkpoint` populated
-- [ ] Human-owned choices are resolved; surviving checkpoints need unavailable pre-code
-      evidence or action-time approval
-- [ ] Slice proof commands, cwd, prerequisites, and provenance inputs are portable and preflightable
-- [ ] Every UI slice names `Design brief states` and binary `Visual acceptance`
-- [ ] `Key links` rows cover every cross-slice wiring (or state `none`)
-- [ ] Cross-boundary contracts name producer, consumer, invariants/errors/order, and proof
-- [ ] `Shared contract proof` contains one complete, consuming provider/consumer table, or one specific no-impact statement
-- [ ] Any wide mechanical refactor is sliced expand → migrate batches → contract, with green migrate batches or an integration branch + final verify slice
-- [ ] No `Gate: blocking` slice is implicitly chained behind an AFK slice without surfacing the dependency
+- [ ] Every AC maps to a slice
+- [ ] Dependencies are acyclic/risk-first
+- [ ] Applicability matches live evidence; outputs name owner, recovery, slice, proof
+- [ ] `MVP cut` is shippable/self-contained: ACs proven, no dependency below
+- [ ] Deviations are justified
+- [ ] Destructive/migration steps have rollback
+- [ ] Each `Mode: HITL` slice has `Gate`, `SLA`, `Checkpoint`
+- [ ] Human choices resolved; checkpoints need unavailable pre-code evidence/action approval
+- [ ] All horizon items remain; blockers/planning items resolved or validly spiked;
+      local/checkpoint register fields fully populated
+- [ ] Proof command/cwd/prereqs/provenance portable + preflightable
+- [ ] UI slices name `Design brief states` + binary `Visual acceptance`
+- [ ] `Key links` cover cross-slice wiring (or `none`)
+- [ ] Contracts name producer, consumer, invariants/errors/order, proof
+- [ ] Deploy/config/schema/app/worker/flag order is safe across old/new or N/A
+- [ ] `Shared contract proof` has one consuming table or specific no-impact
+- [ ] Wide refactor is expand → green migrate batches → contract, or branch + final verify
+- [ ] No hidden `Gate: blocking` dependency behind an AFK slice
 ```

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

@@ -57,7 +57,8 @@ 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
+- A **concept** with footprint in this repo → live code through the primary index selected by
+  `standards/tooling.md` (one named-predicate cross-check only when needed), 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).

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

@@ -8,51 +8,47 @@ disable-model-invocation: true
 
 # $rite-learn: review durable lessons
 
-Use native session memory and reviewed project Markdown instead of an engine
-miner, score, nudge, or convention registry. This command proposes durable
-guidance; it never turns an inferred pattern into a rule on its own.
+Use reviewed Markdown/native memory, not miners or registries. This proposes maintenance
+of one authority; it cannot promote a rule alone.
 
 ## Modes
 
 - `$rite-learn` reviews recurring evidence across shipped work.
-- `$rite-learn "<lesson>"` evaluates one proposed lesson or rejected direction.
+- `$rite-learn "<lesson>"` evaluates one lesson or rejected direction.
 
 ## Workflow
 
-1. Read the applicable `AGENTS.md` or `CLAUDE.md`, accepted ADRs, and relevant
-   `.devrites/archive/*/{decisions,drift,review,seal}.md` files. Use native host
-   memory or session history when available, but verify every durable claim
-   against repository evidence.
-2. For a broad review, ask the exact `devrites-retrospector` agent to inspect the
-   bounded archive in a fresh read-only context. Wait for its result and
-   reconcile it against the cited files.
-3. Keep a candidate only when it is specific and supported by either:
-   - the same correction in at least two distinct features; or
-   - one explicit, durable product/architecture decision with its rationale.
-4. Choose the smallest authoritative home:
-   - `AGENTS.md`, `CLAUDE.md`, or a scoped standards document for an operating
-     rule;
-   - an ADR for a significant durable architecture decision;
-   - the active feature's `decisions.md` for a feature-scoped decision;
-   - no change for a one-off, stale, or generic observation.
-5. Show the evidence and exact proposed edit. Apply it only after the user
-   approves the durable rule or decision.
+1. Read [durable promotion](../devrites-lib/reference/standards/documentation.md#promote-durable-guidance).
+   Bound the archive; inspect applicable
+   `AGENTS.md`/`CLAUDE.md`, accepted ADRs, and relevant
+   `.devrites/archive/*/{decisions,drift,review,seal}.md` files.
+2. In broad mode, dispatch exact `devrites-retrospector` fresh/read-only; reconcile its
+   claims against cited files.
+3. Keep a correction repeated in two features or one explicit durable product/architecture
+   decision with rationale. Drop one-off, generic, or stale items.
+4. Verify claims against live authoritative repository sources. State the currentness signal,
+   applies/does-not-apply scope, and `unknown` where unverifiable.
+5. Search guidance for the same/contrary rule. Choose one existing canonical owner: nearest
+   instruction/standard, architecture ADR, or feature `decisions.md`; name discovery.
+6. Show the exact edit and duplicate/conflict/supersession disposition. Update, narrow,
+   replace, or retire contradictions; apply only after user approval of the exact edits.
 
 ## Rules
 
-- Live repository evidence outranks memory.
-- Do not maintain a parallel learning ledger, convention score, health score,
-  timeline, fingerprint index, or promotion queue.
-- Do not duplicate guidance already stated by a higher or nearer authority.
-- A rejected direction returns only when new evidence changes its recorded
-  rationale.
+- Live repository evidence outranks memory; unverifiable is unknown, not false.
+- Never create a learning ledger/index/queue, score, timeline, or parallel authority.
+- Rejected directions return only when evidence changes their rationale.
 
 ## Output
 
 ```text
 Done: reviewed <scope>.
-Candidates: <specific proposals or none>.
-Evidence: <feature/file references>.
-Awaiting: <approval for exact edits | none>.
-Next: <single action>.
+Candidate: <specific proposal or none>
+Currentness: <live source + signal | unknown>
+Scope: applies <trigger>; does not apply <boundary>
+Authority: existing <path|none>; canonical <path>; consumers/discovery <route>
+Disposition: <no conflict | update/narrow/replace/retire path + reason>
+Evidence: <feature/file references>
+Awaiting: <approval for exact edits | none>
+Next: <single action>
 ```