@oevery/rsp 2.0.3 → 3.1.0-beta.0

package/skills/rsp/SKILL.md

@@ -1,99 +1,172 @@
 ---
 name: rsp
-description: Use this skill when initializing RSP in a repository, operating an existing .rsp project, auditing or repairing .rsp state, or deciding whether a change needs durable updates before archive.
-compatibility:
-  agents:
-    - any agent that supports the Agent Skills format
-  requirements:
-    - Node.js 18+
-    - local filesystem read/write access
-    - shell access for `rsp` or `npx -y @oevery/rsp`
-  optional_requirements:
-    - network access for first-run `npx` installation or skill refresh
+description: Use this skill when initializing RSP, operating an existing .rsp project, auditing or repairing .rsp state, or deciding whether a change needs durable updates before archive.
+license: MIT
 metadata:
   author: oevery
-  version: 2.0.3
+  version: "2026.07.24.1"
 ---
 
 # RSP Skill
 
-Load this skill when you need to initialize RSP, operate an existing RSP project, audit or repair `.rsp/`, or decide whether a change needs durable updates before archive.
+Load this skill when you need to initialize RSP, operate `.rsp/`, audit or repair RSP state, or make a durable-update decision before archive.
 
-This skill operationalizes the rules in `.rsp/rules/rsp-rules.md`. Always load and follow those rules first.
+This skill is the preferred operational guide. `.rsp/rsp-rules.md` is the only runtime fallback protocol when this skill is unavailable; old projects migrate to it with `rsp update`.
 
 Prefer exact file paths, exact commands, and exact durable facts over vague summaries.
 
+Choose response language and artifact language independently. Render human-facing response headings, field labels, explanations, and conclusions in the language explicitly requested for the response; otherwise follow response-specific project instructions, then the conversation language. Write artifact prose in the language explicitly requested for that artifact; otherwise follow artifact-specific project instructions, then the existing artifact's language, then the conversation language. Preserve canonical RSP artifact headings, keywords, identifiers, paths, commands, and machine-consumed values unchanged. Response-only Continuation and Durable Decision headings and labels are not canonical artifact headings and must be localized.
+
+Write persistent artifacts in domain, system, user, or operator language. Mention AI or agents only when they are actual product actors, consumers, interface participants, or constraints; using AI to perform the work is not itself a durable fact.
+
 ## When to use
 
-- Use this skill when a repository already contains `.rsp/` and the task is to operate within that workflow.
-- Use this skill when adopting RSP in a repository that does not yet have `.rsp/`.
-- Use this skill when the task is to audit or repair `.rsp/`, `AGENTS.md`, generated indices, or focus markers.
-- Use this skill when deciding whether a completed change needs durable updates before archive.
+- Use for RSP setup, repair, focused RSP work, and pre-archive durable decisions.
+- Use when a user explicitly asks to adopt, inspect, or operate the RSP workflow.
 
 ## When not to use
 
-- Do not load this skill for general coding tasks unrelated to `.rsp/`.
-- Do not use this skill as a substitute for reading `.rsp/rules/rsp-rules.md` during a focused RSP task.
-- Do not use this skill when the repository does not use RSP and the user did not ask to adopt it.
+- Do not load for general coding tasks unrelated to `.rsp/`.
+- Do not load when the repository does not use RSP and the user did not ask to adopt it.
+- Do not create an RSP change for a simple current-session task unless the user explicitly wants RSP tracking.
+- Do not treat this skill or the fallback protocol as a replacement for nearest project `AGENTS.md` instructions or relevant module `CONTEXT.md`.
+
+## Derive one next action
+
+Before operating the workflow, derive the current stage from user intent, nearest project authority, `rsp status --json`, the selected Change's readiness, fresh verification evidence, and blockers. Stages are derived guidance, never persisted state.
+
+### Route implementation evidence
+
+When work has reached implementation, classify the decisive evidence before selecting a capability:
+
+- **Diagnosis:** an observed failure is reproducible or materially evidenced, but its cause or owning layer remains unexplained. Conflicting, intermittent, or multi-layer symptoms also take this branch. Select `rsp-diagnose` only when it is available; otherwise use the manual diagnosis fallback: reproduce, locate, test the smallest discriminating hypothesis, and return the evidenced cause without speculative production edits.
+- **TDD:** there is no unexplained failure, the required or corrected behavior is clear, and test-first work is explicitly required by the user, selected Change, or project instructions, or a concrete changed risk makes an observed pre-mutation RED materially safer. Concrete risks include public APIs or protocols, persisted data, security or money, concurrency or cancellation, complex state transitions, and defects that escaped to production. Select `rsp-tdd` only when it is available; otherwise use the manual TDD fallback: observe the focused RED, make the minimum GREEN change, optionally REFACTOR while green, then rerun required checks. Behavior being testable, a test being possible, or the work being a fix is not sufficient by itself.
+- **Ordinary implementation:** this is the default when diagnosis does not apply and no TDD gate above is met. Continue with ordinary `rsp-implement` when the required behavior, cause, or edit is sufficiently evidenced, or use the single manual implementation/verification action when that Skill is unavailable.
+
+Diagnosis takes precedence over TDD: do not encode an unexplained symptom as a guessed regression test. Fresh verification is required, but a new test is only one evidence option; prefer the cheapest decisive existing test, static check, build, or acceptance evidence that covers the changed risk. Each branch returns its evidence, Tasks, Verify updates, and unresolved Blockers to the same selected Change. Capability availability changes execution assistance, not the owner or required outcome.
+
+### Route release documentation
+
+Use the release-documentation branch only when the selected Change explicitly owns a confirmed release identity or range and still has unfinished changelog, release-note, or migration work. Lifecycle stage, completed implementation, or archive readiness alone is insufficient; ordinary Changes continue to the Core durable decision.
 
-## Workflow
+When both conditions hold, select `rsp-release-docs` when available. Otherwise use the manual release-documentation fallback against the same Change: confirm the release range and audience, build one net-release evidence ledger, and project it into the repository-owned changelog, release notes, and applicable migration guidance. This route prepares or audits documentation only; it does not grant commit, tag, push, release creation, publication, deployment, or approval authority.
 
-### Adopt or initialize
+Apply these gates in order:
 
-1. Use one of these commands:
-   - `npx -y @oevery/rsp init --agents-mode managed`
-   - `npx -y @oevery/rsp init --agents-mode print`
-   - `npx -y @oevery/rsp init --with-project-setup --agents-mode managed`
-   - `npx -y @oevery/rsp init --with-project-setup --agents-mode print`
-2. If the repository still needs an explicit bootstrap change and you did not use `--with-project-setup`, run `npx -y @oevery/rsp create project-setup`.
-3. Fill `changes/project-setup.md`.
-4. Set an explicit `kind` in the change frontmatter.
-5. Write durable architecture, boundaries, defaults, and constraints into `specs/design.md`.
-6. Write stable local workflow or validation rules into `rules/project-rules.md` only when they are long-lived.
-7. Run `npx -y @oevery/rsp doctor`.
+1. If authority, selection, or a material owner decision is ambiguous, return the one decision or evidence needed to proceed. If a declared blocker prevents the next operation, return its owning artifact or person; do not route around it.
+2. If the user explicitly requests managed continuation, select `rsp-manage` only when it is available. Its eligibility gate activates only for one focused ready Change with genuinely independent slices, long authorized continuation, or interruption recovery; an ineligible request returns the exact ordinary Core or Discipline next action without mutation or controller artifacts. Managed routing is never implicit and grants no lifecycle, Git, publication, deployment, approval, or human-acceptance authority.
+3. If the user requests a report-only review against a fixed scope, select `rsp-review` only when it is available; otherwise name the manual read-only review and return its findings to the selected Change's Tasks, Verify, or Blockers.
+4. If no Change is selected, use the status plan to name one ready WorkRef and the direct focus action. For tiny settled work, return the direct engineering action without creating RSP state. For unclear non-trivial work, select `rsp-shape` only when it is available and the user authorized its Change mutation; otherwise give the manual fallback of creating or refining one Change.
+5. If the user or Shape has isolated one material domain, module/seam, or evidence-seeking design question for the selected Change, select `rsp-design` when available; otherwise return the compact manual design fallback: inspect project authority and the live path, compare credible alternatives, separate evidence from owner choice, and return the result to the same WorkRef without implementation or durable-truth mutation.
+6. If the selected Change is not shape-ready and no bounded design question has been isolated, select `rsp-shape` under the same authority rule or give the manual fallback of completing its Proposal, Spec, Design, Tasks, Verify, and Blockers.
+7. If a shape-ready Change has incomplete implementation tasks, or its required verification is missing, stale, or failed, apply the implementation-evidence routing above. Select only its resulting available capability when authorized; otherwise name its manual fallback owned by that Change.
+8. If implementation Tasks and required verification pass with no blocker, and the selected Change meets both release-documentation conditions above, select `rsp-release-docs` under the same availability rule or use its manual fallback. Return its evidence and artifact dispositions to the same Change.
+9. Otherwise, when required Tasks and verification pass with no blocker, perform the Core durable decision. Archive only after required current facts and rationale are written or explicitly judged unnecessary. Recommend explicit archive as the next action before final Git delivery; Core does not execute archive or grant authority to stage, commit, push, or publish.
 
-### Operate an existing project
+State the derived stage, one next action, required input, returned owner, and decisive evidence. Name at most one available optional capability. Only name an optional capability when it is the one next action, and treat it as available only when it appears in the host's loaded skill inventory. Missing optional capabilities never invalidate RSP; always provide the manual fallback against the same owner.
 
-1. Follow the read order in `.rsp/rules/rsp-rules.md`.
-2. If a focused change is missing an explicit `kind`, repair the frontmatter before continuing.
-3. If an existing open change should become current work, use `npx -y @oevery/rsp focus <name>`.
-4. Do not treat unfocused files in `changes/` as current work unless the user explicitly asks for them or you first run `npx -y @oevery/rsp focus <name>`.
+Do not preload, enumerate, or recursively invoke optional capabilities. Do not infer implementation, review, Git, publication, or approval authority from routing, readiness, or capability availability.
 
-### Audit or repair
+## Workflows
 
-1. Check that `.rsp/` exists.
-2. Check that `AGENTS.md` contains the managed RSP block.
-3. Check that `specs/design.md` exists.
-4. Check that `specs/INDEX.md` and `archives/INDEX.md` are still generated files.
-   `specs/INDEX.md` should list only additional spec files beyond `specs/design.md`.
-5. Check that `focus.d/` markers and `changes/` files are in sync.
-6. If generated indices or the managed AGENTS block drift, run `npx -y @oevery/rsp update`.
+### Setup or repair
+
+1. Initialize with `npx -y @oevery/rsp init [--agents-mode managed|print] [--with-project-setup]`.
+2. `--with-project-setup` creates and focuses `changes/project-setup.md`; otherwise create it with `npx -y @oevery/rsp create project-setup` only when explicit bootstrap tracking is still needed.
+3. Fill the bootstrap change if it exists, write durable architecture facts to `.rsp/specs/design.md`, and keep stable scoped operating instructions in the nearest project-owned `AGENTS.md`.
+4. For diagnostics, run `npx -y @oevery/rsp doctor`.
+5. For safe deterministic repairs, run `npx -y @oevery/rsp doctor --fix` or `npx -y @oevery/rsp update`.
+6. When auditing manually, verify `.rsp/`, managed roots, and nested Spec parents are real directories; the project `AGENTS.md`, managed markers, fallback/config files, indexes, and placeholders are regular files; `AGENTS.md` has the managed block; `specs/design.md` and the configured Decision Record directory exist; every group has one valid brief with matching direct children; work and archive trees are flat or one group level; and `focus.d/` markers match executable Changes.
+7. Treat `doctor --fix` `fixed` entries as actual filesystem changes. An empty `fixed` array or `No safe fixes needed.` means the repair pass changed nothing.
+8. Do not use repair commands for semantic decisions such as stale focus removal, durable updates, or archive readiness.
+
+### Focused work
+
+1. Follow the managed `AGENTS.md` read order: nearest instructions, relevant context, this skill or fallback protocol, focus, optional sibling Group Brief, selected Change, then relevant Specs and Decision Records.
+2. Treat only `focus.d/` markers as current RSP work; do not treat unfocused files in `changes/` as current work unless the user explicitly asks or you run `npx -y @oevery/rsp focus <name>`.
+3. Resolve executable Change names as either `<change>` or one direct `<group>/<change>` child. Require a real `changes/` root and real existing `focus.d/`, `archives/`, and group prefixes; reject symlinks, incomplete inspection, deeper paths, and file/directory identity collisions.
+4. Use a Change Group only for at least two independently executable Changes sharing one goal or completion contract. Create it with `npx -y @oevery/rsp group create <group> [goal]`, then replace the brief placeholders and declare every direct child identity and boundary under `Slices` before creating children.
+5. Treat logical `<group>/brief`, physically stored as `<group>/00-brief.md`, as non-executable and non-focusable. For grouped work, read it before the selected child Change. Its `Slices` declaration order guides navigation; a Brief blocker is inherited as an external blocker by every direct child without creating edges. Archive children independently, then close only the brief with `npx -y @oevery/rsp group close <group>` when all group gates pass.
+6. Declare an exact prerequisite only as `- requires \`<change-work-ref>\`: <reason>` under the dependent Change's `Blockers`. Targets must be executable Changes, not Group Briefs. Keep external blockers as ordinary prose and never infer an edge from them.
+7. Use `npx -y @oevery/rsp status --json` as the derived dependency view. Read `plan.nodes`, `plan.ready`, `plan.edges`, `plan.blocked`, and `plan.waves`; nodes distinguish selected Changes from prerequisite context, and each edge reads as “`change` requires `requires`” with `reason` and `state`. Filtered plans retain the transitive prerequisite closure needed to explain the selection. Human status renders the same flat graph as a dependency forest; do not infer nested JSON ownership from that presentation. Do not create or maintain a separate graph or copy live delivery state into a Group Brief. Archived prerequisites resolve without rewriting the dependent Change, while incomplete archive inspection produces no ready plan.
+8. Read the focused change before editing code.
+9. If a focused change is missing an explicit `kind`, repair the frontmatter before continuing.
+10. Run `npx -y @oevery/rsp check --focused` before treating focused work as ready; resolve dependency errors, placeholders, or clarification warnings when they represent real unfinished content.
+11. Treat `rsp check` warnings as deterministic hygiene signals, not as the durable-update decision.
+12. Use `npx -y @oevery/rsp create <name> --lite` only when the user explicitly wants RSP tracking for a small, straightforward change.
+13. Convert actionable `## Tasks` checkboxes into your agent-local task tracker when one is available.
+14. Keep implementation sequential by default; parallelize only independent read-only discovery or mechanical checks.
+15. Update `## Tasks`, `## Verify`, and any invalidated `## Proposal`, `## Spec`, or `## Design` content in the same working session as implementation facts change.
+16. Keep the selected Change as a convergent snapshot of the current plan and final decisive evidence. Replace stale or superseded content; keep routine attempts, RED/GREEN loops, command transcripts, and correction chronology in the response, then compress any material history to final outcomes, coverage, omissions, and unresolved risks before archive.
+17. Keep temporary debugging notes, task history, and command transcripts out of `specs/` and project-owned `AGENTS.md` instructions.
+
+### Route artifacts by owner
+
+Use one semantic routing matrix throughout shaping, execution, and pre-archive review:
+
+| Content | Owner | Boundary |
+| --- | --- | --- |
+| Planned future design | selected Change `## Design` | Never write planned state as current truth. |
+| Implemented stable current facts | smallest relevant Spec, usually `.rsp/specs/design.md` or an existing domain Spec | Write only observed stable facts under authority. |
+| Lasting rationale and tradeoffs | one exact file under `durableReview.decisionRecordsPath` | Judge independently from current facts; do not duplicate them. |
+| Stable scoped navigation or current context | project-owned `CONTEXT.md`, when that convention exists | Preserve project ownership and edit only with explicit authority. |
+| Stable operating instructions | nearest project-owned `AGENTS.md` outside the managed RSP block | Preserve project ownership and edit only with explicit authority. |
+| Temporary execution state | response continuation | Not durable truth; write a file only when explicitly authorized. |
+
+When accepted work remains, return this compact artifact-scoped continuation in the response:
+
+```md
+## <localized RSP Continuation heading>
+- <localized WorkRef label>: <selected Change>
+- <localized Authority label>: <project, Change, Spec, decision, or report pointers>
+- <localized Current state label>: <completed, partial, failed, unavailable, or blocked plus decisive state>
+- <localized Changed artifacts label>: <paths or none>
+- <localized Fresh verification label>: <command and result, or pending reason>
+- <localized Blockers label>: <exact blocker and owner, or none>
+- <localized Next action label>: <smallest bounded action and owner>
+```
 
-## Expected outputs
+Treat this continuation shape as semantic field order rather than fixed English wording. Localize its human-facing title and labels to the response language while preserving WorkRefs, paths, commands, identifiers, and machine-consumed values. A localized label may retain a technical token in parentheses but must not use that English token alone; for example, use `工作引用（WorkRef）` in a Chinese response. Do not use the response language to rewrite referenced project artifact prose.
 
-- exact file paths to read or update
-- exact RSP commands to run
-- a single durable-decision result in the required template when evaluating archive readiness
+The continuation points to existing owners; it is not a second state store. On resume, reopen every authority pointer, inspect worktree and artifact drift, and refresh any verification supporting the next action. Never create hidden handoff/controller state or persist the continuation without explicit path authority.
 
-## Trigger examples
+### Handle an active Git conflict
 
-- "Set up RSP in this repository."
-- "Repair the broken .rsp state in this project."
-- "Check whether this change needs spec or rule writeback before archive."
-- "Audit the RSP setup and tell me what is missing."
+When a merge, rebase, or cherry-pick conflict intersects authorized implementation:
+
+1. Inspect the exact Git operation, conflicted paths, current index/worktree, and pre-existing user changes.
+2. Interpret base, ours, and theirs in that operation; trace the relevant behavior and authority instead of choosing a side mechanically.
+3. Resolve only evidenced content inside the WorkRef and mutation authority. Preserve unrelated work and do not stage the resolution unless separately authorized.
+4. Stop when the conflict includes unrelated user work, an unresolved product decision, incomplete side/base evidence, or out-of-scope content. Return the exact conflict and required owner input in the continuation.
+5. After an authorized working-tree resolution, rerun affected checks and return their fresh result.
+
+Do not continue or abort the Git operation, commit, push, or infer Git delivery authority from implementation or conflict-resolution authority. RSP does not need a separate merge-conflict Skill for this fallback.
+
+### Pre-archive durable decision
+
+1. Run `npx -y @oevery/rsp check --focused` for focused work, or `npx -y @oevery/rsp check` when reviewing all open changes.
+2. Run `npx -y @oevery/rsp show --focused --json` or `npx -y @oevery/rsp ready <name> --json` to collect readiness, warnings, context paths, and `durableReview` guidance.
+3. Treat `durableReview.factCandidateTargets` and `durableReview.decisionRecordsPath` as advisory routing context, not as permission to edit generated indexes or invent a Decision Record filename.
+4. Treat `Spec` delta markers (`### ADDED`, `### MODIFIED`, `### REMOVED`) as planning aids only; do not merge them automatically.
+5. Read only the current Change, relevant Specs and Decision Records, nearest project-owned `AGENTS.md`, and code files needed for the semantic decision.
+6. Produce the durable decision output before archiving.
 
 ## Durable decision
 
-Before `npx -y @oevery/rsp archive <name>`:
+Choose one current-fact decision and one rationale decision independently.
+
+Current facts:
 
-1. Read the current change.
-2. Read only the relevant `specs/` and `rules/` files.
-3. Inspect code only if needed.
-4. Return exactly one decision:
+- `No current-fact update needed`
+- `Update existing spec or scoped instruction`
+- `Create a new durable spec` only when the knowledge is project-level, reusable, and does not fit `specs/design.md`, an existing spec, or a scoped project instruction
 
-- `No durable update needed`
-- `Update existing spec or rule`
-- `Create a new durable spec` only when the knowledge is truly project-level, reusable, and does not fit `specs/design.md`, an existing spec, or a rule file
+Rationale:
+
+- `No Decision Record needed`
+- `Create or update a Decision Record`
+
+Prefer no update on either axis when there is no concrete stable fact or lasting rationale worth rereading.
 
 Write a durable update only when one of these is true:
 
@@ -102,75 +175,47 @@ Write a durable update only when one of these is true:
 - future agents or developers would likely make mistakes without the fact
 - the fact is worth rereading in later sessions as durable project knowledge
 
-When unsure whether a fact is truly durable, prefer `No durable update needed` over speculative promotion.
-
-Default to no spec writeback unless the change produced project-level durable knowledge that future work must reread.
-
-Do not write these into `specs/` or `rules/`:
-
-- temporary debugging history
-- task-by-task execution notes
-- one-off implementation context
-- archive-only historical detail
-- a catch-all summary file like `specs/changes.md`
+Create or update a Decision Record only when the choice is hard to reverse, would be surprising without context, and reflects a real tradeoff. Decision Records own rationale, alternatives, tradeoffs, and consequences; Specs own what is currently true.
 
-Choose the smallest correct target:
+Apply the artifact-routing matrix and choose the smallest correct target:
 
-- project-wide design, boundaries, defaults, and durable context -> `specs/design.md`
-- stable local workflow or validation rules -> `rules/project-rules.md`
-- another durable rule set -> `rules/<name>.md`
-- an additional reusable project-level spec -> `specs/<name>.md`
+- project-wide design, boundaries, defaults, and durable context -> `.rsp/specs/design.md`
+- stable project or module operating instructions -> nearest project-owned `AGENTS.md`, only with authority to edit its non-managed content
+- stable navigation or scoped current context -> project-owned `CONTEXT.md`, only when the project uses it and authority permits the edit
+- an additional reusable project-level spec -> `.rsp/specs/<name>.md`
+- lasting rationale -> one exact Markdown file under `durableReview.decisionRecordsPath`
 
-Prefer `specs/design.md` or an existing durable file before creating a new spec file.
+Do not choose generated indexes, `.rsp/rsp-rules.md`, or the managed RSP block in `AGENTS.md` as ordinary durable writeback targets.
 
-When writing the durable update:
+Prefer `.rsp/specs/design.md` or an existing durable file before creating a new spec file.
 
-- write stable facts, not narrative history
-- prefer concrete facts and boundaries over summaries like "implemented X" or "investigated Y"
-- if you cannot identify a concrete durable target or concrete durable facts, do not invent them
-
-Set archive readiness like this:
-
-- If `Blockers` still contains a real blocker, set `Archive ready: no`.
-- If a durable update is required but not yet written, set `Archive ready: no`.
-- If no durable update is missing and the remaining `Verify` risk is consciously accepted, set `Archive ready: yes`.
-- Do not use CLI warning text as a substitute for semantic durable-update judgment.
+Write stable facts or lasting rationale, not narrative history, task-by-task notes, temporary debugging history, or archive-only detail. Do not duplicate current facts into a Decision Record or rationale into a Spec. If you cannot identify concrete durable content, do not invent it.
 
 ## Output template
 
-Use this exact format:
+Use these semantic fields in this exact order. Localize the heading and human-facing labels to the response language; preserve the decision values shown in angle brackets as canonical values.
 
 ```md
-## Durable Decision
-- Decision: <No durable update needed | Update existing spec or rule | Create a new durable spec>
-- Target: <path or N/A>
-- Why:
-  - <reason>
-- Facts to write:
-  - <durable fact>
-- Archive ready: <yes | no>
+## <localized Durable Decision heading>
+- <localized Current facts label>: <No current-fact update needed | Update existing spec or scoped instruction | Create a new durable spec>
+- <localized Current-fact target label>: <exact file path or N/A>
+- <localized Facts to write label>:
+  - <durable fact or none>
+- <localized Decision Record label>: <No Decision Record needed | Create or update a Decision Record>
+- <localized Decision Record target label>: <exact file path or N/A>
+- <localized Rationale to write label>:
+  - <lasting rationale or none>
+- <localized Archive ready label>: <yes | no>
 ```
 
-Minimal example:
-
-```md
-## Durable Decision
-- Decision: Update existing spec or rule
-- Target: .rsp/specs/design.md
-- Why:
-  - The change introduced a stable default and boundary that future work must follow.
-- Facts to write:
-  - Default API retries are capped at 3 attempts.
-  - Background sync stops retrying after a permanent authentication failure.
-- Archive ready: no
-```
+These are response labels, not canonical RSP artifact headings. A localized label may retain its technical field identity in parentheses; for example, a Chinese response may use `## 持久化决策`, `决策记录（Decision Record）`, and `可归档（Archive ready）`, but not their English labels alone.
 
 Rules for the output:
 
-- `Target` must be a concrete file path when the decision is not `No durable update needed`.
+- Each target must be an exact file path when its decision requires an update; `durableReview.decisionRecordsPath` is a directory, not the final target.
 - `Facts to write` must contain durable facts, not task history or debugging notes.
-- If the decision requires a durable update that is not yet written, `Archive ready` must be `no`.
-
-## Refresh guidance
-
-- After rule or skill changes, prefer a fresh session and reread `AGENTS.md` plus `.rsp/rules/*.md`.
+- `Rationale to write` must contain lasting rationale, alternatives, tradeoffs, or consequences, not a duplicate of current facts.
+- If real blockers remain or a required fact or rationale update is not yet written, `Archive ready` must be `no`.
+- If neither axis has a missing update and remaining verify risk is consciously accepted, `Archive ready` may be `yes`.
+- Do not use CLI warning text as a substitute for semantic durable-update judgment.
+- CLI `archiveReady: judgment` means the skill or a human must decide; it is not automatic approval.

package/skills/rsp-address-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: rsp-address-review
+description: Resolve one fixed rsp-review report for an RSP-tracked change. Use when the user authorizes disposition of review findings, bounded fixes for accepted findings, fresh verification, re-review, or a recoverable artifact-scoped handoff; keep the reviewer report-only and never infer Git or publication authority.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.22.1"
+---
+
+# RSP Address Review
+
+Resolve one fixed review report without changing what the reviewer observed. Treat resolution as a bounded correction pass, not a retry loop or a second project lifecycle.
+
+Render headings, field labels, explanations, and conclusion prose in the language explicitly requested by the user; otherwise follow nearest project instructions, then the conversation language. Treat report and handoff shapes as semantic field order rather than fixed English wording: translate their human-facing labels when the output language differs. Preserve paths, commands, identifiers, WorkRefs, FindingRefs, severity labels, and the dispositions `accepted`, `rejected`, and `needs-clarification` unchanged.
+
+## Fix scope and authority
+
+Require the review report, its fixed comparison or file set, the selected Change and sibling Group Brief when applicable, relevant project authority, and explicit permission for any proposed mutation. Read the current worktree and the smallest behavior chain needed to verify each Finding. Preserve unrelated modified, staged, and untracked work.
+
+Identify a Finding by its report order plus severity, title, and location. Stop if the report, comparison, Change, or Finding identity is missing or conflicting. A report grants investigation only: correction, verification, re-review, Git delivery, publication, deployment, approval, and external actions retain their own authority. Never infer Git or publication authority.
+
+## Disposition every finding
+
+Assign exactly one disposition and concise evidence to every input Finding:
+
+- `accepted`: current production or document evidence confirms the issue, the intended correction is authoritative, and the fix is inside the selected Change and mutation authority;
+- `rejected`: direct evidence disproves the issue or shows that its suggested action is not required by the selected authority; record the evidence and do not edit for it;
+- `needs-clarification`: an owner decision, authoritative requirement, reproducible trigger, or safe scope is missing; name the required input and do not edit for it.
+
+Do not accept feedback for politeness, reject it from intuition, or silently reinterpret an ambiguous Finding. When one correction covers multiple accepted Findings, retain each disposition and point them to the shared fix.
+
+## Fix accepted findings
+
+In one resolution pass, implement the smallest complete correction for accepted Findings only. Add or adjust focused tests when the corrected behavior or failure contract requires them. Do not modify `rsp-review`, the original report, or unrelated findings to make the result appear clean.
+
+After the last relevant edit, run fresh verification for the affected behavior and the selected Change. A failed, unavailable, stale, or omitted check cannot close an accepted Finding. If a check exposes another defect, return it as evidence; do not begin an automatic retry loop.
+
+Require a fresh fixed-scope re-review before claiming resolution. Return a re-review request containing the original comparison, selected authority, post-fix file set or immutable comparison, implementation summary, dispositions, and verification evidence. The re-review remains report-only. On resume with its report, correlate original Findings as resolved or remaining and treat any new Finding as unresolved input for a later authorized pass.
+
+## Handoff and recovery
+
+When work stops before a clean re-review, return Core's compact artifact-scoped continuation with review state embedded in the shared fields:
+
+```md
+## <localized Review Resolution Handoff heading>
+- <localized WorkRef label>: <selected Change>
+- <localized Authority label>: <project, Change, fixed report, and comparison pointers>
+- <localized Current state label>: <review input, FindingRef dispositions, and re-review status>
+- <localized Changed artifacts label>: <reviewed and changed paths, or none>
+- <localized Fresh verification label>: <command and result, or pending reason>
+- <localized Blockers label>: <unresolved FindingRefs and required owner input, or none>
+- <localized Next action label>: <smallest bounded action and owner>
+```
+
+The handoff contains authoritative pointers, not project truth. Return it in the response unless the user explicitly authorizes a path; never create a hidden receipt or persistent run state. It is not durable truth or a second state store. Exclude secrets, full logs, and duplicated Change text.
+
+To recover, reopen every authority pointer, confirm the WorkRef and comparison still identify the intended scope, inspect current worktree drift, and revalidate claimed verification. Mark stale evidence pending instead of trusting the handoff. Continue only the named pass; host threads, agents, hooks, or proprietary resume features are optional and never required.
+
+## Return ownership
+
+Report the disposition table, changed artifacts, preserved unrelated work, fresh verification, re-review status, and the handoff when anything remains. Resolution is complete only when every Finding has a supported disposition, every accepted Finding has a verified correction, the fresh fixed-scope re-review is clean, and no `needs-clarification` input remains. Never claim archive, commit, push, publication, deployment, or approval.

package/skills/rsp-design/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: rsp-design
+description: Resolve one material domain-model, module/seam, or evidence-seeking design question for an explicit or unambiguously focused RSP Change without implementing production behavior or writing durable project truth.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.22.2"
+---
+
+# RSP Design
+
+Resolve one design question and return the result to its existing RSP owner. Do not implement the result.
+
+## Establish the question and authority
+
+Require an explicit WorkRef or exactly one unambiguous focus marker. Read the nearest project instructions and context, the RSP core Skill or fallback protocol, the selected Change and sibling Group Brief, then the smallest relevant Specs, decisions, code, tests, callers, and runtime evidence.
+
+State the single material question before analysis. If the WorkRef, question, required evidence, owner intent, or mutation authority is missing or ambiguous, stop with the smallest blocker. Never invent product intent.
+
+## Load one design mode
+
+Load only the reference matching the question:
+
+- Read [domain modeling](references/domain-modeling.md) for vocabulary, identity, lifecycle, invariants, relationships, or ownership.
+- Read [module and seam design](references/module-seams.md) for interface obligations, caller complexity, adapters, test surfaces, or seam placement.
+- Read [reversible exploration](references/reversible-exploration.md) only when a material conclusion depends on unobserved behavior and a cheap safe probe can provide it.
+
+Keep evidence-driven conclusions separate from choices only the owner can make. Compare at least one credible alternative when alternatives exist; do not manufacture options for a conclusion forced by evidence or authority.
+
+## Preserve artifact ownership
+
+Default to report-only. When the user or project explicitly authorizes updating the selected Change, write settled planned design only under its `Design` section. Do not write Specs, Decision Records, `CONTEXT.md`, `AGENTS.md`, production code, lifecycle state, focus, archives, or Git state. Identify possible durable current facts or rationale only as artifact-routing candidates for the Core durable review.
+
+An exploration additionally requires explicit disposable-code authority and the cleanup contract in its reference. A design request alone grants neither production mutation nor external side-effect authority.
+
+## Return the bounded result
+
+Follow Core's response-versus-artifact language boundary: use the requested language for natural prose, while any authorized `Design` update follows the selected Change's language and canonical headings. Do not use a technical token alone as a response label; retain it only in parentheses after a localized label. Return these semantic fields:
+
+- selected WorkRef and exact question;
+- inspected evidence and material gaps;
+- recommendation and evidence-driven reasoning;
+- credible alternatives and tradeoffs;
+- unresolved owner decisions;
+- artifact routing and any authorized Change update;
+- smallest next action.
+
+Return to Shape or the user against the same WorkRef. Do not create parallel state, recursively invoke another Skill, implement, review, archive, stage, commit, push, publish, deploy, or approve.

package/skills/rsp-design/references/domain-modeling.md

@@ -0,0 +1,11 @@
+# Domain modeling
+
+Use this procedure only for a question about domain language, identity, lifecycle, invariants, relationships, or ownership.
+
+1. Collect the project's existing terms from its authoritative context, Specs, code, tests, and user language. Record contradictions rather than silently choosing one source.
+2. Trace concrete scenarios across creation, transition, failure, cancellation, deletion, and relevant scope boundaries. Prefer observable lifecycle evidence over type names alone.
+3. Identify each concept's identity, owner, allowed transitions, invariants, and relationships. Distinguish a domain concept from a transport shape, persistence record, UI label, or implementation helper.
+4. Propose the smallest coherent vocabulary and ownership model that explains the evidence. Test it against at least one edge case and one existing production consumer.
+5. Separate conclusions forced by evidence from product choices that require owner confirmation.
+
+Return canonical terms, definitions, ownership and lifecycle implications, conflicts with current usage, alternatives, and unresolved owner decisions. Planned vocabulary may update only the authorized selected Change `Design`; flag possible current-fact or rationale destinations without writing them.

package/skills/rsp-design/references/module-seams.md

@@ -0,0 +1,11 @@
+# Module and seam design
+
+Use this procedure only for a question about an interface, caller complexity, adapter, test surface, or seam placement.
+
+1. Trace the direct production consumer and the smallest complete call/data path before proposing a seam. Confirm the live path reaches the candidate owner.
+2. List what callers must know: inputs, outputs, invariants, ordering, failures, configuration, cancellation, and relevant performance constraints.
+3. Locate where behavior or policy actually varies. Do not add an interface for hypothetical variation or wrap an existing pass-through for symmetry.
+4. Compare credible placements by caller leverage, implementation locality, dependency direction, state ownership, and whether callers and tests can use the same public surface.
+5. Recommend the smallest interface that hides meaningful complexity while preserving domain ownership. State migration or compatibility consequences without implementing them.
+
+Return the proposed owner, seam, interface obligations, affected consumers, verification surface, alternatives, and unresolved owner decisions. Treat code sketches as explanatory output only; do not write production code.

package/skills/rsp-design/references/reversible-exploration.md

@@ -0,0 +1,19 @@
+# Reversible exploration
+
+Use this procedure only when a material design conclusion depends on behavior that available code, tests, documentation, or runtime evidence does not establish.
+
+## Define the probe
+
+- State one question, falsifiable hypothesis, observation, and stop condition.
+- Prefer inspection or an existing focused command. Create code only when that cheaper evidence cannot answer the question.
+- Require explicit authority for disposable mutations and any runtime or external side effect. Otherwise describe the probe and return the authority blocker.
+
+## Isolate and clean up
+
+- Keep disposable code outside production owners and name it clearly as temporary. Do not change public interfaces, migrations, persistent data, credentials, or delivery state.
+- Record the pre-probe file state and exact cleanup target. Avoid the probe when unrelated work makes safe cleanup uncertain.
+- Run only the minimum observation, capture the evidence, then remove every disposable artifact before returning. Verify cleanup without discarding unrelated work.
+
+## Return evidence, not architecture
+
+Report the hypothesis, method, observation, confidence and limitations, cleanup evidence, design implication, and remaining owner decision. A probe can support a recommendation; it is never durable architecture or permission to implement production behavior.

package/skills/rsp-diagnose/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: rsp-diagnose
+description: Diagnose one selected RSP Change when a reproducible or materially evidenced failure has an unexplained cause or owning layer. Use for conflicting, intermittent, or multi-layer symptoms before production correction.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.22.1"
+---
+
+# RSP Diagnose
+
+Establish a confirmed cause before correction. Keep the selected Change as owner and return investigation evidence to it.
+
+Follow Core's response-versus-artifact language boundary.
+
+## Establish bounds
+
+Resolve exactly one executable open Change from an explicit work reference or unambiguous focus. Read the user request, nearest project instructions, relevant context, RSP rules, the sibling Group Brief when present, the selected Change, and only the code, tests, logs, configuration, and worktree evidence needed to investigate.
+
+A diagnosis request grants read-only investigation and safe diagnostic command execution. Editing tests, instrumentation, fixtures, or the Change requires explicit mutation authority. Production correction is outside this Skill even when separate fix authority exists.
+
+Stop with one evidence request when the target, expected behavior, investigation scope, or safe reproduction conditions are unclear.
+
+## Diagnose
+
+1. **REPRODUCE.** Capture the smallest command or observation that exposes the symptom, its expected and actual result, and relevant conditions. When reproduction is unsafe or unavailable, label the supplied evidence and its limits. Continue only with a stable symptom or material evidence.
+2. **LOCATE.** Trace the live path to the first boundary where actual behavior diverges from expected behavior. Identify the affected layer and owner; verify that any suspected adapter, validator, cache, or wrapper is reached by the production consumer.
+3. **HYPOTHESIZE.** State the smallest set of live competing causes and the distinct observation each predicts. A single hypothesis is sufficient only when existing evidence already excludes credible alternatives.
+4. **DISCRIMINATE.** Run the smallest safe check that separates the leading hypotheses. Record the exact command or observation and decisive result. Prefer one discriminating check over broad speculative changes.
+5. **CONFIRM.** Confirm a cause only when observed evidence selects it over the remaining live alternatives and explains the reproduced symptom. Otherwise return `unresolved` with the missing evidence and one bounded next check.
+
+## Return evidence
+
+Return:
+
+- selected Change;
+- result: `confirmed` or `unresolved`;
+- reproduction or supplied-evidence limit;
+- cause and affected owner, or remaining hypotheses;
+- decisive evidence and impact boundary;
+- investigation mutations, if explicitly authorized;
+- exactly one next action.
+
+For `confirmed`, name one correction entrypoint owned by the same Change; do not apply it. For `unresolved`, name the next discriminating check or blocker. Update that Change's Tasks, Verify, or Blockers only with authority and observed facts. Preserve unrelated work and never infer Git, delivery, publication, or approval authority.
+
+When correction, further discrimination, or other work remains, use Core's compact continuation fields in order: `WorkRef`, `Authority`, `Current state`, `Changed artifacts`, `Fresh verification`, `Blockers`, and `Next action`. Put the result, reproduction limit, cause or hypotheses, decisive evidence, and impact boundary in `Current state`; put authorized investigation mutations in `Changed artifacts`. Reopen authority pointers, inspect drift, and refresh decisive evidence before resuming. This response is not durable truth or a second state store; persist it only with explicit path authority.

package/skills/rsp-implement/NOTICE.md

@@ -0,0 +1,27 @@
+# Third-party notice
+
+The fresh-verification discipline in this Skill adapts concepts from
+`obra/superpowers`, revision `d884ae04edebef577e82ff7c4e143debd0bbec99`,
+`skills/verification-before-completion/SKILL.md`.
+
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.