devrites 7.1.2 → 7.2.1

package/pack/generated/dsh/skills/devrites-lib/reference/standards/agents.md

@@ -0,0 +1,231 @@
+# Agent orchestration
+
+> Applies when: dispatching or admitting any devrites-* role; the source-writing boundary.
+
+Follow DevRites policy and [`depth profiles`](../orchestration-profiles.md).
+
+## Authority
+
+<!-- root-only -->
+- Root owns scope, questions/decisions/results, `.devrites/**`, phase transitions — not product source/tests; vetted executable workflow artifacts follow [`workflow-artifacts.md`](workflow-artifacts.md).
+- Every named role runs; unavailable → HITL, never skip/substitute.
+<!-- /root-only -->
+- Among lifecycle `devrites-*` specialists, only bounded wright writes product
+  source/tests; others inspect an immutable candidate. The independent `/rite-fast`
+  lane instead uses only its existing `fast-builder` as writer under its own roster;
+  never substitute a lifecycle role. Root remains source/test nonwriter.
+- Leaves never invoke agents, ask humans, change phase, push, install/deploy, migrate live data, or act irreversibly; they return evidence/proposals for root acceptance. Sole exception: one local unpushed transfer commit by an eligible native-worktree `devrites-slice-wright` — transport, not shipping authority or a checkpoint.
+
+<!-- root-only -->
+## Agents
+
+| Agent |
+| --- |
+| `devrites-evidence-scout` |
+| `devrites-plan-drafter` |
+| `devrites-upgrade-planner` |
+| `devrites-proof-runner` |
+| `devrites-strategy-reviewer` |
+| `devrites-plan-reviewer` |
+| `devrites-doubt-reviewer` |
+| `devrites-spec-reviewer` |
+| `devrites-code-reviewer` |
+| `devrites-test-analyst` |
+| `devrites-frontend-reviewer` |
+| `devrites-security-auditor` |
+| `devrites-performance-reviewer` |
+| `devrites-devex-reviewer` |
+| `devrites-simplifier-reviewer` |
+| `devrites-retrospector` |
+| `devrites-slice-wright` |
+
+Files own briefs; [`parallel-dispatch.md`](../parallel-dispatch.md) owns rosters.
+<!-- /root-only -->
+
+<!-- root-only -->
+## Native invocation
+
+Skills name exact fresh roles, omit native fields;
+hosts spawn/wait/deliver. Root MUST NOT advance/claim completion before admitting required results;
+running/orphaned/unavailable = `gap` — no root/generic substitute.
+Where a feature workspace exists, every fresh dispatch to a named `devrites-*`
+role — wave or solo — builds its read-set with `devrites-engine context --skills-root .dsh/skills <slug>
+--phase <p> --role <role>` and tracks the launch through `devrites-engine
+dispatch <slug> open|start|seal|return` (a solo dispatch is a wave of one;
+start/return auto-record metrics). Without a workspace the plain host dispatch
+contract above applies and no engine tracking is required.
+Workflow-named skills (e.g. devrites-source-driven) are invoked inline in the root context, never dispatched as agents.
+<!-- /root-only -->
+
+## Source-writing boundary
+
+Among lifecycle `devrites-*` specialists only (independent Fast exception below):
+Claude grants only wright `acceptEdits`; Codex root is workspace-capable (children cannot elevate). Wright alone `:workspace`; others `:read-only`. Wright gets the smallest exact project-relative source/test list — no directories/globs, traversal, or `.devrites/**`; no scope widening; root rejects `git diff --name-only` extras. Never patch product source/tests in root, bypass/substitute wright, accept drift, or recreate a dispatch bridge.
+
+Independent Fast exception: `/rite-fast` uses its existing `fast-builder` write-capable
+profile, not a `devrites-*` substitute, under the exact Fast roster and lane contract.
+Only that bounded writer may edit its exact project-relative source/test paths; no
+workspace writes, scope widening, or second writer. Root remains source/test nonwriter.
+This exception grants no additional tools, permissions, phase, agent-launch, or Git authority.
+
+Isolated-worktree pilot only under [`wright-dispatch.md`](../../../rite-build/reference/wright-dispatch.md#isolated-writer-worktree-pilot): one writer, committed/clean baseline, non-submodule parent, exact transfer commit, candidate reconciliation — never parallel writers nor weaker exact-path admission. Root may materialize only exact Vet-ready workflow-artifact paths per [`workflow-artifacts.md`](workflow-artifacts.md) — not a writer dispatch or candidate mutation.
+
+Each job gets objective/exclusions, exact paths/immutable candidate, rubric/result shape, a **stop condition** (when to return), and the exact result shape; a dispatch missing them is malformed and re-issued. Briefs MUST NOT seed verdict/severity cap/conclusion/suppression. Results state status/scope, outcome, commands/escalation; wright adds paths, changed files, gates, stood decisions; results never widen scope.
+
+**Same-tree concurrent sessions claim first.** Worktree dispatch isolates
+parallel batch siblings, but two agent *sessions* (two hosts, two features, or
+a human plus an agent) can share one working tree. Before a same-tree writer
+starts, its `dispatch open` records an advisory claim with `--claim-session <id>
+--claim <path>...` and fails, creating no wave, while a live foreign session holds
+a path (without a wave: `claim add --session <id> <paths>`, keep its `<claim-id>`,
+then `claim check`); a held claim from a
+live foreign session is never merged later or overridden. Unattended, skip only
+work that needs those paths, run independent work, and re-check `claim list`
+before stopping; stop and report the holder only when nothing independent remains.
+On every host-confirmed terminal path after `add` or a claimed `dispatch open` ([unknown outcomes keep it](../parallel-dispatch.md#cancellation-and-terminal-reconciliation)),
+the wave's completing `return` releases its claim, `dispatch abandon --release`
+releases it on any other (a stop or a refused launch), and a `claim add` claim runs
+`devrites-engine claim release --session <id> --id <claim-id>`. Claims expire
+by TTL only as crash recovery; `claim list` shows who holds what. Claims are
+advisory coordination, never a substitute for the one-writer-per-worktree rule.
+Claims cover product paths only; root-authored `.devrites/**` files use
+[`workflow-artifacts.md`](workflow-artifacts.md) admission instead.
+Expiry is not proof the holder stopped: size `--claim-ttl` or `claim add --ttl <minutes>` to the
+expected write (engine max 240) and re-add before it lapses; before writing, also
+read `claim list` — a foreign `expired` claim on overlapping paths whose
+session is not proven terminal counts as held (stop and report). `dead` (engine-proven
+exited holder) or `released` is terminal: reconcile per
+[§ Cancellation](../parallel-dispatch.md#cancellation-and-terminal-reconciliation). **Failing case:**
+session B's `claim check` passes at minute 35 over session A's still-running wright.
+
+## Independence
+
+- A fresh result sees scope/paths-diff/rubric only — never another result's or the root's conclusions, severities, expected verdicts, chosen verification methods, or edited context; seeding voids the packet. Canonical workspace artifacts in the engine-generated `--role` read-set (state cursor, decisions, `strategy.md` scores, prior review records) are inputs, not seeding: a verdict they record is a historical claim the reviewer re-verifies, never this pass's conclusion. The same holds for status, readiness-checklist, or gate lines inside a read-set artifact (e.g. a `spec.md` `Status:`/`Spec gate:` line from an older workspace). Never hand-edit installed read-sets or swap them for excerpts to strip that history.
+- Never message a running read-only leaf: a mid-run note voids it like a seeded packet.
+  Root proof that lands after dispatch is weighed at reconciliation, not forwarded; a
+  leaf gap it would close (e.g. "no independent runtime run") closes there.
+- A recheck packet lists only fingerprints that same role raised, plus the correction
+  diff. Another role's finding goes to that role's recheck, never a sibling's packet.
+- **Verify the packet is clean before admitting the account.** Confirm the returned packet/trace carries no host-injected context: an automatic memory/summary banner naming an earlier phase verdict (e.g. `past Temper PASS … next is /rite-define`) or harness reminder text seeds the pass and voids it. Cancel that account — never admit it — name the lost coverage, and re-dispatch with the host's context injection disabled for that child. Tool config changes that do not stop native child auto-injection are not a fix; verify on the next spawn instead of assuming.
+- A parent-context pass contributes attributed evidence but is not independent: exclude it from independent accounting and name the lost coverage.
+- Final severity is set at reconciliation after re-verifying the claimed consequence at the cited site (reviewer severity advisory); dismissals record a reason, and true facts about neighboring code route elsewhere instead of being dismissed.
+- Conflicting required results are arbitrated by re-verifying evidence at the site; the deciding evidence is recorded, truly unresolved conflicts stay open blockers. Two results describing the same defect merge only when both defect and fix path match; otherwise the more conservative classification stands, and severity never widens without new site evidence — an overridden or demoted finding stays visible with the reason, never silently merged away.
+
+## Result admission
+
+Each required reviewer/analyst/auditor starts with exactly one:
+`Outcome: findings`, `Outcome: no-findings`, or `Outcome: gap`.
+
+**Canonical finding shape (C2 — all `devrites-*-reviewer` / auditor agents):**
+
+```text
+Outcome: <findings | no-findings | gap>
+Counts: critical=<n> important=<n> suggestion=<n> nit=<n> fyi=<n> gap=<n>
+Finding: <severity> conf <n> | <file:line or artifact section> | `<quoted cited line>` <observed result> | when <input/state/sequence> → <effect> | breaks <ID or standard §> "<quoted line>" | <minimum fix>
+Basis: <files read · commands run to reach this finding>
+```
+
+- **`findings`:** each row uses the shape above; confidence 1–10 on Critical/Important.
+  Critical/Important requires 7+, exact evidence, concrete impact, and a non-empty
+  `Basis` — a correct verdict reached by an unrecorded inspection path is unproven.
+  A Critical/Important row carries `conf <n>` in its severity cell, opens its observed
+  cell with the cited line's quote in backticks, and writes impact
+  as `when <input/state/sequence> → <effect>`; missing conf or trigger, root admits it as
+  `Unverified: <claim> — missing trigger` (stays `gap`).
+- **Proportionality:** a Critical/Important row's `breaks` quotes the line it violates:
+  a spec ID (`AC`/`REQ`/`INV`/`PROH`/`DEC`/`EDGE`) or a shipped standard rule
+  (`<standard>.md § <section>`: security, regression, principles). Root anchors the
+  quote like the `file:line` quote. A repair contract, recheck packet, earlier
+  finding or plan item (`plan.md`, `tasks.md`, `architecture.md`, `test-plan.md`)
+  only restates root's own claim and is never an anchor; quote the spec ID or
+  standard rule it traces to. No anchor, or one
+  the defect does not break,
+  admits the row as Suggestion logged `Deferred: <claim> — no spec anchor` for an
+  optional follow-up slice; it never drives a repair round. Hardening no spec line
+  asks for is a Suggestion, however plausible. The `when` must also be reachable:
+  a hostile actor enters only through a trust boundary the feature really has
+  (users, network, external systems, untrusted files). A trigger that needs one it
+  never faces — the code under test forging its own evidence, a tampering second
+  user on a single-owner dev host, a swapped remote daemon under a local dev tool —
+  is a Suggestion too. So is an environment state the feature's declared
+  environment does not have (a mount option, kernel setting or daemon location
+  absent from the target host): guard against it only when the spec names it.
+  A finding never pulls a deferred slice's scope forward.
+- **`no-findings`:** `No-findings:` names checks and inspected evidence. Bare
+  pass, empty list, or “looks good” is malformed.
+- **`gap`:** names missing/unreadable/stale input; skipped/failed required check;
+  tool/reviewer failure; or another limit. Required gaps block. A reviewer gap
+  that asks for more evidence without showing a defect is required only when it
+  quotes the anchor that demands that evidence, as Proportionality does: a spec ID,
+  an owner decision, or a shipped standard rule. Without one, root logs it
+  `Deferred: <claim> — no anchor`. Advisory gaps follow
+  [security.md § Reachability sets severity](security.md#reachability-sets-severity).
+- **Transport failure is not a finding.** A read-only leaf aborted, timed out, lost,
+  or with host-rejected output is `gap` quoting the host error. Re-dispatch one fresh
+  child with the same brief and read-set — never a resume of the failed child. The
+  retry spends any user-granted budget; ask only if it would exceed it. A second
+  transport failure of the same role is a host defect: stop for HITL with both errors
+  and `/rite-doctor`. Never design capture or retention machinery around it.
+
+Root treats results as claims; verifies proposed Critical/Important blockers
+against candidate, first running `devrites-engine check anchors --skills-root .dsh/skills <slug> <return-file>`,
+which anchors each row's quote at its cited `file:line` on the live candidate and its
+`breaks` quote, and prints the digest root confirms equals the reviewed packet's: exact → admit; found at exactly one other location → relocate,
+keeping both locations; not found or found at several → `Unverified: <claim> —
+anchor lost|ambiguous`, a gap that is never a finding, a dismissal or a repair-round
+input (exit 3). A leaf result
+produced by spawning a nested agent is `gap`, and each hidden child counts toward
+the concurrent pool and `max_agents`. Missing fields become
+`Unverified: <claim> — missing <proof>` and stay `gap` until verified/rejected
+with evidence—never silently dropped/demoted. Null/timeout/failure/malformed
+output is `gap`, never `no-findings`. Conditional `Not-applicable` must name the
+inspected scope and why its trigger did not fire. **Failing case:** parent admits a
+wright "done" with no `git diff --name-only` ⊆ path-contract (allowlist) observation.
+
+### Return budget
+
+Every read-only leaf returns rows, not prose, so the root keeps its context for
+decisions and nothing is lost in a retelling. Exempt: `devrites-plan-drafter` (its
+return is the bundle the root writes) and the wright's change evidence.
+
+- Lead with the result line (`Outcome:` for reviewers, the role's own status line
+  otherwise), then `Counts:` with the number of rows per severity or kind.
+- A reviewer, auditor or test-analyst head is strict: line 1 is
+  `Outcome: findings|no-findings|gap` (no title line above it), line 2 is
+  `Counts: key=N ...` with keys from the role's closed vocabulary:
+  `critical important suggestion nit fyi gap`, plus `contract mechanism` for
+  `devrites-plan-reviewer`, only `suggestion nit fyi gap` for
+  `devrites-simplifier-reviewer`. `findings` needs a non-`gap` count above 0;
+  `no-findings` needs every count at 0. `dispatch return --result <file>` stores
+  the return and records a malformed or inconsistent head as `gap`, never
+  `no-findings`.
+- No restated task, preamble, approach narrative or closing summary. An optional
+  `Notes:` block carries at most five lines that no row can hold.
+- Your last message is your return; the host delivers only that message. If a
+  hook, rule judge or system reminder arrives after your report, reply with the
+  complete report again, head first, with any correction inside it. Never end on a
+  reply that only answers the reminder. **Failing case:** a rule judge flagged a
+  simplifier's finished report; it answered the flag, and the host delivered that
+  answer instead of its rows.
+- Point, don't paste: cite `file:line` with at most one quoted line (160
+  characters); for a command, give the exact command, its exit code and the one
+  decisive output line. Never paste whole files, diffs, logs or test output.
+- Each row stands alone: a reader of that row alone can re-check it from its pointer.
+- The root records admitted rows verbatim, adds its own verification beside them, and
+  never rewrites, merges or summarizes a row; deduplication references rows by
+  position or ID instead of rewording them.
+
+<!-- root-only -->
+## Reconciliation
+
+Root rejects stale/out-of-scope work, dedupes by root cause, records
+accepted conclusions, and reruns only affected proof/review. Reconciliation runs
+only after every dispatch reaches a terminal classification
+([parallel-dispatch.md](../parallel-dispatch.md)); findings that do not survive stay
+visible as `withdrawn: <n> (<reason>)` in the account rather than being silently
+dropped, so a later reader can audit what was discarded and why.
+Route defects before correction: product/acceptance → Spec Drift Guard/Clarify;
+architecture/slicing/proof → Plan/Vet; source/test → wright;
+external/pre-existing → blocker/defer. Never patch downstream to hide an upstream
+defect.
+<!-- /root-only -->

package/pack/generated/dsh/skills/devrites-lib/reference/standards/anti-patterns.md

@@ -0,0 +1,50 @@
+# DevRites: universal anti-patterns
+
+> Applies when: universal rationalizations; load when tempted to shortcut any standard.
+
+The pack-wide rationalizations the agent reaches for when discipline gets in
+the way. Apply at every phase. Each `rite-*/reference/anti-patterns.md`
+extends this with phase-specific items.
+
+This file is the **single source** of the universal anti-rationalization table.
+`core.md` points here when an excuse appears.
+
+## Universal rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "I'll add the tests later." | Tests written after the fact don't drive design and miss the boundary cases the act of writing exposes. Test now or the tests you eventually write are worse. |
+| "Lint and build pass, that proves quality." | Automation proves syntax and style, not design or correctness. Never cite clean automation as evidence of good design. |
+| "It's only a small refactor while I'm in here." | Feature scope only: drive-by cleanup balloons the diff, hides intent, and gets rejected at seal. Record as an FYI follow-up. |
+| "This is a special case, the pattern doesn't apply." | Special cases multiply silently. Either they really are special (record *why* in `decisions.md`) or they're not (and the pattern wins). |
+| "The user will tell me if something is wrong." | Drift detection is the workflow's job, not the user's QA. Surface assumptions; route material questions through the Spec Drift Guard. |
+| "Generic name (`processData`, `handleItem`) is fine: the code is self-evident." | Generic AI naming is slop. Match the project's idiom; one concept gets one word across the codebase. |
+| "Better safe than sorry: add the defensive null/length check." | Over-defensive guarding is slop. Validate at boundaries; trust the core. A check inside trusted code hides bugs in the boundary. |
+| "It's faster to skip the small step." | Process shortcuts pay back later as drift, missed criteria, or unrecorded decisions. The step is the point. |
+| "I observed it pass; recording is bureaucracy." | Un-recorded pass = unproven. The next phase reads `evidence.md`, not your memory. |
+| "User clearly wants this, so I'll bypass the gate." | Gates exist for the failure modes asks miss. Honor the gate; the gate exists *because* of the ask. |
+| "The test is failing. I'll just skip it / loosen the assertion to get green." | Faking green is reward-hacking, not progress. Never delete / skip / `xfail` / `.only` / loosen a failing test: a red test means fix the code or agree the change. Diff review and dedicated test analysis treat weakening as Critical. |
+| "This project principle doesn't really apply to my case." | A declared invariant (`.devrites/principles.md`) is not advisory. Either it genuinely needs relaxing (record a scoped, dated exception a human approves) or it applies and the change is wrong. Silently routing around a principle is the defect the gate exists to catch (`principles.md`). |
+
+## Pack-wide red flags
+
+These show up at any phase and are equally damning regardless:
+
+- Touching files that aren't in `touched-files.md` "while I'm here".
+- A finding / decision / assumption recorded only in chat, not in the workspace files (it dies on `/clear`).
+- Catching the broadest possible error and continuing past it.
+- A test that asserts the implementation, not the behavior.
+- A failing test deleted, skipped, `xfail`-ed, `.only`-narrowed, or loosened to make the suite pass.
+- Commenting out code instead of deleting it.
+- A `// TODO` left in shipped code.
+- Adding a dependency or a second design system without rationale in `decisions.md`.
+- A change that violates a declared project principle (`.devrites/principles.md`) with no recorded, human-approved exception.
+- "I'll fix it in a follow-up PR" with no follow-up opened.
+
+## Where this gets loaded
+
+Phase-specific `rite-*/reference/anti-patterns.md` files extend this table with only their local cases. Load this file when the rationalization is broader than one phase.
+
+## Behavioral coverage
+
+A new behavior-shaping rebuttal needs a matching behavioral eval; prose alone does not prove the guard holds under pressure.

package/pack/generated/dsh/skills/devrites-lib/reference/standards/architecture-health.md

@@ -0,0 +1,64 @@
+# Architecture health
+
+> Applies when: an audit, vet, or seal needs a structural read on the whole
+> codebase — not the diff — and a dependency index is available.
+
+A health score compresses six structural signals into one 0–100 number with a
+letter grade. It is an *audit instrument*, not a gate: it ranks surfaces for
+attention and tracks drift between milestones. It never proves a change safe
+and never substitutes for review.
+
+## When to measure
+
+Compute a score only when a code index covers the repo (see
+[`code-index.md`](code-index.md) § Preflight). With no index,
+report `unmeasured` — a placeholder number presented as a measurement is a
+false pass. **Failing case:** an audit reports "health: 100/100" on a repo the
+instrument could not parse.
+
+## Dimensions
+
+Weight the dimensions exactly once; do not invent extra dimensions ad hoc —
+record repo-specific signals as findings instead.
+
+| Dimension | Weight | What it measures | Healthy | Warning |
+| --- | --- | --- | --- | --- |
+| Coupling | 25% | Cross-file edges per file; penalize god-file outliers (max ≫ 3× mean) and >70% cross-directory share | avg ≤3 connections | avg >10 |
+| Cohesion | 20% | Share of a directory's edges that stay inside it | ≥70% internal | <30% |
+| Circular deps | 20% | File-level dependency cycles per 100 files | 0 cycles | >5 per 100 |
+| God files | 15% | Files with >3× mean connections | none | >6% of files |
+| Orphans & dead exports | 10% | Unreferenced files; exported symbols with zero dependents (60/40 blend) | 0% orphans | >10% orphans or >5% dead exports |
+| Depth | 10% | Longest dependency chain, cycles collapsed to one hop each (SCC-condensed DAG) | ≤4 levels | >8 |
+
+Grade bands: ≥90 A · ≥80 B · ≥70 C · ≥60 D · below F.
+
+## Rules
+
+- **Measure before and after.** A score's value is the delta: record
+  before/after for structural work in `evidence.md`; a drop >3 points needs a
+  named cause, not a shrug.
+- **Count runtime edges, not type-only edges.** `import type`-style
+  relationships inform dead-code analysis but do not execute; including them
+  overstates coupling.
+- **Exclude fixtures and generated files** from orphan/dead counts — a
+  directory of test fixtures is not dead code.
+- **Depth is computed on the condensed graph.** Collapse each cycle (strongly
+  connected component) to one node first; an exact longest-path search on a
+  cyclic graph is unbounded and returns no honest number.
+- **Every recommendation names the dimension it moves.** "Improve the
+  architecture" is not an action; "extract `x/` → `y/` edge to cut cross-dir
+  coupling (Coupling, est. +8)" is.
+- **Trend over snapshots.** Keep the score per milestone in `evidence.md` or
+  the feature's audit artifact; a single reading without a baseline is a
+  weather report, not a climate signal.
+
+## Orphan and dead-export semantics
+
+An orphan file has zero cross-file runtime edges. A dead export is an exported
+top-level symbol (function/class/interface/type/enum/constant) with zero
+incoming edges — member-level symbols (methods, properties) are excluded:
+they are not meaningful architecture-level candidates and produce false
+positives. Both counts feed only this dimension; the *removal decision* for a
+dead export follows [`deprecation.md`](deprecation.md), including its
+confidence rubric — a low-confidence dead lead is a watch item, never an
+automatic deletion.

package/pack/generated/dsh/skills/devrites-lib/reference/standards/assumption-checkpoints.md

@@ -0,0 +1,42 @@
+# Assumption-delta checkpoints
+
+> Applies when: planning or vetting a slice whose scope generalizes an existing
+> boundary — the seam where a quiet assumption loses its monopoly.
+
+Most quietly imported architectural debt comes from the seam: a later change adds a
+*second case* — platform, auth method, tenant, region, source of truth — and nobody
+re-asks whether the original abstraction still names the right thing. The change that
+adds the second case is the cheap moment to ask.
+
+## The detector
+
+Scan the phase scope, spec delta, or task list for transition signals:
+
+| Signal | Shape | The question it raises |
+|---|---|---|
+| `pluralization` | A second X where exactly one existed (platform, provider, tenant, region, source of truth) | Does the identity model still name the right noun? |
+| `optionality` | A required or `only`-assumed field becomes optional | Is that field still the right anchor, or did the anchor move? |
+| `choice` | A derived value becomes chosen; a constant becomes a parameter | Has a config decision silently become a modeling decision? |
+
+Code blocks, comments, and prose that merely *mention* a trigger word do not count.
+
+## Firing the checkpoint
+
+A firing signal surfaces **one** question before the plan is finalized — not a
+redesign, one question: *does the name/model chosen when N=1 still hold at N=2?*
+
+- `detected:false` — skip the checkpoint; do not raise it.
+- `skipped` — the scope was never examined. A skipped check asserts *nothing*: never
+  record "no assumption changed" from a skipped result; skipped ≠ negative.
+- `detected:true` — ask the one question and record the answer in `decisions.md` or
+  `assumptions.md`; an answered checkpoint that leaves no trace re-fires next round.
+
+## Promote, don't add alongside
+
+When a generalization is real, the default-correct move is to **promote** the general
+representation to primary and demote the old specific one to a detail of one variant —
+not to add the new shape alongside the still-required old one, which silently
+contradicts the generalized intent.
+
+**Failing case:** `region` added as an optional column beside `primaryRegion`; every
+write now guesses which is authoritative.

package/pack/generated/dsh/skills/devrites-lib/reference/standards/audit-coverage.md

@@ -0,0 +1,107 @@
+# Coverage-led auditing
+
+> Applies when: auditing a surface larger than one feature diff — a repo, subsystem,
+> or trust boundary — where "I looked at it" must become countable coverage.
+
+A surface audit must answer *what the run covered and what it never examined* — with
+a coverage ledger, not a summary paragraph.
+
+## Coverage ledger
+
+The coordinator alone maintains the ledger; a unit is one auditable cell — surface
+(path/endpoint/command) × trust boundary × check class.
+
+States: `planned` → `assigned` → `candidate` (produced a finding candidate) →
+`covered` (evidence recorded); plus `deferred` (postponed, reason recorded),
+`blocked` (exact blocker recorded), and `out_of_scope` (declared-scope exclusion —
+never written as `covered`). `deferred` and `blocked` are honest states; a unit
+silently dropped is a lie.
+
+Instruments obey the same honesty rule: a scanner or metric that could not read
+its target reports `unmeasured`/`no_data`, never a placeholder presented as a
+measurement. A health score computed over zero parseable files is not a 100.
+When the audit covers whole-repo structure, score it per
+[`architecture-health.md`](architecture-health.md) and record before/after
+deltas as ledger evidence.
+
+## Findings carry three verdicts, not two
+
+- **`confirmed`** — complete source trace plus a bounded observed or owner-observable
+  result; names the lower-trust principal, crossed boundary, affected
+  principal/resource, and concrete effect.
+- **`needs_validation`** — a real lead blocked on one exact unresolved fact, which is
+  named. Carries **no severity**: severity without established impact is theater.
+- **`rejected`** — a disproved candidate kept with its disproof; it suppresses
+  re-raising the same unchanged claim, never coverage of its unit.
+
+Hardening notes are not findings: if one layer already prevents the attack, the
+absent second layer is a depth observation, not a vulnerability.
+
+## Finder never verifies its own find
+
+Every surviving candidate goes to a fresh verifier that did not produce it and tries
+to **disprove** it, per [`agents.md`](agents.md) § Independence — a seeded packet
+voids the verification. Promotions to `confirmed` and material changes to root
+cause, trace, reproduction, impact, or severity require fresh independent
+verification. Without that independent evidence, keep the candidate unresolved;
+a rewritten explanation is not verification.
+
+## Critics between waves
+
+After each hunting wave, a **coverage critic** — a fresh agent comparing the ledger
+with targeted source and entry-point evidence — looks for holes: unseeded surfaces,
+boundaries with no check class,
+units stuck `assigned`, `rejected` patterns suggesting a hunter fires blanks.
+Accepted discoveries become `planned` units. Coverage is `complete` only after a
+critic returns no accepted missing or reassigned unit and no unit is `planned`;
+otherwise the run is partial, and a wave or agent cap is never evidence of
+completeness. A reassigned unit gets a fresh owner; the old attempt's evidence stays
+attributed to it and is never merged into the new attempt. Reserve critic and verifier capacity
+**before** spending on hunters; a wave launched with no verification reserve hunts
+for findings nobody may claim.
+
+## Re-runs are additive, never assumed
+
+A prior ledger must be re-checked against current source — a prior commit ref is not
+evidence a path is unchanged. Prior `confirmed` carries forward only when its source
+is unchanged **and** it re-passes current verification; prior `needs_validation` /
+`blocked` / `deferred` become current work and never suppress a unit. A partial prior
+run contributes recorded evidence and gaps, never an implied "the rest is fine"; no
+prior ledger → the report says so.
+
+## Profiles scale breadth, never the bar
+
+`quick` (one hunter wave + one critic pass, coarser units), `standard` (waves to
+critic-clean, per-candidate fresh verifier), `deep` (units split per
+subsystem/lifecycle; carried records re-verified). Profiles change granularity and
+redundancy, never the evidence bar: boundary-plus-result, independent verification,
+three verdicts, and honest `deferred`/`blocked` survive every profile. A scoped run
+presents itself as partial coverage.
+
+## Budget discipline
+
+A budget counts agent invocations, not effort. Reserve critic and verifier capacity
+before spending on hunters; a budget that cannot fund reconnaissance plus required
+reserves funds nothing — narrow scope or profile instead of silently thinning
+evidence. A run exhausted mid-verification ends `incomplete` with unvalidated
+candidates still linked to `candidate` units — never relabeled, never reported
+complete.
+
+## Target execution is sandboxed
+
+When a unit requires *running* the target — a build, a test, a probe — execute
+it under containment, never in the operator's ambient environment:
+
+- No external network and no live-service probing from the audit run.
+- No credentials, tokens, or secrets visible to target-controlled processes.
+- Only commands the repository or CI itself sanctions run verbatim; invented
+  commands are findings to propose, not actions to take.
+- Output captured through the harness, not through target-written files the
+  run then trusts.
+
+An audit that executed unaudited code with ambient privileges has crossed the
+boundary it was measuring; that run's `confirmed` rows name the execution
+context so reviewers can judge contamination.
+
+**Failing case:** "no critical findings" reported while 40% of units sit `planned` —
+the honest sentence was "60% of the surface was examined."

package/pack/generated/dsh/skills/devrites-lib/reference/standards/browser-proof-checklist.md

@@ -0,0 +1,37 @@
+# Browser proof checklist
+
+> Applies when: UI proof: compact sweep before claiming a rendered/browser pass.
+
+Compact sweep only. Numbers and failing cases live in
+[`quality-standards.md`](../../../devrites-frontend-craft/reference/quality-standards.md)
+§ Focus & states, § Responsive, and § Browser chrome — do not restate a shorter
+viewport set here.
+
+- Open the real UI (never screenshot-only); check console and network for errors.
+- Before reading the builder's verdict, inventory the raw captures against the
+  required routes/states/viewports and candidate identity. Open each capture: a
+  wrong route, blank render, unexpected login wall, inconsistent dimensions, or
+  stale candidate is missing evidence. Recapture; until resolved, record
+  `cannot_verify` and block visual approval. A convincing narrative cannot repair it.
+- **Evidence matrix.** Layout-bearing states (default, long content, and every
+  role-applicable surface state from [`quality-standards.md`](../../../devrites-frontend-craft/reference/quality-standards.md) § Focus & states) × every
+  canonical viewport; interaction states at ≥1 small and ≥1 large viewport (hover
+  only with a hover-capable pointer); one keyboard traversal; a `reduce` capture when
+  motion changed; every shipped theme. Each cell holds a capture, `cannot_verify`, or
+  `not-needed (<reason>)`; an empty cell is `cannot_verify`. States must exist in source
+  — an unreachable state's capture proves nothing.
+- A capture counts only with fonts loaded, animations settled, the real route (a harness
+  or story capture is labelled and never fills a route cell) and matching candidate
+  identity. Hover, touch, iOS zoom or safe-area behaviour seen only in emulation is
+  `unverified (device)`, never a pass.
+- A finding closes only with a capture of the same route, state and viewport class on the
+  corrected candidate; a failed or incomplete capture run never counts as gone.
+  **Failing case:** a 320 px overflow closed by a clean 1440 px screenshot.
+- Browser-default chrome is judged by § Browser chrome; reflow, zoom and bounded
+  two-dimensional exceptions by § Responsive. Compare to `design-brief.md` → Visual Verdict.
+- Tooling unavailable ⇒ record fallback + limitation. Backend-only changes record
+  that disposition instead of capturing quietly; UI copy follows
+  `devrites-frontend-craft`, long-form prose follows `devrites-prose-craft`
+  ([`prose-style.md`](prose-style.md)).
+
+Detailed skill: `devrites-browser-proof`.

package/pack/generated/dsh/skills/devrites-lib/reference/standards/ci-cd.md

@@ -0,0 +1,62 @@
+# CI/CD & automation
+
+> Applies when: creating or changing a build/deploy pipeline or CI config.
+
+Read this only when creating or changing a build/deploy pipeline. [`hooks.md`](hooks.md) owns local checks, [`development-workflow.md`](development-workflow.md) owns trunk health, and [`deprecation.md`](deprecation.md) owns migrations.
+
+## Pipeline gates
+
+- Put each check at the earliest affordable stage: editor → pre-commit → pre-push → CI.
+- Keep batches small so failures are attributable and releases remain reversible.
+- Run lint → type-check → unit → build → integration → audit → E2E as applicable. A red gate stops the line; fix the defect rather than disabling the rule, weakening the test, or skipping the gate. CI is the source of truth for green.
+
+## Failure loop and ownership
+
+Read the specific failure, fix its root cause, verify locally, then push again. Do not blind-rerun a flaky pipeline. Use `devrites-debug-recovery` when a test or build failure needs reproduction.
+
+A designated Build Cop (a human/team role, not a pack agent) owns restoring a broken trunk by fixing or reverting, whichever is faster. Restoring trunk outranks feature work.
+
+## Verification economy
+
+Paid or remote validation runs once per prepared state, not per attempt: batch repairs,
+verify locally first, and never blind-retry an infra operation that already reported
+failure (deploy, migrate, seed) — read the failure output, fix the cause, then re-run.
+A green check the diff cannot affect is not re-run; an expected run that is deliberately
+skipped is named in the report, not omitted. Capture failure output as an artifact so the
+next attempt starts from evidence, not memory.
+
+## Deploy versus release
+
+Keep incomplete or risky behavior disabled behind a flag so deploy and release remain separate and rollback does not require a redeploy. Every flag has an owner and a removal trigger; remove it through the [`deprecation.md`](deprecation.md) expand/contract path.
+
+## Deployment order and configuration
+
+- Derive an explicit order for schema, application, worker, contract, config, and flag
+  changes. Prove the system remains safe at every intermediate old/new combination;
+  "deploy together" is not an atomicity guarantee across units.
+- Validate required configuration at startup or the earliest safe boundary. Record names,
+  owners, environments, safe defaults, and rollback values without recording secrets.
+  A staging value copied by memory is not production evidence; a configuration mismatch
+  blocks exposure until the exact target value/owner is verified.
+- Documentation drift in commands, configuration, migration order, or rollback steps is a
+  delivery defect: update the canonical doc and execute the documented path before exposure.
+- Migration and destructive steps apply [`data-integrity.md`](data-integrity.md); service,
+  queue, webhook, and cache changes apply
+  [`integration-reliability.md`](integration-reliability.md). Their recovery/observability
+  gates precede exposure.
+- Feature flags separate exposure only when both states are tested, the off path preserves
+  current behavior, and disabling the flag stops the risky effect. A flag cannot undo an
+  already destructive schema or data change. Each flag names its removal trigger (full
+  rollout or kill); a flag past its trigger is dead code ([`deprecation.md`](deprecation.md)).
+
+## Secrets
+
+Commit `.env.example` without values; never commit real `.env` files. Inject CI secrets from the platform store and scope them to the job. Build runners do not receive production credentials.
+
+## Slow pipelines
+
+When wall time exceeds roughly ten minutes, measure before and after. Improve in order: cache dependencies, parallelize independent jobs, path-filter, shard the slow suite, re-tier genuinely slow tests, then consider larger runners.
+
+## Scope
+
+Change only the pipeline surface in scope; record wider CI redesign as follow-up work.