@oevery/rsp 3.3.0 → 4.1.0

package/skills/rsp/references/groups-dependencies.md

@@ -1,12 +1,14 @@
 # Groups and dependencies
 
 Load this reference before creating, focusing, planning, or closing grouped or dependent work.
+Use the same selected CLI throughout; `rsp` below denotes that invocation, not a request to fetch or install a package.
 
-- Executable WorkRefs are `<change>` or one direct `<group>/<change>` child. Deeper paths are unsupported.
-- Use a Change Group only for at least two independently executable Changes sharing a goal or completion contract. Create it with `npx -y @oevery/rsp group create <group> [goal]`, replace placeholders, and declare each direct child under `Slices` before creating it.
-- `<group>/brief`, stored as `<group>/00-brief.md`, is not executable or focusable. Read it before a selected child. Its declaration order guides navigation and its blockers are inherited as external blockers, not graph edges.
+- Use the [shared work model](work-model.md) for Group and child identities when those definitions are missing from the current context.
+- Use a Change Group only for at least two independently acceptable/deliverable Changes with dependencies or an integration obligation. Create it with `rsp group create <group> [goal]`, replace placeholders, and declare each direct child under `Slices` before creating it.
+- The Brief is not focusable. Read it before a selected child. Its declaration order guides navigation and its blockers are inherited as external blockers, not graph edges.
+- Group-level integration obligations belong in the Brief's `Completion Conditions`. Use a named `Integration:` condition for the durable boundary and record fresh integration evidence before marking it complete. A boundary supplied only by the current request is transient and cannot complete Group closeout until it is written back.
 - Declare an exact prerequisite only as `- requires \`<change-work-ref>\`: <reason>` under the dependent Change's `Blockers`. Targets must be executable Changes.
-- Use `rsp status --json` as the derived dependency view. `plan.nodes`, `ready`, `edges`, `blocked`, and `waves` are authoritative for the current inspection. Each edge means “change requires prerequisite”; filtered plans retain transitive prerequisite context.
+- Use plain `rsp status` for the default semantic view and `rsp status --json` when exact dependency fields are needed. In the default JSON projection, `plan.nodes`, `plan.edges`, `plan.blocked`, and `plan.waves` are authoritative; the first non-empty wave is the current ready work. Each edge means “change requires prerequisite”; filtered plans retain transitive prerequisite context.
 - Do not infer nested ownership from the human dependency forest, create a parallel graph, or copy live delivery state into a Group Brief. Archived prerequisites resolve without rewriting dependents; incomplete inspection fails closed.
 - Archive children independently. Close the brief with `rsp group close <group>` only after every direct child and group completion gate passes.
 - Closed Group recovery never reuses its identity through `rsp group create` and never cascades into children or dependents. Core's direct reopen-recovery procedure owns the lifecycle sequence and exact retained-archive selection.

package/skills/rsp/references/response-language.md

@@ -8,4 +8,6 @@ Durable artifact prose is repository-owned. For a new authorized artifact: expli
 
 Commit-message prose: explicit current instruction → configured effective commit language → nearest repository authority → clear recent non-merge history.
 
+When precedence needs configured RSP language, use the same selected CLI's successful `rsp config --json` summary, optionally `--compact`; the CLI resolves defaults and inheritance. Reuse it until relevant configuration changes or recovery requires refresh. Raw YAML and status do not resolve effective language. On failed or unavailable projection, diagnose without inventing values or silently dropping configured precedence. Only the dependent choice waits; existing-file preservation, explicit overrides and independently authorized work needing no unresolved setting may continue. Other configuration systems retain their own readers.
+
 Preserve canonical headings, paths, commands, identifiers, WorkRefs, Conventional Commit types and scopes, trailers, severity labels, and machine values. Language and locale never rename or translate an existing WorkRef. Persistent prose belongs to the domain, system, user, or operator; mention AI or agents only when they are actual product actors or constraints.

package/skills/rsp/references/setup-repair.md

@@ -1,11 +1,46 @@
 # Setup and repair
 
-Load this reference only before initializing, auditing, migrating, or repairing RSP-managed state.
+Load before initializing, inspecting or updating RSP-managed assets, including upgrades.
 
-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`. Without it, create that Change only when explicit bootstrap tracking is still needed.
-3. Put project-wide boundaries in `.rsp/specs/design.md`, use `rsp specs` for direct current-file navigation and bounded literal discovery, put cohesive reusable facts in the smallest domain Spec, and keep stable operating instructions in the nearest project-owned `AGENTS.md` outside its managed block.
-4. Diagnose with `npx -y @oevery/rsp doctor`. Apply only deterministic repository repairs with `doctor --fix` or `rsp update`; `fixed` entries are real filesystem mutations, while an empty list means nothing changed.
-5. Do not use repair commands to decide stale focus, semantic durable updates, or archive readiness.
+Use the runtime selected in AGENTS: an exact package pin in .rsp/version for
+consumer projects, or this checkout's built CLI when .rsp/source explicitly
+selects source mode. The two markers are mutually exclusive. Do not substitute a
+published package for source mode because version strings match. An authorized
+package upgrade deliberately selects its exact target CLI and runs its update for
+the complete managed environment; source update keeps the local selection. Never
+substitute @latest, a version range or an unverified global binary; package fetching
+requires separate authority. Upgrade notices grant no migration authority.
 
-For manual audit, require `.rsp/`, managed roots, and nested Spec parents to be real directories. Require the project `AGENTS.md`, managed markers, fallback/config files, `specs/design.md`, placeholders, and any reserved generated-index compatibility path to be regular files. Confirm the managed block, direct Specs query, configured Decision Record exclusion, valid group briefs and direct children, supported path depth, and focus markers matching executable Changes. Symlinks, special files, incomplete inspection, unrecognized reserved indexes, and file/directory identity collisions fail closed. Fresh initialization and Spec creation never generate indexes. `rsp update` removes only a root `INDEX.md` or any `00-index.md` with exact generated Specs metadata, using complete preflight, quarantine, direct-query postcheck, and rollback; owner-controlled reserved content is preserved for explicit review.
+- **Initialize:** rsp init [--agents-mode managed|print] [--with-project-setup] creates missing scaffolding and the complete core suite. Existing user files remain unchanged. Retry an incomplete init with the same target; repeated init cannot adopt a different pinned version. Retired Rules require update instead.
+- **Update:** rsp update replaces the selected package's owned assets; optional --dry-run previews without writes. No separate installation or migration switches are needed.
+- **Inspect:** rsp doctor and rsp skills list are read-only. Only explicit doctor --check-updates queries stable metadata. Reports and notices grant no mutation authority.
+
+## Ownership and failure
+
+Core Skill installation directories and exact retired Skill/Rules names are
+package-owned: replace or delete them, including local changes. Preserve needed
+customizations beforehand. Unknown Skills, config, Specs, work, archives, Decision
+Records and Focus are user-owned; update does not rewrite or repair them. Missing
+config values use read-time defaults. AGENTS changes are confined to its managed
+block; write a consumer pin last, and never create one in source mode. Preserve
+canonical maintainer links to package sources.
+
+Only metadata-recognized generated indexes may be deleted from user knowledge
+directories. Stop for owner-controlled reserved paths, invalid config, unexpected
+symlinks or unsupported targets. Do not bypass validation or downgrade the pin.
+
+Failure stops without whole-update rollback or recovery copies. Completed steps
+remain applied. Inspect the reported failure, fix its cause and rerun the same exact
+target command; do not infer completion or switch to the old pin's CLI midway.
+Concurrent external edits and crash recovery are unsupported. No recovery entry exists.
+
+## Project knowledge
+
+Keep architecture contracts in .rsp/specs/design.md, domain contracts in their Specs, navigation in
+CONTEXT and scoped instructions outside the managed AGENTS block. For an existing
+or explicitly requested architecture model, use [architecture knowledge](architecture.md)
+for its relationship to contracts and its context entry. Use rsp specs to
+query knowledge. A legacy context map selects [context migration](context-migration.md);
+discovery alone grants no merge or deletion. Semantic writeback and archive decisions
+remain outside deterministic setup. Missing required Skills stop dependent work;
+never fall back to retired Rules or install implicitly.

package/skills/rsp/references/work-model.md

@@ -0,0 +1,37 @@
+# Shared work model
+
+Read when selecting, reporting or operating a tracked RSP owner, or writing/reviewing its records, and the relevant definitions are not already available in context. Direct untracked work needs no RSP identity. These shared definitions require no Core execution.
+
+## Work shapes
+
+Direct work is a clear bounded request without durable continuity needs. Change retains one acceptance/delivery boundary for sustained work or recovery. Group coordinates independently acceptable/deliverable child Changes with dependencies or integration obligations. Complexity, file count and worker count alone select neither Group nor delegation. Agent topology is a separate execution choice.
+
+Ordinary completion and checkpoint commits leave a Change open. Final delivery or an explicit close request uses the closeout policy; reopen is exceptional recovery, not the normal iteration path.
+
+## Identity and ownership
+
+A WorkOwner is the selected owner of the requested work: a Change, or a Group for its coordination boundary. A direct untracked request retains its explicit scope without inventing a Change, Group or WorkRef.
+
+A Change WorkRef is its logical name: `<change>` for an ungrouped Change, or `<group>/<change>` for a grouped child. Use that identity in commands, reports and ownership trailers. Its Markdown file is `.rsp/changes/<work-ref>.md`: a location for reading or evidence, never the WorkRef value. For example, `checkout/cache-ttl` identifies the child whose file is `.rsp/changes/checkout/cache-ttl.md`. Evidence may cite a file and line separately.
+
+A Group reference is `<group>/brief` and resolves to `.rsp/changes/<group>/00-brief.md`; it names the Group, not an executable child Change. Identities are shallow; deeper nesting is invalid. Read its Brief for shared scope and dependencies, then select the actual child before child work. Do not substitute a Group reference, Brief path or directory for a child WorkRef. A Group-level judgment retains its Group reference and identifies the included direct child Changes.
+
+An explicit user-selected owner wins over default focus discovery. Focus markers locate open-work candidates; multiple candidates alone are not a blocker. Resolve intent and relevant state rather than guessing ownership. Preserve existing work and its owner when changing scope.
+
+## Authority and evidence
+
+Identity, focus, readiness, dependency state and capability availability grant no action authority. A Group Brief supplies context, not permission to implement every child. A completed check proves only its tested boundary; neither it nor a review report grants lifecycle completion, Git delivery, publication or approval. Each capability retains its own action and stop conditions.
+
+In a Change's Blockers, record only unresolved dependencies or decisions preventing required work. Write standalone `None` when none remain; keep non-blocking verification limits in Verify. Exact prerequisites use ``- requires `<work-ref>`: <reason>``. Other prose, including an explanation after `None`, remains an external blocker declaration.
+
+Use only the selected owner's relevant artifacts and authoritative project context. Installed files are shared across the suite, but separate workers do not inherit one another's loaded instructions. Reuse applicable definitions in the same context; obtain this file before depending on missing definitions. If the shared resource is unavailable, report an incomplete suite and stop dependent actions rather than inventing a substitute or installing implicitly.
+
+## Current work records
+
+A Change retains six sections: Proposal, Spec, Design, Tasks, Verify and Blockers. During work it states the current authorized intent, approach and actual progress; at closeout it records the delivered outcome. Update affected content as facts change instead of appending rounds, dates or session summaries. Keep a date only when it matters to provenance or applicability. Record cleanup never authorizes dropping unmet scope or acceptance obligations.
+
+- **Tasks:** keep current checkable work and completion. Replace, split or merge tasks within authorized scope; reopen or rewrite invalidated results. Routine attempts, fixes, retries and individual check runs are not new tasks. Completion proves neither verification nor independent or human acceptance.
+- **Verify:** keep declared acceptance checks and their required/optional distinction, then retain only information needed to judge acceptance, evidence applicability or locate necessary evidence. Do not restate results already expressed by check items. Commands, counts, candidate/environment details and review steps belong here only when their omission would change those judgments or prevent that lookup; occurrence alone is no reason to retain them. Replace superseded conclusions only within their covered scope, preserve still-applicable reused evidence, and distinguish full review, correction-only re-review and human acceptance. Mark invalidated coverage incomplete. Keep shared evidence once and detailed execution/review records with their existing owner; no run history or debugging narrative.
+- **Focus:** keep only additional context needed to resume safely or avoid costly repeated discovery; refer to Change state without maintaining a second task, verification or blocker list. The conditional [Focus method](focus-continuation.md) owns replacement and cleanup. Ordinary progress needs no snapshot.
+
+Keep decision rationale, useful before/after outcome comparisons and material failure dispositions with their existing owner. For resolved ordinary failures, remove the attempt narrative; preserve any effect on acceptance or evidence validity. Routine history stays in conversation and raw evidence with its existing owner. Removing stale prose does not delete reports, conversation or Git history, require a new log, or move discarded history into Focus or an appendix.

package/skills/rsp-commit/SKILL.md

@@ -1,63 +1,108 @@
 ---
 name: rsp-commit
-description: Create one authorized, exact-scope local commit for a Core- or Manage-derived direct, Change, Group, or release boundary with a repository-consistent structured message.
+description: Inspect or create one authorized exact-scope local commit for direct, Change, integration, Group or release delivery. Preserve unrelated work; do not infer lifecycle, remote delivery or history-rewrite authority.
 license: MIT
 metadata:
   author: oevery
-  version: "2026.08.17.1"
+  version: "2026.10.16.1"
 ---
 
 # RSP Commit
 
-Create one reviewable local commit after Core or qualified Manage has already derived one transient Commit envelope. Skill availability grants none of its facts. The envelope contains exactly one owner variant, exact allowed paths, fresh decisive verification, current commit authority, and lifecycle evidence only when the owner variant requires it.
+For tracked work, read the [shared work model](../rsp/references/work-model.md) when its identity and ownership definitions are missing from the current context. Use logical WorkRefs in commands and reports; cite file locations separately. Direct invocation needs no prior Core execution.
 
-Accept exactly one owner variant:
+Own exact local Git delivery, invoked directly or through Core. This default core capability grants no authority through availability. Readiness-only work stays read-only. Commit only with current local authority, one exact owned boundary and applicable passing verification.
 
-| Owner | Required identity and evidence | RSP metadata |
+Responses follow explicit instruction, personal instructions, then conversation language; existing artifacts retain theirs. Commit prose follows explicit commit-language instruction, effective configuration, nearest repository authority, then clear recent non-merge style. Response language does not select it. Preserve commands, identifiers, Conventional types/scopes and trailers.
+
+Resolve needed RSP defaults/inheritance through the selected CLI's successful `rsp config --json`, refreshing on drift or recovery. Raw YAML is diagnostic only. Projection failure leaves dependent language unresolved before staging; history cannot replace it, while independent authorized inspection may continue. Resolve material conflicts with the owner.
+
+## Establish the delivery boundary
+
+Resolve the smallest request: kind, purpose, owner or summary, real included WorkRefs when relevant, exact paths, current local authority, applicable verification pointers and lifecycle evidence only when applicable. Derive these facts from direct user intent or Core's bounded handoff; do not require a transport schema or create a second source of truth.
+
+| Kind | Identity and applicable evidence | RSP trailers |
 | --- | --- | --- |
-| `direct` | a concise owner summary for one confirmed direct Tiny/Small boundary | none |
-| `change` | one real WorkRef and its applicable checkpoint or lifecycle evidence | `RSP-WorkRef` |
-| `group` | one integration-coupled wave or Group closeout, its Group ref, included WorkRefs, and applicable lifecycle evidence | `RSP-Group` and included `RSP-WorkRef` values |
-| `release` | one confirmed release identity and release-boundary evidence | only real included WorkRefs, when supplied |
+| direct | One confirmed direct outcome permitted by project tracking rules | none |
+| change | One real WorkRef | RSP-WorkRef |
+| integration | At least two real WorkRefs and one evidenced shared delivery boundary | included RSP-WorkRef values |
+| group | Group reference, included WorkRefs and one wave or closeout boundary | RSP-Group and included RSP-WorkRef values |
+| release | Confirmed release identity and release-boundary evidence | only real included WorkRefs |
 
-A direct owner is a transient Git delivery boundary, not a durable RSP WorkOwner. Never require it to create a Change, invent a WorkRef, or supply lifecycle evidence.
+A durable owner is a Change WorkRef or Group reference; included children never replace it. Direct, integration and release may have no durable WorkOwner. Integration creates no Group, direct creates no Change, and commit count is independent from Change count.
 
-Follow Core's response-versus-artifact language boundary for all user-visible control narration; when the response language differs, keep exact canonical values only as secondary parenthesized or code-formatted tokens.
+Purpose is separate from kind:
 
-## Audit the envelope
+- A checkpoint keeps the Change open and delivers a verified current slice without claiming completed acceptance, closing an issue or requiring archive.
+- A terminal delivery claims completion only for its selected boundary. Tracked terminal inputs require complete Tasks, decisive Required Verify and no active blocker; legacy unclassified Verify is Required. Optional omissions remain explicit but do not block. Direct work uses its own acceptance, not an invented lifecycle gate.
 
-Read nearest project authority and the selected owner evidence: the supplied direct outcome summary, relevant open Change, Group Brief and children, archive, or confirmed release boundary. Then inspect `git status`, staged, unstaged, and untracked paths, the cached diff, and recent non-merge commit messages. Recheck supplied verification and any applicable lifecycle facts against current repository state. For a terminal Change or Group child, inspect its open or archived Verify section and stop before staging when a Task or Required Verify item remains incomplete or a blocker remains active. Legacy unclassified Verify items are Required. Optional coverage warnings do not block a terminal commit, but include a material omission in the commit body when it affects review. A checkpoint commit remains explicitly non-terminal and does not claim completed acceptance.
+A generic commit request is a checkpoint unless final delivery is already established. For tracked final delivery, resolve the closure decision through [Core closeout](../rsp/references/closeout.md) before staging, including direct invocation; do not repeat an already settled decision. Commit pauses for its owning capability to perform necessary writing or authorized lifecycle work. Lifecycle authority stays upstream. If terminal delivery includes authorized archive or Group closeout, require that action and its inspected diff before staging. Do not archive, update Specs or clean up a Change inside Commit. A valid explicitly authorized local commit without lifecycle authority does not gain it or require an invented archive.
 
-Stop without staging when the owner variant, its required identity, allowed paths, commit authority, verification, applicable lifecycle evidence, or logical boundary is missing, ambiguous, stale, or conflicts with unrelated work. A missing WorkRef or lifecycle state is not a defect for a valid direct owner. Refuse an active merge, cherry-pick, revert, rebase, mail-apply, or sequencer operation before commit execution. Stop when an allowed path contains mixed owned and unrelated changes that cannot be staged without guessing. Never infer archive, Group closeout, commit, cross-branch integration, push, tag, publication, approval, amend, rebase, force-push, or history-rewrite authority.
+## Audit before staging
 
-## Derive the message
+Read nearest authority and the selected current owner, plus the relevant Brief/children or archive when needed. Inspect status, the complete staged, unstaged and untracked boundary, cached diff and recent non-merge messages. Reread decisive verification and applicable lifecycle facts; copied handoff prose is insufficient.
 
-Choose subject and body prose language from explicit current commit-language instruction, then the configured effective commit language, nearest repository commit authority, and finally the clear style of recent non-merge commits. Response language and preferences remembered from another repository do not select it. Preserve Conventional Commit types/scopes and trailers as technical values. When recent history is materially mixed and no nearer rule resolves it, return the single language decision to its owner.
+Reuse traceable passing results while relevant content, dependencies, configuration, tools, inputs and environment still apply. Run only authorized missing or invalidated checks with settled scope and method, or explicitly required executions; entering Commit alone requires no rerun. Failed or unavailable required evidence stops delivery.
 
-Use the repository's established Conventional Commit form when present. Derive type and scope from the owned outcome and repository history, not from the conversation. Keep the subject concise and imperative or otherwise repository-consistent.
+Stop without changing the index on missing or ambiguous authority, stale evidence, an invalid kind/purpose, unrelated staged work, mixed ownership that cannot be separated without guessing, or active merge, cherry-pick, revert, rebase, mail-apply or sequencer state. Preserve pre-existing owned partial staging unless the exact additional content is authorized. Never broaden paths, unstage unrelated work or reset the index to make a boundary fit.
 
-Describe the accepted diff as a reader who did not see the working session. Omit rejected session-only alternatives, corrections, and temporary attempts that never entered the authoritative baseline. Such an alternative is not an omission: do not name or paraphrase it as a `without X`, `did not add X`, or `did not use X` compliance claim. Name a removal, exclusion, failed external action, compatibility boundary, migration, safety rule, audit fact, or requested comparison when it is a real owned change or material review fact.
+Before reporting eligibility, confirm verification covers the exact proposed content. Matching filenames or a working-tree pass containing excluded changes is insufficient. For a staged slice, compare evidence with the current index. Check excluded code, configuration, fixtures and generated inputs for invalidation. Obtain missing evidence within authority or report the gap; preserve unrelated work.
 
-A tiny, mechanical, or direct `Tiny` or `Small` boundary may be subject-only when that subject fully explains it. For a non-trivial Change, integration wave, Group closeout, or release commit, add two to four concise bullets covering:
+Before dependent `git add` or `git commit`, run required audits and preparation as separately observed commands by default. If batching, explicitly gate each dependent write on all its prerequisites succeeding; shell newlines and the batch's final exit code do not provide that gate. A failed or unavailable prerequisite blocks its dependent write. Inspect actual index/worktree effects before permitted recovery; later success does not erase an earlier write after failure. Commit's one-attempt rule still applies.
 
-- the observable outcome;
-- material behavior or compatibility boundaries; and
-- an important omission or risk when one affects review.
+For readiness-only work, report eligibility, gaps and the next owner here; do not stage, prepare files or commit.
 
-Do not copy file lists, command transcripts, routine verification output, execution chronology, or the full Change or archive. Project trailers from the selected owner variant: add one `RSP-WorkRef:` per real included WorkRef and `RSP-Group:` only when the Group is the owner. A direct or release owner with no included WorkRefs emits no RSP trailer. Add authoritative external references already owned by the work and `BREAKING CHANGE:` only for an actual breaking change. Never invent a WorkRef, Group, issue, co-author, sign-off, breaking change, or AI attribution.
+## Review the final index and message
 
-Project every owned issue relationship as a non-closing `Issue: <canonical-url>` reference when proportionate. Only a terminal commit whose selected Change acceptance is complete may additionally use a provider-supported closing keyword for an explicit `relation: closes`. Checkpoints, `relation: relates`, ambiguous Change or Group ownership, and unresolved provider or repository identity emit no closing keyword. When safe shorthand cannot be resolved, keep only the canonical URL; never infer an issue from changed files or mutate the external tracker.
+1. Stage only the authorized content with exact path handling. Reread status, complete cached paths and diff, including sensitive material, and prove one reviewable logical boundary. Stop if it does not match; do not repair unrelated staging.
+2. Confirm the final index matches the content covered by the audited evidence. If staging changed that boundary, reassess applicability and fill only missing or invalidated coverage before proceeding; unchanged applicable results need no rerun. Record the reviewed HEAD (or unborn state) and index tree. These bind content, file modes and deletions, not only names; keep them transient.
+3. Derive the message from that final cached diff, not conversation chronology or a copied Change. Follow applicable project message rules and checks, using the established Conventional form when present and a concise repository-consistent subject. When the project permits and the subject is sufficient, omit the body; otherwise add only the rationale, behavior differences, compatibility or risk needed by a reader without the session.
+4. Load [message and references](references/message.md) for tracked, integration, Group, release, issue-related or non-trivial messages. Keep real removals, migration constraints and important omissions; omit session-only attempts, file inventories and routine command output. A supplied prepared message must still match the reviewed boundary; do not edit it when nearer authority forbids editing.
+5. Prepare actual multiline text, preferably outside the worktree or at an explicitly allowed path. Never use literal backslash-n as a newline transport or include a temporary message file in delivery. Legitimate escape notation in prose stays literal; do not decode it or reject it merely for containing backslash-n.
 
-## Commit the exact boundary
+## Execute once and observe
 
-Stage only the explicit allowed paths. Re-read `git status --short`, inspect the complete cached path list and cached diff, and confirm they represent exactly one owner boundary with no sensitive material. If the cached boundary is wrong, stop and leave unrelated work untouched; do not repair it by broad staging, destructive reset, or history rewrite.
+Use native Git inside this capability; no RSP commit wrapper or generated delivery
+script is required. Missing Commit capability has no Core substitute. Respect a
+nearer required method or denial; an incompatible requirement needs an owner
+decision, not a trial commit or automatic fallback.
 
-Transport a structured multiline message with actual line breaks or a safely prepared message file. Do not rely on ordinary quoted `\n` escape sequences as portable newlines; a host shell may pass those characters through literally.
+1. Inspect operation state through `git rev-parse --git-path` for MERGE_HEAD,
+   CHERRY_PICK_HEAD, REVERT_HEAD, rebase-merge, rebase-apply and sequencer. Any
+   active operation or incomplete inspection stops ordinary delivery. Resolve
+   paths through Git, not a presumed .git directory, so worktrees are covered.
+2. Read HEAD with `git --no-replace-objects rev-parse --verify 'HEAD^{commit}'`.
+   A failed read is not automatically unborn: require `git symbolic-ref -q HEAD`
+   to name refs/heads/... and `git show-ref --verify --quiet <that-ref>` to confirm
+   absence (exit 1). Other errors stop. Immediately before execution, recheck this
+   HEAD/unborn state and `git write-tree` against the reviewed snapshot. A caller's
+   fixed snapshot cannot be replaced on its behalf. Drift stops without index repair.
+3. Attempt exactly once: `git commit --cleanup=verbatim -F <message-file>`, replacing
+   the placeholder with the safely prepared, quoted path. Preserve normal hooks
+   and signing policy; do not disable either to obtain success. Snapshot checks
+   are sequential observations, not a cross-process lock.
+4. Read resulting HEAD, then inspect that immutable SHA using
+   `git --no-replace-objects cat-file commit <sha>` for the raw message, tree and
+   parents, and `git --no-replace-objects diff-tree --root --no-commit-id --name-only --no-renames -r -z <sha>`
+   for actual paths. Use NUL-delimited path observations before and after delivery;
+   do not split unusual filenames on whitespace or treat display quoting as identity.
+5. Require the committed tree and paths to match the reviewed index, one parent
+   equal to reviewed HEAD (no parents for unborn), and the complete stored message
+   to match the prepared text with at most one terminal LF difference. Recheck
+   final HEAD still identifies that SHA and inspect remaining staged, unstaged
+   and untracked work against the prior boundary. Obtain committed facts from the
+   immutable object, not several movable HEAD reads.
 
-When the packaged CLI is available, use `rsp commit --message-file <path> [--json]` for the exact local execution step. The command reads the prepared message file, rejects unintended literal `\n` sequences, and invokes `git commit --cleanup=verbatim -F -` through Node's direct child-process API. It operates only on the existing staged boundary; it never stages paths itself.
+Post-commit verification inspects these Git results and hook effects, not routine repetition of product tests. If hooks changed relevant inputs, report which evidence no longer applies; delivery remains stopped on mismatch or uncertain effects.
 
-Create one local commit with the prepared subject, optional body, and trailers. Do not cherry-pick, clean another checkout, push, tag, publish, amend, rebase, or force-push. Afterward observe exact before and after `HEAD`, the raw complete committed message, committed paths, remaining worktree paths, and remote refs when required. Confirm that committed paths equal the reviewed staged boundary. Compare the observed stored message with the prepared message exactly, allowing only one terminal LF difference in either direction for Git's message-file boundary. A successful commit is still a post-commit mismatch when either paths or message differ; report the complete observed receipt and stop without inferring amend or second-commit authority. If the command is unavailable, use a safely prepared message file with a direct non-shell Git invocation and retain the same preflight and post-commit checks.
+Exit zero alone is not exact delivery. After any failure, observe HEAD and actual
+index/worktree effects before classifying the result. Distinguish refusal before
+execution, Git failure with observed unchanged HEAD, created-commit mismatch and
+incomplete observation. Even unchanged HEAD cannot rule out hook side effects.
+An attempted commit or uncertain effects stops delivery without retry, amend,
+reset, rollback or a repair commit. Preserve the observed state and report gaps;
+never claim successful delivery when required observations fail or disagree.
 
-## Return the receipt
+## Return the result
 
-Return before and after `HEAD`, the commit SHA, owner kind and identity, included WorkRefs when present, the complete stored message with parsed subject/body/trailers, committed paths, remaining worktree paths, and explicit omissions. Report a stop before staging, commit failure, receipt-observation failure, or post-commit path or message mismatch truthfully; never silently amend or create a second commit to repair the first. An available Commit Skill that rejects an invalid envelope returns that stop; manual fallback is only for capability unavailability.
+Concisely report kind and purpose, owner or refs when relevant, commit SHA when observed, delivered paths and message subject; include remaining work and material omissions when present. Retain the complete message and content/history observations as evidence; expand them when requested or needed to explain a mismatch, not as routine output. For a stop, name the missing condition, observed Git effects and safe next action. No stage grants push, tag, publication, deployment, approval, cross-branch integration or history rewrite.

package/skills/rsp-commit/references/message.md

@@ -0,0 +1,34 @@
+# Message and owned references
+
+Load for tracked, integration, Group, release, issue-related or non-trivial messages after the final cached boundary is reviewed.
+
+## Project contract and subject
+
+Read applicable project instructions, message conventions and configured checks. Recent relevant commits supplement explicit rules, never override them. RSP does not require adopting Conventional Commits; where adopted, distinguish its syntax from stricter project requirements. Report conflicts with required checks instead of bypassing them. Preserve the entrypoint's commit-language precedence.
+
+Derive type from the accepted change and scope from a stable domain or module, not session activities or path inventories. Summarize one reviewable outcome. If the message exposes unrelated outcomes, return to the delivery-boundary check; do not silently split or broaden the authorized commit.
+
+## Body by information need
+
+When project rules permit, omit the body if the subject suffices and no material rationale, compatibility, migration or risk needs explanation. File count and change type alone do not determine that need. Otherwise explain only what a reader without the session needs: the problem and motivation, important old/new behavior differences, consequential tradeoffs or limitations.
+
+For Conventional messages, separate the body from the subject with a blank line. Use prose for causes/tradeoffs, lists for independent points or both as needed. Do not require a bullet list, Why/What/Testing template or prose-plus-list sequence. Omit padding and subject repetition.
+
+Keep real removals, migration constraints and important omissions. Do not copy the Change, execution chronology, routine checks or full path lists. Omit session-only attempts; retain a consequential reason for rejecting an alternative or accepting a tradeoff only when it explains the final design. A decisive measurement or verification limitation may matter, but command success must not imply broader acceptance.
+
+Follow project length and wrapping checks without inventing universal 50/72-character limits. Otherwise wrap for readability without breaking URLs, identifiers, commands or natural Chinese text. If an exact required reference conflicts with a hard check, report the conflict rather than truncating it or bypassing the check.
+
+## Owned footers
+
+Body freedom does not remove footer syntax. Keep footers separated by a blank line from the body, or from the subject when the body is absent. Emit ownership trailers as standalone fields, not body-list items; a necessary footer does not require a filler body. For Conventional breaking changes, use `!` or a `BREAKING CHANGE` footer as permitted, requiring both only when the project does. Explain the affected contract and migration needs proportionately; use the footer's exact token and syntax when present.
+
+Project trailers from real ownership:
+
+- Add one RSP-WorkRef per included Change.
+- Add RSP-Group only when a Group is the durable owner; integration alone emits none.
+- Direct and release without real included WorkRefs emit no RSP trailer.
+- Keep authoritative external references already owned by the work. Use BREAKING CHANGE only for a real breaking contract.
+
+Never invent a WorkRef, Group, issue, co-author, sign-off, breaking change or AI attribution.
+
+Represent owned issue relationships with a proportionate non-closing Issue reference. A terminal delivery with complete selected Change acceptance may additionally use the provider-supported closing keyword only for an explicit closes relation. Checkpoints, relates, ambiguous ownership or unresolved provider/repository identity emit no closing keyword. If shorthand cannot be resolved safely, retain only the canonical URL; do not infer issues from files or mutate the tracker.

package/skills/rsp-doc/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: rsp-doc
+description: Write or revise repository documents, Skills and release communication, including final Change convergence and knowledge writeback. Own writing and author self-checks, not product planning, formal read-only review or publication.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.11.04.2"
+---
+
+# RSP Doc
+
+For tracked work, read the [shared work model](../rsp/references/work-model.md) when its identity and ownership definitions are missing from the current context. Use logical WorkRefs in commands and reports; cite file locations separately. Direct invocation needs no prior Core execution.
+
+Write a grounded artifact usable without the author conversation. Use the artifact method for whole-record reconciliation, inspect final consistency and retain already-converged text. Local wording fixes and mechanical status/evidence updates need no full writing pass unless the whole record needs reconciliation. A no-op decision needs no new artifact or routine report field.
+
+## Produce the artifact
+
+1. **Fix the outcome.** Identify the reader, task, authorized files and expected result. For a document set, distinguish authoritative owners from summaries. Keep routine narration in conversation and retained evidence with its existing owner.
+2. **Establish the facts.** Read existing content, relevant callers and the smallest authoritative contract, code or source chain. Check commands, defaults, links and behavior with available tools. Distinguish current behavior, intended requirements and unknowns. Resolve material contradictions before rewriting a promise. Interpret tool output as evidence; it grants no permission and does not prove semantic correctness.
+3. **Draft for the task.** Use the artifact's role below. For Skill creation or revision, load [Skill authoring](references/skill-authoring.md); for changelogs, release notes, migration guidance or authorized release-document reconciliation, load [release communication](references/release-communication.md).
+4. **Verify the result.** Check the edited meaning in context. For structural edits, also follow the affected reading path and references. Use the checks below; reuse traceable unchanged mechanical results. Writing completion does not automatically trigger Review, but separately requested or required judgment remains binding.
+
+## Match the artifact to the reader
+
+- README and procedures supply the starting point, prerequisites, actions and recognizable success. Concepts and decisions explain meanings, reasons, alternatives and consequences; references supply exact, navigable contracts.
+- CONTEXT defines vocabulary and relationships and directs readers to authoritative owners. Specs state what consumers may rely on, including conditions, failures and exceptions; add scenarios only to resolve ambiguity. Scoped operating instructions own commands, authority and required checks.
+- For architecture models or changes to their bound documents, use [architecture knowledge](../rsp/references/architecture.md) for synchronization and reference checks.
+- Before writing a Change, load the [current work record rules](../rsp/references/work-model.md#current-work-records) when absent from context; the same resource owns Blockers syntax. Keep its six sections current during iteration and reconcile the whole record for closeout. Readers must find the outcome, applicable evidence and remaining work without reconstructing attempts; preserve useful before/after results and decision reasons when removing chronology.
+
+## Check facts and reading paths
+
+Use the checks relevant to the change:
+
+- Check affected links, anchors, examples and metadata with existing tools. Execute examples only within safe authorized scope.
+- Keep repository references portable: use project-root-relative file citations and document-relative Markdown links, following any existing machine-field path contract. Keep execution-root locations separate from durable file references; retain necessary external locations, original evidence and host-required display paths without copying local checkout prefixes into authored repository references.
+- For linked artifacts, compare shared claims, terminology, defaults and handoffs against their authoritative owner. Correct authorized summaries and links without copying full definitions or changing unassigned owners. Report out-of-scope contradictions to their owner.
+- API comments and embedded guidance: compare claims with their contract and implementation without assuming either side correct. Keep ordinary inline comments locally accurate and useful: retain constraints, rationale or usage that nearby code does not make clear, and remove restatement that adds no information; no full writing workflow is needed. Compiler/tool annotations retain implementation ownership.
+- Examples: label illustrative pseudocode or incomplete snippets; check copyable commands against real prerequisites, outcomes and safe use without inferring execution or installation authority.
+
+For agent-facing instructions, trace the relevant branch and its targets. Distinguish local reading-path reasoning from actual agent execution and required independent evidence; retain background human co-readers need.
+
+For a failed command, inspect cause and actual effects before recovery. Change a permitted read/search or repeat-safe check method only within unchanged goal, scope, authority, baseline and required evidence. Named checks and protected RSP operations retain their methods/owners; unavailable Required evidence, unknown mutation or unsafe replay stops affected work.
+
+## Resolve language
+
+- Response: explicit request → personal instructions → conversation language.
+- Existing files: preserve language unless the user asks to change it.
+- New files: explicit artifact language → effective configuration → scoped instructions → conversation language. Resolve needed RSP defaults/inheritance through the selected CLI's successful `rsp config --json`; refresh on relevant drift or recovery. Raw YAML is diagnostic only. Failed projection leaves dependent choices unresolved, not replaced by lower precedence; independent authorized work may continue. Other projects retain their configuration readers.
+- Keep canonical identifiers, machine values and required headings exact.
+
+## Write precisely
+
+- Explain unfamiliar concepts and mechanisms needed for the reader to reason, troubleshoot or assess guarantees. Do not force every artifact into an action list, tutorial or closing next step.
+- State the actor, action and object directly. Prefer short, complete sentences when easier to follow. Separate independent actions; preserve causal and conditional links. Give each paragraph one useful purpose. Put prerequisites before use, conditions beside actions and exceptions beside their rules. Keep necessary local context; link branch-only detail with its reading condition and purpose.
+- Number steps when their order matters; make each step a bounded action. Use peer bullets for independent items and connected prose for reasoning. Use tables for useful fixed mappings/comparisons, not branching Skill judgments.
+- Remove filler, repetition and irrelevant chronology. Keep author voice, decision-relevant reasoning and required audit evidence. Prefer concrete actions; use contrasts or examples when they resolve a real ambiguity. No fixed sentence length, list size or compression ratio defines quality.
+- Preserve negation, conditions, exceptions, permissions, quantities, units and certainty. Merge failure explanations with the same decision effect. Retain permission, outcome, stop and safe-recovery conditions, including rare boundaries preventing unauthorized action, serious harm or unsafe replay. Keep incident details with their evidence owner. Do not turn a proposal or unknown into a verified fact. Shorter wording proves no behavioral equivalence.
+- Wording edits preserve meaning, ownership, anchors and technical literals. Structural edits may merge, move or reorder content within scope, checking completeness and references. When the request authorizes simplifying instructions, remove an unnecessary obligation rather than merely restating it; verify the remaining behavior and safety. Wording-only authority does not permit that contract change.
+- Use ordinary words for conjunctions. Preserve technical syntax; reserve | for closed alternatives, / for established pairs, → for defined transitions and : for label/value boundaries.
+
+## Preserve ownership
+
+- Follow nearest project instructions and the authorized file boundary. Keep a selected WorkRef when tracked; bounded direct work needs no automatic Change.
+- Doc owns writing and self-checks; formal fixed-scope Review remains read-only and independent when required. A combined request retains both responsibilities: Review grants no repair authority, but originally authorized corrections may continue.
+- Product decisions stay with their design owner. Release writing grants no version decision, release verification, Git delivery or external publication authority. Missing optional methods do not require installation or block an available bounded method.
+- Preserve unrelated work. Ask when a missing choice materially changes the result or authority; stop when required evidence is unavailable. Writing alone grants no installation, deployment, Git delivery or publication.
+
+Return changed artifacts, decisive checks and material limits. Tracked work retains necessary conclusions in its existing record; stable knowledge belongs to its document and retained evidence to its existing owner. Focus maintenance remains Core's responsibility.

package/skills/rsp-doc/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: RSP Doc
+  short_description: 'Write clear, grounded documents and Skills'

package/skills/rsp-doc/references/release-communication.md

@@ -0,0 +1,39 @@
+# Release communication
+
+Load only for changelog, release-note or migration writing, including authorized reconciliation of release documents. Doc owns writing and self-checks, not release execution or independent acceptance.
+
+## Establish the release boundary
+
+Resolve the released unit, audience, evidence range, target surfaces and allowed edits. Follow nearest instructions, existing release artifacts, relevant release-tool configuration and prior published conventions. Preserve Doc's artifact-language precedence; prior releases may inform style but do not override it. Inspect only relevant non-secret settings; do not create configuration or persist preferences without authority.
+
+Confirm a version only from explicit user instruction or authoritative repository release configuration. Until confirmed, keep authorized drafts or fragments version-neutral; do not invent versioned headings, paths, exact-version commands or tag comparisons. A missing range or delivered behavior prevents factual release claims, not a bounded explanation of what evidence is needed.
+
+Use established project tools for inventories or generated drafts when useful. Inspect their effects before invoking them: generation may also commit, tag, push or publish. Tool availability and release-writing authority permit none of those actions.
+
+## Explain the net result
+
+Inspect the smallest sufficient net diff, direct public consumers, accepted fragments or work records and verification evidence. Git history and generated notes locate evidence; they are not proof of delivered behavior. Reconcile material disagreements and label historical results with their revision or date.
+
+Describe final user or operator outcomes. Omit reverted additions, fold prerelease corrections into final behavior and include housekeeping only for compatibility, packaging, security or operational effects. Omit rejected session-only proposals. Retain material removals, deprecations and known limits. Ground each claim and check meaningful omissions; add no permanent ledger or per-commit transcript.
+
+Project only the requested or existing surfaces:
+
+- **Changelog:** concise cumulative notable outcomes in the project's categories; use Added, Changed, Deprecated, Removed, Fixed and Security only as a fallback, omitting empty categories.
+- **Release notes:** lead with audience-relevant outcomes, required action, compatibility and validation limits. Use a stable public range link when available; do not invent links or duplicate the whole changelog.
+- **Migration guidance:** state affected users, old and new behavior, ordered actions, applicable compatibility window, success checks, and known rollback or support paths. Unknown operational decisions remain explicit. Keep a short note inline and use a separate guide only when needed and authorized.
+
+Breaking changes and required actions come first. Follow established formats; writing alone requires no Release Change, manifest edit, separate release commit or archive.
+
+## Check surfaces and handoff
+
+Compare claims, version, date, terminology, links and required actions across the selected surfaces and their authoritative sources. A draft may be unfinished when labelled as such; final shipped prose must remain true before and after publication. Keep pending publication, authentication, command progress and unverified live availability in the transient handoff, not shipped documents. Final comparisons use the target tag or immutable ref, not moving HEAD.
+
+When preparing final documents, name the observed candidate and fresh relevant evidence or gaps. Document consistency is not a release-ready verdict; package checks, implementation closeout and independent acceptance follow the project's declared gates and actual authority.
+
+For Core-routed work, release checks without a WorkOwner stay with Core and the project's declared checks; WorkOwner-declared verification uses Verify. These are caller responsibilities, not installed dependencies or permission for Doc to create a Change or execute a release workflow.
+
+For post-publication reconciliation, use observed tag, hosted release or registry facts only as needed. Modify only authorized mutable document surfaces; immutable shipped discrepancies need a corrective version or owner. Never move tags or rewrite published packages.
+
+Never retain passwords, tokens, device codes or authentication URLs in artifacts, command output or responses. Stop before a credential-emitting interactive step; authorized human authentication occurs in a trusted terminal and returns credential-free status.
+
+Return the range, confirmed identity or draft state, changed surfaces, checks, material omissions and decisions. State required user/operator actions and their consequences directly; links alone are insufficient. Preserve explicitly required safe command, API and version tokens exactly in the handoff. Report evidence limits and external-action status without claiming publication or approval.

package/skills/rsp-doc/references/skill-authoring.md

@@ -0,0 +1,36 @@
+# Skill authoring
+
+Use for creating or revising a Skill. Apply Doc's language, expression and authority rules; this branch adds package-specific decisions.
+
+## Establish the package
+
+- For creation, resolve the goal, inputs and observable result before choosing structure.
+- Honor an explicit destination; otherwise use project instructions and host constraints. Check for existing content before creating files.
+- For revision, inspect the authored package and its callers. State the revision's purpose and supporting evidence; preserve unrelated adaptations.
+- Start with SKILL.md. Use a host initializer when useful; add resources only for a real task need.
+- Preserve existing packages and global configuration. Creation is not installation or publication.
+
+## Make discovery precise
+
+- Describe the capability and triggering intents that distinguish it from neighboring Skills. Put detailed procedures in the body, not discovery metadata; avoid promises beyond the actual capability.
+- Remove exhaustive synonyms. Add an exclusion only for a likely adjacent misroute.
+- For creation or trigger changes, select useful probes by risk: direct requests, paraphrases or nearby non-triggers. Resource-only edits do not automatically need selection probes.
+- Preserve invocation policy. Optional distribution does not mean explicit-only invocation; change policy only with user intent and verified host support.
+
+## Make execution concise
+
+- Organize the ordinary task around its goal, necessary inputs, authorized action, completion evidence and real stops. Choose headings for the task, not a universal template. Continue ordinary authorized checks. Prescribe order only for correctness, safety or contract dependencies.
+- Revise the existing owner before adding a rule for the same decision. Merge repeated conditions and remove instructions no longer needed within the authorized contract delta. An incident warrants a new constraint only for a reusable gap, not noncompliance or tool/fixture failure alone.
+- Keep shared guidance and necessary local safety context visible. Link substantial branch-only knowledge with its reading condition and purpose; ordinary tasks need no unrelated recovery or delivery detail. A short Skill needs no router or extra files. Split or merge resources only when it improves the reading path, not when it merely moves mandatory text. Honor the declared distribution boundary. RSP ships as a suite: shared concepts may reference Core resources directly; independent Skills keep their own resource closure. Never depend on a maintainer repository Spec.
+- Retain generic teaching or old model-compensation instructions only for a current task-specific need. A newer model label alone proves neither redundancy nor safe removal of a constraint.
+- Reuse tools for deterministic work; the Skill owns method selection and interpretation within its authority. Preserve named mandatory commands, provenance, independence and protected operations when replacing a tool-only method. Add a script only when repetition or fragility warrants it, and run changed helpers safely. Check incoming links before moving resources.
+
+## Check the changed risk
+
+1. Validate supported metadata, names, local links and package contents using existing tools. Do not import another host's schema.
+2. Trace the ordinary task and changed branches through completion, including standalone use, unnecessary reads/handoffs, correct restraint, erroneous stops and the final answer. Check behavior and explanation together. Use realistic task outcomes and a relevant restraint case for changed behavior; judge artifacts and effects, not exact wording or reading commands. Formal Review selects applicable Code/Document perspectives within its own fixed scope.
+3. Report structural checks separately from model execution. Explicit invocation does not prove discovery; self-checks do not prove independent review.
+
+Use isolated inputs for write tests. Paid model calls, external effects and extra workers require actual authorization.
+
+For an optimization claim, compare success and corrections alongside available token, call and time costs under comparable inputs. Otherwise leave the effect unverified.