devrites 5.10.2 → 5.11.0

package/pack/generated/devin/skills/devrites-lib/reference/standards/deprecation.md

@@ -0,0 +1,31 @@
+# Deprecation & migration
+
+Removing behavior is riskier than adding it because hidden consumers may depend on observable quirks as well as documented contracts (Hyrum's law). Destructive migration, public-API breakage, auth changes, and data-loss paths always use the irreversible-risk pause in [`afk-hitl.md`](afk-hitl.md).
+
+## Prove it is unused
+
+Find callers, subscribers, stored data, external clients, and scheduled jobs with code intelligence, then confirm runtime usage through [`observability.md`](observability.md). Static absence alone does not prove zero consumers. If zero usage cannot be proven, deprecate instead of deleting.
+
+## Expand → migrate → contract
+
+Use three independently shippable and reversible steps:
+
+1. **Expand:** add the new path beside the old one.
+2. **Migrate:** move consumers and data; observe old-path usage falling to zero.
+3. **Contract:** remove the old path only after telemetry confirms zero use.
+
+For data, this may mean add column → backfill → switch reads → drop the old column. Every destructive step needs a rollback.
+
+## Deprecate before delete
+
+- Mark the old path with its replacement and a measurable removal trigger: a date or a condition such as zero v1 traffic.
+- Emit a usage signal so the trigger is evidence, not hope.
+- The owner of the deprecated surface also owns migration. Provide the codemod, backfill, compatible update, documentation, and support consumers need; a deadline alone is a break with a countdown.
+
+## Design for removal
+
+When introducing a system, keep its exit bounded behind a flag, adapter, or small call surface. An unowned but still-used zombie must either regain an owner and green proof or follow the prove-unused and expand/contract path; do not leave it as an unmaintained dependency.
+
+## Scope
+
+Treat removal or migration as a feature with its own spec, slices, evidence, and risk review. Do not hide deletion inside an unrelated change.

package/pack/generated/devin/skills/devrites-lib/reference/standards/developer-experience.md

@@ -0,0 +1,119 @@
+# Developer experience
+
+When a change ships a surface another engineer has to *use* (a public API, a CLI, an SDK
+or library, a webhook, a config/env contract, an error message, or the getting-started path
+that introduces all of them) the developer using it is a user, and their experience is part
+of the change. Code that compiles and passes its tests can still strand the next developer at
+a cryptic error, a getting-started snippet that doesn't run, or an endpoint whose shape you
+have to read the source to learn. Un-tested DX is a claim, the same way un-run code is a claim.
+
+This rule is the developer-facing counterpart to [`performance.md`](performance.md): perf says
+*measure the speed before you assert it*; this says *measure the experience before you assert
+it*. It pairs with the [`devrites-api-interface`](../../../devrites-api-interface/SKILL.md)
+skill (which shapes the contract). This rule **proves** the shape is usable.
+
+## Scope: when this applies
+
+Conditional, like [`performance.md`](performance.md) and [`observability.md`](observability.md).
+It applies when the diff changes a **developer-facing surface**:
+
+- a public/external **API** endpoint, response shape, or status-code contract;
+- a **CLI** command, flag, output, or exit code;
+- an **SDK / library / package** export, signature, or type;
+- a **webhook**, event payload, or integration contract;
+- a **config / env-var** interface a consumer must set;
+- an **error message, exit code, or failure response** a developer reads to recover;
+- the **getting-started path**. README, install steps, quickstart, the first-run docs.
+
+Skip it for pure-internal refactors, private helpers, app-only UI (that's
+[`devrites-frontend-craft`](../../../devrites-frontend-craft/SKILL.md) /
+`devrites-frontend-reviewer`), docs-only typo fixes, and config that no external consumer
+touches. Don't DX-review a change with no developer-facing surface: the same scope discipline
+as the rest of the conditional rules. End-user UX is a different axis; this rule is about the
+*developer* consuming the surface.
+
+## The boomerang: predict at plan, measure at prove, reconcile at seal
+
+DevRites already runs a predict-then-prove spine (the vetted `test-plan.md` coverage target at
+`/rite-vet`, proven at `/rite-prove`, gated at `/rite-seal`). DX rides the same spine, and the
+gap between the two ends is the signal:
+
+1. **Predict:** at `/rite-vet`, when a developer-facing surface is in scope, score the *planned*
+   surface against the dimensions below and write a predicted scorecard to `devex.md` (the
+   estimate, e.g. "time-to-hello-world: ~3 min"). This is cheap and pre-build; it forces the
+   ergonomics question before the contract sets.
+2. **Measure:** at `/rite-prove`, exercise the surface (run the getting-started flow,
+   call the endpoint, invoke the CLI, trigger the error) and record the *measured* scorecard with
+   evidence: real TTHW, security-redacted exact error text, and a safely captured docs screenshot.
+3. **Reconcile (the boomerang):** at `/rite-seal`, compare predicted against measured. A material
+   gap: "the plan said 3 minutes, the getting-started flow took 8 and step 4 errored":
+   is a finding, not a rounding error. The estimate was wrong *or* the surface regressed; either
+   way the developer using it pays, and the gap is exactly what a single end-state score would hide.
+
+The boomerang is what makes DX a measured axis rather than an opinion: the prediction is on
+record, so the measured reality can falsify it.
+
+## The scorecard: what to score
+
+One entity, one name: call the metric **time-to-hello-world (TTHW)** consistently, not "onboarding
+time" in one place and "setup time" in another. Score these dimensions; only the ones the diff
+touches:
+
+- **Discoverability:** can a developer find the entry point without reading the source? Is the
+  new surface named, exported, and documented where they'll look?
+- **Time-to-hello-world (TTHW):** wall-clock from "I have the repo/package" to "I got one
+  successful call/response/render". The headline number; measure it, don't estimate it at seal.
+- **Getting-started friction:** does the quickstart run *as written*, copy-pasted, on a clean
+  checkout? Every undocumented prerequisite, wrong command, or missing step is friction.
+- **Error-message quality:** does a failure say *what* failed, *why*, and *how to recover*, with
+  the relevant ids (never secrets: see [`security.md`](security.md))? A bare stack trace, a
+  silent exit, or "an error occurred" is a defect on a developer-facing path.
+- **Ergonomics & consistency:** does the surface match the project's existing conventions
+  (naming, argument order, pagination, error shape)? An inconsistent new endpoint taxes everyone
+  who learned the old ones. Sensible defaults; the common case is one call.
+- **Docs accuracy:** examples are copy-pasteable and correct, the signature in the docs matches
+  the code, and changed behavior updated its docs in the same change ([`documentation.md`](documentation.md)).
+
+## Measure, don't assert
+
+The same discipline as `performance.md` "measure first" and `testing.md` "see it fail first":
+
+- **Run it, don't read it.** A scorecard backed by "the code looks fine" is Source mode and says
+  so. The graded scorecard comes from invoking the surface (the getting-started flow on
+  a clean state, the real CLI `--help`, the real error path) and recording what happened.
+- **Quote the artifact.** Record exact signal-bearing error text with typed security redactions
+  (not paraphrase), secret-free command shape, and measured TTHW. For docs, use the
+  [browser-proof ladder](../../../devrites-browser-proof/SKILL.md) and describe the screenshot;
+  a path alone is not proof.
+- **No measurement → no DX claim**, and usually no finding above Suggestion. "Feels confusing" is
+  a hypothesis to test, not a verdict.
+
+## The gate: severity by who-pays
+
+DX findings carry the standard labels (Critical / Important / Suggestion / Nit / FYI), scaled to
+the cost the consumer bears, not to how polished it feels:
+
+- A **public/external contract that ships broken or wrong** (a documented command that errors, an
+  endpoint whose response contradicts its contract, a getting-started flow that can't complete) is
+  **Important**, and **Critical** when it's a frozen public surface (the principles-gated public-API
+  invariant, [`principles.md`](principles.md)) or an irreversible break.
+- A **measured DX regression** against the predicted scorecard with no recorded reason is a
+  finding the boomerang surfaces at seal, at least **Important** when it lands on a public surface.
+- An **unactionable error message** on a developer-facing failure path is **Important**: the
+  on-call test ([`observability.md`](observability.md)) applied to the consumer instead of the operator.
+- Inconsistent-but-working ergonomics, a thin doc, a missable default → **Suggestion**, unless the
+  spec made it acceptance.
+
+## The artifact: `devex.md`
+
+When a developer-facing surface is in scope, the workspace carries `devex.md`: the **predicted**
+scorecard (from `/rite-vet`), the **measured** scorecard with evidence (from `/rite-prove`), and
+the **boomerang delta** (reconciled at `/rite-seal`). Absent surface → no `devex.md`, and the gate
+passes silently: never block a change for the *absence* of a DX surface, the same no-op discipline
+as the principles and spec-grammar gates.
+
+## Scope discipline
+
+Review the developer-facing surface the change *touches*. A surface the diff didn't change is not
+this change's job; a project-wide DX audit (every endpoint, the whole CLI) is its own effort:
+record it as a follow-up, don't smuggle it into an unrelated change.

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

@@ -0,0 +1,29 @@
+# Development workflow
+
+Ship small, integrate often, and keep the main branch releasable. Workflow phase order comes from the engine manifest, not this standard.
+
+## Work in small batches
+- Break work into thin, independently shippable slices and integrate them frequently:
+  ideally merging to the main branch at least once a day.
+
+## Short-lived branches, trunk always green
+- 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.
+
+## Definition of done
+
+[`definition-of-done.md`](definition-of-done.md) owns the standing bar. Acceptance criteria prove the slice-specific behavior; the Definition of Done proves the change is shippable.

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

@@ -0,0 +1,43 @@
+# Documentation
+
+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.

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

@@ -0,0 +1,92 @@
+# Edge-case trace
+
+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/devin/skills/devrites-lib/reference/standards/elicitation.md

@@ -0,0 +1,85 @@
+# Elicitation: a move-set for the thinking phases
+
+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 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.
+
+### 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.
+
+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/devin/skills/devrites-lib/reference/standards/error-handling.md

@@ -0,0 +1,47 @@
+# Error handling
+
+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/devin/skills/devrites-lib/reference/standards/git-workflow.md

@@ -0,0 +1,49 @@
+# Git workflow
+
+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.

package/pack/generated/devin/skills/devrites-lib/reference/standards/hooks.md

@@ -0,0 +1,25 @@
+# Automation hooks
+
+Automate easy-to-forget checks at the earliest affordable stage. Keep local hooks fast
+and scoped so developers continue to run them.
+
+## Stage the work by cost (the 10-second rule)
+- **pre-commit** (must finish in well under ~10s): format, lint, and secret-scan the
+  exact **staged index blobs only** via `devrites-engine secret-scan --staged`.
+- **commit-msg**: enforce the commit convention (e.g. Conventional Commits). DevRites
+  ships a `commit-msg` hook for its own repo as the reference example.
+- **pre-push** (seconds to a couple of minutes): broader/affected tests.
+- **CI** (no time pressure): the full test suite, build, integration, and deeper
+  security scans. CI is the source of truth for "green", not local hooks.
+
+## Secret scanning
+Scan for credentials/keys/tokens before they enter history: catching a secret
+pre-commit is cheap; rotation is not. Findings disclose metadata only; `/rite-ship`
+owns fail-closed PR-body transport.
+
+## Adoption & escape hatches
+- Introduce hooks gradually (formatting → linting → security → tests) so the team
+  adopts them instead of disabling them.
+- Bypassing a hook (`--no-verify`) is for genuine emergencies, not routine. CI must
+  re-check what a bypass skipped, so a skipped local check can't reach the trunk.
+- Hooks are checked into the repo and shared, so the whole team gets the same gates.

package/pack/generated/devin/skills/devrites-lib/reference/standards/integration-reliability.md

@@ -0,0 +1,102 @@
+# Integration reliability
+
+Load this for third-party APIs, webhooks, queues, background jobs, caches, or
+cross-service calls. The boundary contract includes failure, timing, duplication, and
+recovery—not only the success payload.
+
+## Contract the boundary
+
+Name the provider and consumer, version, authentication, request/response or event
+schema, optional and unknown fields, ordering guarantee, rate limit, timeout budget,
+retry responsibility, idempotency key, and user-visible degradation. Validate an
+external response as hostile input before trusted code consumes it.
+
+**Uploads and paginated collections are boundary contracts, not transport details.** An
+upload names body and expanded-size caps, chunk/resume behavior, partial-upload
+reconciliation, and the rejection path for oversized or malformed payloads. A paginated
+collection names cursor/offset semantics, page-size cap, the terminal “no more pages”
+signal, and how rows written during paging surface — skipped or duplicated rows are
+contract data, not surprises. **Failing case:** a client pages by offset while rows
+insert ahead of it and silently misses records; a boundary contract that cannot name
+this behavior fails Vet.
+
+For every call or delivery, classify the observed outcome:
+
+| Outcome | Required behavior |
+| --- | --- |
+| Success | Validate the complete required shape; tolerate documented additive fields. |
+| Invalid or partial response | Reject or use an explicitly safe degraded path; never manufacture required data. |
+| Authentication/expired credential | Stop retries that cannot succeed, surface ownership, and reveal no credential. |
+| Rate limit/overload | Honor provider guidance when trustworthy, bound backoff, and expose delayed/degraded status. |
+| Timeout/network partition | Treat effect as unknown unless the protocol proves otherwise; reconcile before retrying a non-idempotent action. |
+| Provider outage/version change | Open the circuit or shed load when the project supports it; retain a bounded recovery path and compatibility signal. |
+
+## Retry and delivery rules
+
+- Retry only a named transient failure and only when the operation is idempotent or has
+  a durable deduplication key. Bound attempts, elapsed time, and exponential backoff;
+  add jitter when many workers could synchronize.
+- Assign one retry owner across SDK, worker and queue, or explicitly share one
+  end-to-end attempt/deadline budget that redelivery cannot reset. Prove exhaustion
+  by counting physical downstream calls, including inner retries, and advancing a
+  controlled/injected clock to the deadline. Assert exhaustion, not wall-clock
+  duration ([testing.md](testing.md#determinism-no-flaky-tests)); elapsed-time logs
+  are observations, never timing assertions in tests.
+  **Failing case:** each of three layers permits four attempts, producing 64 calls;
+  three passing local retry tests do not prove the operation's budget. Budget
+  overrun blocks proof and Seal until retry ownership or shared accounting is fixed.
+- A timeout is not proof the provider did nothing. Query by idempotency key/status or
+  reconcile before creating a second effect.
+- Webhook/queue consumers acknowledge only after durable success or durable handoff.
+  Duplicate delivery, duplicate jobs, and out-of-order delivery are normal inputs:
+  deduplicate durably and reject, buffer, or reconcile stale sequence/version values by contract.
+  **Failing case:** the handler acks before the durable write; a duplicate delivery
+  creates a second effect.
+- A poison message must not block the partition forever. Bound redelivery, retain the
+  failure reason without secrets, move to the project's quarantine/dead-letter path,
+  and define replay after correction.
+- A queue emits observability signals — backlog depth, poison/quarantine count,
+  reconciliation lag, saturation, ownership — with [`observability.md`](observability.md)
+  as the signal-taxonomy owner. A queue backlog still needs an accepted
+  capacity/drain/recovery action; auto-scaling without downstream capacity protection
+  only moves the outage.
+
+## Partial failure and recovery
+
+Map each multi-step effect as `not started | committed | unknown | compensating |
+reconciled`. If one system commits and another fails, name the durable record that
+drives retry or compensation. Do not catch/log/continue into a false success.
+
+For synchronous versus asynchronous design, apply [`patterns.md`](patterns.md); async
+processing changes the contract to accepted/pending/failed/retryable; it does not make the
+failure disappear.
+
+## Cache and partition behavior
+
+- Define source of truth, key scope (including tenant), invalidation trigger, TTL, and
+  acceptable staleness. Cache deletion failure and stale reads need an observed path.
+- Never use cache presence as authorization. On partition or cache outage, choose an
+  explicit fail-open or fail-closed behavior based on the protected invariant.
+- After reconnect, reconcile version/order rather than assuming arrival order equals
+  commit order.
+
+## Required plan and proof
+
+For each boundary, `plan.md` records:
+
+| Boundary | Timeout/retry/idempotency | Duplicate/order/partial handling | Degradation/recovery | Observability | Proof |
+| --- | --- | --- | --- | --- | --- |
+| `<provider → consumer>` | `<budgets/key>` | `<rules>` | `<user/system path>` | `<signals/owner>` | `<test/rehearsal>` |
+
+Proof drives success, invalid shape, partial response, auth failure, rate limit, timeout,
+duplicate, out-of-order delivery, and outage when relevant. Deterministic cases use a
+contract-capable fake or sandbox per [`testing.md`](testing.md) — never a mock that
+simply returns the expected payload (that tests the stub, not the boundary) — plus at
+least one real boundary check when authorized and safe.
+
+## Stop conditions
+
+Stop planning or Seal when a non-idempotent unknown outcome can be blindly retried, a
+consumer can acknowledge before durable handling, a poison/backlog path has no owner, a
+partial response can become success silently, or outage recovery and monitoring are
+missing. Unavailable provider evidence is `cannot_verify`, not a pass.