devrites 5.11.0 → 5.12.0

package/pack/generated/codex/skills/devrites-lib/reference/standards/skill-authoring.md

@@ -1,5 +1,7 @@
 # Skill authoring
 
+> Applies when: creating or editing skills, agents, hooks, or standards.
+
 > **Source-checkout only:** where `pack/.claude/` exists, edit canonical source; run
 > `bash scripts/build-host-artifacts.sh`, then validate. Installed generated mirrors are not authoring surfaces.
 
@@ -68,6 +70,10 @@ Optional flags obey `core.md` rule 10.
   core.md's PASS/FAIL/NOT-RUN contract beside a pointer to the same section.
 - One read shows outcome, triggers, preconditions, decisions/failure, write owner,
   proof, exit; omit irrelevant fields. Examples distinguish branches.
+- Name the capability before the tool: "check the worktree is clean" before
+  `git status`. A tool rename must never orphan the contract it serves.
+- Keep quantifiers local to the action: "every dispatch" reads next to the step that
+  dispatches, not in a distant header the reader must carry forward.
 - Split only for independent load path or eval-proven inline failure; keep one owner; co-locate each rule/caveat/example cluster.
 - Every public optional-flag skill obeys the shared
   [`core.md`](core.md#operating-rules-every-phase): declare its
@@ -85,6 +91,31 @@ Optional flags obey `core.md` rule 10.
   those indexes. A skill-local reference must not be the only path to
   another non-catalog file in that skill.
 
+## Read-set manifest
+
+Every executable skill declares a `loads:` manifest (HTML comment, strict JSON)
+immediately after frontmatter, followed by a `> Read-set manifest:` line naming
+the engine command that bundles it. The engine fails closed on malformed JSON.
+
+- `always`: files loaded on every `context` call — keep to what every invocation
+  truly needs; a file read only under a named condition belongs in `triggers`.
+- `triggers`: name → files loaded only when the caller passes `--trigger <name>`
+  or the engine lists it under `suggested=[...]`. Names are validated against the
+  manifest; inventing one fails the call.
+- `workspace`: feature artifacts any reader of this skill may need.
+- `workspaceByRole`: dispatch role → its artifact subset. A listed role reads only
+  its own list (empty list = no workspace files); an unlisted role falls back to
+  `workspace`. Author lists from what the role's contract actually cites, not the
+  union of everything.
+- A body reference to a trigger-gated file names its trigger in prose
+  (e.g. "trigger `workflow-artifacts`") so the caller passes it; an omitted
+  applicable trigger is a gap, not a shortcut.
+- Re-wrap edits must keep asserted literal phrases on a single line —
+  validators grep `grep -F` fixed strings and a mid-phrase line break silently
+  deletes the check's target. **Failing case:** re-flowing "Reject a result that
+  omits any required key" across two lines while the phase-gate test still
+  asserts the single-line phrase.
+
 Classify active instructions by load path:
 
 - `core.md`: required by every workspace rite;
@@ -104,6 +135,23 @@ regresses.
   its enforcement does not is decoration. **Failing case:** a merged rule whose asserted
   string or eval case no longer exists anywhere — the merge silently deleted the check.
 
+## Agent-facing surfaces
+
+Design for the call the agent already makes; instructions and descriptions are
+low-salience steering — making the default output sufficient lands where exhortation
+does not.
+
+- A tool's first answer must be usable alone: agents abandon tools whose output
+  needs a follow-up call to become actionable, and a couple of hard errors teach
+  abandonment for the rest of the session.
+- Reserve hard errors for genuine stop conditions; a recoverable empty result is
+  data with a stated meaning, not an error.
+- Serve state honestly: when output may lag the working tree, say so on the
+  response (a staleness note naming the lagging inputs) rather than answering
+  stale silently.
+- Keep agent-facing rules on one canonical surface; a repeated rule is two copies
+  that drift.
+
 ## Router, docs, and evals
 
 - Public `rite-*`: `$rite` router + `docs/skills.md` + `docs/command-map.md`.

package/pack/generated/codex/skills/devrites-lib/reference/standards/spec-grammar.md

@@ -1,5 +1,7 @@
 # Spec grammar: testable requirements, checked by native re-read
 
+> Applies when: writing or reviewing behavioral requirements and acceptance criteria.
+
 Acceptance criteria are the contract the seal checks ([`testing.md`](testing.md), [`code-review.md`](code-review.md)). Prose criteria can't falsify ambiguity ("handle errors gracefully") — it slips every gate. This adds an **optional, recommended structure** making behavioral requirements testable by construction; the root re-reads the spec before `$rite-define` plans against a malformed requirement. Grammar counterpart to testing: testing proves behavior; this writes each behavior so it can be proven.
 ## Progressive rigor: when to use the structured form
 
@@ -115,15 +117,24 @@ each item against the file's exact headings and text. **No parser or replacement
 
 - [ ] `## Acceptance criteria` exists and every buildable criterion has one
   unique `AC-###` ID; success metrics have none.
-- [ ] Every `### Requirement:` header is non-empty and unique.
+- [ ] Every `### Requirement:` header is non-empty, unique, descriptive, and
+  under ~50 characters.
 - [ ] Every structured requirement contains a normative `SHALL` or `MUST`
   statement and at least one `#### Scenario:`.
-- [ ] Every scenario has an observable trigger/outcome (WHEN/THEN or EARS WHILE/IF), plus an `AC-###` criterion; it describes behavior rather than implementation.
-- [ ] Delta headings use only ADDED, MODIFIED, or REMOVED. Each named capability
+- [ ] Scenario names are unique within their requirement; every scenario has an
+  observable trigger/outcome (WHEN/THEN or EARS WHILE/IF), plus an `AC-###`
+  criterion; it describes behavior rather than implementation.
+- [ ] Delta headings use only ADDED, MODIFIED, or REMOVED; every delta section
+  names at least one `### Requirement:` block, and no structured requirement
+  sits outside a delta H2 when delta sections exist. Each named capability
   is contained under `.devrites/specs/`, and MODIFIED/REMOVED headers match the
-  current ledger exactly.
+  current ledger exactly. A near-match (case, whitespace, or word drift) is a
+  typo to fix in the spec — never a rename-by-append.
 - [ ] Exactly one capability-impact declaration exists and agrees with the ledger
   deltas, or gives a specific `none` justification.
+- [ ] Every requirement admits one reading — the two-engineers test: if two
+  competent engineers could implement the clause differently and both claim
+  compliance, it is ambiguous; sharpen it into a scenario or split it.
 - [ ] Re-read the entire requirements and acceptance sections once more after
   corrections so duplicates and partial edits cannot hide between blocks.
 
@@ -159,6 +170,9 @@ The system SHALL default to the OS colour-scheme on first load.
 Removed — superseded by system-preference detection.
 ```
 
+A **REMOVED** block is header plus removal rationale only — it carries no
+`#### Scenario:` blocks; deleted scenarios never fold anywhere.
+
 The Polish fold (`$rite-polish`) previews and writes through the host
 filesystem. **ADDED** appends, **MODIFIED** replaces the same-named requirement, and
 **REMOVED** deletes it. Matching is by **header identity** (the rule

package/pack/generated/codex/skills/devrites-lib/reference/standards/test-proof-checklist.md

@@ -1,5 +1,7 @@
 # Test proof checklist
 
+> Applies when: compact sweep before claiming test proof.
+
 - New behavior has an asserting test, preferably written before implementation.
 - The test was seen fail for the right reason.
 - Verification commands and relevant output are recorded.
@@ -8,6 +10,9 @@
   and time-zone risks have discriminating cases or a recorded dismissal.
 - Mocks do not remove the risk being claimed; wiring proof follows real data to the promised surface.
 - A claimed pre-existing/environment-only failure has a same-command baseline.
+- A runnable check that failed, timed out, was skipped, or could not start is a named blocker —
+  fix the environment and rerun, or record the concrete blocker; never folded into "mostly green".
+- Facts come from executed runs; anything reasoned but unexecuted is labeled an assumption.
 - Passing existing tests alone is not proof of the change.
 
 Detailed standard: `testing.md`.

package/pack/generated/codex/skills/devrites-lib/reference/standards/testing.md

@@ -1,5 +1,7 @@
 # Testing
 
+> Applies when: writing, reviewing, or relying on tests as evidence.
+
 Tests are evidence. They exist to prove behavior and to catch regressions, not to hit a
 coverage number.
 
@@ -51,7 +53,9 @@ implementation is theatre, and it's the shape AI reaches for by default. Reject
 A behavioral requirement is proved only by observed positive, discriminating evidence that
 would fail if the behavior were absent or wrong. Skipped, focused, filtered, or pending tests,
 zero-test runs, assertion-free tests, tautologies, unexecuted commands, and success inferred
-only from exit status cannot prove behavior.
+only from exit status cannot prove behavior. A fact is something observed in an executed
+run; anything reasoned but unexecuted is an assumption — label it as such in evidence and
+replies, never report it as verified.
 
 Build, compile, typecheck, and lint prove only their corresponding static criterion, never
 runtime behavior. Explicit shell assertions and golden/text comparisons remain valid when the
@@ -78,6 +82,17 @@ discriminates the required result.
   that a test would catch it breaking. Where the project has a mutation runner,
   use its documented command; a surviving mutant is a behaviour no test checks.
 
+### Falsifiable checks and goldens
+
+- **A gate that cannot go red is unproven.** Before trusting a new validator or
+  oracle, feed it a planted defect and observe it fail — a check that stays green on
+  a known-bad input is checking nothing.
+- **Golden fixtures are verified by blind derivation, not inspection.** Derive the
+  expected output from rules and inputs *without looking at the golden*; adjudicate
+  any divergence against the external spec — never by majority vote between
+  reviewers, and never because the fixture is committed. A golden nobody re-derived
+  is a rumor.
+
 ### Safe perturbation
 
 For required mutation or critical-link probes, use a faithful isolated copy of the
@@ -103,7 +118,9 @@ A failing test is a signal, not an obstacle. Never delete it, skip it (`it.skip`
 loosen its assertions to turn the suite green. A red test means one of two things: the code is
 wrong (fix the code) or the test is wrong (surface it as a blocking question and get the change
 agreed): never quietly make the red go away. A test weakened to clear a gate is a **Critical**
-finding. The root's diff review and dedicated test analysis compare the
+finding. The same rule runs in reverse for a red test in code the diff did not touch: check
+whether the assertion is stale, and fix the assertion as a recorded, reviewable change —
+never bend working product code just to satisfy it. The root's diff review and dedicated test analysis compare the
 candidate with its base and reject deleted, skipped, focused, or weakened tests.
 
 ## The verification gap: green, but the test doesn't prove the change

package/pack/generated/codex/skills/devrites-lib/reference/standards/tooling.md

@@ -1,5 +1,7 @@
 # Optional tooling: code intelligence, docs, memory
 
+> Applies when: using or substituting optional tools (indexes, docs, memory).
+
 Every external tool here is optional; fall back to `Read` / `Grep` / `Glob`, always available. Never assume installation or block a phase on a missing tool. A step that needs an optional tool names its fallback chain up front and re-verifies availability after any environment change — a wrapper script or alias can satisfy a "missing" binary, and a skipped step over an absent-in-name tool is a finding, not a shortcut. An unreadable, quarantined, or permission-blocked target is recorded as a finding (`cannot_verify: unreadable <path>`), never silently skipped — a scan that reports clean while skipping files has not run.
 
 For the pack-canonical decision tree (graph vs LSP vs grep vs read), load
@@ -38,6 +40,11 @@ search cannot attribute which pattern matched; split into separate runs when per
 provenance matters. **Failing case:** three sequential greps over one tree for sibling
 patterns, each paying the full walk.
 
+**Batches are dependency steps.** Calls in one batch must be output-independent; a call whose
+arguments need another call's output goes in the *next* batch — never emit a probe whose inputs
+aren't known yet. Writes are barriers: don't batch a write with calls that must observe its
+result. Read-only calls in the same step may run in parallel; mutating ones order the batch.
+
 ## Primary-first gate (C1)
 
 Before a third content-grep sweep for the same unresolved predicate during Build
@@ -88,5 +95,10 @@ Per [`prose-style.md`](prose-style.md): say what you learned ("touches three cal
   decisions until verified or resolved by the owning question/Spec Drift route.
 - **Citation contract:** every external claim carries `path:line`/URL, version, and retrieval date; it counts when the source loads, is relevant, and supports it — uncited/unsupported = assumption. A cited URL was opened or its resolution re-verified in the session; a URL quoted from memory is an assumption (3–13% of agent-cited URLs do not resolve). A live URL is not enough: the cited title, identifier (DOI/CVE/commit SHA), and author/publisher must match the retrieved record. Identifier hijacking (a real DOI or CVE paired with the wrong title) is a citation failure, same standing as a dead URL. **Failing case:** the DOI resolves and the title in the claim is a different paper.
 - **Staleness:** re-verify remembered facts that would change a material decision, conflict with local behavior (local wins, delta recorded), or predate the pinned dependency's current release boundary. **Failing case:** a docs-dated API claim from before the pinned dependency's current release is treated as current without re-verify, and it changes a material decision.
+- **Cached evidence:** bind reuse to the fetched representation, version, and
+  research query. Keep a derived summary distinguishable from raw evidence; a
+  later unrelated HEAD response or a 304 for another representation cannot
+  retroactively establish that summary's freshness. Revalidate the same retained
+  representation or fetch supporting content before refreshing its status.
 - **Human checkpoints:** ask only when the answer changes product, risk, scope, security posture, or spend; repository-answerable questions are never asked.
 - **Cost discipline:** depth scales with risk — trivial lookups take one authoritative read; parallel sweeps need a stated reason in the consuming artifact.

package/pack/generated/codex/skills/devrites-lib/reference/standards/verification-methods.md

@@ -0,0 +1,110 @@
+# Verification methods and coverage
+
+> Applies when: choosing how to check work — Prove, Review, Seal, Vet oracles,
+> audit sweeps, or any claim that a scope was verified.
+
+A check earns its place by what it can catch. This file is the selection
+discipline: distinct methods, an explicit coverage denominator, honest status
+vocabulary, and named fallbacks when a capability is missing. The `gates.md`
+acceptance ledger ([`gates.md`](gates.md)) binds runnable oracles to evidence;
+this file governs how methods are *chosen* and how coverage is *counted*.
+
+## A method is distinct only when its failure target differs
+
+A method names five things: the **failure** it hunts, the **procedure**, the
+**oracle** that separates pass from fail, the **material/scope** inspected, and
+the **evidence** it leaves. Count distinct failure targets supported by the
+observed checks, not command or tool names. Re-running the same check with
+cosmetic flags adds no method. If tests, build, and lint all stop at the same
+dead import, those runs supply no evidence of their later checks.
+
+Overlapping detection does not make different checks identical: executed tests
+asserting retry exhaustion, a build checking interface compatibility, and lint
+checking unsafe shell interpolation can support three distinct targets. Record
+each target and observation; neither three command names nor a shared ability
+to catch bad imports decides the count.
+
+Different methods may share the authoritative oracle (the spec, the ledger,
+the diff). Inventing a second expected answer to look independent is not
+independence. Where a requirement supports it, prefer complementary families:
+
+- **functional** — execute the behavior at boundaries and failure paths;
+- **structural** — inspect the changed surface, its interfaces, and callers;
+- **adversarial** — metamorphic properties, differential baselines, fault
+  injection, or a different render/interaction path.
+
+## Enumerate the denominator before claiming coverage
+
+Before work is called covered, write the inventory it must cover: every
+unit × check × environment row. Examples of rows a denominator may need:
+
+- Code: changed behaviors, affected callers, edge cases, supported runtimes.
+- UI: routes × viewport boundaries × interactive states (loading, empty,
+  error, disabled, success, focus) × agreed browsers.
+- Fixed-layout documents: every page × required visual check on the final
+  render — a thumbnail sheet or extraction pass is not visual inspection.
+- Reflowable documents: content units × renderer/viewport/font states;
+  reflow invalidates prior visual coverage even when the text is unchanged.
+- Data: schema, reconciliation, missing-data treatment, transformation classes.
+
+Two rules keep the denominator honest:
+
+1. **Never shrink it to reach 100%.** An exclusion needs a recorded decision
+   with authority; a unit that cannot be inspected stays visible as missing.
+   A percentage without the inventory proves nothing.
+2. **Sampling is not coverage.** A sample can surface a defect; only a row per
+   required unit satisfies a complete-inspection claim. If exhaustive coverage
+   exceeds budget, narrow scope with the human — do not quietly redefine done.
+
+## Status and result are separate facts
+
+Record two fields per row, never one:
+
+- **status** — `fresh` (run on this candidate), `reused` (carried forward after
+  a recorded applicability check), `failed` (the check ran and could not
+  complete — environment, timeout, parse), `missing` (never run), `blocked`
+  (cannot run: no tool, no authority).
+- **result** — `pass`, `fail`, `unverified`.
+
+A missing check is not a negative result; a failed check is not an unavailable
+tool; freshness alone is not a pass. Only applicable `fresh` or `reused`
+evidence with a supported `pass` satisfies a required row. Reuse keeps the
+original observation and records the new applicability check separately —
+see [`candidate-integrity.md`](../candidate-integrity.md#evidence-validity).
+When change impact cannot be bounded, recheck the full affected scope.
+
+## Judge evidence before counting a method
+
+Before any check counts, answer five questions:
+
+1. What distinct failure could this method reveal?
+2. What material and environment did it actually inspect?
+3. What independent observation separates pass from fail?
+4. Where is the observation recorded, and which candidate does it bind?
+5. What does this method not establish?
+
+Duplicate answers mean one method, not two. A property no available tool can
+verify is `unverified` — name the fallback, never manufacture a pass.
+
+## Capability fallbacks
+
+A missing capability gets a named fallback, not a fabricated check:
+
+| Missing | Honest fallback |
+| --- | --- |
+| Network | Dated local sources with their limits stated; a decision that needs current facts blocks or narrows scope with approval. |
+| Question tool | Numbered text options with a marked recommendation and a free-text path; a skipped answer stays `unanswered` ([`elicitation.md`](elicitation.md)). |
+| Fresh-context reviewer | `gap` under [`agents.md`](agents.md) result admission; required review waits for an authorized reviewer — self-review is labeled, never relabeled independent. |
+| Delegation permission | No dispatch. Prepare a neutral handoff; never bypass the restriction through another CLI.<!-- pack-scan-ignore: defensive rule prohibiting bypass, not instructing it --> |
+| Renderer/vision | Mechanical checks run; the visual-coverage rows stay `blocked` until real inspection or a recorded narrower scope. |
+| Budget | Stop or reduce scope with approval; failed attempts stay in the record, never deleted to look clean. |
+
+## Exercise the recipient's path
+
+Verification ends at the artifact as its recipient meets it: install the
+package, open the archive, run the binary, follow the entry point, navigate
+the UI. Installation, host discovery, activation, and actual behavior are four
+different facts — each proves only itself. Check relative paths, bundled
+resources, links, metadata, licensing, and instructions on the packaged form,
+from a clean location where feasible. A check run only against the working
+tree proves the working tree.

package/pack/generated/codex/skills/devrites-lib/reference/standards/windows.md

@@ -0,0 +1,51 @@
+# Windows — the deferral ledger
+
+> Applies when: a change introduces a deferral marker (TODO, FIXME, XXX, HACK,
+> a skipped test, a stub body) or `windows.md` waivers are authored or judged.
+
+`windows.md` is the broken-windows ledger. A review finding can describe a new
+`TODO`, a skipped test, or a stubbed body; this artifact makes the register
+countable instead: every deferral marker the change *introduces* must either
+be removed or carry an explicit waiver row, or `check windows` fails. The
+target is not zero deferrals — it is zero *silent* deferrals. Pre-existing
+markers on the baseline are pre-existing debt and are never attributed to the
+current change; only added lines count.
+
+Optional until a marker is introduced: a feature with no new markers needs no
+`windows.md`. Once any hit exists, Seal treats an unwaived marker as NO-GO.
+
+## Grammar
+
+```markdown
+- <project-relative path> | <marker token> | <reason>
+```
+
+- One waiver per row; each row waives exactly one hit at that path carrying
+  that marker. Five new TODOs in one file need five rows — a blanket row
+  cannot cover them.
+- `marker token` is the literal marker the checker reported (`TODO`, `t.Skip(`,
+  `NotImplementedError`, `panic("TODO`, …).
+- `reason` must be non-empty and should name the follow-up owner or slice; a
+  row with an empty reason warns and waives nothing.
+- Rows never suppress coverage — they explain it. Reviewers still judge
+  whether the deferral itself is acceptable.
+
+## Command
+
+```text
+devrites-engine check windows <slug> [--worktree|--staged|--base <ref>]
+```
+
+Exit `0` when no marker is introduced or every hit is waived; `3` when any
+introduced marker lacks a waiver or the workspace/ledger is unreadable; `2`
+on usage errors. The check parses the unified diff (`-U0`) for added lines,
+treats untracked files as wholly new, ignores binary files, deletions, and
+`.devrites/` paths, and runs on worktree, staged, or base-reference diffs.
+
+## Reviewer posture
+
+A waived marker is disclosed, not approved. The Seal reviewer asks whether
+each deferral belongs in this change at all, whether the reason is honest
+(owner and follow-up named, not "later"), and whether the diff could simply
+remove the marker instead. A waiver that exists only to silence the gate is
+an `Important` finding.

package/pack/generated/codex/skills/devrites-lib/reference/standards/workflow-artifacts.md

@@ -1,5 +1,7 @@
 # Workflow Artifact identity
 
+> Applies when: a plan declares root-authored executable workflow files.
+
 Workflow Artifact plans/isolates/proves; never enters product candidate/readiness/
 built count or authorizes consumption. Module owns semantics; callers retain only
 link and entry/return.

package/pack/generated/codex/skills/devrites-lib/reference/workspace-artifact-schema.md

@@ -24,10 +24,10 @@ accept safe legacy basenames. Ordinary phases never rename them.
 | clarify | spec artifacts plus `decision-coverage.md` |
 | temper | clarified spec artifacts plus `strategy.md` when temper runs |
 | define/plan | clarified spec artifacts plus `architecture.md`, `plan.md`, `tasks.md`, `traceability.md` |
-| vet/build/converge | plan artifacts plus `eng-review.md`, `test-plan.md`; Build creates and maintains `touched-files.md` after its first green slice |
+| vet/build/converge | plan artifacts plus `eng-review.md`, `test-plan.md`, `gates.md`; Build creates and maintains `touched-files.md` after its first green slice |
 | prove/polish/review | vetted plan artifacts plus `evidence.md`, `touched-files.md` |
 | seal/ship/done | proof artifacts plus `review.md`, `seal.md`; Ship writes `ship.md` |
-| conditional | `flows.md` when diagrams clarify; `visual/` HTML+`.outline.md` companions when a richer reviewable visual earns it (optional; never readiness-required); `design-brief.md` and `browser-evidence.md` for UI; `drift.md` for drift; `polish-report.md` for polish; `handoff.md` only when requested; `references.md` + `references/` when references exist; `investigation-map.md` for pressure-test; `dogfood.md` for dogfood; `packets/` for by-reference dispatch packets and admitted accounts (≤ 64 KiB each; older closed rounds may be deleted; never transcripts); `history/` for verbatim relocated checkpoint narrative (append-only, never a read-next) |
+| conditional | `flows.md` when diagrams clarify; `visual/` HTML+`.outline.md` companions when a richer reviewable visual earns it (optional; never readiness-required); `design-brief.md` and `browser-evidence.md` for UI; `drift.md` for drift; `polish-report.md` for polish; `handoff.md` only when requested; `references.md` + `references/` when references exist; `investigation-map.md` for pressure-test; `dogfood.md` for dogfood; `windows.md` when the diff introduces deferral markers (waiver ledger for `check windows`); `packets/` for by-reference dispatch packets and admitted accounts (≤ 64 KiB each; older closed rounds may be deleted; never transcripts); `history/` for verbatim relocated checkpoint narrative (append-only, never a read-next); `readiness-inputs.json` as the advisory per-input drift baseline written by `check drift --record` after Vet's binding (never a gate input; regenerated, not hand-edited); `notes.md` for anchored notes bound to verbatim code quotes (engine-regraded; non-exact anchors block seal) |
 
 ## What each file owns
 
@@ -43,7 +43,7 @@ accept safe legacy basenames. Ordinary phases never rename them.
 | `visual/<name>.html` | optional portable human-viewable visualization; pair with sibling `.outline.md`; self-contained preferred | 400 lines |
 | `visual/<name>.outline.md` | required machine dual-read companion for the sibling HTML; outline wins on conflict; never a candidate path | 200 lines |
 | `visual/README.md` | optional index of visuals in the workspace | 80 lines |
-| `decisions.md` | ADR-style `DEC-###` log: status, context, options, decision, consequences, related IDs | 200 lines |
+| `decisions.md` | ADR-style `DEC-###` log: status, context, options, decision, consequences, related IDs; optional `Files:`/`Tags:` fields make entries queryable by path or theme | 200 lines |
 | `assumptions.md` | assumptions with confidence, owner, validation status | 160 lines |
 | `questions.md` | current `q-YYYY-MM-DD-NNN` (or released `Q-###`) open/resolved questions, gate, answer, impact | 180 lines |
 | `plan.md` | technical approach, slice strategy, canonical shared-contract proof, validation strategy, rollback | 220 lines |
@@ -51,6 +51,7 @@ accept safe legacy basenames. Ordinary phases never rename them.
 | `traceability.md` | matrix: AC/REQ ID, slice IDs, test/proof, evidence ID, touched files, status | 220 lines |
 | `eng-review.md` | vetted scope/architecture/quality/performance, failure modes, preflight, stable-input binding, `## Deferred findings` (late rows: severity · site · role · kind · round) for Review | 240 lines |
 | `test-plan.md` | executable proof commands, preflight/provenance contract, acceptance and interaction coverage | 260 lines |
+| `gates.md` | machine-checked acceptance ledger: one gate per required outcome — runnable `CHECK`/`EXPECT`/`CWD` or manual `EVIDENCE`; engine-bound evidence, `ABANDON:` handoffs | 200 lines |
 | `state.md` | compact cursor table/key-values; no narrative log | 120 lines |
 | `evidence.md` | `EVID-###` command/action, result, timestamp if available, related AC/slice IDs, limitation | 280 lines |
 | `browser-evidence.md` | UI route/viewports/screenshots/console/network/interactions and Visual Verdict | 220 lines |
@@ -63,6 +64,8 @@ accept safe legacy basenames. Ordinary phases never rename them.
 | `review.md` | reconciled Review verdict: `## Spec` and `## Code review` accounts, deferred-finding labels/actions, drift | 240 lines |
 | `seal.md` | seal preflight, exact reviewer roster accounts, GO/NO-GO verdict and disclosures | 200 lines |
 | `ai-spec.md` | model/RAG/agent/eval/LLM-output scope for AI surfaces | 160 lines |
+| `windows.md` | deferral-marker waiver ledger: one `- path | marker | reason` row per introduced marker; `check windows` fails on unwaived hits | 120 lines |
+| `notes.md` | `NOTE-###` anchored notes — rationale/warnings bound to a verbatim quote in one repository file; `note check` regrades anchors and drift blocks seal | 160 lines |
 
 For visual pairs load only matching [playbooks](visual-playbooks/index.md); use
 the [required outline headings](visual-playbooks/outline-template.md).
@@ -158,6 +161,23 @@ Apply [[`context-hygiene.md`](standards/context-hygiene.md) dispatch packets](st
 for byte-size checks and lossless retrieval; budget overrides neither rewrite protected
 history nor require loading it all.
 
+## Anchored notes
+
+`notes.md` carries agent-authored knowledge bound to code it describes — a rationale,
+warning, or review stop that must not silently drift when the code moves or changes.
+Write it only through `devrites-engine note add <slug> <subject> <quote> <title>
+[body]`: the engine assigns `NOTE-###` IDs, stores the subject path and verbatim
+`quote`, and keeps the file parseable. One note per fact; quote the smallest
+contiguous run that identifies the anchor (identifiers, literals, signatures —
+whitespace is normalized, other edits stale it).
+
+`note list` and `note check` regrade every anchor: `exact` (quote found in subject),
+`moved` (quote lives in exactly one other file — `note check --repair` rewrites the
+subject), `stale`/`ambiguous`/`lost` otherwise. Dependency and workspace trees
+(`node_modules`, `.devrites`, vendor, build output) never count as relocation.
+`check seal` refuses malformed notes and non-exact anchors; fix or `note rm` them,
+never attest past them.
+
 ## Native readiness ownership
 
 `decision-coverage.md` owns topology; `test-plan.md`, executable proof; `eng-review.md`,
@@ -214,6 +234,11 @@ unless the stated reason makes the boundary irreducible.
 
 ## Read next by phase
 
+Run `devrites-engine next <slug>` at phase entry for the minimal remaining path
+(current phase, open questions, missing artifacts, next `/rite-*` command), then
+read the phase row below — or hand `devrites-engine context <slug> --phase <p>`
+to the engine and read the bundle it emits.
+
 | Phase | Read |
 | --- | --- |
 | spec | `README.md`, `brief.md`, `spec.md`, `references.md`, `questions.md` |

package/pack/generated/codex/skills/devrites-prose-craft/SKILL.md

@@ -3,6 +3,8 @@ name: devrites-prose-craft
 description: Rewrite prose to remove AI tells while preserving meaning and voice. Use for artifacts, replies, commits, or PR copy; not code comments or UI craft.
 user-invocable: false
 ---
+<!-- loads: {"always":["devrites-lib/reference/standards/prose-style.md"],"triggers":{"word-choice":["devrites-prose-craft/reference/banned-phrases.md"],"structure":["devrites-prose-craft/reference/structures.md"],"examples":["devrites-prose-craft/reference/examples.md"]}} -->
+> Read-set manifest: `devrites-engine context [slug] --skill devrites-prose-craft` bundles every file named below into one deduplicated read. Trigger names map to the conditional rules in the sections that follow.
 
 # devrites-prose-craft: prose that reads human
 
@@ -56,7 +58,7 @@ In detect-only, report Tier 1A (figurative filler) separately from Tier 1B (word
 - Always read [`prose-style.md`](../devrites-lib/reference/standards/prose-style.md) for the two
   registers, preservation contract, and core checks.
 - Load [`reference/banned-phrases.md`](reference/banned-phrases.md) when word choice or tone is
-  the problem.
+  the problem (trigger `word-choice`).
 - Load [`reference/structures.md`](reference/structures.md) when sentence shape, rhythm, or
   formatting is the problem.
 - Load [`reference/examples.md`](reference/examples.md) when the target artifact's shape is

package/pack/generated/codex/skills/devrites-source-driven/SKILL.md

@@ -3,6 +3,8 @@ name: devrites-source-driven
 description: Verify uncertain framework or library behavior in installed source or official docs. Use for unfamiliar APIs; not internal code.
 user-invocable: false
 ---
+<!-- loads: {"always":["devrites-lib/reference/standards/core.md","devrites-lib/reference/standards/tooling.md"],"triggers":{"agents":["devrites-lib/reference/standards/agents.md"]},"workspace":["state.md","spec.md","plan.md","decisions.md","evidence.md","references.md"],"workspaceByRole":{"evidence-scout":["state.md","spec.md","plan.md","references.md"]}} -->
+> Read-set manifest: `devrites-engine context [slug] --skill devrites-source-driven` bundles every file named below into one deduplicated read.
 
 # devrites-source-driven: verify, don't guess
 

package/pack/generated/codex/skills/devrites-ux-shape/SKILL.md

@@ -3,6 +3,8 @@ name: devrites-ux-shape
 description: Shape UX/UI direction, states, and interactions before code. Use for screens, forms, dashboards, or settings; not for implementation or polish.
 user-invocable: false
 ---
+<!-- loads: {"always":["devrites-ux-shape/reference/brief-template.md","devrites-ux-shape/reference/visual-direction-probe.md","rite-build/reference/frontend-trigger.md","devrites-frontend-craft/reference/design-references.md","devrites-frontend-craft/reference/quality-standards.md"],"triggers":{"afk":["devrites-lib/reference/standards/afk-hitl.md"]}} -->
+> Read-set manifest: `devrites-engine context [slug] --skill devrites-ux-shape` bundles every file named below into one deduplicated read. Trigger names map to the conditional rules in the sections that follow.
 
 # devrites-ux-shape: plan the UX/UI before code
 

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

@@ -5,6 +5,8 @@ argument-hint: "[verb [args...]]"
 user-invocable: true
 disable-model-invocation: true
 ---
+<!-- loads: {"always":["devrites-lib/reference/standards/core.md"],"triggers":{"intent":["devrites-lib/reference/intent-map.md"],"menu":["rite/reference/menu.md"],"dispatch":["devrites-lib/reference/parallel-dispatch.md"],"reply":["devrites-lib/reference/reply-contract.md"]}} -->
+> Read-set manifest: `devrites-engine context [slug] --skill rite` bundles every file named below into one deduplicated read. Trigger names map to the conditional rules in the sections that follow.
 
 # $rite: DevRites menu + router
 

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

@@ -4,6 +4,8 @@ description: Adopt an existing codebase into DevRites by reverse-engineering cur
 argument-hint: "[path or area to adopt] [+ what you want to build next]"
 user-invocable: true
 ---
+<!-- loads: {"always":["rite-adopt/reference/adoption.md","rite-adopt/reference/anti-patterns.md","rite-polish/reference/ledger.md"],"triggers":{}} -->
+> Read-set manifest: `devrites-engine context [slug] --skill rite-adopt` bundles every file named below into one deduplicated read. Trigger names map to the conditional rules in the sections that follow.
 
 # $rite-adopt: onboard existing code
 

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

@@ -5,6 +5,10 @@ argument-hint: "[idea] [--ship|--yolo] [--max-slices N] [--parallel N] [--full]
 user-invocable: true
 ---
 
+<!-- loads: {"always":["devrites-lib/reference/standards/core.md","devrites-lib/reference/standards/afk-hitl.md","devrites-lib/reference/standards/one-shot-actions.md","devrites-lib/reference/orchestration-profiles.md","devrites-lib/reference/standards/acceptance-preserving-reslice.md","rite-autocomplete/reference/decision-policy.md","rite-autocomplete/reference/loop.md","rite-autocomplete/reference/stop-conditions.md"],"triggers":{"workflow-artifacts":["devrites-lib/reference/standards/workflow-artifacts.md"]},"workspace":["state.md","spec.md","plan.md","tasks.md","questions.md","decisions.md","drift.md","evidence.md","test-plan.md"]} -->
+> Read-set manifest: `devrites-engine context <slug> --phase autocomplete` bundles every file named below into one deduplicated read. Trigger names map to the conditional rules in the sections that follow.
+
+
 # $rite-autocomplete: full lifecycle, unattended
 
 Run every phase after one clarification window. Irreversible-risk,
@@ -21,7 +25,8 @@ Read [`core.md`](../devrites-lib/reference/standards/core.md) and [`afk-hitl.md`
 [`one-shot-actions.md`](../devrites-lib/reference/standards/one-shot-actions.md) before any stop/continue or execution decision involving a
 consumptive action. Before honoring a terminal cursor that names missing
 executable controller/harness/bundle bytes or a missing writer, read
-[`workflow-artifacts.md`](../devrites-lib/reference/standards/workflow-artifacts.md). Before classifying any Reslice, read `.agents/skills/devrites-lib/reference/standards/acceptance-preserving-reslice.md`.
+[`workflow-artifacts.md`](../devrites-lib/reference/standards/workflow-artifacts.md)
+(trigger `workflow-artifacts` — only when a workspace declares them). Before classifying any Reslice, read `.agents/skills/devrites-lib/reference/standards/acceptance-preserving-reslice.md`.
 
 <!-- BEGIN RESLICE ROUTE-TO-ACTION -->
 - `FOLD` → keep Plan repair/affected Vet internal; no stop solely for topology/count.

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

@@ -75,7 +75,13 @@ Workspace files carry state; chat does not. Read and execute each phase skill:
 
 Before advancing, check
 [stop-conditions.md](stop-conditions.md). After source edits, discard stale pass
-evidence. Re-read the active workspace before each phase.
+evidence. Re-read the active workspace before each phase. On a cold resume or
+new activation, run `devrites-engine check regression <slug>`: `BLOCKED` names a
+durable fact lost since the last checkpoint — restore or route it through its
+owning phase before continuing; `unproven` does not block. After each phase's
+durable advance lands (green check loop, checkpoint commit), run
+`devrites-engine check regression <slug> --update` to ratchet the progress
+floor; `--update` never excuses an unreconciled regression.
 
 ## Sequence continuation