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

package/dist/entry-UWUX3HM7.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import {
+  inspectPackagedSkillInventory
+} from "./chunk-4K53353L.mjs";
+import {
+  openTerminalSession,
+  truncateDisplay
+} from "./chunk-JOMFFQRG.mjs";
+import "./chunk-OTJFL6XH.mjs";
+
+// src/skills-tui/entry.tsx
+import process from "process";
+import { render } from "ink";
+import ReactRuntime from "react";
+
+// src/skills-tui/app.tsx
+import { Box, Text, useApp, useInput, useStdout } from "ink";
+import { useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+function SkillsApp({ initialWidth, inventory, messages, onComplete }) {
+  const { exit } = useApp();
+  const { stdout } = useStdout();
+  const width = Math.max(40, initialWidth ?? stdout.columns ?? 80);
+  const optional = useMemo(() => inventory.skills.filter((skill) => skill.kind === "optional"), [inventory]);
+  const defaults = useMemo(() => inventory.skills.filter((skill) => skill.kind === "default"), [inventory]);
+  const [selected, setSelected] = useState(/* @__PURE__ */ new Set());
+  const [cursor, setCursor] = useState(0);
+  const [phase, setPhase] = useState("select");
+  const finish = (selection) => {
+    onComplete(selection);
+    exit();
+  };
+  const selectedNames = () => [...defaults.map((skill) => skill.name), ...optional.filter((skill) => selected.has(skill.name)).map((skill) => skill.name)].sort();
+  useInput((input, key) => {
+    if (phase === "replace") {
+      if (input.toLowerCase() === "y") {
+        finish({ kind: "confirmed", names: selectedNames(), force: true });
+      } else if (input.toLowerCase() === "n" || key.escape) {
+        finish({ kind: "cancelled" });
+      }
+      return;
+    }
+    if (key.escape || input === "q" || key.ctrl && input === "c") {
+      finish({ kind: "cancelled" });
+      return;
+    }
+    if ((key.upArrow || input === "k") && optional.length > 0) {
+      setCursor((value) => (value - 1 + optional.length) % optional.length);
+    } else if ((key.downArrow || input === "j") && optional.length > 0) {
+      setCursor((value) => (value + 1) % optional.length);
+    } else if (input === " " && optional[cursor]) {
+      const name = optional[cursor].name;
+      setSelected((current) => {
+        const next = new Set(current);
+        if (next.has(name))
+          next.delete(name);
+        else
+          next.add(name);
+        return next;
+      });
+    } else if (key.return) {
+      const names = selectedNames();
+      const divergent = inventory.skills.some((skill) => names.includes(skill.name) && skill.status === "divergent");
+      if (divergent)
+        setPhase("replace");
+      else
+        finish({ kind: "confirmed", names, force: false });
+    }
+  });
+  const status = (value) => messages[value];
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", width, children: [
+    /* @__PURE__ */ jsx(Text, { bold: true, children: messages.title }),
+    /* @__PURE__ */ jsx(Text, { children: truncateDisplay(`${inventory.package.name}@${inventory.package.version}`, width) }),
+    /* @__PURE__ */ jsx(Text, { children: truncateDisplay(`${messages.target}: ${inventory.target}`, width) }),
+    /* @__PURE__ */ jsx(Text, { children: " " }),
+    /* @__PURE__ */ jsx(Text, { bold: true, children: messages.defaultHeading }),
+    defaults.map((skill) => /* @__PURE__ */ jsx(Text, { children: truncateDisplay(`  [x] ${skill.name}  ${messages.locked} \xB7 ${status(skill.status)}`, width) }, skill.name)),
+    /* @__PURE__ */ jsx(Text, { children: " " }),
+    /* @__PURE__ */ jsx(Text, { bold: true, children: messages.optionalHeading }),
+    optional.length === 0 && /* @__PURE__ */ jsx(Text, { dimColor: true, children: `  ${messages.none}` }),
+    optional.map((skill, index) => /* @__PURE__ */ jsx(Text, { children: truncateDisplay(`${index === cursor ? "\u203A" : " "} ${selected.has(skill.name) ? "[x]" : "[ ]"} ${skill.name}  ${status(skill.status)}`, width) }, skill.name)),
+    /* @__PURE__ */ jsx(Text, { children: " " }),
+    /* @__PURE__ */ jsx(Text, { color: phase === "replace" ? "yellow" : void 0, children: phase === "replace" ? messages.replaceTitle : messages.selectHelp }),
+    phase === "replace" && /* @__PURE__ */ jsx(Text, { children: messages.replaceHelp })
+  ] });
+}
+
+// src/skills-tui/messages.ts
+var skillsCatalogs = {
+  "en": {
+    title: "RSP Skill manager",
+    target: "Target",
+    defaultHeading: "Default lifecycle Skills",
+    optionalHeading: "Optional project Skills",
+    missing: "missing",
+    unchanged: "unchanged",
+    divergent: "divergent",
+    locked: "locked",
+    none: "none",
+    selectHelp: "\u2191/\u2193 move \xB7 Space select \xB7 Enter confirm \xB7 Esc cancel",
+    replaceTitle: "Replace divergent selected Skills?",
+    replaceHelp: "y replace \xB7 n cancel"
+  },
+  "zh-CN": {
+    title: "RSP Skill \u7BA1\u7406\u5668",
+    target: "\u76EE\u6807",
+    defaultHeading: "\u9ED8\u8BA4\u751F\u547D\u5468\u671F Skills",
+    optionalHeading: "\u53EF\u9009\u9879\u76EE Skills",
+    missing: "\u672A\u5B89\u88C5",
+    unchanged: "\u4E00\u81F4",
+    divergent: "\u6709\u5DEE\u5F02",
+    locked: "\u9501\u5B9A",
+    none: "\u65E0",
+    selectHelp: "\u2191/\u2193 \u79FB\u52A8 \xB7 \u7A7A\u683C\u9009\u62E9 \xB7 \u56DE\u8F66\u786E\u8BA4 \xB7 Esc \u53D6\u6D88",
+    replaceTitle: "\u66FF\u6362\u6240\u9009\u7684\u5DEE\u5F02 Skill\uFF1F",
+    replaceHelp: "y \u66FF\u6362 \xB7 n \u53D6\u6D88"
+  }
+};
+
+// src/skills-tui/entry.tsx
+var signalExitCodes = { SIGHUP: 129, SIGINT: 130, SIGTERM: 143 };
+var defaultRuntime = {
+  inspect: inspectPackagedSkillInventory,
+  render,
+  openSession: openTerminalSession,
+  host: process,
+  reportError: (message) => console.error(message)
+};
+async function runSkillsTui(locale, runtime = defaultRuntime) {
+  const screenReader = runtime.host.env.INK_SCREEN_READER === "true" || runtime.host.env.INK_SCREEN_READER === "1";
+  const session = runtime.openSession(runtime.host.stdout, { screenReader });
+  let instance;
+  let selection = { kind: "cancelled" };
+  const listeners = /* @__PURE__ */ new Map();
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned)
+      return;
+    cleaned = true;
+    for (const [signal, listener] of listeners)
+      runtime.host.off(signal, listener);
+    listeners.clear();
+    instance?.unmount();
+    session.cleanup();
+  };
+  try {
+    const inventory = await runtime.inspect();
+    instance = runtime.render(ReactRuntime.createElement(SkillsApp, {
+      inventory,
+      messages: skillsCatalogs[locale],
+      onComplete: (value) => {
+        selection = value;
+      }
+    }), { exitOnCtrlC: false, patchConsole: false });
+    for (const signal of Object.keys(signalExitCodes)) {
+      const listener = () => {
+        cleanup();
+        runtime.host.exit(signalExitCodes[signal]);
+      };
+      listeners.set(signal, listener);
+      runtime.host.once(signal, listener);
+    }
+    await instance.waitUntilExit();
+    cleanup();
+    return selection;
+  } catch (error) {
+    cleanup();
+    runtime.reportError(`  Error: ${error instanceof Error ? error.message : String(error)}`);
+    return { kind: "error" };
+  }
+}
+export {
+  runSkillsTui
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oevery/rsp",
   "type": "module",
-  "version": "3.1.0-beta.0",
+  "version": "3.1.0-beta.2",
   "description": "RSP (Reliable Software Practice), a repository-native engineering workflow for humans and AI agents",
   "author": "oevery",
   "license": "MIT",
@@ -37,9 +37,11 @@
   },
   "scripts": {
     "prepare": "pnpm run build",
-    "release:check": "pnpm run build && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run release:package-check",
+    "release:check": "pnpm run release:metadata-check && pnpm run build && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run release:package-check",
+    "release:candidate-check": "node scripts/release-candidate-check.mjs && pnpm run release:check",
+    "release:metadata-check": "node scripts/release-metadata-check.mjs",
     "release:package-check": "node scripts/clean-install-check.mjs",
-    "prepublishOnly": "pnpm run release:check",
+    "prepublishOnly": "pnpm run release:candidate-check",
     "build": "tsup",
     "dev": "tsup --watch",
     "lint": "eslint .",
@@ -52,17 +54,17 @@
     "citty": "^0.2.2",
     "ink": "~7.1.1",
     "picocolors": "^1.1.1",
-    "react": "~19.2.3",
+    "react": "~19.2.8",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.0.0",
-    "@types/node": "^22.19.19",
-    "@types/react": "19.2.14",
-    "eslint": "^10.4.0",
+    "@antfu/eslint-config": "^9.2.0",
+    "@types/node": "^22.20.1",
+    "@types/react": "19.2.17",
+    "eslint": "^10.8.0",
     "ink-testing-library": "4.0.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.0",
-    "vitest": "^4.1.7"
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
   }
 }

package/rules/rsp-rules.md

@@ -18,28 +18,25 @@ This file is the minimal fallback protocol for agents that cannot load the `rsp`
 
 ## Core
 
-- Choose response language and artifact language independently. Localize human-facing response headings, labels, explanations, and conclusions according to the requested response language, response-specific project instructions, then conversation language. Write artifact prose according to the requested artifact language, artifact-specific project instructions, existing artifact language, then conversation language. Preserve canonical RSP artifact headings, WorkRef values, paths, commands, identifiers, and machine-consumed values. Response-only Continuation and Durable Decision labels are not artifact headings; a technical token may appear in parentheses but cannot replace the localized label.
+- Choose response language and artifact language independently. Localize response prose from the explicit request, scoped instructions, then conversation language; write authorized artifacts from the explicit request, scoped instructions, existing artifact language, then conversation language. Preserve canonical headings, WorkRefs, paths, commands, identifiers, and machine values.
 - Write persistent artifact prose in domain, system, user, or operator language. Mention AI or agents only when they are real product actors, consumers, interface participants, or constraints; agent authorship, execution narration, or convenience for a hypothetical future agent is not durable content.
 - `changes/` stores open work; `archives/` stores completed history; `specs/` stores stable current facts; the configured Decision Record path stores lasting rationale.
 - Every Change is one Markdown file with explicit `kind` and the fixed `Proposal`, `Spec`, `Design`, `Tasks`, `Verify`, and `Blockers` sections.
 - A Change is a convergent current-plan and final-evidence snapshot, not an append-only execution log. Keep Tasks aligned with current delivery and Verify limited to final decisive commands or scenarios, results, proven scope, omitted or unavailable coverage, and remaining risk. Replace superseded plans and evidence; retain an earlier failure only when it still explains a current blocker, coverage gap, or risk.
 - In a Change `Blockers` section, `- requires \`<change-work-ref>\`: <reason>` declares an exact dependency on another executable Change. Other meaningful blocker prose remains external and is never inferred as a dependency.
 - Executable Change identities are either `<change>` or `<group>/<change>`. Recursive work paths are unsupported.
-- A Change Group is the only composite work shape. Use it only when at least two independently executable direct child Changes share one goal or completion contract.
-- `<group>/brief`, physically stored as `<group>/00-brief.md`, owns Goal, Scope, Shared Constraints, Slices, Completion Conditions, Durable Outcomes, and Blockers. Every direct child must be declared by `Slices`, and every declared slice must be open or archived.
-- A Group Brief is not executable or focusable. Read it before a grouped child, archive children independently, and use `rsp group close <group>` only after derived completion passes. Archived Group identities cannot be reopened.
+- A Change Group is the only composite shape and requires at least two independent direct children. Its non-executable, non-focusable `<group>/brief` at `<group>/00-brief.md` owns shared scope, constraints, declared Slices, completion, durable outcomes, and blockers. Read it before a child; archive children independently and close only a derived-complete Group.
 - A file and directory cannot claim the same work identity.
-- `changes/` must exist as a real directory. Existing `focus.d/`, `archives/`, and direct group prefixes must also be real directories; symlinks, missing open-work roots, and incomplete inspection fail closed.
-- Initialization, repair, status inspection, Spec creation, and index generation use the same no-follow managed-path rules; recursive Specs may use only real directories and regular files.
-- Final managed files, including the project `AGENTS.md`, focus markers, fallback/config files, indexes, and placeholders, must be regular files rather than symlinks or special entries.
+- Managed roots, Group prefixes, recursive Spec paths, and final managed files must be real directories or regular files as applicable. Initialization, repair, inspection, Spec/index work, and mutations use shared no-follow checks; symlinks, special entries, missing roots, and incomplete inspection fail closed.
 - `status`, `check`, and `doctor` share work-tree, Change Group, and dependency inspection. They fail visibly on unsupported structure, membership mismatches, malformed or missing dependency targets, self-dependencies, and cycles. With no focus, status uses Group Brief declaration order and derived blockers to recommend the first executable slice.
-- `status` derives minimal graph nodes, dependency edges with their reasons, ready Changes, blockers, and stable execution waves from exact blocker references. Filtered plans retain transitive prerequisite context and distinguish selected nodes from prerequisite nodes; human output renders the same flat graph as a dependency forest whose parent requires its children. Archived prerequisites resolve automatically; incomplete dependency or archive inspection fails closed and marks open Changes blocked for readiness; no graph file or delivery state is persisted; and Group Briefs are not dependency targets.
+- `status` derives blockers, exact edges and reasons, ready Changes, and stable waves without persisted graph or delivery state. Filtered views retain prerequisite context. Archived prerequisites resolve; invalid or incompletely inspected graphs fail closed.
 - Parallel Changes in one Group follow the Brief `Slices` declaration order in plan output; unrelated work uses stable lexical ordering.
 - A Group Brief blocker is inherited by its direct child Changes as an external blocker; it does not create inferred dependency edges.
 - Persist only `open` and `archived`; readiness, blockers, verification, and next actions are derived.
-- Ordinary implementation is the default after unexplained failures have been ruled out. Use test-first work only when user, Change, or project authority requires it or a concrete changed risk makes a focused pre-mutation failure materially safer. Retain a new test only when it protects observable behavior or a real boundary, adds distinct future confidence, avoids duplicate or implementation-detail coverage, and has proportionate maintenance cost; otherwise remove the temporary probe and use the smallest decisive final verification.
-- Route one isolated domain, module/seam, or evidence-seeking design question to `rsp-design` when available, or use a compact manual design pass. Return evidence, alternatives, owner decisions, and any authorized planned-design update to the same selected Change; do not implement or write durable current truth from that pass.
-- Route release documentation only when the selected Change explicitly owns a confirmed release identity or range and still has unfinished changelog, release-note, or migration work. Select `rsp-release-docs` when available, or use the same evidence-led manual fallback; lifecycle stage, completed implementation, and archive readiness alone are insufficient. This route never grants commit, tag, push, release creation, publication, deployment, or approval authority.
+- Ordinary implementation is the default after unexplained failures are ruled out. Use test-first only when authority requires it or a concrete risk makes pre-mutation failure materially safer. Retain a new test only when it protects observable behavior or a real boundary with distinct proportionate value; otherwise remove the temporary probe and use decisive final verification.
+- This fallback does not emulate `rsp-manage`, even when project configuration selects automatic activation or local closeout. Invalid configuration grants nothing and remains visible. For an explicit managed request or an automatically eligible completion/continuation, resolve the smallest owner using ordinary Core rules: reuse one unambiguous selected ready Change, send tiny settled work direct without a synthetic Change, and shape only independently authorized planning artifacts for clear non-trivial work. Configuration grants no planning or product-mutation authority. Stop for material product, acceptance, interface, scope, mutation, or external-action decisions. Perform at most one ordinary Core or Discipline action, return its WorkRef and next action, and never dispatch, auto-continue successors, loop review corrections, archive, stage, commit, push, or persist controller state. Load the `rsp` and `rsp-manage` Skills when controller behavior is required.
+- Route one explicit isolated domain, module/seam, or evidence-seeking question to `rsp-design` when available, or use a compact manual design pass. Without a selected Change, use report-only Pre-Change Design without inventing a WorkRef only when the question is already bounded; when outcome, scope, non-goals, acceptance, or decomposition remains materially unclear, route to Shape. With a selected Change, return evidence, alternatives, owner decisions, and any authorized planned-design update to the same WorkRef. Do not implement or write durable current truth from either mode.
+- Route release documentation only for an explicit release operation with a confirmed identity or range and unfinished surfaces; no Release Change is required. Confirm identity only from explicit instruction or authoritative configuration. Until then stay version-neutral and do not mutate versioned surfaces. Keep ledgers transient; use an optional Release Change only for material decisions, coordination, recovery, blockers, or acceptance. This route grants no Git, publication, deployment, or approval authority.
 - Do not infer current work from open Changes or filenames.
 - Prefer RSP commands for deterministic setup, status, validation, repair, focus, index, and archive operations.
 
@@ -49,7 +46,8 @@ This file is the minimal fallback protocol for agents that cannot load the `rsp`
 - Project-owned `CONTEXT.md` owns stable navigation or scoped current context, while project-owned `AGENTS.md` owns stable operating instructions. Preserve their conventions and never treat RSP as their owner.
 - Before archive, decide independently whether current facts need a Spec or scoped-instruction update and whether lasting rationale needs a Decision Record.
 - Before archive, compress the Change to its final outcome, current design, completed delivery tasks, final decisive verification, and unresolved risks. Keep RED/GREEN/REFACTOR cycles, temporary probes, command transcripts, and step-by-step review corrections in the response instead of the Change or Archive.
-- After required durable updates, Core recommends explicit archive before final Git delivery. Core does not execute archive or grant authority to stage, commit, push, or publish.
+- After required durable updates, Core recommends explicit archive before final Git delivery. Ordinary work requires separate Git and release authority; fallback Core never executes archive, stage, commit, push, or publication.
+- When loaded Core or qualified Manage has already derived one authorized RSP-owned commit boundary, prefer the `rsp-commit` Skill for exact staging, repository-consistent structured message construction, one local commit, and complete post-commit observation. If that Skill alone is unavailable, loaded Core may provide its equivalent bounded manual action against the same owner; this minimal fallback still grants and executes no Git action.
 - Decision Records are for hard-to-reverse choices with real tradeoffs; they do not duplicate current facts.
 - Change Spec deltas are planning aids and are never promoted automatically into Specs or Decision Records.
 - Keep task history, debugging notes, and transient execution state out of Specs and Decision Records.

package/skills/rsp/SKILL.md

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

package/skills/rsp/references/conflict-handling.md

@@ -0,0 +1,11 @@
+# Conflict handling
+
+Load this reference only when an active merge, rebase, or cherry-pick conflict intersects authorized implementation.
+
+1. Inspect the exact Git operation, conflicted paths, index/worktree, and pre-existing user edits.
+2. Interpret base, ours, and theirs in that operation; resolve behavior from authority and evidence rather than choosing a side mechanically.
+3. Modify only evidenced content inside the WorkRef and mutation authority. Preserve unrelated work and do not stage without separate authority.
+4. Stop for unrelated user work, an unresolved product decision, incomplete side/base evidence, or out-of-scope content. Return the exact conflict and owner input.
+5. After an authorized working-tree resolution, rerun affected checks.
+
+Conflict-resolution authority does not authorize continuing or aborting the Git operation, staging, committing, or pushing.