devrites 5.5.0 → 5.6.0

package/pack/generated/pi/skills/rite-ship/reference/git-ship.md

@@ -0,0 +1,120 @@
+# The irreversible ship: type-GO + git ladder
+
+`/rite-ship` alone runs irreversible actions. A seal GO is never authorization for Git.
+Require fresh approval for one disclosed attempt plus native permission.
+
+## The type-GO prompt (render verbatim, wait)
+
+```
+Feature:  <slug>
+Verdict:  GO  (seal.md)
+Acceptance criteria proven: <n / total>
+Branch:   <target branch>
+Candidate paths: <exact project-relative paths>
+Checkpoint collapse: <exact `git reset --soft '<merge-base>'` command | skip>
+Collapse slugs: <active slug plus every recorded sequence slug in the range | n/a>
+Stage plan: <exact argv-safe `git add -- '<path>'` command for every manifest row>
+Commit:   <exact git commit command>
+Push:     <exact git push command | skip>
+Tag:      <exact git tag command | skip>
+PR:       <exact PR command, target, title, and body source | skip>
+Close:    <exact `devrites-engine state close '<slug>'` for each sealed sequence predecessor | skip>
+
+Type "GO" exactly to approve this attempt once. Anything else cancels.
+```
+
+Rules:
+- Render every attempt; autocomplete flags only reach this boundary.
+- Only literal `GO` proceeds. Anything else cancels, records
+  `user declined irreversible step at <ts>` in `ship.md`, and stops.
+- `GO` is one-use for the shown scope/commands; changed/retried plans re-prompt.
+- Prior answers, AFK, seal GO, and native approval do not replace type-GO;
+  type-GO never replaces/bypasses native permission or sandbox approval.
+
+## The candidate-safe Git ladder
+
+Follow `standards/git-workflow.md` and project convention; invent no release flow.
+Candidate identity always comes from `devrites-engine check candidate`; do not
+implement a Git-side hash.
+
+### Before type-GO
+
+Pre-GO is read-only. Do not run the disclosed collapse or staging commands.
+
+0. **Protect existing index work.** Read the NUL-delimited staged state/path set.
+   Refuse a pre-existing staged path outside the manifest; never unstage, stage,
+   reset, or discard user work.
+1. **Analyze checkpoint history without mutating it.** Read the upstream, merge
+   base, commit OIDs, and full subjects. If no checkpoint commit exists, disclose
+   `skip`. A collapse is eligible only when every commit in its range has the exact
+   `WIP(<slug>):` prefix for the validated active slug — or, for a release ship of a
+   deferred-ship sequence, for a slug recorded in the parent's `decisions.md`
+   sequence whose workspace is sealed in this run
+   ([afk-hitl.md § Sequence continuation](../../devrites-lib/reference/standards/afk-hitl.md#sequence-continuation-continue_sequence-max_workspaces));
+   disclose the exact slug set. A different slug, missing colon, broad `WIP(` match,
+   ordinary commit, or mixed history blocks; never reinterpret the range.
+2. **Verify the candidate.** Rerun `devrites-engine check candidate <slug>` and
+   `devrites-engine check seal <slug>`, compare every binding, require the
+   candidate worktree paths to be unchanged, and inspect the existing staged
+   scope. These checks do not prepare the index.
+3. **Prepare the disclosure.** Build argv-safe commands from literal validated
+   paths, without `eval` or command-string interpolation. Run only read-only
+   secret scans of the existing staged state and proposed PR body. Render the
+   literal prompt with the exact optional collapse command or `skip`, exact stage
+   plan, commit, push, tag, and PR commands; then wait.
+
+### After type-GO
+
+1. **Optional checkpoint collapse.** If and only if the prompt disclosed it,
+   recheck that `HEAD`, merge base, and every subject are unchanged and that each
+   subject starts exactly `WIP(<slug>):` for the disclosed slug set, then run the
+   exact disclosed `git reset --soft "$mb"`. Otherwise skip. Any different or mixed
+   subject blocks without mutation.
+2. **Exact staging.** Run `git add -- "$path"` once for each disclosed manifest
+   row, passing each validated project-relative path as its own quoted argv
+   element. Use no glob, directory, `-A`, `.env`, secret, out-of-scope path,
+   `eval`, or interpolated command string.
+3. **Compare staged scope.** Compare the NUL-delimited output of
+   `git diff --cached --name-status --no-renames -z` to the manifest's exact
+   state/path set. `present` maps only to `A` or `M`; `deleted` maps only to `D`.
+   Reject missing, extra, renamed, duplicated, or differently classified paths.
+4. **Compare staged bytes.** Require no index-to-worktree difference for any
+   manifest path. A dirty manifest path stops; never stage or reinterpret it
+   after this comparison.
+5. **Revalidate immediately before commit.** With no intervening mutation,
+   rerun `devrites-engine check candidate <slug>` and
+   `devrites-engine check seal <slug>`, require the exact candidate digest and
+   every evidence/browser/review/Seal binding, then run the staged secret scan.
+   Any scope, byte, identity, binding, scan, history, or command drift invalidates
+   the one-use approval. Stop and render a fresh type-GO prompt; do not repair the
+   drift under the old approval.
+6. **Commit** one logical change using Conventional Commit and a why-body.
+   Non-trivial work adds applicable `Constraint:`, `Rejected:`, `Confidence:`,
+   `Scope-risk:`, and `Not-tested:` workspace trailers; trivial edits omit them.
+7. **Verify the commit.** Immediately after the authorized commit and before any
+   push or tag, compare
+   `git diff-tree --root --no-commit-id --name-status --no-renames -r -z HEAD`
+   to the manifest using the same exact state/path mapping. Require candidate
+   paths still match `HEAD`, then rerun `devrites-engine check candidate <slug>`
+   and `devrites-engine check seal <slug>` and compare the exact digest again.
+   Any mismatch stops; do not reinterpret it.
+8. **Push** to the project-conventional target branch.
+9. **Tag / PR** only when project convention requires it; otherwise skip.
+10. **Close sealed predecessors** only when the prompt disclosed them: run the
+    exact `devrites-engine state close '<slug>'` once per predecessor. Each is safe
+    because `ACTIVE` names the release workspace; a nonzero exit stops the rest and
+    is reported, never retried against an unverified destination.
+
+Record SHA(s), branch, and tag/PR URL in `ship.md`.
+
+## Pull request body
+
+When this ship opens a PR, include only applicable sections:
+
+- **Summary:** what shipped and acceptance proven.
+- **Risk & rollback:** migration/auth/destructive risk and reversal from `seal.md`.
+- **What to scrutinize:** highest-blast-radius review stops.
+- **Evidence:** condensed proof plus the archived evidence bundle.
+
+For an agent-owned staged rollout, apply [`rollout.md`](rollout.md). CI-owned deploys
+skip that branch. Delete empty sections rather than writing `N/A`.

package/pack/generated/pi/skills/rite-ship/reference/rollout.md

@@ -0,0 +1,62 @@
+# Staged rollout and recovery: live deploys only
+
+Load this only when `/rite-ship` itself is explicitly authorized to drive a live
+deployment. Git-only Ship stops before rollout; CI-owned deployment follows the pipeline's
+runbook. A Seal GO or AFK setting never authorizes production action.
+
+## Preconditions before exposure
+
+Record one rollout sheet in `ship.md`:
+
+| Item | Required decision/evidence |
+| --- | --- |
+| Units and order | Repository/deployable, schema, config, application, worker, contract, and flag order; safe old/new combinations. |
+| Exposure stages | Project-native internal/canary/cohort/percentage/region stages and hold window. |
+| Advance/hold/abort signals | Project baseline or SLO, measurement window, minimum sample, exact threshold, and owner. |
+| Recovery | Fastest safe mechanism, steps, owner, measured/rehearsed time, and data/external-effect reconciliation. |
+| Observability | Watched dashboard/query/alert, failure signal, and executable first action. |
+| Authorization | Exact target/action approved for this attempt; no inferred retry permission. |
+
+Do not import generic percentage, latency, error-rate, or time-to-rollback numbers. Use
+accepted product risk, current baseline/SLO, traffic volume, and platform capability. If the
+project has no defensible threshold or signal, the monitoring gap blocks live exposure.
+
+## Choose the smallest reversible mechanism
+
+- A feature flag is useful only when the off path preserves current behavior, both states
+  are tested, disabling it stops the risky effect, and it has an owner/removal trigger.
+  Do not add a flag to a change already reversible by a safe atomic deploy.
+- A flag cannot reverse destructive data/schema effects. Apply
+  [`data-integrity.md`](../../devrites-lib/reference/standards/data-integrity.md) and prove
+  restore or forward recovery separately.
+- External APIs, webhooks, queues, jobs, and caches apply
+  [`integration-reliability.md`](../../devrites-lib/reference/standards/integration-reliability.md):
+  reconcile unknown outcomes, drain/quarantine/replay safely, and protect downstream capacity.
+- Multi-root/service rollout follows
+  [`repository-topology.md`](../../devrites-lib/reference/standards/repository-topology.md);
+  references to another repository never grant write/deploy authority there.
+
+## Stage, observe, decide
+
+At each authorized stage:
+
+1. Verify the intended versions/config/schema and candidate identity on the exact target.
+2. Exercise one critical success path and the declared degradation/recovery signal.
+3. Observe for the recorded window and sample; bind results to the stage and baseline.
+4. **Advance** only when every advance condition holds. **Hold** on ambiguous or
+   insufficient evidence. **Abort/recover** immediately on an abort condition, security or
+   tenant breach, data-integrity violation, unreconciled duplicate/unknown effect, or loss of
+   observability.
+5. Re-verify after recovery; record partial effects and reconciliation. A rollback command
+   exiting zero is not proof the prior state or data was restored.
+
+Never compress stages because an early sample "looks fine," continue through a monitoring
+gap, or retry a failed live action without fresh authorization when the attempt/target changes.
+
+## Completion
+
+Rollout is complete only when full intended exposure meets the recorded window/signals,
+telemetry is still watched, migrations/backfills and queues/reconciliation are settled,
+documentation matches deployed behavior, and temporary flags/compatibility paths have a
+dated removal owner. Otherwise report the exact current stage and remaining risk; do not call
+the launch done.

package/pack/generated/pi/skills/rite-ship/reference/ship-template.md

@@ -0,0 +1,39 @@
+# `ship.md` template
+
+Write before close-out; it moves to `.devrites/archive/<slug>/ship.md`.
+
+```markdown
+# Ship: <slug>
+
+- Shipped at: <iso>
+- Verdict: GO (seal.md)
+- Branch: <branch>
+- Commit(s): <sha> [<sha> …]
+- Tag/PR: <value|none>
+
+## What shipped
+<project-vocabulary paragraph>
+
+## Acceptance
+- Proven: <n/total> (evidence.md/seal.md)
+- Outstanding: <rows below | none>
+
+## Evidence
+- seal.md — verdict/reconciliation
+- evidence.md — acceptance; browser-evidence.md if UI
+- review.md — review findings
+
+## Follow-up reconciliation
+Checked: strategy.md (if present), decisions.md, review.md, seal.md.
+
+| Source | Item | Disposition | Destination / rationale |
+|---|---|---|---|
+| <file + section> | <item> | tracked | <durable path/ID> |
+| <file + section> | <item> | no-action | <decision or explicit human no-action approval + reason/revisit> |
+
+<If empty: No residual items found.>
+```
+
+Keep pointers short. Acceptance MUST match `seal.md`. Each source residual appears
+once; a missing target, unsupported `no-action`, vague disposition, or conflict blocks
+close-out.

package/pack/generated/pi/skills/rite-spec/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: rite-spec
+description: Specify new, vague, or high-risk behavior before code. Use for features, auth, migrations, or public API changes; not for planning an approved spec.
+argument-hint: "<feature or idea>"
+user-invocable: true
+---
+
+# /rite-spec: investigate and write the spec
+
+Investigate and resolve material gaps into a placed, covered `spec.md`.
+`/rite-clarify` audits topology next. Write no plan, task, or code here.
+
+> Use `/rite-quick` for a typo, copy/config edit, or one-function fix. It returns
+> here for auth, data, migration, public API, or multi-slice work.
+
+## Rules consulted (read on demand from `.pi/skills/devrites-lib/reference/standards/`)
+Pull `documentation.md` for significant decisions and `principles.md` for
+declared invariants; an unavoidable principle violation is blocking.
+For behavioral/high-risk acceptance, use `spec-grammar.md` plus workspace schema;
+simple criteria stay flat `AC-###`. Apply
+[`acceptance-criteria.md`](reference/acceptance-criteria.md) so each is binary and observable.
+Use [`edge-case-trace.md`](../devrites-lib/reference/standards/edge-case-trace.md)
+to populate only relevant edge/prohibition rows. The spec's applicability map routes
+topology, data, integration, security, and delivery concerns to their focused standard;
+load a routed standard to discover required behavior, not to prescribe implementation.
+
+## Operating rules (DevRites core)
+- No silent assumptions or guessing; prefer conventions; ask on scope,
+  placement, data, UX, security, migration, or acceptance changes.
+- **Root authority:** controlling chat asks humans, decides, and writes workspace;
+  evidence work follows [`agents.md`](../devrites-lib/reference/standards/agents.md).
+- **Author one section at a time:** problem → goal → requirements → acceptance →
+  edges. For contested requirements/boundaries/assumptions, apply
+  [`elicitation.md`](../devrites-lib/reference/standards/elicitation.md) before continuing.
+
+## Workflow
+0. Read core; if `.devrites/ACTIVE` exists, require its `state.md`.
+0a. **Adoption check.** For a never-adopted existing codebase, route first to
+   `/rite-adopt` with `$ARGUMENTS`; it derives baseline spec/principles. HITL
+   offers ranked adopt-first and spec-only choices; permitted AFK adopts.
+   Silently skip greenfield/onboarded projects, and never block solely on absence:
+   ```bash
+   if [ ! -d .devrites/archive ] \
+      && [ -z "$(ls .devrites/work 2>/dev/null)" ] \
+      && [ -n "$(git ls-files 2>/dev/null | grep -vE '^\.(devrites|claude)/' | head -1)" ]; then
+     echo "brownfield, not yet adopted → recommend /rite-adopt first (carry this idea as its next objective)"
+   else echo "greenfield or already onboarded → continue spec"; fi
+   ```
+1. **Understand the request** (`$ARGUMENTS`). State outcome and underlying
+   problem in one sentence. **Completion:** it includes both.
+1a. **Dedupe.** Search local issues/PRDs, work, and archive. On a close match ask
+   extend/adopt/new, then record the choice; otherwise continue silently.
+   A recorded [feature-sequence continuation](../rite-plan/reference/slicing.md#continuation-workspaces)
+   is a **new** workspace (`<parent>-2`): carry the parent slug and position into
+   `brief.md`, read the parent artifacts as design input, and do not route to
+   `/rite-plan revise` on the parent. When the ask is open and archived work records
+   an unfinished sequence, propose that next continuation (slug + objective) as the
+   recommended option instead of a fresh slug.
+2. **Investigate:** follow [investigation](reference/investigation.md) through its
+   complete findings and done-when gate. Discover the project's **test /
+   build/typecheck/lint** commands, frontend/backend systems, and declared project guidance
+   (`PRODUCT.md`, `DESIGN.md`, `CLAUDE.md`, `AGENTS.md`, and `.devrites/principles.md` when
+   present).
+   **Consult the capability ledger**, which records current system behavior
+   ([`ledger.md`](../rite-polish/reference/ledger.md)); Polish folds accepted deltas
+   before Review. List `.devrites/specs/*/spec.md` with the
+   host filesystem and read only capabilities this feature touches. Search accepted ADRs and
+   relevant `.devrites/**/decisions.md` files directly before asking the human to revisit a
+   settled architecture, API, or auth choice. Compare exact requirement headers and meanings
+   with the current ledger to choose ADDED/MODIFIED/REMOVED; never classify from memory. Use
+   `spec-grammar.md`'s singular `Capability impact:` declaration to name the affected
+   capabilities and change, or give its specific `none` justification.
+   Inventory affected observable behavior from current test/contract/runtime/source
+   evidence; map each outcome to preserving REQ/AC. Greenfield `none` needs the
+   template's specific justification.
+   Identify proof constraints now: human-only credentials, unavailable environments, approval
+   windows, or acceptance not observable through existing test/runtime/browser surfaces.
+   An unfamiliar framework/version routes to `devrites-source-driven`; missing or
+   contradictory documentation is evidence to reconcile, never a license to guess.
+   Split independent placement, blast-radius, and external-fact questions into at most three
+   bounded `devrites-evidence-scout` tasks on one frozen candidate. Wait for and reconcile every
+   cited dossier before step 4. The scout supplies facts only; it never asks the human or writes
+   the spec.
+3. **Gather design references when provided:** [references-intake](reference/references-intake.md).
+   The human may attach screenshots, mockups, a Figma link, a video, links, or nothing.
+   Skip this step when none are provided. Otherwise, **view or fetch**
+   them, **save local files** into `.devrites/work/<slug>/references/`, and index them in
+   `references.md` as target, constraint, or inspiration. Later phases honor that role
+   rather than treating every reference as a fidelity target.
+   **Completion:** every supplied reference is saved and classified, or absence is explicit.
+3a. **Shape UX/UI before code when the feature is frontend**
+   ([frontend-trigger](../rite-build/reference/frontend-trigger.md)). Apply
+   `devrites-ux-shape` within the spec phase. It turns the
+   references and spec into a feature-level **`design-brief.md`** (design direction, key
+   states, interaction model, optional Figma/image visual-direction probe) that `/rite-build`
+   targets for the build. In HITL it pauses for the human to
+   confirm the direction; in AFK it asserts the best guess and logs it. Pure
+   backend/data/CLI features skip this.
+4. **Resolve human-owned gaps.** Recommend an option and let the human decide. Apply
+   [question-protocol](reference/question-protocol.md), the shared
+   [`afk-hitl.md` option-set and decision-ownership rules](../devrites-lib/reference/standards/afk-hitl.md#decision-ownership-search-before-asking),
+   and [`interview-patterns.md`](reference/interview-patterns.md) for a vague ask. Every
+   material dimension is resolved by a human pick or explicitly deferred as non-blocking;
+   only genuinely reversible, low-impact details go to `assumptions.md`. A paper-only
+   uncertainty may take one scoped `/rite-prototype` detour. A declared-principle conflict
+   remains blocking until the human approves a recorded, scoped exception.
+4a. **Build-interruption forecast.** Search first, then list and close foreseeable human needs:
+   product/acceptance ambiguity, irreversible/external approval, or human-only access. Record
+   owned prerequisites. Keep a build checkpoint only for unavailable pre-code evidence or a
+   mandatory action-time approval. **Completion:** no foreseeable human choice is deferred.
+5. **Create or update the workspace** + set `.devrites/ACTIVE` from
+   [state-workspace](reference/state-workspace.md). If the slug already exists,
+   update the existing workspace rather than overwrite it; preserve history and
+   unrelated settled content. Write every required artifact and conditional
+   annex exactly from [spec-template](reference/spec-template.md)
+   ([ai-spec-template](reference/ai-spec-template.md)), including its
+   capability impact, existing-behavior preservation, grammar/delta,
+   stakeholder/constraint/invariant, failure/recovery, applicability, coverage-seed,
+   qualified backstop, edge/prohibition, UI, and AI rules. Native
+   hierarchical instructions remain stable; do not rewrite `AGENTS.md` or
+   `CLAUDE.md` for the active workspace.
+5a. **Check the spec prose** with [spec-checklists](reference/spec-checklists.md).
+   Emit every applicable domain checklist and fix each CRITICAL by correcting the spec,
+   never by softening the question.
+6. **Run the complete readiness gate** at the bottom of
+   [spec-template](reference/spec-template.md), then apply the
+   **Native grammar re-read checklist** in `spec-grammar.md` to the complete
+   saved `spec.md`. Re-open the file after corrections and verify every
+   applicable item; there is no parser or replacement script. Natively compare
+   deltas with the current ledger using exact header semantics and the ledger's
+   complete-block preservation rule.
+   `tasks.md` deliberately does not exist yet; cross-artifact traceability starts in
+   `/rite-define`. Any grammar or delta failure blocks. The interruption forecast must be resolved, owned, or a justified
+   action-time gate. Then write `Spec gate: passed <iso>`.
+6a. **Existing-spec delta.** For a pre-existing slug/workspace, compare old/new
+   spec and questions, then show `Acceptance delta` (added/removed/reworded IDs)
+   and `Open-question delta` (opened/resolved/reworded IDs), using `none` for
+   empty categories. Show before proceeding; new workspaces skip.
+6b. **Review-before-code digest.** Before planning, render the compact human review:
+   `Intent` (one sentence), `Done means` (top acceptance/scenario IDs), `Scope/risk` (what is in/out
+   plus the hard gates), and `Build exactly this?` (yes → next phase; no → revise now). The digest
+   is a view over `spec.md`, not a new artifact. **Stop** after the digest.
+
+> **Mid-flight discipline.** Do not skip investigation, gap resolution, or placement
+> decisions. See [`anti-patterns`](reference/anti-patterns.md).
+
+## Output
+
+When the ask overlaps the ACTIVE feature (same intent, >50% scope), route to
+`/rite-plan revise` (its gate decides) rather than minting a parallel workspace.

package/pack/generated/pi/skills/rite-spec/reference/acceptance-criteria.md

@@ -0,0 +1,31 @@
+# Acceptance criteria
+
+Acceptance criteria are the contract the seal checks. Write them so each is
+**independently verifiable by evidence**, not opinion.
+
+## A good criterion
+- Is observable: a test passes, a command outputs X, a screenshot shows Y.
+- Is binary: met or not: no "mostly".
+- Names the evidence: "`npm test path/x.test.ts` passes" or "POST /export returns 200
+  with a CSV body" or "empty state renders 'No exports yet' at 375px".
+- Belongs to a slice: every criterion maps to at least one slice (mapped in `/rite-define`).
+
+## Forms
+| Type | Template |
+|---|---|
+| Functional | "Given <state>, when <action>, then <observable result>." |
+| API | "<METHOD> <route> with <input> returns <status> and <shape>." |
+| UI | "<screen> shows <element/state> at <viewport>; <interaction> does <result>." |
+| UI vs reference | "<screen> matches design reference <Rn> at <viewport>." |
+| Non-functional | "<operation> completes under <budget> / handles <volume>." |
+| Negative | "<invalid input> is rejected with <message>, no <side effect>." |
+
+## Anti-patterns
+- "Works well" / "is fast" / "looks good": unverifiable. Attach a number or an
+  observation.
+- Criteria with no slice: orphaned scope.
+- Criteria only provable by reading the code: require runtime/test evidence instead.
+
+## At seal time
+Each criterion gets a checkbox + the evidence that proves it. Unproven critical
+criteria force **NO-GO**.

package/pack/generated/pi/skills/rite-spec/reference/ai-spec-template.md

@@ -0,0 +1,40 @@
+# `ai-spec.md` template
+
+Create this annex only when the feature touches model calls, RAG, agents, evals,
+or LLM output.
+
+```markdown
+# AI-SPEC: <Feature>
+
+## AI surface
+| Surface | Purpose | Owner |
+| --- | --- | --- |
+| <model call/RAG/agent/eval> | <why it exists> | <module/team> |
+
+## Model/runtime choice
+- Framework/model/provider: <choice or project default>
+- Settings that matter: <temperature, tools, retrieval scope, limits>
+- Fallback/degradation: <what users see when AI is unavailable>
+
+## Domain evals
+| Eval ID | Scenario / slice | Dataset provenance | Expected signal + threshold | Gate |
+| --- | --- | --- | --- | --- |
+| EVAL-001 | <representative/adversarial/empty-context case> | <held-out source/version> | <pass condition and baseline delta> | build/seal |
+
+For RAG, cover retrieval relevance/context recall, context precision, answer
+faithfulness, citation support, tenant/ACL isolation, poisoned or conflicting documents,
+and insufficient-context fallback as applicable. A single polished example is not an eval.
+
+## Guardrails
+- Inputs: <validation, prompt-injection boundaries, tenant/data limits>
+- Retrieval: <source provenance, indexing validation, tenant/ACL filter, freshness/deletion>
+- Outputs: <schema checks, refusals, human review, citations only to supporting retrieved sources>
+- Privacy/security: <data sent to model, retention, secrets policy>
+- Unknown/insufficient context: <abstain, clarify, or bounded fallback; never fabricate>
+
+## Monitoring
+- Runtime metrics/logs: <latency, cost, retrieval/quality, refusal/error/fallback rates>
+- Alerts or manual review: <trigger>
+- Rollback/kill switch: <prompt/model/index version and reversible mechanism>
+- Drift evaluation: <reference set, schedule/trigger, regression threshold, owner>
+```

package/pack/generated/pi/skills/rite-spec/reference/anti-patterns.md

@@ -0,0 +1,27 @@
+# rite-spec: anti-patterns
+
+Load this when standing a non-trivial decision in `/rite-spec`, or when the
+agent feels reluctance toward investigation depth, gap-closing, or
+placement decisions.
+
+Pack-wide rationalizations + red flags: see [standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "User said *just make it work*: no spec needed." | Vague asks are exactly where `/rite-spec` earns its keep; load `devrites-interview` and ask one question at a time. |
+| "I already understand the request." | Then writing the placement + acceptance criteria takes minutes and saves drift later. Investigation isn't for *you*, it's for `/rite-define`. |
+| "Too small for a spec." | If it's big enough for `/rite-build`, it's big enough for one paragraph of WHAT/WHY + measurable acceptance. |
+| "No design refs were attached, so skip references." | Skip the *gathering*, not the *acknowledgement*. Note "no references provided" in the spec: silence is ambiguous. |
+| "I can resolve gaps as I build." | Drift discovered at slice 3 costs more than 5 questions answered now. |
+| "I'm confident of the answer, so I'll just decide this myself." | Confidence changes the *cost* of the question, not its *owner*. A material decision (scope · placement · data model · UX · security · migration · acceptance) is put to the human as a ranked option set: near-certainty just makes it a one-pick confirm, never a silent decision. |
+| "Presenting options for every gap is over-asking." | Over-asking is many questions at once or asking what the codebase answers. One ranked option set per *material* gap, recommended-first, is the opposite: it hands the human the decision cheaply. Reversible low-impact details you still auto-decide and log. |
+
+## Red Flags
+
+- About to start writing `spec.md` without a Placement & integration section.
+- Spec has no measurable acceptance criteria: "works as expected" is not measurable.
+- A `[NEEDS CLARIFICATION]` marker remains on a blocking item.
+- Design references were attached but never opened, saved, or indexed in `references.md`.
+- The investigation didn't read the module/component that currently owns this area.

package/pack/generated/pi/skills/rite-spec/reference/interview-patterns.md

@@ -0,0 +1,56 @@
+# Interview patterns
+
+Question ladders by domain. Pull the rung that matches the biggest current unknown.
+Each question still follows the protocol: one at a time, best guess attached.
+
+## Vague ask? Map the decision tree first
+For a fuzzy one-liner (`"design a contact page"`, `"add reporting"`), sketch the branches
+the answer splits into, then resolve each **depth-first**: one branch to a decision before
+opening the next:
+
+```text
+contact page
+├─ purpose?   ── sales lead | support request | general
+├─ fields?    ── name/email/message | + company/phone | file upload
+├─ on submit? ── email | ticket/CRM | DB row | embedded third-party form
+└─ success?   ── inline confirm | redirect | autoresponder
+```
+
+Once per interview you may **challenge the premise** instead of refining it
+(*"is a form even the right answer, or a mailto / booking link?"*): a good reframe
+collapses whole branches. Then use the domain ladders below for each open branch.
+
+## Objective / problem
+- "What does success look like in one sentence?"
+- "Who hits this, how often, and what do they do today instead?"
+- "If we shipped only one thing here, what must it be?"
+
+## Scope boundaries
+- "What is explicitly **out** of scope for this first version?"
+- "Is this a new capability or a change to an existing flow?"
+- "What's the smallest version that's still useful?" (→ slice 1)
+
+## Data model
+- "What are the core entities and how do they relate?"
+- "What's the source of truth, and can these fields change after creation?"
+- "Any uniqueness, ordering, or soft-delete needs?"
+
+## UX / flow
+- "Walk me through the happy path screen by screen."
+- "What are the empty / loading / error / permission-denied states?"
+- "Brand surface (marketing) or product surface (app UI)?" (drives craft)
+
+## Integration / external
+- "Which external systems or APIs are involved, and who owns them?"
+- "Sync or async? What happens when the dependency is down?"
+
+## Non-functional
+- "Any latency, scale, or volume targets I should design to?"
+- "Auth/permission rules? Anything sensitive (PII, secrets, payments)?"
+
+## Acceptance
+- "How will we *prove* this works: what's the test or observation?"
+- "What would make you reject the PR?"
+
+## Anti-references (taste)
+- "Show me one thing that does this well, and one that does it badly."

package/pack/generated/pi/skills/rite-spec/reference/investigation.md

@@ -0,0 +1,83 @@
+# Investigation before specification
+
+Understand the requirement, decide where it belongs, define the outcome, and identify
+every issue and gap. Resolve material gaps with the user before the spec is ready. A
+gap first found during `/rite-build` is a drift event.
+
+Use a code-intelligence index if available (see
+`../../devrites-lib/reference/standards/tooling.md`) for structural questions such as
+where code lives, what calls it, and what it could break. With none present, use
+Read/Grep/Glob. When a gap depends on an external fact, such as a standard, UX pattern,
+or comparable product, **search the web if available** (brave MCP preferred;
+`../../devrites-lib/reference/standards/tooling.md`). Cite the finding in the option
+presented to the human.
+
+## Check the archive first
+Before external research, check whether the project already shipped related work. Search
+the archive for the feature's key nouns. A hit may indicate an extension, conflict, or
+replacement and provides prior decisions:
+Use native file search over `.devrites/archive/*/{spec,decisions}.md`.
+- **Overlap found** → read the overlapping `spec.md` + its `decisions.md`, then put it to
+  the human as a ranked option (*extend the shipped feature* · *this supersedes it* ·
+  *genuinely distinct*) same option-set contract as a gap.
+- **No archive / no hit** → skip silently; never block a spec on absent history (the
+  brownfield / principles no-op discipline).
+
+## Produce these findings (write into spec.md)
+1. **The request and problem:** restate the goal and the problem behind it (people ask
+   for "a dashboard" when they want an answer to a question). Who hits it, how often,
+   what they do today instead.
+2. **Current behavior:** how it works today, or what's absent. Read the actual code and
+   flows; don't assume.
+3. **Placement**
+   - Which module / layer / file / component should own this; the right seam.
+   - Existing patterns/components/utilities to **extend or reuse** instead of duplicating.
+   - **Integration points**: callers and dependents, the data it reads/writes, the
+     APIs/events/contracts it touches (interface analysis: how it interacts with the
+     rest of the system).
+4. **Outcome:** the result and how to observe it (feeds
+   success + acceptance criteria).
+5. **Issues:** conflicts with existing code/UX/data/permissions, constraints, and
+   anything that makes the obvious approach wrong. Each issue gets a disposition.
+6. **Gaps:** unknowns, ambiguities, undecided behavior, missing inputs. **Every gap
+   becomes a question** (next section).
+7. **Blast radius:** what this change could break (use the code graph's impact/callers).
+   Informs risks, test strategy, and rollback.
+8. **Human prerequisites:** credentials, accounts, approval windows, or irreversible
+   action-time decisions the acceptance path requires. Separate these from agent-owned
+   implementation and diagnostic work.
+
+Design/reference materials the human supplies: see [references-intake](references-intake.md).
+
+## Gap analysis (present → desired)
+State the present and desired states. Their delta defines the work; unknowns in that
+delta are gaps. Resolve them before `/rite-define`. Mark each gap inline with
+`[NEEDS CLARIFICATION: question]`.
+
+## Present gaps and issues as options
+For each material gap or issue that changes scope, placement, data model, UX, security,
+migration risk, or acceptance, **ask the human** one gap at a time with a ranked
+option set with the recommended option **first and marked `(Recommended)`** plus an escape
+hatch (via `AskUserQuestion` in HITL):
+```
+<gap/issue stated in one line>. Why it matters: <...>
+1. <recommended option> (Recommended) — <implication / where it places the work; cite any web/docs finding>
+2. <alternative> — <implication>
+3. <alternative> — <implication>
+4. Something else — I'll describe it
+```
+Investigate and recommend, but do not settle a material decision. High confidence may
+make the answer a one-pick confirmation; it does not change the decision owner.
+Only a **genuinely reversible, low-impact** gap is decided and recorded in `assumptions.md`
+without asking. Full render contract + AFK behaviour: [`afk-hitl.md`](../../devrites-lib/reference/standards/afk-hitl.md).
+
+## Done when
+- The shipped archive was checked for prior art; any overlap was surfaced to the human.
+- The problem, current behavior, placement, and outcome are written down.
+- Every issue has a disposition; every material gap is resolved **by a human pick** from its
+  option set (or explicitly deferred as non-blocking), not settled silently on your confidence.
+- Every foreseeable build-time human prerequisite is resolved, assigned, or justified as an
+  action-time gate; objective repair/retry work is not disguised as a question.
+- No blocking `[NEEDS CLARIFICATION]` remains. The spec covers the gaps found during
+  authoring and records correct placement. This is the `/rite-spec` readiness gate
+  before `/rite-clarify` performs the systematic topology scan.

package/pack/generated/pi/skills/rite-spec/reference/question-protocol.md

@@ -0,0 +1,36 @@
+# Spec question protocol
+
+For vague or unknown intent, invoke `devrites-interview` for ordered one-question turns,
+recommendations, option sets, pass limits, reframing, and closure.
+This file owns only Spec-specific coverage and recording. Render through
+[`Option set`](../../devrites-lib/reference/standards/afk-hitl.md#option-set-how-every-gap-is-presented).
+
+## Coverage gate: am I done asking?
+Each dimension MUST be **resolved** or **explicitly deferred** (logged, non-blocking),
+never skipped:
+- [ ] **Objective:** one-sentence success + the real problem behind it.
+- [ ] **Scope**: what's in vs explicitly out for v1.
+- [ ] **Data model**: core entities + relationships (or "none").
+- [ ] **UX / flow**: happy path + empty/loading/error/permission states (or "no UI").
+- [ ] **Integration**: external systems/APIs/contracts (or "none").
+- [ ] **Non-functional**: auth, sensitive data, latency/scale (or "n/a").
+- [ ] **Acceptance**: how each requirement is *proven* (test/observation).
+- [ ] **Human prerequisites**: credentials, approval windows, irreversible action-time gates
+  (or "none").
+
+An agent recommendation is not a user answer. A human-owned material product, scope, UX,
+compatibility, or acceptance choice closes only by the user's option selection, free-form
+answer, or explicit deferral. Packets MAY be bounded; readiness MUST NOT. Rescan and continue
+while blockers remain. If the user stops, keep them blocking and MUST NOT pass `/rite-spec`
+readiness.
+
+## Spec question boundary
+- Search code, decisions, authoritative docs before asking discoverable facts.
+- Decide and log agent-owned reversible implementation/test details.
+- Record tooling failures as prerequisites or blockers; never ask the human to authorize repair.
+- Ask only material choices, not everything at once.
+
+## Record
+Confirmed answers → `decisions.md` (with rationale). Agent-owned reversible, low-impact
+technical assumptions →
+`assumptions.md`. Open non-blocking items → `questions.md`.