@oevery/rsp 2.0.4 → 3.1.0-beta.0

package/dist/locale-HT44UIUP.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+// src/tui/i18n/locale.ts
+function normalizeLocale(value) {
+  if (!value)
+    return null;
+  const normalized = value.replaceAll("_", "-").split(".")[0].toLowerCase();
+  if (normalized === "en")
+    return "en";
+  if (normalized === "zh" || normalized === "zh-cn" || normalized.startsWith("zh-cn-") || normalized === "zh-hans" || normalized.startsWith("zh-hans-"))
+    return "zh-CN";
+  return null;
+}
+function resolveUiLocale(explicit, environmentLocale, hostLocale) {
+  if (explicit !== "auto")
+    return explicit;
+  return normalizeLocale(environmentLocale) ?? normalizeLocale(hostLocale) ?? "en";
+}
+export {
+  resolveUiLocale
+};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@oevery/rsp",
   "type": "module",
-  "version": "2.0.4",
-  "description": "RSP (Rules, Specs, Plans) workflow for lightweight AI-assisted change management",
+  "version": "3.1.0-beta.0",
+  "description": "RSP (Reliable Software Practice), a repository-native engineering workflow for humans and AI agents",
   "author": "oevery",
   "license": "MIT",
   "homepage": "https://github.com/oevery/rsp#readme",
@@ -13,6 +13,9 @@
   "bugs": "https://github.com/oevery/rsp/issues",
   "keywords": [
     "rsp",
+    "reliable-software-practice",
+    "repository-native",
+    "engineering-workflow",
     "rules",
     "specs",
     "plans",
@@ -30,28 +33,34 @@
     "skills/"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "scripts": {
     "prepare": "pnpm run build",
-    "release:check": "pnpm run build && pnpm run lint && pnpm run test && npm pack --dry-run --ignore-scripts",
+    "release:check": "pnpm run build && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run release:package-check",
+    "release:package-check": "node scripts/clean-install-check.mjs",
     "prepublishOnly": "pnpm run release:check",
     "build": "tsup",
     "dev": "tsup --watch",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "dependencies": {
     "citty": "^0.2.2",
+    "ink": "~7.1.1",
     "picocolors": "^1.1.1",
+    "react": "~19.2.3",
     "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",
+    "ink-testing-library": "4.0.0",
     "tsup": "^8.4.0",
     "typescript": "^5.8.0",
     "vitest": "^4.1.7"

package/rules/rsp-rules.md

@@ -1,99 +1,71 @@
 ---
 name: rsp-rules
-description: Core RSP rules for Rules, Specs, and Plans driven development.
+description: Minimal fallback protocol for Rules, Specs, and Plans driven development.
 ---
 
-# RSP
+# RSP fallback protocol
 
-This file is the canonical RSP rules source.
+This file is the minimal fallback protocol for agents that cannot load the `rsp` skill. It is not the project instruction or design store.
 
-## Scope
+## Entry
 
-- RSP directory paths such as `changes/`, `focus.d/`, `specs/`, and `rules/` are relative to `.rsp/`; project-root files such as `AGENTS.md` are named explicitly.
-- These rules are tool-agnostic and apply even when the agent does not support skills.
-- If the agent supports Agent Skills, load the `rsp` skill for initialization, audit or repair, and durable-decision tasks.
-- Keep this file compact because it is the always-read canonical truth source; put operational procedure in the RSP skill and explanatory detail in README or design docs.
-
-## Read order
-
-1. Read `AGENTS.md`.
-2. Read `.rsp/rules/rsp-rules.md` in full.
-3. Read `focus.d/`.
-4. If `focus.d/` is empty and the user has not provided a concrete task, ask what to work on or suggest `npx -y @oevery/rsp create <name>` for tracked work.
-5. Read each `changes/<name>.md` file marked in `focus.d/`.
-6. Read `specs/design.md` and `specs/INDEX.md`.
-   `specs/INDEX.md` lists only additional spec files beyond `specs/design.md`.
-7. Read only the relevant additional `rules/` and `specs/` files.
-
-## Core rules
-
-- Treat `rules/` as the canonical rules source.
+- Read nearest `AGENTS.md` and relevant `CONTEXT.md` before RSP work. Use root `CONTEXT-MAP.md` when present.
+- Prefer the `rsp` skill for setup, focused work, readiness, repair, and durable review.
+- If the `rsp` skill is unavailable, read this file before operating `.rsp/`.
 - Treat `focus.d/` as the only current-focus source.
-- Treat `changes/` as open work.
-- Treat `archives/` as completed history.
-- Treat each change as a single `.md` file under `changes/`. Do not create multi-file change bundles or supplementary files alongside a change.
-- RSP uses only two lifecycle states: `open` (in `changes/`) and `archived` (in `archives/`). Do not introduce intermediate states such as "in review" or "verified".
-- Keep every change file in the fixed six-section structure.
-- Prefer an RSP command when it clearly covers deterministic setup, status, validation, repair, index, focus, or archive operations.
-- Do not infer current work from `changes/` alone.
-- When no focus exists, status and show commands may suggest next actions, but they must not infer current work from open changes.
-- Do not treat `AGENTS.md` as the long-term rules or design store.
-- Do not redefine the core change structure through project config.
-
-## File ownership
-
-- Manage only the `<!-- rsp:begin --> ... <!-- rsp:end -->` block in `AGENTS.md`.
-- Do not modify content outside the managed AGENTS block unless the user explicitly asks for it.
-- Do not edit `specs/INDEX.md` or `archives/INDEX.md` manually; use `npx -y @oevery/rsp update`.
-- Treat `specs/design.md` as the durable design file. Prefer sections: `Purpose`, `Stable Facts`, `Boundaries`, `Constraints`.
-- Treat all `specs/<name>.md` as durable-truth documents. Use the same section structure as `specs/design.md`.
-- Treat `rules/project-rules.md` as the durable local-rules file.
-- Create `rules/project-rules.md` only when the project has stable local rules worth keeping.
-- Create or update `specs/` only for durable project-level facts that are stable, reusable, and worth rereading in later sessions.
-- Prefer updating `specs/design.md` or an existing durable file before creating a new spec file.
-- Create a new `specs/<name>.md` only when the knowledge forms a distinct durable project topic that does not fit `specs/design.md` or an existing durable file.
-- Write stable facts to the smallest correct durable file. Do not duplicate the same fact across multiple durable files without a clear long-term reason.
-
-## Command rules
-
-- Use RSP commands for deterministic setup, status, validation, repair, index, focus, and archive operations.
-- Use `rsp create` only for explicitly tracked open work; use `rsp create --lite` only when that tracked work is small and straightforward.
-- Use `rsp doctor --fix` only for safe deterministic repairs. Treat `fixed` output entries as actual filesystem changes, not attempted checks.
-- If RTK is available, you may prefix RSP commands with `rtk`.
-- Do not use `rsp create <name>` to re-focus an existing change.
-- Do not create RSP-managed files directly when an RSP command already exists for that file type.
-
-## Change rules
-
-Every change file must contain:
-
-- an explicit `kind` field in frontmatter
-- `## Proposal`
-- `## Spec`
-- `## Design`
-- `## Tasks`
-- `## Verify`
-- `## Blockers`
-
-Do not leave `kind` unresolved.
-
-Do not leave built-in template placeholders or unresolved clarification markers in a change once the details are known. `rsp check` reports these as warnings because they are deterministic hygiene signals, not semantic archive decisions.
-
-If a section does not apply, keep it and write `- none` or `- not needed: <reason>`.
-
-## Archive gate
-
-- `rsp archive <name>` never blocks. It warns but always completes the move.
-- `rsp ready` and `rsp show` expose deterministic readiness and advisory durable-review guidance; they never perform spec or rule writeback.
-- Make a durable-update decision before archive. Set `Archive ready: no` when real blockers remain or required durable updates are missing.
-- Change `Spec` delta markers (`### ADDED`, `### MODIFIED`, `### REMOVED`) are planning aids only and are never auto-merged.
-- Durable updates should contain stable facts only. Default to no spec writeback unless future work must reread the fact.
-
-## Prohibitions
-
-- Do not create placeholder or empty-shell files merely for completeness.
-- Do not create archive entries directly under `.rsp/archives/`; use `npx -y @oevery/rsp archive <name>`.
-- Do not create spec files that duplicate `specs/design.md` or another durable file.
-- Do not create a catch-all summary file like `specs/changes.md`.
-- Do not create supplementary files alongside a single change file.
-- Do not promote archive history, temporary troubleshooting notes, or task-by-task execution logs into `specs/` or `rules/`.
+- If `focus.d/` is empty and the user has not provided a concrete task, ask what to work on or suggest `npx -y @oevery/rsp create <name>`.
+- For grouped work, read the sibling Group Brief before the focused child Change. Then read only the relevant Specs and Decision Records under the configured authoritative path.
+
+## 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.
+- 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 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.
+- `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.
+- 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.
+- Do not infer current work from open Changes or filenames.
+- Prefer RSP commands for deterministic setup, status, validation, repair, focus, index, and archive operations.
+
+## Durable review
+
+- Route artifacts by semantic owner: planned future design stays in the selected Change; implemented stable current facts go to the smallest authoritative Spec or, with explicit authority, project-owned context/instructions; lasting rationale is judged independently for the configured Decision Record path; temporary continuation stays in the response unless a path is explicitly authorized.
+- 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.
+- 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.
+- Generated indexes and archives are not current-truth owners.
+
+## Continuation and conflicts
+
+- When execution stops with accepted work remaining, return one compact continuation with the semantic fields `WorkRef`, `Authority`, `Current state`, `Changed artifacts`, `Fresh verification`, `Blockers`, and `Next action`. Keep this field order, but localize the human-facing title and labels to the response language without changing referenced artifact prose or canonical technical values. Reopen its authority pointers, inspect drift, and refresh verification before resuming; it is not durable truth or a second state store.
+- Write a continuation file only when explicitly authorized. Never persist hidden handoff or controller state.
+- If an active merge, rebase, or cherry-pick conflict intersects authorized implementation, inspect the exact operation and conflicted paths, then compare base/ours/theirs semantics in that operation. Resolve only evidenced in-scope content while preserving unrelated work.
+- Stop on unrelated user work, an unresolved product decision, incomplete side/base evidence, or scope beyond the WorkRef. Name the exact conflict and required owner input; do not choose a side, stage a resolution, continue or abort the Git operation, commit, or infer any Git authority.
+- After an authorized working-tree resolution, rerun affected checks and return the continuation. Conflict-resolution authority alone does not grant Git continuation or delivery.
+
+## Safety
+
+- Do not create RSP-managed files directly when a command owns the operation.
+- Do not create archive entries directly; use `npx -y @oevery/rsp archive <name>`.
+- Do not modify content outside the managed RSP block in `AGENTS.md` unless explicitly requested.
+- Archive reports warnings but does not grant commit, push, publication, deletion, or external approval authority.

package/skills/rsp/SKILL.md

@@ -1,28 +1,24 @@
 ---
 name: rsp
 description: Use this skill when initializing RSP, operating an existing .rsp project, auditing or repairing .rsp state, or deciding whether a change needs durable updates before archive.
-compatibility:
-  agents:
-    - any agent that supports the Agent Skills format
-  requirements:
-    - Node.js 18+
-    - local filesystem read/write access
-    - shell access for `rsp` or `npx -y @oevery/rsp`
-  optional_requirements:
-    - network access for first-run `npx` installation or skill refresh
+license: MIT
 metadata:
   author: oevery
-  version: 2.0.3
+  version: "2026.07.24.1"
 ---
 
 # RSP Skill
 
 Load this skill when you need to initialize RSP, operate `.rsp/`, audit or repair RSP state, or make a durable-update decision before archive.
 
-This skill operationalizes `.rsp/rules/rsp-rules.md`; it does not replace that canonical rules source.
+This skill is the preferred operational guide. `.rsp/rsp-rules.md` is the only runtime fallback protocol when this skill is unavailable; old projects migrate to it with `rsp update`.
 
 Prefer exact file paths, exact commands, and exact durable facts over vague summaries.
 
+Choose response language and artifact language independently. Render human-facing response headings, field labels, explanations, and conclusions in the language explicitly requested for the response; otherwise follow response-specific project instructions, then the conversation language. Write artifact prose in the language explicitly requested for that artifact; otherwise follow artifact-specific project instructions, then the existing artifact's language, then the conversation language. Preserve canonical RSP artifact headings, keywords, identifiers, paths, commands, and machine-consumed values unchanged. Response-only Continuation and Durable Decision headings and labels are not canonical artifact headings and must be localized.
+
+Write persistent artifacts in domain, system, user, or operator language. Mention AI or agents only when they are actual product actors, consumers, interface participants, or constraints; using AI to perform the work is not itself a durable fact.
+
 ## When to use
 
 - Use for RSP setup, repair, focused RSP work, and pre-archive durable decisions.
@@ -33,7 +29,43 @@ Prefer exact file paths, exact commands, and exact durable facts over vague summ
 - 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 use this skill as a substitute for reading `.rsp/rules/rsp-rules.md` during focused RSP work.
+- Do not treat this skill or the fallback protocol as a replacement for nearest project `AGENTS.md` instructions or relevant module `CONTEXT.md`.
+
+## Derive one next action
+
+Before operating the workflow, derive the current stage from user intent, nearest project authority, `rsp status --json`, the selected Change's readiness, fresh verification evidence, and blockers. Stages are derived guidance, never persisted state.
+
+### Route implementation evidence
+
+When work has reached implementation, classify the decisive evidence before selecting a capability:
+
+- **Diagnosis:** an observed failure is reproducible or materially evidenced, but its cause or owning layer remains unexplained. Conflicting, intermittent, or multi-layer symptoms also take this branch. Select `rsp-diagnose` only when it is available; otherwise use the manual diagnosis fallback: reproduce, locate, test the smallest discriminating hypothesis, and return the evidenced cause without speculative production edits.
+- **TDD:** there is no unexplained failure, the required or corrected behavior is clear, and test-first work is explicitly required by the user, selected Change, or project instructions, or a concrete changed risk makes an observed pre-mutation RED materially safer. Concrete risks include public APIs or protocols, persisted data, security or money, concurrency or cancellation, complex state transitions, and defects that escaped to production. Select `rsp-tdd` only when it is available; otherwise use the manual TDD fallback: observe the focused RED, make the minimum GREEN change, optionally REFACTOR while green, then rerun required checks. Behavior being testable, a test being possible, or the work being a fix is not sufficient by itself.
+- **Ordinary implementation:** this is the default when diagnosis does not apply and no TDD gate above is met. Continue with ordinary `rsp-implement` when the required behavior, cause, or edit is sufficiently evidenced, or use the single manual implementation/verification action when that Skill is unavailable.
+
+Diagnosis takes precedence over TDD: do not encode an unexplained symptom as a guessed regression test. Fresh verification is required, but a new test is only one evidence option; prefer the cheapest decisive existing test, static check, build, or acceptance evidence that covers the changed risk. Each branch returns its evidence, Tasks, Verify updates, and unresolved Blockers to the same selected Change. Capability availability changes execution assistance, not the owner or required outcome.
+
+### Route release documentation
+
+Use the release-documentation branch only when the selected Change explicitly owns a confirmed release identity or range and still has unfinished changelog, release-note, or migration work. Lifecycle stage, completed implementation, or archive readiness alone is insufficient; ordinary Changes continue to the Core durable decision.
+
+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.
 
 ## Workflows
 
@@ -41,45 +73,100 @@ Prefer exact file paths, exact commands, and exact durable facts over vague summ
 
 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, then write durable architecture facts to `.rsp/specs/design.md` and stable local workflow rules to `.rsp/rules/project-rules.md` only when they are long-lived.
+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/` exists, `AGENTS.md` has the managed block, `specs/design.md` exists, generated indexes are intact, and `focus.d/` markers match `changes/` files.
+6. When auditing manually, verify `.rsp/`, managed roots, and nested Spec parents are real directories; the project `AGENTS.md`, managed markers, fallback/config files, indexes, and placeholders are regular files; `AGENTS.md` has the managed block; `specs/design.md` and the configured Decision Record directory exist; every group has one valid brief with matching direct children; work and archive trees are flat or one group level; and `focus.d/` markers match executable Changes.
 7. Treat `doctor --fix` `fixed` entries as actual filesystem changes. An empty `fixed` array or `No safe fixes needed.` means the repair pass changed nothing.
 8. Do not use repair commands for semantic decisions such as stale focus removal, durable updates, or archive readiness.
 
 ### Focused work
 
-1. Follow the read order in `.rsp/rules/rsp-rules.md`.
+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. Read the focused change before editing code.
-4. If a focused change is missing an explicit `kind`, repair the frontmatter before continuing.
-5. Run `npx -y @oevery/rsp check --focused` before treating focused work as ready; resolve placeholder or clarification warnings when they represent real unfinished content.
-6. Treat `rsp check` warnings as deterministic hygiene signals, not as the durable-update decision.
-7. Use `npx -y @oevery/rsp create <name> --lite` only when the user explicitly wants RSP tracking for a small, straightforward change.
-8. Convert actionable `## Tasks` checkboxes into your agent-local task tracker when one is available.
-9. Keep implementation sequential by default; parallelize only independent read-only discovery or mechanical checks.
-10. Update `## Tasks`, `## Verify`, and any invalidated `## Proposal`, `## Spec`, or `## Design` content in the same working session as implementation facts change.
-11. Keep temporary debugging notes, task history, and command transcripts out of `specs/` and `rules/`.
+3. Resolve executable Change names as either `<change>` or one direct `<group>/<change>` child. Require a real `changes/` root and real existing `focus.d/`, `archives/`, and group prefixes; reject symlinks, incomplete inspection, deeper paths, and file/directory identity collisions.
+4. Use a Change Group only for at least two independently executable Changes sharing one goal or completion contract. Create it with `npx -y @oevery/rsp group create <group> [goal]`, then replace the brief placeholders and declare every direct child identity and boundary under `Slices` before creating children.
+5. Treat logical `<group>/brief`, physically stored as `<group>/00-brief.md`, as non-executable and non-focusable. For grouped work, read it before the selected child Change. Its `Slices` declaration order guides navigation; a Brief blocker is inherited as an external blocker by every direct child without creating edges. Archive children independently, then close only the brief with `npx -y @oevery/rsp group close <group>` when all group gates pass.
+6. Declare an exact prerequisite only as `- requires \`<change-work-ref>\`: <reason>` under the dependent Change's `Blockers`. Targets must be executable Changes, not Group Briefs. Keep external blockers as ordinary prose and never infer an edge from them.
+7. Use `npx -y @oevery/rsp status --json` as the derived dependency view. Read `plan.nodes`, `plan.ready`, `plan.edges`, `plan.blocked`, and `plan.waves`; nodes distinguish selected Changes from prerequisite context, and each edge reads as “`change` requires `requires`” with `reason` and `state`. Filtered plans retain the transitive prerequisite closure needed to explain the selection. Human status renders the same flat graph as a dependency forest; do not infer nested JSON ownership from that presentation. Do not create or maintain a separate graph or copy live delivery state into a Group Brief. Archived prerequisites resolve without rewriting the dependent Change, while incomplete archive inspection produces no ready plan.
+8. Read the focused change before editing code.
+9. If a focused change is missing an explicit `kind`, repair the frontmatter before continuing.
+10. Run `npx -y @oevery/rsp check --focused` before treating focused work as ready; resolve dependency errors, placeholders, or clarification warnings when they represent real unfinished content.
+11. Treat `rsp check` warnings as deterministic hygiene signals, not as the durable-update decision.
+12. Use `npx -y @oevery/rsp create <name> --lite` only when the user explicitly wants RSP tracking for a small, straightforward change.
+13. Convert actionable `## Tasks` checkboxes into your agent-local task tracker when one is available.
+14. Keep implementation sequential by default; parallelize only independent read-only discovery or mechanical checks.
+15. Update `## Tasks`, `## Verify`, and any invalidated `## Proposal`, `## Spec`, or `## Design` content in the same working session as implementation facts change.
+16. Keep the selected Change as a convergent snapshot of the current plan and final decisive evidence. Replace stale or superseded content; keep routine attempts, RED/GREEN loops, command transcripts, and correction chronology in the response, then compress any material history to final outcomes, coverage, omissions, and unresolved risks before archive.
+17. Keep temporary debugging notes, task history, and command transcripts out of `specs/` and project-owned `AGENTS.md` instructions.
+
+### Route artifacts by owner
+
+Use one semantic routing matrix throughout shaping, execution, and pre-archive review:
+
+| Content | Owner | Boundary |
+| --- | --- | --- |
+| Planned future design | selected Change `## Design` | Never write planned state as current truth. |
+| Implemented stable current facts | smallest relevant Spec, usually `.rsp/specs/design.md` or an existing domain Spec | Write only observed stable facts under authority. |
+| Lasting rationale and tradeoffs | one exact file under `durableReview.decisionRecordsPath` | Judge independently from current facts; do not duplicate them. |
+| Stable scoped navigation or current context | project-owned `CONTEXT.md`, when that convention exists | Preserve project ownership and edit only with explicit authority. |
+| Stable operating instructions | nearest project-owned `AGENTS.md` outside the managed RSP block | Preserve project ownership and edit only with explicit authority. |
+| Temporary execution state | response continuation | Not durable truth; write a file only when explicitly authorized. |
+
+When accepted work remains, return this compact artifact-scoped continuation in the response:
+
+```md
+## <localized RSP Continuation heading>
+- <localized WorkRef label>: <selected Change>
+- <localized Authority label>: <project, Change, Spec, decision, or report pointers>
+- <localized Current state label>: <completed, partial, failed, unavailable, or blocked plus decisive state>
+- <localized Changed artifacts label>: <paths or none>
+- <localized Fresh verification label>: <command and result, or pending reason>
+- <localized Blockers label>: <exact blocker and owner, or none>
+- <localized Next action label>: <smallest bounded action and owner>
+```
+
+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.
 
 ### Pre-archive durable decision
 
 1. Run `npx -y @oevery/rsp check --focused` for focused work, or `npx -y @oevery/rsp check` when reviewing all open changes.
 2. Run `npx -y @oevery/rsp show --focused --json` or `npx -y @oevery/rsp ready <name> --json` to collect readiness, warnings, context paths, and `durableReview` guidance.
-3. Treat `durableReview.candidateTargets` as advisory context for likely writable durable files, not as permission to edit generated indexes or bundled core rules.
+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 plus relevant `specs/`, `rules/`, and code files needed for the semantic decision.
+5. Read only the current Change, relevant Specs and Decision Records, nearest project-owned `AGENTS.md`, and code files needed for the semantic decision.
 6. Produce the durable decision output before archiving.
 
 ## Durable decision
 
-Return exactly one decision:
+Choose one current-fact decision and one rationale decision independently.
 
-- `No durable update needed`
-- `Update existing spec or rule`
-- `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 rule file
+Current facts:
 
-Prefer `No durable update needed` when no concrete stable fact is worth rereading in future sessions.
+- `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
+
+Rationale:
+
+- `No Decision Record needed`
+- `Create or update a Decision Record`
+
+Prefer no update on either axis when there is no concrete stable fact or lasting rationale worth rereading.
 
 Write a durable update only when one of these is true:
 
@@ -88,52 +175,47 @@ Write a durable update only when one of these is true:
 - future agents or developers would likely make mistakes without the fact
 - the fact is worth rereading in later sessions as durable project knowledge
 
-Choose the smallest correct target:
+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.
+
+Apply the artifact-routing matrix and choose the smallest correct target:
 
 - project-wide design, boundaries, defaults, and durable context -> `.rsp/specs/design.md`
-- stable local workflow or validation rules -> `.rsp/rules/project-rules.md`
-- another durable rule set -> `.rsp/rules/<name>.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 or bundled `rules/rsp-rules.md` as ordinary durable writeback targets unless the task explicitly changes RSP itself.
+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, not narrative history, task-by-task notes, temporary debugging history, or archive-only detail. If you cannot identify concrete durable facts, do not invent them.
+Write stable facts or lasting rationale, not narrative history, task-by-task notes, temporary debugging history, or archive-only detail. Do not duplicate current facts into a Decision Record or rationale into a Spec. If you cannot identify concrete durable content, do not invent it.
 
 ## Output template
 
-Use this exact format:
+Use these semantic fields in this exact order. Localize the heading and human-facing labels to the response language; preserve the decision values shown in angle brackets as canonical values.
 
 ```md
-## Durable Decision
-- Decision: <No durable update needed | Update existing spec or rule | Create a new durable spec>
-- Target: <path or N/A>
-- Why:
-  - <reason>
-- Facts to write:
-  - <durable fact>
-- Archive ready: <yes | no>
+## <localized Durable Decision heading>
+- <localized Current facts label>: <No current-fact update needed | Update existing spec or scoped instruction | Create a new durable spec>
+- <localized Current-fact target label>: <exact file path or N/A>
+- <localized Facts to write label>:
+  - <durable fact or none>
+- <localized Decision Record label>: <No Decision Record needed | Create or update a Decision Record>
+- <localized Decision Record target label>: <exact file path or N/A>
+- <localized Rationale to write label>:
+  - <lasting rationale or none>
+- <localized Archive ready label>: <yes | no>
 ```
 
-Short example:
-
-```md
-## Durable Decision
-- Decision: Update existing spec or rule
-- Target: .rsp/specs/design.md
-- Why:
-  - The change introduced a stable default that future agents must follow.
-- Facts to write:
-  - Default API retries are capped at 3 attempts.
-- Archive ready: no
-```
+These are response labels, not canonical RSP artifact headings. A localized label may retain its technical field identity in parentheses; for example, a Chinese response may use `## 持久化决策`, `决策记录（Decision Record）`, and `可归档（Archive ready）`, but not their English labels alone.
 
 Rules for the output:
 
-- `Target` must be a concrete file path when the decision is not `No durable update needed`.
+- Each target must be an exact file path when its decision requires an update; `durableReview.decisionRecordsPath` is a directory, not the final target.
 - `Facts to write` must contain durable facts, not task history or debugging notes.
-- If real blockers remain or a required durable update is not yet written, `Archive ready` must be `no`.
-- If no durable update is missing and remaining verify risk is consciously accepted, `Archive ready` may be `yes`.
+- `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.