@oevery/rsp 3.1.0-beta.0 → 3.1.0-beta.2

package/skills/rsp-release-docs/SKILL.md

@@ -1,120 +1,75 @@
 ---
 name: rsp-release-docs
-description: Prepare and audit evidence-based changelogs, release notes, and migration notes. Use when drafting or updating release documentation, reviewing an Unreleased section, summarizing a version range, deciding references or omissions, or checking that release prose matches shipped behavior and repository conventions.
+description: Draft, audit, finalize, or reconcile evidence-based changelogs, release notes, and migration notes for an explicit release operation.
 license: MIT
 metadata:
   author: oevery
-  version: "2026.07.22.1"
+  version: "2026.07.26.1"
 ---
 
 # RSP Release Docs
 
-Build one release evidence ledger, then project it into the repository's release surfaces. Treat Git history as navigation, not product truth.
+Build one net-release evidence ledger and project it into repository-owned release surfaces. Git history locates evidence; it is not product truth.
 
 ## Establish authority
 
-Resolve requirements in this order:
+Resolve user scope, audience, language, format, references, and mutation authority first; then nearest project instructions, release-tool configuration, target-artifact conventions, and prior published releases. Higher-precedence evidence wins. Ask one focused question only when an unresolved owner choice materially changes the public result.
 
-1. Follow the user's explicit scope, audience, language, format, reference, and mutation requirements.
-2. Follow the applicable instruction hierarchy; nearer project instructions override broader host or personal defaults.
-3. Follow existing release-tool configuration.
-4. Preserve the target artifact's current structure, terminology, and language.
-5. Match prior published releases and tag, link, and tracker conventions.
-6. Apply the defaults in this Skill only where the repository is silent.
+Read [convention discovery](references/convention-discovery.md) when repository, personal, tool, or historical conventions must be located or reconciled. Do not invent configuration or persist preferences without authority.
 
-Use the higher-precedence source when two sources conflict. Ask one focused question only when the unresolved choice would materially change the public result. Read [convention discovery](references/convention-discovery.md) when locating or reconciling repository and personal conventions. Persist a preference only when the user explicitly authorizes its project or personal instruction owner.
+A release identity is confirmed only by explicit user instruction or authoritative repository release configuration. Never infer it from semantic-version ordering, prior prereleases, commits, planned prose, or package-manager convention. Until confirmed, keep work version-neutral and do not mutate manifests, target changelog headings, exact-version commands, versioned note paths, or tag comparisons.
 
-Completion criterion: name the release range, target version or draft state, audience, output surfaces, language, link style, and allowed mutations from observed authority.
+Before continuing, name the range, confirmed version or draft state, audience, surfaces, language, link style, and allowed mutations.
 
-## Select the branch
+## Select one branch
 
-- **Audit:** inspect existing release prose and return findings without editing.
-- **Prepare:** draft requested artifacts; for a formal release, always include release notes. Update a changelog only when the repository owns one or the user requests one. Include migration guidance whenever users must act.
-- **Finalize:** replace Unreleased markers, dates, comparison links, or draft labels only when the release identity is confirmed.
+- **Audit:** inspect fixed release prose and return findings without editing.
+- **Draft:** collect and project evidence. While identity can change, keep the ledger transient or use an existing release-fragment owner. Once identity is confirmed, update only authorized surfaces. Formal releases include release notes; update a changelog only when the repository owns one or the user asks; include migration guidance whenever users must act.
+- **Finalize for publication:** require confirmed identity and range, completed implementation Change closeout, and an exact clean candidate. An explicit tag, hosted release, registry publication, or equivalent public request must pass this branch even after prose review. Bind `ready` to the exact release commit.
+- **Reconcile published release:** observe the published identity and external surfaces, repair only authorized mutable surfaces, and assign immutable discrepancies to a corrective version or owner. Never rewrite a published package or move a tag to manufacture consistency.
 
-Publication is a separate branch. Preparing prose never grants commit, tag, push, release creation, registry publication, deployment, deletion, or approval authority.
+Exactly one branch is active. Give every requested surface one disposition: draft, finalize, reconcile, audit only, not applicable, or blocked by a named decision.
 
-Completion criterion: every requested surface has one disposition: draft, update, audit only, not applicable, or blocked by a named decision.
+## Keep release coordination proportional
 
-## Collect evidence
+A confirmed mechanical release does not require an RSP Change. Keep the ledger, command progress, authentication state, and publication handoff transient; manifests, changelog, release commit, tag, hosted release, and registry record own durable release history.
 
-Inspect the smallest sufficient set:
+Use an optional Release Change only when material version/range, migration, rollback, security, compatibility, cross-repository/team, multi-stage handoff, recovery, blocker, or acceptance decisions need a persistent owner. Do not create one for a checklist, verification transcript, or prose already owned by release surfaces.
 
-- previous release tag or user-supplied base and the target ref;
-- commits and net diff in the release range;
-- PRs, issues, tracked Changes, changesets, news fragments, and release PRs when available;
-- public API, CLI, configuration, packaging, migration, security, and operator-facing changes;
-- existing changelog, prior release notes, migration guides, version files, and release configuration;
-- fresh verification and known acceptance gaps when the release claims compatibility or readiness; label archived evidence with its observed revision or date instead of presenting it as current.
+## Build evidence before prose
 
-Use diffs and direct consumers to verify behavior. Use commit messages and labels to locate intent. Prefer accepted work artifacts and public documentation for business meaning. Reconcile disagreements explicitly instead of choosing the most convenient source.
+Inspect the smallest sufficient set: base and target refs; commits and net diff; relevant PRs, issues, Changes, fragments, and release PRs; public API, CLI, configuration, packaging, migration, security, and operator behavior; release surfaces and configuration; fresh verification and known acceptance gaps.
 
-Completion criterion: every commit and every relevant tracked item in the range is represented by evidence or has an explicit exclusion reason.
+Use direct consumers and diffs for behavior, work artifacts and public docs for meaning, and commit metadata for navigation. Reconcile disagreements explicitly. Historical verification must name its observed revision or date.
 
-## Build the release ledger
+Read [evidence and surfaces](references/evidence-and-surfaces.md) before drafting the ledger, classifying statement lifetime, or deciding exclusions. Read [output contracts](references/output-contracts.md) before introducing a format, preparing a major/breaking release, or producing multiple surfaces.
 
-Create a working ledger before writing prose. Keep it in the response or temporary work unless the repository already owns release fragments or the user authorizes a path.
+Every relevant commit and work item must map to a net outcome or explicit exclusion. Collapse implementation chronology, omit additions reverted within the range, fold prerelease fixes into final behavior, and exclude internal work unless it changes public behavior, packaging, compatibility, security, operations, or release integrity.
 
-For each net change record:
+## Project distinct surfaces
 
-- evidence identifiers and links;
-- user-visible or operator-visible outcome;
-- affected audience;
-- breaking, deprecation, security, compatibility, or migration impact;
-- changelog disposition;
-- release-note disposition;
-- reference choice;
-- exclusion or uncertainty, if any.
+- **Changelog:** concise cumulative notable outcomes using the existing categories, or Keep a Changelog categories as fallback. Put breaking changes and required action first.
+- **Release notes:** audience-specific narrative led by the most important outcomes, required action, evidenced compatibility and limitations, plus the full range link. Do not merely duplicate the changelog.
+- **Migration notes:** identify affected users, ordered actions, changed defaults or removed surfaces, compatibility window, validation, and known rollback/support. Use a separate guide when this would overwhelm the notes.
 
-Collapse multiple commits into one outcome. Omit changes added and reverted within the same range. Fold fixes to never-released behavior into the final feature description. Keep internal work out unless it changes public behavior, packaging, compatibility, security, operations, or release integrity.
+Every claim must map to the ledger. Keep terminology aligned while respecting each surface's audience and lifetime.
 
-Completion criterion: the ledger describes the net released state rather than commit chronology, and every exclusion is intentional.
+## Finalize the exact candidate
 
-## Project the artifacts
+Read [publication lifecycle](references/publication-lifecycle.md) before a publication handoff or post-publication reconciliation.
 
-Read [output contracts](references/output-contracts.md) before creating a new format, preparing a major or breaking release, or producing more than one surface.
+Finalization inspects public release surfaces and package inventory at the exact candidate—not every internal workflow artifact present in the tag. Require version, date, changelog, notes, migration guidance, comparisons, manifests, package inventory, release checks, and lifecycle closeout to agree. Shipped prose must remain true before, during, and after publication; transient publication or authentication state belongs only in the handoff.
 
-### Changelog
+When Git delivery is authorized, implementation Changes remain independently reviewable and versioned shipped surfaces are finalized in a separate release commit. Return the version, immutable candidate ref, required external actions, fresh checks, omissions, and `ready` or `not ready`. `ready` means internally eligible for a separately authorized operation; it is neither publication authority nor evidence of publication.
 
-Write a concise cumulative record of notable outcomes. Preserve existing categories; otherwise use Keep a Changelog categories and omit empty sections. Put breaking changes and required action first. Describe behavior, not implementation mechanics.
+## Protect authority and credentials
 
-### Release notes
+This Skill never executes or grants authority for commit, tag, push, hosted release creation, registry publication, deployment, deletion, approval, or rewriting immutable history. Publication is a separate external operation.
 
-Write a release-specific narrative for the observed audience. Lead with the most important outcomes, make required action prominent, include compatibility or known limitations when evidenced, and link to the full changelog or comparison range. Do not merely duplicate the changelog.
+Treat one-time passwords, browser-auth URLs, device codes, tokens, and token-bearing query strings as credentials. Never retain their values in release prose, Changes, ledgers, logs, summaries, or responses. If a command would expose them to retained output, stop and let the authorized human authenticate in a trusted terminal; resume only with credential-free status.
 
-### Migration notes
+## Return an evidence-complete result
 
-State who is affected, required actions in order, changed defaults or removed surfaces, compatibility window, validation steps, and rollback or support path when known. Use a separate guide when the instructions would overwhelm the release notes.
+Before returning, confirm consistent range and identity; ledger coverage or explicit exclusions; claims bounded by evidence; prominent breaking, migration, security, deprecation, and known-limit information; convention-compatible links, dates, headings, language, and terminology; publication-invariant shipped prose; transient state with its owner; credential-free retained output; and edits limited to authorized paths.
 
-Completion criterion: every statement maps to the ledger, each surface serves its distinct audience and lifetime, and terminology remains consistent across surfaces.
-
-## Apply reference policy
-
-Follow repository policy first. Otherwise:
-
-1. Add a version-level compare or tag link.
-2. Prefer PR links for implementation context.
-3. Prefer issue or tracked-work links for rationale and migration context.
-4. Use commit links when no better semantic anchor exists, exact provenance matters, or the user requires them.
-
-Do not force a reference onto every bullet. Use stable public links only; keep private tracker identifiers out of public prose unless the repository already exposes them.
-
-Completion criterion: references add useful context without turning the artifact into a Git log or exposing private information.
-
-## Audit before returning
-
-Check all of the following:
-
-- range and version identity are consistent across artifacts;
-- every ledger item is included or intentionally excluded;
-- no claim exceeds implementation or verification evidence;
-- verification counts, package identities, and compatibility claims name their observed revision or date when they were not refreshed in the current run;
-- breaking, migration, deprecation, security, and known-limit information is prominent where applicable;
-- user-visible net outcomes are not fragmented by commit;
-- links, dates, headings, language, and terminology match observed conventions;
-- changelog and release notes agree without becoming copies;
-- working-tree edits stay within authorized files.
-
-Return the release range, artifacts drafted or changed, coverage and exclusions, unresolved decisions, validation performed, and whether any external release action occurred.
-
-Completion criterion: the result is evidence-complete, convention-compatible, and truthful about omissions and publication state.
+Return the range, branch, changed or audited artifacts, coverage and exclusions, unresolved owner decisions, validation, handoff readiness when applicable, and whether any external action occurred.

package/skills/rsp-release-docs/references/evidence-and-surfaces.md

@@ -0,0 +1,21 @@
+# Evidence and surfaces
+
+Load this reference before drafting the release ledger, assigning statement lifetime, or deciding exclusions.
+
+## Evidence ledger
+
+Keep a transient table or equivalent notes with: evidence identifiers/links, net user or operator outcome, audience, breaking/deprecation/security/compatibility/migration impact, changelog and release-note dispositions, reference choice, and exclusion or uncertainty owner.
+
+The ledger is an analysis device, not a new project state store. Persist it only in an existing release-fragment system or explicitly authorized destination. It describes the released net state rather than commit chronology.
+
+## Surface lifetime
+
+- **Shipped surfaces:** package metadata and release communication captured by the tag or package, including README, changelog, repository notes, manifests, and migration guides. Internal workflow records keep their own artifact lifetime. Shipped statements must be publication-invariant: exclude “not yet published,” “available after publication,” pending authentication, unverified registry state, and comparisons ending at `HEAD`.
+- **Mutable public surfaces:** hosted release descriptions, safely mutable registry metadata, and other external records. Keep stable narrative aligned with shipped surfaces; add live verification only after observing it.
+- **Transient release state:** credentials, authentication, command progress, pending publication, and unverified availability. Keep it in an authorized tracker, temporary ledger, or response handoff—never shipped prose.
+
+When immutable published content is wrong, preserve it, explain the discrepancy on an authorized mutable surface, and name a corrective version or owner.
+
+## References
+
+Follow repository policy first. Otherwise add a version-level tag or comparison link, prefer PRs for implementation context, issues or tracked work for rationale and migration, and commits when no better semantic anchor exists or exact provenance is required. Links are optional per bullet and must be stable and public; do not expose private tracker identifiers.

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

@@ -4,16 +4,6 @@ Use these as fallbacks. Preserve an established repository format whenever it ex
 
 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
@@ -85,14 +75,6 @@ For each required action, answer:
 
 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.

package/skills/rsp-release-docs/references/publication-lifecycle.md

@@ -0,0 +1,24 @@
+# Publication lifecycle
+
+Load this reference before finalizing an exact publication candidate or reconciling an observed publication.
+
+## Finalization gate
+
+Require all of the following at the exact candidate:
+
+- target version agrees across manifests, changelog heading/date, release notes, migration guidance, and exact-version assertions;
+- the target changelog entry is not labeled `Unreleased`;
+- stable comparisons end at the target tag or immutable ref, not `HEAD`;
+- shipped surfaces contain no pending-publication, authentication, or unverified-live-state prose;
+- package inventory and release checks are fresh, with omissions named;
+- required implementation lifecycle closeout is in the candidate revision and its worktree relationship is explicit.
+
+Any missing evidence yields `not ready` with the failed gate and owner. A `ready` result identifies the version, immutable candidate ref, required external actions, checks, and omissions without executing them.
+
+## Reconciliation
+
+After publication, observe the tag target, hosted release, registry version/dist-tags, and exact-version consumer command where applicable. Compare them with the finalization handoff and shipped inventory. Update authorized mutable surfaces only from observed state. Mark unknown facts unverified and record immutable drift with a corrective version or owner; never move tags or rewrite packages.
+
+## Credential boundary
+
+Keep authentication values and URLs out of retained output. A human performs any credential-emitting interactive step in a trusted terminal; the handoff records only credential-free required/completed status.

package/skills/rsp-shape/SKILL.md

@@ -4,7 +4,7 @@ description: Shape or rigorously challenge unclear non-trivial work into one exe
 license: MIT
 metadata:
   author: oevery
-  version: "2026.07.24.1"
+  version: "2026.07.25.2"
 ---
 
 # RSP Shape
@@ -17,38 +17,40 @@ Follow Core's response-versus-artifact language 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.
+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; 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.
 
+During an explicit managed goal, its original planning-artifact authority remains valid for clear in-scope discovery. Keep a cohesive correction in the current Change; create one Change for an independently closable result, or one shallow Group for at least two such results sharing the goal. Return the ready WorkRef to Core for fresh qualification without another authorization round. Stop on changed behavior, acceptance, public interfaces, goal scope, mutation authority, or external action.
+
 ## 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.
+Inspect the repository before asking. Ask only for an owner decision changing behavior, data, interfaces, compatibility, safety, ownership, migration, or acceptance. Write only authorized answers.
 
-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.
+Read [deep clarification](references/deep-clarification.md) when the user explicitly asks for rigorous challenge, a high-risk decision remains, or one design question returns. Prefer the installed `rsp-design` capability; otherwise use its fallback.
 
 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.
+Read [complex shaping](references/complex-shaping.md) when clarification needs multiple rounds, 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.
+Prefer one ordinary Change only for one observable outcome sharing a consistency, focused-verification, review, archive, and rollback boundary. Use a shallow Group for independent outcomes under one goal; an integration gate never merges them. A shared completion contract gates Group closure, not child archive unless declared there. Keep Brief `Slices`, child `Blockers`, and derived readiness. Add no hierarchy.
 
-Follow the core RSP protocol for exact Change and Group structure. Keep one observable outcome per Change:
+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`.
+- `Proposal`: outcome, scope, non-goals;
+- `Spec`: requirements and acceptance;
+- `Design`: boundaries and choices;
+- `Tasks`: executable steps;
+- `Verify`: decisive evidence;
+- `Blockers`: dependencies and 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.
+Plan a 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.
+A Change is a convergent current-plan/final-evidence snapshot, not an append-only execution log. Replace superseded evidence; keep process in the response. Before archive, retain final 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.
+Use domain language. Mention agents only as real product actors or constraints, not authors or execution narrators.
 
 ## Apply the Shape Ready gate
 
@@ -62,4 +64,4 @@ A Change is ready only when:
 - 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.
+After mutation, run the focused RSP check. Return WorkRef, artifacts, validation, and next action or blocker.

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

@@ -10,9 +10,9 @@ Use an installed interview or grilling capability only when the work boundary is
 
 ## Choose a complex owner
 
-Keep cohesive work in one Change when it has one consistency and verification boundary.
+Keep cohesive work in one Change only when it delivers one observable outcome and its tasks must converge across the same consistency, focused-verification, review, archive, and rollback boundary. A shared file, module, deadline, or integration check does not establish that cohesion by itself.
 
-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 a shallow Group when at least two observable outcomes can be independently implemented, focused, verified, reviewed, archived, and rolled back. Preserve those outcomes as direct child Changes even when they share one broad integration, release, or acceptance gate. The Brief owns that aggregate gate plus the shared goal, constraints, slices, completion, and durable outcomes. Child Changes own their outcome, implementation tasks, focused verification, lifecycle, 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: