devrites 7.1.1 → 7.2.0

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

@@ -0,0 +1,55 @@
+# Documentation
+
+> Applies when: writing docs, comments, READMEs; recording decisions.
+
+Document intent/decisions; public inputs, outputs, errors, and gotchas; non-obvious
+constraints; and real build/test/run commands. Update with behavior; prefer one runnable
+example. Do not restate code or types.
+
+## Drift check (docs describe what runs)
+
+A documented command/example that no longer runs is a **documentation-drift finding** at
+review/polish: run it — failure plus output is the evidence. A behavior change updates the
+doc or records the divergence; doc and code never hold contradictory "truths".
+
+## Record decisions
+
+- Capture significant context, decision, consequences, accepted trade-off, change trigger,
+  and why viable alternatives lost. DevRites uses `decisions.md` for feature decisions.
+- ADRs move `PROPOSED → ACCEPTED → SUPERSEDED / DEPRECATED`. Preserve accepted history;
+  a replacement ADR cites and supersedes the old one rather than rewriting it.
+
+## Promote durable guidance
+
+Promotion is maintenance of an existing authority, not a new memory system.
+
+1. **Trigger:** the same reviewed correction appears in at least two distinct features, or
+   one explicit product/architecture decision has durable rationale. A one-off, generic,
+   stale, or merely inferred observation does not trigger promotion.
+2. **Ground:** verify each current claim against live authoritative repository sources.
+   Report the source and currentness signal. Unverifiable means `unknown`, not false.
+3. **Scope:** state when the guidance applies and does not apply. Reject a candidate whose
+   observable trigger cannot be named. If final code/tests/docs already recover the
+   reasoning, reject or consolidate the lesson; promote only the missing durable constraint.
+   **Failing case:** a regression test already explains input rejection, yet a second
+   generic "validate input" rule is added with no lost reasoning identified.
+4. **Own and expose:** choose one existing canonical owner (`AGENTS.md`/`CLAUDE.md`, a scoped
+   standard, or an ADR) and name the phases, agents, or contributors that discover it and
+   how (direct read, index link, or existing on-demand route).
+5. **Reconcile:** search current guidance for duplicates, contradictions, and supersession.
+   Update, narrow, replace, or retire contradicted guidance at its owner; do not append a
+   competing rule. Record the conflict/retirement disposition.
+6. **Approve:** show evidence and the exact durable edit before writing; user approval is
+   required. Never create a learning ledger, index, queue, score, or parallel authority.
+
+Long reference material stays behind its existing on-demand route.
+
+## Living documents
+
+Canonical documents are updated, not appended to. When truth changes, rewrite the
+owning section in the present tense; sealed artifacts take dated deltas through the
+owning rite instead ([`core.md`](core.md) #4). Pick a steering verb deliberately —
+`create`, `consolidate`, `split`, `trim`, `retire` — rather than letting the last-opened
+file absorb every new topic. Document what code cannot own (contracts, invariants,
+decisions, rationale); a doc that restates implementation drifts the day it lands.
+Sparse is correct — never pad a document to look complete.

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

@@ -0,0 +1,129 @@
+# Duplicate code
+
+> Applies when: a review or polish pass needs near-duplicate leads that survive
+> renaming, or a dup finding needs a dismissal that persists.
+
+`devrites-engine check dup` is the deterministic scanner. It normalizes source
+(strips comments, collapses strings, canonicalizes identifiers and literals),
+matches token shingles between files, clusters overlapping matches, and prints
+advisory clusters — **leads**, not findings. The engine never judges whether a
+cluster is worth merging; that decision is semantic and belongs to the
+reviewer. Successful scans exit 0 even with clusters; usage and operational
+errors, including incomplete scans, exit 2.
+
+## Running it
+
+```text
+devrites-engine check dup [slug] --worktree|--staged|--base <ref>|--all
+    [--min-lines n] [--threshold f] [--ignore-file <path>]
+    [--limit n] [--exclude <csv>]
+```
+
+- `--staged` / `--worktree` / `--base <ref>`: scan the repo, then print only
+  clusters with a unit overlapping the diff's changed hunks, marked `*`. Pick
+  the mode matching the diff under review: `--base <ref>` when the feature's
+  commits are landed (the common `/rite-review` case), `--staged`/`--worktree`
+  for uncommitted diffs. `--staged` reads index blobs for every comparator and
+  excludes untracked files, regardless of working-tree edits or deletions.
+  Keep the index stable during the scan. Other modes read working-tree bytes.
+- `--all`: whole-repo triage, includes untracked source files. Use in
+  `/rite-polish` or `/devrites-audit` passes.
+- `--min-lines` (default 8): minimum meaningful overlap. Lower it for tiny
+  helper-heavy languages, raise it to cut boilerplate noise.
+- `--threshold` (default 0.6): minimum similarity score per reported pair.
+- `--exclude`: extra path prefixes to skip (fixtures, generated code).
+- `dup: scanned … units` in the header is the coverage line — a scan of 3
+  files in a 300-file repo proves nothing.
+
+## Evidence limits
+
+This is a bounded heuristic, not exhaustive duplicate detection. The scanner
+limits eligible files (8,192), source bytes (64 MiB total, 1 MiB per file),
+Git listing/diff output (16 MiB), repeated-shingle postings, pair anchors, and
+reported clusters. Normalization loses language semantics; a successful scan
+with no leads does not prove the repository has no duplication.
+
+No eligible input and intentional generated exclusions are reported explicitly
+with exit 0, without claiming a successful source scan. Unreadable/non-regular
+source, unresolved index entries, Git failures, and input resource limits exit 2.
+A partial scan may print available leads, but never an `ok` verdict or a success
+metric. Generated exclusions are counted separately from unavailable input.
+Repeated options, conflicting modes, missing/flag-like values, and nonfinite
+thresholds fail before scanning or metrics. Diff helpers and text conversion
+are disabled so configured executables cannot change the inspected evidence.
+
+## Output shape
+
+```text
+dup: scanned 42 files (2 skipped), 17 units; ignore-file .devrites/dup-ignore
+dup: 2 cluster(s) (1 ignored)
+cluster 1 (a1b2c3d4e5f6) score 0.93:
+  * engine/a.go:10-58
+    engine/b.go:120-168
+cluster 2 (f6e5d4c3b2a1) score 0.81:
+    pkg/x/util.py:30-70
+    pkg/y/util.py:14-54
+```
+
+`*` marks a unit that overlaps the diff's changed lines. The hex after
+`cluster N` is the cluster's stable hash.
+
+## Triage each cluster
+
+For every reported cluster a reviewer returns exactly one verdict:
+
+| Verdict | When | Action |
+|---|---|---|
+| **merge** | Same logic, same contract, no behavioral reason to differ | Finding: extract a shared helper or call the canonical implementation. Name which unit survives. |
+| **keep** | Convergent code (test scaffolding, protocol mirrors, intentional fork points) | Record the cluster hash in the ignore ledger with a one-line reason. |
+| **watch** | Similar now, likely to diverge — copied seed that is about to change | FYI finding noting the drift risk; do not ignore. |
+
+Ranking boosts distant matches across directories or far apart within one file.
+Distance is a triage hint, not proof that two contracts are interchangeable.
+Check whether fixes to one copy should also apply to the other.
+
+A `merge` verdict (cluster or reimplemented-elsewhere twin) states the compared contract
+(inputs, outputs, errors, side effects, ordering), each unit's callers, and the tests
+protecting each copy. Any contract difference is `keep` or `watch`, not merge. When the
+survivor's tests miss the removed copy's callers, the finding adds a characterize-first
+step. A merge without the comparison is admitted only as an FYI lead. **Failing case:** two
+parsers score 0.9; one errors on empty input, the other returns a default; "merge" is wrong.
+
+## Ignore ledger
+
+`.devrites/dup-ignore` (project-root default; `--ignore-file` overrides) holds
+one cluster hash per line, `#` comments allowed:
+
+```text
+a1b2c3d4e5f6  # test scaffolding mirrors on purpose — do not merge
+```
+
+The hash derives from normalized code *content*, not line numbers. It survives
+renames, comment churn, literal tweaks, and line moves, but **changes when the
+code's structure changes** — a dismissed cluster that gets edited resurfaces
+for re-triage. This is intentional: a ledger entry must never permanently
+blind the scan.
+
+Rules:
+
+- Never add a hash without reading both units — an unread dismissal is a gap.
+- Judge member pairs, not the cluster: a hash is ignored only when every pair is `keep` and
+  one line explains it. A mixed or uncertain cluster gets a finding or `watch`, never an
+  ignore line, whatever the report volume. **Failing case:** A~B is a real copy, B~C is
+  coincidental, and the A~B~C hash lands in the ledger.
+- Write the reason on the same line after `#`; a bare hash is an unexplained
+  dismissal and counts as a skipped check.
+- Do not commit-ignore clusters introduced by the *current* diff — a `*` unit
+  needs a verdict (merge/keep/watch), not suppression.
+
+## Reporting dup findings
+
+Dup findings use the C2 shape like any other finding, plus the cluster hash so
+the dismissal ledger can reference it:
+
+```text
+Finding: Suggestion | engine/a.go:10 | cluster a1b2c3d4e5f6 duplicates engine/b.go:120 (score 0.93) | fixes to one will drift from the other | extract shared helper `dupNormalize` into engine/internal/lib
+```
+
+A reviewer that ran `check dup` and found nothing reports it under
+`No-findings:` / `Basis:` (`dup: 0 clusters over 42 files`) — not by silence.

package/pack/generated/dsh/skills/devrites-lib/reference/standards/edge-case-trace.md

@@ -0,0 +1,94 @@
+# Edge-case trace
+
+> Applies when: a boundary, branch, or failure mode changes in spec, plan, diff, or proof.
+
+Use this when requirements, plans, diffs, or proof change a boundary, branch,
+validation rule, deletion contract, retryable action, or claim that a path is safe.
+The trace finds relevant cases, records why irrelevant ones were dismissed, and prevents
+confidence from turning an untested negative claim into a pass.
+
+## Scope before enumeration
+
+Name the observable surface, caller/actor, state or data it owns, external boundaries,
+and the must-NOT outcome the author would reject even if the happy path worked. Do not
+expand into a whole-system checklist: a class applies only when the changed surface can
+reach it.
+
+## Closed probe classes
+
+Probe each relevant class once:
+
+| Class | Questions |
+| --- | --- |
+| Boundary | Empty/missing, minimum/maximum, off-by-one, oversized, invalid encoding/shape. |
+| State | Initial, repeated, stale, terminal, illegal transition, interruption and resume. |
+| Ordering | Duplicate, out-of-order, retry, partial completion, clock/time-zone boundary. |
+| Concurrency | Competing writer, lost update, cancellation, race, deadlock or resource exhaustion. |
+| Authority | Unauthenticated, unauthorized, wrong tenant, forged identity, privilege increase. |
+| Dependency | Timeout, partial/invalid response, rate limit, outage, version/config mismatch. |
+| Persistence | Transaction split, crash, migration/backfill restart, rollback, retention/deletion. |
+| Compatibility | Old/new reader or writer, caller not updated, feature-flag off/on, environment difference. |
+| Wiring | Code exists but is not registered, called, awaited, persisted, emitted, or consumed with real data. |
+| Removal | Deleted behavior, caller, data, telemetry, docs, or fallback has no surviving owner. |
+
+Route detailed applicable cases to
+[`repository-topology.md`](repository-topology.md),
+[`data-integrity.md`](data-integrity.md),
+[`integration-reliability.md`](integration-reliability.md), or
+[`security.md`](security.md); do not repeat those standards here.
+
+## Trace procedure
+
+1. **Walk explicit paths.** Follow every changed condition, loop exit, error, and
+   boundary value to the nearest observable outcome.
+2. **Walk fixed-set siblings.** A special case for one enum/status/role/mode implies
+   every untouched sibling is a path to check.
+3. **Follow real wiring.** Verify existence, substance, registration/call path, and
+   real data flow. A complete-looking implementation can still be hollow, orphaned,
+   or a stub.
+4. **Check negative intent.** Ask what silently permitted outcome would violate a
+   requirement, invariant, non-goal, or security boundary. Add a prohibition only
+   when bespoke intent is not already owned by a standard.
+5. **Check removal.** Name the contract removed code carried and its surviving owner,
+   or cite the accepted decision that retires it.
+
+## Disposition and evidence
+
+Every applicable case receives one status:
+
+- `covered`: mapped to a REQ/AC and positive discriminating test or observed runtime proof;
+- `backstop`: an independent held-out, property/metamorphic, or direct behavioral check
+  names the wrong outcome it would detect — and is **exogenous**: not produced or
+  executed by the same code path it validates (a check the changed code also controls is
+  `covered` evidence, not a backstop);
+- `dismissed`: unreachable or irrelevant with a concrete reason and supporting evidence;
+- `unresolved`: a material case lacks a fact or proof surface and blocks the owning gate.
+
+Judgment may dismiss a demonstrably irrelevant case; it cannot prove behavior. When a
+case is not inferable from available evidence, say `unresolved`/`cannot_verify` rather
+than estimating confidence upward.
+
+## Backstop honesty (fail-closed)
+
+A row marked `covered` or `backstop` **must** name an evidence class: test path,
+command output, observed runtime, or an independent held-out/property check. A row
+with disposition but **no** evidence class is **`cannot_verify`** at Prove/Seal — not
+a pass.
+
+**Failing case:** the happy-path suite is green, the trace lists "error path handled"
+with no test or runtime proof → Prove blocks until the row gains a discriminating
+surface or moves to `unresolved`.
+
+## Outputs
+
+Spec records relevant cases in **Edge Coverage** and bespoke negative intent in
+**Prohibitions**. Plan/Vet maps applicable cases to a slice, recovery, and proof. Review
+reports only reachable gaps:
+
+```md
+Finding: <severity> | path:line | <trigger> reaches <unhandled outcome> | <observable harm> |
+<minimal handling>; missing proof: <test/signal>.
+```
+
+Use the caller's severity scale. Do not create a separate edge score, pad rows with
+irrelevant classes, or report a case already handled and proven.

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

@@ -0,0 +1,114 @@
+# Elicitation: a move-set for the thinking phases
+
+> Applies when: a thinking phase needs more than the default review shape for a section.
+
+The thinking phases (`/rite-temper` on the spec, `/rite-vet` on the plan) default to one shape each.
+A pre-mortem, a plan review. That's a floor, not a ceiling. When a section needs deeper thought,
+this is the menu you reach into: named reasoning techniques, each with the shape it produces, so
+"make this stronger" becomes a concrete move instead of a vibe.
+
+## How to use it (progressive: no ceremony by default)
+1. Look at the **one section** in front of you (a requirement, a risk, an estimate, a boundary).
+2. Read its **risk**, then pull the 3-5 techniques below whose *When to reach for it* matches.
+3. Present them as a short numbered menu; the human picks one (or `skip`).
+4. Run that technique on that section, apply the result, move on.
+5. **No-yield exit:** when the technique surfaces nothing that changes the section — no
+   new requirement, mitigation, estimate change, or blocking question — record
+   `elicitation: <technique> — no yield` in the phase artifact and stop offering menus
+   for that section. **Failing case:** repeated technique menus on a settled section are
+   ceremony, not diligence; a second menu without new section input is a process defect.
+
+Selection is by the section's risk, not taste. Reach for the row that fits:
+
+| The section is… | Reach for |
+|---|---|
+| an irreversible / boundary / auth / data-model decision | Red-Team vs Blue-Team · Assumption Audit · Pre-Mortem |
+| a vague or contested requirement | Steelman-then-Attack · Devil's Advocate · Five Whys |
+| an estimate, sizing, or a "how long / how risky" | Delphi · Reference-Class Forecast |
+| a design with more than one plausible shape | Tournament (A vs B) · Inversion · Analogy Mapping |
+| a plan or patch that may be solving the wrong problem | Backward Chain |
+| a spec that feels *too* big or *too* small | Scope Extremes (MVP vs Gold-plate) · YAGNI Pass |
+| a risk surface you suspect is under-explored | Chaos Scenarios · Edge-Case Hunt · Second-Order Effects |
+
+## The techniques
+
+Each entry is **name (when to reach for it) the shape it produces** (`→` reads "then").
+
+### Sharpening a claim
+- **Steelman-then-Attack:** a requirement or approach you're inclined to accept. Build the
+  *strongest* case for it → then attack that strongest form. Survives → keep; falls → revise.
+- **Devil's Advocate:** consensus formed too fast. One voice argues the opposite in good faith →
+  surface the objection the room skipped.
+- **Assumption Audit:** a plan resting on unstated beliefs. List every assumption the section
+  makes → mark each *load-bearing / verified / unverified* → the unverified load-bearing ones are
+  the work.
+- **Five Whys:** a stated requirement whose *reason* is fuzzy. Ask "why" five times down from the
+  ask → reach the root need (often narrower or different than the surface ask).
+
+### Stress-testing a decision
+- **Pre-Mortem:** before committing an irreversible choice. Assume it's six months later and this
+  failed → write the failure story → each cause becomes a mitigation or a blocking question. (This
+  is `/rite-temper`'s default; the others deepen it.)
+- **Red-Team vs Blue-Team:** a security, trust-boundary, or adversarial-input surface.
+  `defense → attack → hardening`: state the defense, attack it as a hostile party, harden the gap.
+- **Inversion:** "how do we make X good?" stalls. Ask instead "how would we *guarantee X fails*?"
+  → invert each failure into a requirement.
+- **Second-Order Effects:** a change that touches shared surface. For each first-order effect ask
+  "and then what?" twice → surface the downstream consequence the diff hides.
+- **Backward Chain:** a plan or patch that may be solving the wrong problem. Write the desired end
+  state as one checkable sentence → ask "what must be true immediately before it?" → recurse to the
+  current state → any planned step that does not land on the chain is wrong-direction work; name the
+  tempting one explicitly.
+
+### Sizing and estimating
+- **Delphi:** an estimate one person is anchoring. Gather independent estimates *without* seeing
+  each other → reveal → discuss the spread → re-estimate → converge. Kills anchoring.
+- **Reference-Class Forecast:** "this'll be quick." Find 3 past changes of the same *class* → use
+  their actual cost as the base rate, not the inside view.
+
+### Widening the option space
+- **Tournament (A vs B):** two plausible designs. Put them head-to-head on the *decision hinge*
+  (the one axis that differs) → pick on that axis, not on a feature checklist.
+- **Analogy Mapping:** a novel problem. "What is this *like* that's already solved?" → borrow the
+  solved structure, note where the analogy breaks.
+- **Scope Extremes:** a spec of uncertain size. Describe the *MVP* (smallest thing that ships
+  value) and the *gold-plated* version → the right scope is usually named by the gap between them.
+- **YAGNI Pass:** a plan carrying "might need it later." For each speculative piece, demand a
+  *current* acceptance criterion → no criterion, cut it to a follow-up.
+
+### Finding what's missing
+- **Edge-Case Hunt:** a happy-path-shaped spec. Walk empty / boundary / invalid / concurrent /
+  huge-or-weird input for each element → each uncovered case is a missing criterion.
+- **Chaos Scenarios:** a system with external dependencies. "What if the DB is down / the API
+  times out / the clock jumps / the input is hostile?" → each becomes a failure-mode requirement.
+- **Completeness Critic:** end of a section. Ask only "what's *missing*: a modality not covered, a
+  claim not verified, a flow with no path?" → the answer is the next round of work.
+
+## The one rule
+Run the technique on the **section in front of you**, not the whole document: a move applied to
+everything is a move applied to nothing. Record what it changed in the phase artifact (a new
+requirement, a mitigation, a blocking question), not just that you ran it.
+
+## Asking mechanics
+
+- **Batch 2–4 independent questions;** ask serially when one answer determines the next
+  question or the question is an approval gate.
+- **Never ask for the discoverable** — repo, docs, prior artifacts, and conversation
+  first; a question whose answer sits in a file is a stall dressed as diligence.
+- **One decision per question** with enough context to answer without reopening files;
+  recommend a path and name its trade-off — never raw unevaluated options.
+- **At an approval gate, state the defaults you chose** so a wrong assumption gets
+  corrected before it ships.
+- **Never continue past a question by inventing the answer** — headless sessions report
+  the unresolved decision instead of assuming it.
+- **A skipped, declined, or timed-out answer is `unanswered`, not approval.** A
+  proposal, silence, or timeout never becomes a decision. Continue only work the
+  open decision cannot affect; when the unanswered question blocks scope,
+  spending, publication, or anything irreversible, stop and name the specific
+  unresolved choice — do not reissue the same question as if nonresponse were an
+  error.
+- **No question tool → numbered text fallback.** Two to four concrete options,
+  each with its trade-off, one marked as the recommendation, and a free-text
+  escape. A recommendation is labeled, never pre-selected.
+
+A project can append its own house techniques to this file: same entry shape — **name (when to reach for it)** → the shape it produces.

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

@@ -0,0 +1,49 @@
+# Error handling
+
+> Applies when: code can fail; error paths, messages, retries, partial state.
+
+Errors are part of the contract, not an afterthought. Make failure loud, local, and
+recoverable.
+
+## Fail fast
+- Validate preconditions at the top; stop the moment state is invalid, close to the root
+  cause. Don't let bad data propagate and surface as a confusing failure three layers
+  later.
+
+## No silent catches
+- Never swallow an error to make a problem "go away", that hides bugs and corrupts
+  state silently.
+- Catch the **narrowest** error you can handle, not a blanket catch-all. A
+  bare/broad catch masks unrelated failures.
+- If you catch, either recover meaningfully, or rethrow/wrap with added context. Don't
+  log-and-continue past an error you didn't handle.
+
+## Classify the outcome before retrying
+
+Never retry blind — match the outcome first:
+
+- **Rejected** (refused: validation/authz/conflict): fix input; unchanged retry fails again.
+- **Unknown** (timed out mid-call): check state at the source before any retry.
+- **Partial** (half-committed): [`data-integrity.md`](data-integrity.md) (see `Writes, retries, and concurrency`) — reconcile or roll back, never resume blind.
+- **Clean failure** (not started / fully rolled back): safe to retry after fixing the cause.
+
+**Failing case:** an **Unknown** outcome retried unchanged double-applies (duplicate charge). Idempotency: [`data-integrity.md`](data-integrity.md); outcome taxonomies: [`integration-reliability.md`](integration-reliability.md). Not provable → `cannot_verify` and stop.
+
+## Meaningful messages
+- Error messages state what failed, the relevant context (ids, inputs, not secrets),
+  and ideally how to recover. Cryptic messages cost hours.
+- Distinguish *expected* failures (validation, not-found) from *unexpected* (bugs);
+  handle the first as flow, surface the second.
+- Structured error surfaces carry one consistent envelope — **severity, stable code,
+  human message, fix** — so callers and logs can act programmatically; a bare string that
+  forces callers to parse prose is a contract gap.
+
+## Fail closed (security-relevant paths)
+- On error in an auth/permission/transaction path, **deny and roll back**: never
+  default to granting access or committing partial state.
+
+## Logging
+- Log key events (failures, access violations, validation errors) with enough context to
+  debug. Prefer structured logs (key/value or JSON).
+- **Never log secrets, credentials, tokens, or personal data.** Show users a clear,
+  non-revealing message; keep the detail in the logs for the team.

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

@@ -0,0 +1,159 @@
+# Gates — the machine-checked acceptance ledger
+
+> Applies when: authoring or checking the machine-verified acceptance ledger (gates.md).
+
+`gates.md` is the acceptance ledger: every required outcome becomes one
+independently checkable gate, and the engine — not reviewer prose — decides
+whether each gate ran and produced its declared signal. It is the structural
+answer to partial compliance: a feature cannot report "done" while a required
+outcome is unchecked, stale, or abandoned.
+
+Written at Vet alongside `test-plan.md`, executed at Prove, required all-met at
+Seal. Like every required artifact it is phase-bound: vet/build/converge and
+every later phase requires its presence; proof phases require every gate met.
+
+## Grammar
+
+```markdown
+- [ ] AC-001: <observable outcome>
+  CHECK: <exact command from test-plan.md Build-entry preflight>
+  EXPECT: <substring | /regex/flags>
+  CWD: <repository-relative path; omit for repo root>
+  INPUTS: <optional project-relative paths, directories or globs>
+  RUN: <optional writer; default root>
+  EVIDENCE: pending
+
+- [x] AC-002: <human-judged outcome>
+  EVIDENCE: <human attestation, one line>
+
+ABANDON: AC-003 <why the outcome can never be met>
+```
+
+- One `- [ ]`/`- [x]` row per gate; `ID:` ends at the first colon, max 64 chars.
+- `CHECK` and `EXPECT` are a pair: both present (runnable gate) or both absent
+  (manual gate). A partial pair is a parse error.
+- Attributes are indented beneath their gate. Fenced code examples never parse.
+- `EXPECT` is a substring, or `/pattern/flags` with `i`, `m`, `s` flags.
+- `CWD` is repository-relative; absolute paths and `..` segments are rejected.
+- `INPUTS` (optional) lists every file the gate's result depends on: sources,
+  tests, fixtures, build and lock files, and the gate's own scripts. Each pattern
+  must match a file. A gate whose verdict depends on state that no file
+  captures (network, wall clock, live host load) takes no `INPUTS`.
+- `RUN: writer` (optional) lets the wright pre-run a runnable gate with `gates
+  precheck` before returning; that is never evidence and the root still runs the
+  gate. `gates lint` refuses it on a manual gate or with a value other than
+  writer/root.
+- `ABANDON:` starts at column 1, names a known gate, and requires a reason.
+  An abandoned gate blocks completion and demands a handoff — it can never
+  read as a pass.
+- An empty ledger (no gates) is malformed.
+- A `scripts/` test driver (whole `test`/`tests` word) in a Writer allowlist
+  or a `present` touched-files.md row blocks readiness/seal unless a CHECK
+  runs it or `Driver waiver: <path> — DEC-### <reason>` cites a decisions.md heading.
+
+## Runnable gates and the approval boundary
+
+A runnable gate executes only when its exact `(CHECK, CWD)` pair matches a row
+of `test-plan.md`'s `## Build-entry preflight` table (`Command` + `Cwd`
+columns). Approval is exact-text equality after whitespace/cwd normalization —
+a differently spelled command or different directory is a different oracle and
+needs its own vetted row. This is the DevRites approval boundary: the vetted
+test plan is the sole list of commands the engine may run, so gates can never
+execute unreviewed code. `check preconditions` runs those same rows, selected by
+their optional `Run at` cell, writing the same transcripts.
+
+Execution contract: the command runs through the platform shell in the named
+directory with a bounded timeout; pass requires exit 0 **and** output matching
+EXPECT. Without `--transcripts`, output is captured but never persisted, only its
+digest. `--transcripts` writes one file per executed or reused gate under
+`references/gates/<gate-id>/`. Each file holds the command, cwd, attempt, times,
+exit, EXPECT verdict, the candidate digest read before and after the run, and the
+output with known credential shapes masked and capped at 1 MiB. Its
+`OUTPUT_SHA256` equals the ledger evidence digest.
+
+After Vet READY the runnable set is fixed: converting a runnable gate to manual,
+loosening EXPECT, changing CHECK or CWD, adding or narrowing INPUTS, or removing
+a row is Plan repair plus re-Vet, never a Prove or Seal edit. A runnable gate that cannot execute stays unmet
+with `unavailable: <reason>`. Prove attests only gates that were manual at Vet,
+checked by diffing `gates.md` against the Vet record. **Failing case:** AC-003's
+runnable gate fails at Prove, the root deletes CHECK/EXPECT and attests "verified
+manually", and `gates status` reads `all-met`.
+
+## Evidence binding
+
+A successful run writes `EVIDENCE: automatic-evidence=v1; def=<sha256>; …`
+where `def` binds the exact CHECK/EXPECT/CWD (and INPUTS, when declared) the run
+executed. Editing any of them renders prior evidence `stale-unmet` — a stale pass
+cannot hide behind an edited oracle. A gate with `INPUTS` also records
+`inputs=<sha256>` of those files' content. `gates run` and `gates reverify`
+both reuse such a gate while the files are byte-identical, and re-execute it
+when any of them changes. A gate without `INPUTS` keeps the plain rule:
+`run` skips it once met, and `reverify` re-executes it. Prose evidence on a runnable gate is also stale:
+only automatic evidence bound to the current definition counts.
+
+Manual gates are met when checked with non-placeholder human evidence;
+`gates attest` refuses a placeholder note, and one hand-written into the ledger
+stays unmet. A note is a placeholder when every word is a placeholder word
+(`n/a`, `tbd`, `ok`, `done`, `yes`, `pending`, …), the gate ID, or a title word;
+a trailing `(…)` with no nested parentheses is ignored when text precedes it. Honesty of that evidence stays with the Prove/Seal
+reviewers. The engine cannot see who attests, so the note must cite the human's
+own words or source (a `q-…` id the human resolved, or their message in this
+session) and name what was observed and where. An agent's own inspection, or a
+question resolved by AFK or autocomplete auto-pick, is not human evidence: an AFK
+run leaves the gate unmet behind an open `gate: validating` question and never
+self-attests.
+
+## Commands
+
+```text
+devrites-engine gates scaffold <slug>     create gates.md from spec.md AC ids
+devrites-engine gates status <slug>       reduce without executing; all-met/handoff/not-met/malformed
+devrites-engine gates run <slug>          execute unmet runnable gates (and INPUTS gates whose files changed)
+devrites-engine gates reverify <slug>     re-execute every runnable gate except INPUTS gates with unchanged files
+devrites-engine gates lint <slug>         audit oracle quality without executing
+devrites-engine gates attest <slug> <id> <note>   record human evidence on a manual gate
+devrites-engine gates abandon <slug> <id> <why>   record a terminal ABANDON handoff
+```
+
+Run/reverify hold the feature lock, re-read the ledger before writeback, and
+discard a result whose gate definition moved mid-run. Reverify is the
+suspicion-killer: when any doubt exists about prior passes, rerun it rather
+than trusting recorded evidence.
+
+## Oracle quality (`gates lint`)
+
+Lint audits signs an oracle cannot fail honestly — fixed-output CHECKs
+(`echo done`), EXPECT values that also appear in failure output (`pass`,
+`ok`, `0`), path-shaped regexes, activity titles instead of outcomes
+("Improve coverage"), unmeasured numbers in manual titles, unvetted CHECKs,
+and mostly-manual ledgers. Warnings prompt sharpening; an unvetted CHECK is
+an error because the runner can never execute it.
+
+## Authoring guidance
+
+- One gate per observable outcome; gate ids should reuse canonical `AC-###`
+  ids so `check readiness` coverage and the ledger name the same set.
+- Write oracles a stranger could judge: EXPECT a line only success can print,
+  never a word failure output also contains.
+- Source `CHECK` text from the repository's own wiring:
+  `devrites-engine detect commands` resolves test/lint/vet/build commands from
+  the Makefile, `package.json` scripts, and language manifests without
+  executing them. Cite the resolved command verbatim in the preflight row;
+  an `unresolved` slot means Vet must name the concrete command, never guess.
+- Prefer runnable gates; reserve manual gates for genuinely judgment-bound
+  outcomes and make the title's claim inspectable.
+- Pick the strongest oracle the outcome admits: differential (output compared
+  against a recorded baseline or the pre-change behavior) over property
+  (an invariant the output must always satisfy) over example (one concrete
+  input/output case). An example-shaped oracle on a property-shaped outcome is
+  a weak gate — reviewers flag it even when it passes.
+- One CHECK, one oracle: never chain another artifact's self-test before the
+  AC's oracle with `&&` — give the self-test its own gate, so a red self-test
+  never hides the AC's own result.
+- When an outcome becomes impossible, `gates abandon` it and route the
+  handoff — never delete the row to make the ledger pass.
+- The gate set is the coverage denominator: it never shrinks to reach
+  `all-met`. Two gates sharing one normalized CHECK+EXPECT+CWD are one oracle
+  counted twice — `gates lint` flags them as `duplicate-oracle`. Distinct
+  methods and denominator rules live in
+  [`verification-methods.md`](verification-methods.md).

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

@@ -0,0 +1,51 @@
+# Git workflow
+
+> Applies when: committing, branching, writing history.
+
+History is documentation. Keep it clean, atomic, and readable.
+
+## Conventional Commits
+Format: `type(scope): subject`
+- **type**: `feat fix docs style refactor perf test build ci chore revert` (lower-case).
+- **scope**: the area changed (lower-case).
+- **subject**: imperative mood, no leading capital, no trailing period
+  ("add export endpoint", not "Added export endpoint.").
+- Keep the header short (~50, hard cap ~72). Put the *why* in the body, wrapped, after a
+  blank line. Reference issues in the footer.
+
+## Atomic commits
+- One logical change per commit; it should build and pass tests on its own.
+- Don't mix refactor + behavior change in one commit: split them so each is reviewable
+  and revertible.
+
+## Small, focused branches/PRs
+- One concern per branch. Short-lived; rebase/merge per the project's convention.
+- Keep PRs small (see `code-review.md`) so they get a real review.
+
+## Change summary: prove the scope
+When you hand back a change, state what you deliberately left alone as well as what you touched.
+A **"Things I didn't touch (intentionally)"** line (the adjacent smells you noticed and declined
+to fix) proves the diff is feature-scoped ([`core.md`](core.md) rule 7) and matches
+`touched-files.md`, rather than an unsolicited renovation the reviewer has to untangle from the
+real change. Noticed-but-not-fixed becomes an FYI follow-up, never a silent addition to this diff.
+
+## Merge conflict recovery
+When git is mid-merge or mid-rebase, recover before other workflow work:
+
+1. Inspect state: `git status --short --branch`, then note whether this is a merge or rebase.
+2. For each conflicted file, identify **our intent** and **their intent** before editing.
+3. Resolve each hunk by preserving both intents when possible; if intents conflict, pick one and
+   record the trade-off in the commit/PR body.
+4. `git add` the resolved files, then run the smallest relevant checks.
+5. Finish with `git merge --continue` or `git rebase --continue`; abort only when the chosen
+   branch direction is wrong, not because a hunk is annoying.
+
+## Versioning & changelog
+- Semver describes what consumers may rely on. Treat an observable breaking change as major.
+- Derive the version from the tag; do not maintain competing manual copies.
+- Curate changelog entries by user impact in the change that earns them; a changelog is not a git log.
+
+## Never commit
+- Secrets, credentials, tokens, or `.env` files. If one lands in history, rotate it and
+  scrub it: deleting the file in a later commit is not enough.
+- Generated artifacts, dependencies, or large binaries that belong in ignore rules.