@oevery/rsp 2.0.4 → 3.1.0-beta.1

package/skills/rsp-release-docs/references/output-contracts.md

@@ -0,0 +1,115 @@
+# Output contracts
+
+Use these as fallbacks. Preserve an established repository format whenever it exists.
+
+The generic baseline is Keep a Changelog 1.1.0 for cumulative structure and Semantic Versioning 2.0.0 for version meaning. Treat Conventional Commits, forge-generated notes, and label-based categorization as evidence inventories rather than finished prose.
+
+## Release evidence ledger
+
+Maintain a temporary table or equivalent structured notes:
+
+| Evidence | Net outcome | Audience | Risk/action | Changelog | Release notes | Reference | Exclusion/uncertainty |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| PR, issue, Change, commits, diff, docs, verification | What users receive | Users, developers, operators, maintainers | Breaking, migration, security, compatibility, none | Section or omit | Section or omit | PR, issue, work item, commit, compare | Reason or owner decision |
+
+The ledger is an analysis device, not a new project state store. Persist it only when the repository already owns release fragments or the user authorizes a destination.
+
+## Default changelog shape
+
+```markdown
+# Changelog
+
+## [Unreleased]
+
+## [3.0.0] - YYYY-MM-DD
+
+### Added
+
+- Add a user-visible capability. ([#123])
+
+### Changed
+
+- **Breaking:** Change an existing contract. See the [migration guide].
+
+### Fixed
+
+- Prevent an observable failure in a supported workflow. ([abc1234])
+
+[Unreleased]: https://github.com/OWNER/REPO/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/OWNER/REPO/compare/v2.0.0...v3.0.0
+[#123]: https://github.com/OWNER/REPO/pull/123
+[abc1234]: https://github.com/OWNER/REPO/commit/abc1234...
+[migration guide]: https://example.com/migration
+```
+
+Use Added, Changed, Deprecated, Removed, Fixed, and Security as fallback categories. Omit empty categories. Do not add an Unreleased section when the established project intentionally does not use one.
+
+## Default release-note shape
+
+```markdown
+# Version 3.0.0
+
+One short paragraph explaining the release's purpose and who benefits.
+
+## Highlights
+
+- Outcome and benefit, grouped by capability rather than commit.
+
+## Breaking changes and migration
+
+- Who is affected, what action is required, and where to find the full guide.
+
+## Other changes
+
+- Notable improvements and fixes that matter to this audience.
+
+## Compatibility and known limitations
+
+- Supported environments, verified coverage, and explicit non-claims.
+
+**Full changelog:** https://github.com/OWNER/REPO/compare/v2.0.0...v3.0.0
+```
+
+Omit inapplicable sections. Prefer three to seven scannable themes for a typical release; group small visible fixes without hiding high-impact items. Include contributors when the established release surface values attribution.
+
+## Migration contract
+
+For each required action, answer:
+
+1. Who is affected?
+2. What old behavior or surface changes?
+3. What must they do, in what order?
+4. What compatibility window or deadline applies?
+5. How can they verify success?
+6. What rollback, recovery, or support path exists?
+
+Keep a short summary in release notes and link a dedicated guide when the procedure is long, conditional, or operationally risky.
+
+## Reference rules
+
+- Add one compare or tag link for the release range when the forge supports it.
+- Prefer PR links for reviewable implementation context.
+- Prefer issue or tracked-work links for rationale and migration context.
+- Prefer commit links for exact fixes, backports, audit provenance, projects without PRs, or explicit user policy.
+- Keep references optional per bullet; a link must earn its visual cost.
+
+## Net-release examples
+
+- Five commits build one new capability: write one outcome.
+- A feature is added and reverted before release: omit it.
+- A bug is found and fixed before users receive the new feature: fold the final behavior into the feature item.
+- An internal refactor changes no public, packaging, security, or operator behavior: exclude it and record the reason in the coverage audit.
+- A dependency update changes the minimum runtime or bundled behavior: include the observable compatibility impact, not the dependency housekeeping.
+
+## Integrity gate
+
+Before finalizing, require:
+
+- complete range coverage with explicit exclusions;
+- traceable claims and no inferred readiness;
+- archived verification labeled as historical, with a fresh finalization gate when the release range has advanced;
+- matching versions, dates, tags, and links;
+- visible breaking and migration action;
+- no leaked private identifiers or secrets;
+- no external publication implied by a draft;
+- a diff limited to authorized release artifacts.

package/skills/rsp-review/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: rsp-review
+description: Review an RSP-tracked code, document, or mixed change against a fixed comparison scope and project authorities. Use for read-only findings before fixes, durable review, archive, or delivery; keep Code and Document states separate and never implement, commit, publish, or approve.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.22.3"
+---
+
+# RSP Review
+
+Review one fixed change scope without modifying it. Be concise, separate Code and Document judgment, and emit one deduplicated report.
+
+## Fix scope and authority
+
+Resolve before judging:
+
+- one immutable comparison point or explicit fixed file set;
+- reviewed files, including relevant untracked files named by the user;
+- the selected Change and, for grouped work, its Group Brief;
+- nearest project instructions and only relevant Specs and Decision Records;
+- any caller-supplied implementation summary.
+
+Do not switch branches or mutate the worktree to discover scope. If the comparison point is unavailable, report the review as blocked. If multiple focus markers or authorities select different intent, name the conflict, mark dependent pipelines blocked, and do not guess. Continue only pipelines whose inputs remain authoritative.
+
+The user request fixes the requested outcome and allowed operations subject to nearest project instructions. The selected Change defines the intended delta, Specs define stable current facts, and Decision Records define lasting rationale. Implementation and tests are evidence, not authority for missing requirements. Report missing authority instead of inventing a rule, acceptance criterion, or preference.
+
+## Classify the scope
+
+- **Code:** executable code, tests, configuration, scripts, schemas, executable prompts, Skills, commands, hooks, and workflows.
+- **Document:** requirements, plans, Changes, Specs, Decision Records, ADRs, explanatory documentation, and user-facing documentation.
+
+Determine applicability only from artifacts inside the fixed comparison scope. A Change, Spec, instruction, implementation file, or test read only as authority or evidence is not thereby a reviewed artifact. Run each applicable pipeline; return `skipped` for a pipeline with no reviewed artifacts even when authority of that kind was inspected, and never return `clean` for authority-only documents. When such authority is missing, ambiguous, or conflicting, record it in Review Scope, Coverage, and Verdict; do not emit a Finding owned by a skipped pipeline. An executable document may need both; merge evidence for the same underlying issue into one cross-artifact finding.
+
+Inspect in a bounded order: fixed status/diff, selected authority, then only the smallest direct behavior chain and tests needed to resolve a concrete question. Stop when every applicable pipeline can be judged. Do not search unrelated files or broaden authority merely to fill Coverage or Findings.
+
+## Review Code
+
+Check in this order:
+
+1. Safety and correctness: reachable bugs, data loss, security violations, invalid state transitions, broken contracts, unsafe failures, and regressions.
+2. Change and Spec fidelity: observable behavior against explicit intent and stable facts.
+3. Project standards: only rules established by nearest instructions or authoritative local conventions.
+4. Production reachability — hard gate before completing a seam-dependent Finding: when a Finding or suggested correction depends on an adapter, wrapper, validator, normalizer, or similar seam, name the direct production caller, compare its actual callee with that seam, and verify that the changed production consumer actually reaches that seam. Put the comparison in Evidence or Coverage. If the live path bypasses the seam, report the bypass and do not present an isolated seam fix as sufficient.
+5. Regression evidence — hard gate before `clean`: for every changed Code artifact, compare public return and failure behavior at the comparison point with the reviewed diff. Changing failure delivery between throw/rejection, sentinel values, `null`, status codes, or result objects is always a failure-contract change, even when implementation matches the selected Change. Without a focused test or other explicit verification evidence, emit a Finding and return `issues_found`. Absence of a new test is not actionable by itself: apply the simple deterministic-correction exception when the public behavior shape is preserved and no risky branch, state transition, concurrency, persistence, security behavior, or failure delivery changes, even though the corrected value differs. The exception never applies to a failure-contract change.
+6. Simplicity: unnecessary abstraction, duplication, indirection, dependency, or scope expansion with a concrete smaller alternative; never trade away required behavior.
+
+Anchor each Finding to changed lines or the smallest behavior chain. State a realistic trigger and impact. Do not report formatting, naming, generated output, taste, or hypothetical cleanup without authority or demonstrated downside.
+
+## Review Documents
+
+Classify each document by its semantic role: requirement/Change, implementation plan, Spec, Decision Record/ADR, or explanatory/user documentation. Then check:
+
+1. Authority and traceability of claims and decisions.
+2. Internal and cross-artifact coherence, including current implementation facts.
+3. Completeness and ambiguity: undefined terms, unverifiable completion, and choices disguised as decisions. Report an unresolved product, operational, rollback, migration, or completion choice as an ambiguity Finding when no authority resolves it; ask for owner judgment and mark a dependent result blocked only when the choice prevents coherent review.
+4. Feasibility of named paths, interfaces, sequencing, safety, migration, and executable verification, at the detail appropriate to the document role.
+5. Scope and concision: scope leakage, duplicate authority, unrelated requirements, or verbosity hiding a contract.
+
+Before the Document verdict, enumerate every unresolved choice in each changed document. Any unresolved product, operational, rollback, migration, ownership, or completion choice must either have resolving authority or produce an ambiguity Finding; do not stop after finding other defects.
+
+Anchor Findings to the smallest heading or claim. Do not apply code-style or test-coverage rules to semantic documents, auto-fix meaning, or rewrite prose for taste.
+
+## Report
+
+Render headings, field labels, explanations, and verdict prose in the language explicitly requested by the user; otherwise follow nearest project instructions, then the conversation language. Treat the shape below as semantic field order rather than fixed English wording: translate its human-facing labels when the output language differs. Preserve paths, commands, identifiers, WorkRefs, severity labels `P0`-`P3`, and the values `issues_found`, `clean`, `skipped`, and `blocked` unchanged.
+
+Use this shape:
+
+```md
+## <localized Review Scope heading>
+- <localized Comparison label>: <fixed ref, range, or file set>
+- <localized Intent label>: <authorities, missing, or ambiguous>
+- <localized Code label>: <issues_found | clean | skipped | blocked>
+- <localized Document label>: <issues_found | clean | skipped | blocked>
+- <localized Excluded label>: <paths and reasons, or none>
+
+## <localized Findings heading>
+### [P0-P3] <title>
+- <localized Artifact kind label>: <code | document | cross-artifact>
+- <localized Axis label>: <pipeline axis>
+- <localized Location label>: <path:line or precise section>
+- <localized Authority label>: <authority or observed invariant>
+- <localized Evidence label>: <conflicting behavior or text>
+- <localized Impact label>: <real consequence>
+- <localized Suggested action label>: <smallest correction; no edit>
+- <localized Confidence label>: <high | medium | low>
+
+## <localized Coverage heading>
+- <checked and unverified scope, including non-actionable missing coverage>
+
+## <localized Verdict heading>
+<blocked | findings | clean, with the smallest next action>
+```
+
+Omit Finding entries when none exist. `clean` means an applicable pipeline was reviewed with no actionable issue; `skipped` means no applicable artifacts; `blocked` means required scope or authority was unavailable. Deduplicate one underlying issue across pipelines, then order by severity and path. Use P0 for critical security/data/breakage, P1 for normal-path contract failure, P2 for a meaningful edge or maintenance risk, and P3 only for narrow actionable improvement.
+
+Return a report only. Do not edit files, apply fixes, change focus, create RSP artifacts, switch branches, stage, commit, push, open a PR, publish, delete, trigger external review, or approve. Later actions require separate explicit authority.

package/skills/rsp-shape/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: rsp-shape
+description: Shape or rigorously challenge unclear non-trivial work into one executable RSP Change or a justified shallow Change Group without implementing it.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.24.1"
+---
+
+# RSP Shape
+
+Do not implement the shaped work.
+
+Follow Core's response-versus-artifact language boundary.
+
+## Establish the boundary
+
+Read the request, authority, Core or fallback, Change and Brief, then only decisive evidence.
+
+A request to shape, create, or refine a Change grants artifact authority unless no-edit; advice does not. If creation focuses it, preserve the exact prior focus and restore it immediately unless selection was requested. Shaping grants no other authority to focus, implement, archive, edit durable truth, or mutate Git; preserve unrelated work.
+
+Return the request directly to implementation when it is tiny and concrete or the selected Change is already ready. Do not rewrite settled work for style or completeness.
+
+## Resolve material ambiguity
+
+Inspect the repository before asking. Ask only for an owner decision whose answer can change behavior, data, interfaces, compatibility, safety, ownership, migration, or acceptance. Ask the smallest useful question set and write only authorized answers into the Change.
+
+Read [deep clarification](references/deep-clarification.md) when the user explicitly asks for rigorous challenge, a high-risk dependent decision remains, or one bounded design question returns to Shape. Prefer the installed `rsp-design` capability; otherwise use its compact fallback against the same WorkRef.
+
+Never invent a product decision. When a material choice or mutation authority remains unresolved, leave the work open and report the single highest-impact blocker.
+
+## Choose the owner
+
+Read [complex shaping](references/complex-shaping.md) before choosing the owner when material clarification needs more than one round, several direct slices share one completion contract, or independently closable owners converge on terminal delivery.
+
+Prefer one ordinary Change. Use a shallow Group only when at least two direct children are independently implementable, verifiable, focusable, and archivable while sharing one goal or completion contract. A shared completion contract gates Group closure, not each child's archive unless that child declares the dependency. Keep membership in Brief `Slices`, exact prerequisites in child `Blockers`, and derived readiness in CLI output. Do not create another hierarchy or tracker.
+
+Follow the core RSP protocol for exact Change and Group structure. Keep one observable outcome per Change:
+
+- `Proposal`: outcome, scope, and non-goals;
+- `Spec`: observable requirements and acceptance scenarios;
+- `Design`: affected boundaries, constraints, and settled choices;
+- `Tasks`: executable implementation steps;
+- `Verify`: final decisive evidence proving the outcome;
+- `Blockers`: exact dependencies and unresolved external decisions, or `none`.
+
+Plan a new test only when it protects observable behavior or a real boundary, adds distinct future confidence, avoids duplicate or implementation-detail coverage, and costs proportionately. Otherwise prefer smallest sufficient evidence and keep probes temporary.
+
+A Change is a convergent current-plan/final-evidence snapshot, not an append-only execution log. Replace superseded evidence; keep process evidence in the response. Before archive, compress it to outcome, design, tasks, decisive verification, gaps, and risks.
+
+Use domain language. Mention AI or agents only as real product actors, consumers, interfaces, or constraints—not authors or execution narrators.
+
+## Apply the Shape Ready gate
+
+A Change is ready only when:
+
+- outcome, non-goals, and acceptance are concrete;
+- product and mutation authority are settled;
+- affected boundaries and material constraints are known;
+- no hidden assumption can change implementation or acceptance;
+- Tasks are executable without performing them;
+- Verify proves the result without process chronology; Blockers are truthful;
+- one Change or a justified shallow Group is the smallest sufficient owner.
+
+After authorized mutation, run the project focused RSP check when available. Return WorkRef, changed artifacts, validation, and the next implementation action or blocker.

package/skills/rsp-shape/references/complex-shaping.md

@@ -0,0 +1,30 @@
+# Complex shaping
+
+Read this reference only when material clarification needs more than one round, several direct slices share one completion contract, or independently closable owners converge on terminal delivery.
+
+## Close material decisions
+
+List unresolved owner decisions by implementation impact. Ask one to three related questions, write authorized answers into their owning Change sections, and reapply the Shape Ready gate. Repeat only while another material decision remains. If one cannot be settled, keep it in `Blockers` and return it as the next owner decision.
+
+Use an installed interview or grilling capability only when the work boundary is known, the remaining choice is high-risk, and the user selects deeper exploration. Consume its settled decisions afterward; it owns no RSP state.
+
+## Choose a complex owner
+
+Keep cohesive work in one Change when it has one consistency and verification boundary.
+
+Use a shallow Group when at least two direct children are independently implementable, verifiable, focusable, and archivable. The Brief explains the shared goal, constraints, slices, aggregate completion, and durable outcomes. Child Changes own implementation tasks, verification, and exact `requires` edges. Group completion gates closing the Brief; it does not prevent a child from archiving unless that child declares the dependency.
+
+Use an Overall Delivery Change when independently closable semantic owners converge on terminal versioning, packaging, migration, authorization, or publication. It remains an ordinary six-section Change:
+
+- Proposal, Spec, and Design name the terminal outcome, upstream owners, aggregate completion contract, and static ownership map;
+- Tasks and Verify contain only terminal delivery operations;
+- references point to upstream outcomes without copying their tasks, checks, progress, or live status;
+- exact prerequisites remain ordinary Change `Blockers`.
+
+A permission needed only for a later external task belongs in that task and its constraints. Promote it to an active `Blocker` only when it prevents the next executable work; do not block versioning, packaging, or other authorized preparation prematurely.
+
+Do not add a nested Group, delivery-map file, phase entity, or persisted wave plan. If one existing Change or Group already owns the complete outcome, return that owner unchanged.
+
+## Completion criterion
+
+Finish complex shaping when the smallest sufficient owner is selected, every direct slice or upstream owner has one clear boundary, dependencies live only in child or terminal Change `Blockers`, no live state is duplicated, and every executable Change passes the ordinary Shape Ready gate.

package/skills/rsp-shape/references/deep-clarification.md

@@ -0,0 +1,29 @@
+# Deep clarification
+
+Read this reference only when the user explicitly asks for rigorous challenge, or normal shaping leaves a high-risk decision whose dependent choices remain unresolved.
+
+## Establish the fact boundary
+
+Inspect the available code, tests, project instructions, Specs, and Decision Records before questioning the owner. Name the unresolved decision and the implementation consequence that makes it material.
+
+## RSP design return
+
+When `rsp-design` is available, it is the canonical domain or module design capability for an RSP-tracked question. Otherwise use an equivalent project-selected capability or Core's compact manual design fallback. Return one bounded design task containing:
+
+- the unresolved design question;
+- authoritative project inputs by path;
+- the expected existing artifact or decision output;
+- its permitted mutation boundary;
+- the same returning WorkRef.
+
+The selected capability owns only the design analysis, while existing project documents retain domain and architecture authority. Consume its settled result and evidence on return, then resume Shape against the same Change.
+
+## Traverse one decision at a time
+
+Ask exactly one owner decision per turn. Include a recommended answer grounded in inspected facts and the material tradeoff it resolves. After each answer, continue only along that decision's dependencies and derive available facts from the repository.
+
+When no material dependent decision remains, summarize the resulting behavior, boundaries, and acceptance contract, then ask the owner to confirm shared understanding. Keep all artifacts unchanged until that confirmation. After confirmation, write only authorized decisions into their existing RSP owners and reapply the Shape Ready gate.
+
+## Completion criterion
+
+Finish the deep branch when every material dependent decision is either owner-confirmed or recorded as one explicit blocker, the project design task has returned to the same WorkRef when used, and no artifact changed before shared understanding was confirmed.

package/skills/rsp-tdd/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: rsp-tdd
+description: Drive one clear testable behavior owned by a selected RSP Change through observed RED, minimal GREEN, safe REFACTOR, and fresh verification. Use when test-first evidence is the selected next action; return unexplained failures to diagnosis and all results to the same Change.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.24.1"
+---
+
+# RSP TDD
+
+Implement one clear behavior test-first, follow Core's response-versus-artifact language boundary, and return evidence to its selected Change.
+
+## Establish the cycle
+
+Require one selected, ready Change, clear observable behavior, test and production mutation authority, and an executable focused check. Read project authority, current worktree state, and the smallest owning production/test seam.
+
+Stop when behavior or acceptance is unclear, mutation authority is missing, an existing symptom has an unexplained cause, the execution environment is unavailable, or a baseline failure cannot be separated. Return the same Change, evidence, and one needed next action.
+
+## RED
+
+Add the smallest focused test at the real owning seam. Run it before production mutation and observe the expected missing or incorrect behavior.
+
+RED is not a syntax, fixture, environment, or unrelated baseline failure. A passing test disproves the premise; refine it or stop without production mutation. An unexplained failure returns to diagnosis, not a guessed regression test.
+
+## GREEN
+
+Make the minimum production change for GREEN, preserve scope, and rerun the same command. An unexplained failure returns to diagnosis without speculative widening.
+
+## REFACTOR
+
+Refactor only after GREEN for a concrete local improvement; rerun the focused check. Otherwise skip it.
+
+## Retain or remove the test
+
+Keep the test only when it protects observable behavior or a real boundary, adds distinct future confidence beyond existing checks, avoids implementation-detail coupling or duplicate coverage, and has proportionate maintenance cost. A user, Change, or project requirement to retain the test remains authoritative.
+
+Otherwise treat it as a disposable probe: remove it before completion, verify that no disposable fixture or helper remains, and run the cheapest decisive existing check against the final production state. A removed probe is process evidence, not final verification; when automation is insufficient, record applicable manual or environment evidence.
+
+## Verify and return
+
+After cleanup, run fresh required Change checks and narrow risk checks. Failure or unavailability cannot support completion. Update Tasks and Verify with final decisive evidence, omissions, and unresolved risk rather than a chronological test transcript; keep unresolved issues in Blockers.
+
+Return to the same selected Change with WorkRef, final state, artifacts, fresh checks, omissions, Tasks, Blockers, and one next action; do not create parallel lifecycle state or recursively invoke another Skill.
+
+When work remains, use Core's compact continuation fields in order: `WorkRef`, `Authority`, `Current state`, `Changed artifacts`, `Fresh verification`, `Blockers`, and `Next action`. Reopen authority, inspect drift, and refresh verification before resuming; continuation is not durable truth.
+
+Git staging, commit, push, publication, deployment, review, archive, and approval remain separate actions requiring their own authority.