devrites 4.4.2 → 4.6.0

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

@@ -4,22 +4,15 @@ Follow DevRites policy and [`depth profiles`](../orchestration-profiles.md).
 
 ## Authority
 
-- Root owns scope, questions/decisions/results, `.devrites/**`, and phase
-  transitions—not product source/tests. Exact vetted executable workflow artifacts
-  follow [`workflow-artifacts.md`](workflow-artifacts.md).
-- Only bounded wright writes product source/tests; others inspect an immutable
-  candidate.
+- Root owns scope, questions/decisions/results, `.devrites/**`, phase transitions — not product source/tests; vetted executable workflow artifacts follow [`workflow-artifacts.md`](workflow-artifacts.md).
+- Only bounded wright writes product source/tests; others inspect an immutable candidate.
 - Every named role runs; unavailable → HITL, never skip/substitute.
-- Leaves never invoke agents, ask humans, change phase, push, install/deploy,
-  migrate live data, or act irreversibly; return evidence/proposals for root
-  acceptance. The sole exception is one local, unpushed transfer commit by an
-  eligible native-worktree `devrites-slice-wright`; it is transport, not shipping
-  authority or a project checkpoint.
+- 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.
 
 ## Agents
 
 | Agent |
-|---|
+| --- |
 | `devrites-evidence-scout` |
 | `devrites-plan-drafter` |
 | `devrites-upgrade-planner` |
@@ -42,48 +35,39 @@ Files own briefs; [`parallel-dispatch.md`](../parallel-dispatch.md) owns rosters
 
 ## 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.
+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.
 
 ## Source-writing boundary
 
-Claude grants only wright `acceptEdits`; Codex root is workspace-capable because
-children cannot elevate. Wright alone is `:workspace`; others are `:read-only`.
+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.
 
-Give wright the smallest exact project-relative product source/test file list—no
-directories/globs, traversal/`.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.
+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.
 
-A native isolated-worktree pilot is allowed only under
-[`rite-build/reference/wright-dispatch.md`](../../../rite-build/reference/wright-dispatch.md#isolated-writer-worktree-pilot):
-one writer at a time, committed/clean baseline, no submodule parent, exact transfer
-commit, and candidate reconciliation before deletion. Isolation never enables
-parallel writers or weakens exact-path admission.
+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.
 
-The controlling root may materialize only the exact Vet-ready executable workflow
-artifact paths under the active `.devrites/work/<slug>/` using
-[`workflow-artifacts.md`](workflow-artifacts.md). This is not a writer dispatch,
-product slice, candidate mutation, or exception to the source-writing boundary.
+## Independence
 
-## Inputs and results
-
-Each job gets objective/exclusions, exact paths/immutable candidate, rubric/result
-shape. 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.
+- A fresh result sees scope/paths-diff/rubric only — never another result's or the root's conclusions, severities, expected verdicts, or edited context; seeding voids the packet.
+- 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.
 
 ## Result admission
 
 Each required reviewer/analyst/auditor starts with exactly one:
 `Outcome: findings`, `Outcome: no-findings`, or `Outcome: gap`.
 
-- **`findings`:** each states severity, confidence 1–10, exact artifact section or
-  `file:line`, observed quote/command/result/measurement, reachable failure or
-  contract impact, and smallest correction. Critical/Important requires 7+, exact
-  evidence, and concrete impact.
+**Canonical finding shape (C2 — all `devrites-*-reviewer` / auditor agents):**
+
+```text
+Outcome: <findings | no-findings | gap>
+Finding: <severity> | <file:line or artifact section> | <observed quote/result> | <impact> | <minimum fix>
+```
+
+- **`findings`:** each row uses the shape above; confidence 1–10 on Critical/Important.
+  Critical/Important requires 7+, exact evidence, and concrete impact.
 - **`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;

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

@@ -1,9 +1,8 @@
 # Browser proof checklist
 
-- Open the real UI, not only a screenshot path.
-- Check console and network for errors.
-- Exercise default, loading, empty, error, success, disabled, and responsive states when relevant.
-- Compare to `design-brief.md` and record a Visual Verdict.
-- If MCP/browser tooling is unavailable, record the lower-rung fallback and limitation.
+- Open the real UI (never screenshot-only); check console and network for errors.
+- Interactive slices capture each relevant state (default/hover/focus-visible/active/disabled/loading/empty/error) at 320 + 768 px, +1024/1440 when adaptive; state floor: [`../../../devrites-frontend-craft/reference/quality-standards.md`](../../../devrites-frontend-craft/reference/quality-standards.md). Omission needs a one-line `not-needed` reason; states must exist in source — an unreachable state's capture proves nothing.
+- Review browser-default surfaces once per slice (selection, caret, scrollbars, focus ring); no horizontal overflow at captured widths; 200% zoom spot-check; 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 [`prose-style.md`](prose-style.md).
 
 Detailed skill: `devrites-browser-proof`.

package/pack/generated/claude/skills/devrites-lib/reference/standards/code-review.md

@@ -59,17 +59,16 @@ correctness bug, a failing case, a measured number) > **the project's stated sty
 objection bottoms out at the last tier, it's a Suggestion at most: say so, and don't block on it.
 An author who is factually right wins over a reviewer's taste.
 
+## Reviewer-vs-reviewer adjudication
+
+Root re-verifies each claimed consequence at the cited site, keeps the surviving evidence, sets final severity itself (reviewer severity advisory), records what decided ([agents.md § Independence](agents.md#independence)); unresolved conflicts stay open blockers.
+
 ## Scope discipline
 Review the change, not the whole project. Out-of-scope problems become follow-ups, not
 drive-by edits that balloon the diff.
 
 ## Receiving review feedback
-Treat external review as claims to verify, not orders to obey. Clarify unclear feedback before a
-partial fix; check each claim against the live code; push back with evidence when it is wrong;
-then implement blocking → simple → complex items one at a time and test each fix. Technical
-replies state the evidence and next action: no performative agreement, no gratitude theater:
-"Fixed: <what> in <where>" beats "Great catch, thanks!". About to write "Thanks"? Delete it
-and state the fix.
+Treat external review as claims to verify, not orders. Clarify unclear feedback first; check claims against live code; push back with evidence when wrong; implement blocking → simple → complex items one at a time with tests. State evidence and next action — "Fixed: <what> in <where>" beats gratitude theater.
 
 ## Principles and charter are pass/fail gates
 Two project layers are evaluated at `/rite-vet` and re-checked against the diff

package/pack/generated/claude/skills/devrites-lib/reference/standards/core.md

@@ -39,27 +39,15 @@ Repository conventions follow [Precedence](#precedence).
 
 ## Lifecycle rest points
 
-Before advancing a phase, run `devrites-engine check readiness <slug>` for
-structure; exact agents/checklists own semantics. Standalone rites persist and stop
-on block. Under an active controlling caller, an agent-owned technical block is a
-persisted backward edge: return it to that caller instead of producing a
-user-facing stop.
-After native proof/review, `/rite-seal` runs `devrites-engine check seal <slug>`
-for structure/freshness, not prose. HITL/blocked stops follow
-[Persistence before stopping](#persistence-before-stopping-handoff-discipline).
+Before advancing a phase, run `devrites-engine check readiness <slug>` for structure (semantics belong to exact agents/checklists). Standalone rites persist and stop on block; under a controlling caller, agent-owned technical blocks return backward as a nested phase boundary, not a user-facing handoff. `/rite-seal` runs `devrites-engine check seal <slug>` for structure/freshness, not prose. HITL/blocked stops follow [Persistence before stopping](#persistence-before-stopping-handoff-discipline).
 
-## Caller-owned technical backtracking
+### Gate contract
+
+Each gate is declared as **Name · Precondition · Satisfying observation (exact command/artifact state) · Pass/Fail · What failure blocks**, with one type: `preflight`, `revision`, `escalation` (human-only), `abort`. Engine gates keep exit codes; semantic gates are judged by their owner against this contract. A gate whose failure consequence cannot be named is decoration — sharpen or delete it. A mechanical gate's satisfying observation is a command or artifact state a reviewer can re-run or re-read — narrative-only passes are unproven.
 
-When an active rite invokes an earlier rite inline to repair an agent-owned
-technical gap, the original rite remains the controlling caller. A nested
-rite's `STOP` is a nested phase boundary, not a user-facing handoff. The caller
-re-reads `state.md`, follows the durable return cursor and intermediate
-`next_action`, and resumes its originating phase while no human-owned, safety,
-access, budget, or exhausted-recovery stop is active.
+## Caller-owned technical backtracking
 
-Derive `exhausted-recovery` from the exact fingerprint's recorded no-progress
-attempts, not from a stale `state.md` label. A consumed authorization for one
-real action does not exhaust offline recovery from its retained new evidence.
+When a rite invokes an earlier rite inline to repair an agent-owned technical gap, the original rite stays the controlling caller: a nested `STOP` is a phase boundary, not user-facing. The caller re-reads `state.md`, follows the return cursor/`next_action`, and resumes unless a human-owned, safety, access, budget, or exhausted-recovery stop is active ([Persistence before stopping](#persistence-before-stopping-handoff-discipline)). Derive `exhausted-recovery` from the fingerprint's recorded no-progress attempts, not from a stale `state.md` label; one consumed authorization doesn't exhaust offline recovery from retained new evidence.
 
 An intermediate `Next step` is cold-resume metadata. Do not ask the human to
 copy routine `/rite-plan repair`, `/rite-vet`, `/rite-build`, or proof-rerun

package/pack/generated/claude/skills/devrites-lib/reference/standards/debug-recovery.md

@@ -0,0 +1,21 @@
+# Debug recovery (async wait discipline)
+
+Triggered standard for polling async readiness without blind sleep. Skill owner:
+[`devrites-debug-recovery`](../../../devrites-debug-recovery/SKILL.md).
+
+## Condition-based wait (bounded)
+
+When waiting for async readiness (server start, job completion, browser signal):
+
+1. Set `max_wait_ms` (default 30_000 unless artifact specifies otherwise).
+2. Poll with **condition check** — never fixed sleep as the primary strategy.
+3. Capture **last signal** (last log line, HTTP status, DOM state) on timeout.
+4. Record artifact: `{ condition, max_wait_ms, last_signal, outcome }`.
+
+**Failing case:** `sleep(5)` loop with no captured last signal → recovery incomplete;
+treat as flaky/unproven.
+
+## Relationship to debug-recovery skill
+
+The seven-step recovery cycle owns reproduction and fix. This standard owns the
+**wait recipe** only; do not duplicate the full cycle here.

package/pack/generated/claude/skills/devrites-lib/reference/standards/development-workflow.md

@@ -10,9 +10,17 @@ Ship small, integrate often, and keep the main branch releasable. Workflow phase
 - Prefer short-lived branches off the main branch.
 - The main branch is **always in a releasable state**. Validate every change through a
   **fast, reliable CI pipeline** (tests + build) before it merges.
+- **Trunk broken?** Revert first (default repair); fix forward only when revert is harder. Red trunk blocks all merges.
 - Hide incomplete work behind a **feature flag / toggle** rather than a long branch, so
   partial work can land without blocking releases or breaking the trunk.
 
+## Feature-flag lifecycle
+
+- Name the **removal trigger** at flag creation; delete the flag once the work ships — a
+  flag past its trigger is **flag debt**, a review finding. Prove **both states**
+  ([`testing.md`](testing.md)); widen rollout only with the rollback path recorded
+  ([`data-integrity.md`](data-integrity.md)).
+
 ## Review gate
 - A human reviews every change before merge; `code-review.md` owns review scope and evidence.
 

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

@@ -4,6 +4,12 @@ Document intent/decisions; public inputs, outputs, errors, and gotchas; non-obvi
 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,

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

@@ -64,6 +64,17 @@ Judgment may dismiss a demonstrably irrelevant case; it cannot prove behavior. W
 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

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

@@ -16,6 +16,17 @@ recoverable.
 - 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) § partial failure — 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.

package/pack/generated/claude/skills/devrites-lib/reference/standards/performance.md

@@ -11,6 +11,10 @@ Measure first. An optimization without a measurement is a guess that adds comple
 ## Optimize responsibly
 - Fix the **measured** bottleneck, then **re-measure** to prove the win (before/after).
   An optimization that doesn't move the number is just added complexity: revert it.
+- **Measurement not reproducible in CI** (noisy host, external dependency): label the claim
+  `Lab (<named command/environment>)` — never an elapsed-time assertion in shared CI (a
+  flaking wall-clock test is a flaky test, [`testing.md`](testing.md)). Budget regression:
+  re-measure; fix to budget or record the accepted regression with reason and owner.
 
 ## Frontend: Core Web Vitals
 For UI work, measure-first means LCP / INP / CLS judged against real numbers, each labeled

package/pack/generated/claude/skills/devrites-lib/reference/standards/prose-style.md

@@ -1,17 +1,17 @@
 # Prose style: write like a human, not a model
 
 Every chat reply and artifact DevRites writes (`spec.md`, `plan.md`, `decisions.md`,
-`review.md`, `seal.md`, commit bodies, and PR descriptions) should read like a senior engineer
+`review.md`, `seal.md`, commit bodies, PR descriptions) should read like a senior engineer
 wrote it for a teammate. The default LLM voice (filler openers,
 manufactured contrast, fake profundity, hedging, em-dash tics) is a tell; strip it.
 
-This rule is the prose counterpart to [`coding-style.md`](coding-style.md). The heavier
-banned-phrase and structure lists live in the `devrites-prose-craft` skill; this file is the
-always-available core the text-generating phases read.
+Prose counterpart to [`coding-style.md`](coding-style.md). The heavier banned-phrase and
+structure lists live in `devrites-prose-craft`; this file is the always-available core
+the text-generating phases read.
 
 ## Two registers: calibrate, don't flatten
 
-DevRites writes in two voices. The anti-slop rules apply to both, but precision rules differ.
+DevRites writes in two voices; anti-slop rules apply to both, precision rules differ.
 
 - **Prose:** chat replies, and the narrative sections of artifacts (spec overview, plan
   rationale, decision notes, review summaries, ship notes). Optimize for a human voice:
@@ -20,8 +20,8 @@ DevRites writes in two voices. The anti-slop rules apply to both, but precision
   names. Optimize for **precision**: exact domain terms, numbered criteria, and complete
   enumerations are correct here and must stay. Don't "humanize" a spec into vagueness.
 
-The shared rule: cut what carries no information; keep what a reader needs. In prose that
-means killing filler; in technical writing it means keeping the precise list.
+Shared rule: cut what carries no information;
+keep what a reader needs — kill filler in prose, keep the precise list in technical writing.
 
 ## Preservation contract: fidelity before polish
 
@@ -47,7 +47,7 @@ the same decisions from it.
 | False binary contrast. "It's not X, it's Y", "The question isn't X. It's Y", "not just X but Y" | State Y directly. Drop the negation. |
 | Fake profundity. "Let that sink in", "This is the deepest problem", "make no mistake" | Show the thing; trust the reader to weigh it. |
 | Vague declaratives. "The implications are significant", "the reasons are structural" | Name the specific implication or reason. |
-| Marketing adjectives *selling* the work: "a robust, scalable, seamless, production-ready solution" | Say what it does and what proves it. (Calibrated: "robust" / "scalable" / "comprehensive" are legitimate in a *precise technical claim* ("robust to a dropped connection, see `evidence.md`") only slop when they sell. The canonical word-by-word tiering is `devrites-prose-craft/reference/banned-phrases.md` § AI vocabulary.) |
+| Marketing adjectives *selling* the work: "a robust, scalable, seamless, production-ready solution" | Say what it does and what proves it. (Calibrated: "robust"/"scalable"/"comprehensive" are legitimate in a precise technical claim ("robust to a dropped connection, see `evidence.md`"); slop only when they sell. Canonical tiering: `devrites-prose-craft/reference/banned-phrases.md` § AI vocabulary.) |
 | Hedging stacks. "It's important to note that, generally, in most cases" | Make the claim, or cut it. |
 | False agency: "the data tells us", "the complaint becomes a fix", "the decision emerges" | Name who did it. "The grader reads X and returns Y." |
 | Meta-narration, "In this section we'll…", "Let me walk you through…", "as we'll see" | Let the text move; delete the announcement. |
@@ -58,11 +58,10 @@ the same decisions from it.
   returned". Passive hides who acts.
 - **Be specific.** Replace "every / always / never / a lot" with the actual number, file, or
   case when you know it.
-- **Vary rhythm.** Don't stack three short staccato fragments for drama, and don't run three
-  same-length sentences in a row. Mix.
-- **Skip em and en dashes.** Use a comma, period, colon, or parentheses instead. Repeated
-  dashes are a classic AI tell (matches
-  [`rite-polish/reference/anti-ai-slop.md`](../../../rite-polish/reference/anti-ai-slop.md)).
+- **Vary rhythm.** Don't stack three staccato fragments or three same-length sentences in a row.
+- **Skip em and en dashes** — a repeated AI tell (matches
+  [`rite-polish/reference/anti-ai-slop.md`](../../../rite-polish/reference/anti-ai-slop.md));
+  use a comma, period, colon, or parentheses instead.
 - **Trust the reader.** Skip the softening preamble and the recap of what you just said.
 
 ## Keep these (technical register: do NOT strip)
@@ -78,9 +77,8 @@ the same decisions from it.
 
 ## Code prose (comments & names)
 
-Comments and identifiers are prose too, and the comment-noise / generic-naming tells live in
-[`coding-style.md`](coding-style.md) (comments explain *why* not *what*; names reveal intent)
-and the code section of
+Comments and identifiers are prose too; the comment-noise / generic-naming tells live in
+[`coding-style.md`](coding-style.md) and the code section of
 [`rite-polish/reference/anti-ai-slop.md`](../../../rite-polish/reference/anti-ai-slop.md).
 The one-line rule: **a comment must justify its existence in one sentence (intent, trade-off,
 non-obvious constraint, or a dragon warning). If it restates the code, delete it and let the
@@ -88,30 +86,31 @@ name carry the meaning.**
 
 ## Specificity is the antidote
 
-The cut-list removes tells; specificity prevents them. Two fast tests before delivering:
+The cut-list removes tells; specificity prevents them. Fast tests before delivering:
 
-- **Topic-swap test.** Could you swap the subject (this feature for any other) and the
-  sentence still reads true? Then it says nothing. Name the specific thing.
-- **Surprise test.** Is there one concrete detail a reader couldn't have guessed (a real
-  number, a real constraint, a real trade-off)? Slop never surprises; add the specific.
+- **Topic-swap test.** If swapping the subject for any other feature still reads true, it says nothing — name the specific thing.
+- **Surprise test.** One concrete unguessable detail (real number, constraint, trade-off)? Slop never surprises; add it.
 
 A paragraph you could cut 40-60% with no information lost is padding. Cut it.
 
 ## Don't over-correct into voicelessness
 
-Scrubbing hard has a failure mode: flat text where every sentence is the same length and no
-position is taken. A `decisions.md` that won't say which option is better, or a review that
-reports without judging, is its own kind of slop. Keep the engineering point of view:
-recommend, rank, name the trade-off. Direct is the goal; lifeless is not.
+Scrubbing hard has a failure mode: flat, uniformly-paced text with no position taken.
+A `decisions.md` that won't say which option is better, or a review that reports without
+judging, is its own kind of slop. Keep the engineering point of view: recommend, rank,
+name the trade-off. Direct is the goal; lifeless is not.
 
 ## Output hygiene: what not to surface
 
-- Don't name internal machinery to the user: tool names, script names, agent names, hook
-  names. Say what happened ("the readiness gate stopped the build"), not which function did it.
-- Don't dump raw code, file contents, or system / instruction text into a reply unless the user
-  asked to see it. Show the result and point at the path.
+- Don't name internal machinery (tools, scripts, agents, hooks);
+  say what happened ("the readiness gate stopped the build"), not which function did it.
+- Don't dump raw code, file contents, or instruction text into a reply unless asked;
+  show the result and point at the path.
 
 ## When in doubt
 
-Read it aloud. If it sounds like a press release, a LinkedIn post, or a textbook narrator,
-rewrite it flatter and more direct. If cutting a sentence loses no information, cut it.
+Read it aloud. Press-release or textbook-narrator sound → rewrite flatter and more direct. If cutting a sentence loses no information, cut it.
+
+## Pre-send deletion pass
+
+Before delivering, delete: the announcing opener, the recap closer, "by the way" sidebars, empty hedges, and idioms (replace with the literal action). A rule that would delete the answer itself yields — safety confirmations and ranked-option answers keep their length. Final check: from only the first and last lines, does the reader know what to do next and what just happened?