@oevery/rsp 2.0.4 → 3.1.0-beta.0

package/README.md

@@ -1,28 +1,58 @@
-# RSP: Rules, Specs, Plans
+# RSP — Reliable Software Practice
 
 English | [简体中文](./README.zh-CN.md)
 
-RSP = **Rules, Specs, Plans**. A lightweight AI-assisted workflow for durable project knowledge and single-file change tracking.
+**A repository-native engineering workflow for humans and AI agents.**
+
+RSP helps turn unclear intent into shaped, implemented, reviewed, and verified software changes while keeping project knowledge durable and work recoverable. Its ten composable Skills guide the engineering journey without introducing hidden workflow state or replacing the project's own files, tools, and authority.
+
+The workflow rests on a lightweight artifact foundation of **Rules, Specs, and Plans**.
+
+## What RSP helps you do
+
+- Shape ambiguous work into one executable Change or a small set of independent slices.
+- Resolve material design questions from repository evidence before implementation.
+- Route unexplained failures to diagnosis, ordinary evidenced edits to implementation, and only explicit or concrete-risk test-first work to TDD.
+- Review changes against explicit scope, address accepted findings, and rerun fresh verification.
+- Preserve stable facts, scoped instructions, lasting rationale, and completed history in their proper owners.
+- Prepare release documentation when a Change explicitly owns a confirmed release.
+
+## How the workflow fits together
+
+```text
+intent
+  → shape
+  → design when needed
+  → diagnose | TDD | implement
+  → review → address accepted findings
+  → release docs when owned
+  → durable review → archive
+```
+
+RSP derives the next action from the selected Change, repository evidence, verification, and blockers. Each capability returns its result to the existing project or RSP owner. RSP does not infer permission to modify code, continue Git operations, commit, publish, deploy, or approve work.
 
 ## Quick start
 
 ```bash
-npx -y @oevery/rsp init
-npx -y @oevery/rsp doctor
+npx -y @oevery/rsp@3.1.0-beta.0 init
+npx -y @oevery/rsp@3.1.0-beta.0 doctor
 ```
 
 Recommended bootstrap flow:
 
 ```bash
-npx -y @oevery/rsp init --with-project-setup
+npx -y @oevery/rsp@3.1.0-beta.0 init --with-project-setup
 # fill .rsp/changes/project-setup.md
 # fill .rsp/specs/design.md
-npx -y @oevery/rsp doctor
+npx -y @oevery/rsp@3.1.0-beta.0 doctor
 ```
 
-## Core idea
+## Artifact foundation
 
-- `rules/` stores durable constraints.
+`Reliable Software Practice` is the product promise; `Rules, Specs, Plans` describes the lightweight artifact model that makes the workflow repository-native:
+
+- nearest `AGENTS.md` stores scoped project or module instructions.
+- `rsp-rules.md` is the minimal tool-agnostic fallback protocol.
 - `specs/` stores project-level source-of-truth docs.
 - `changes/` stores open work in a single-file format.
 - `focus.d/` mirrors current focused changes with empty marker files.
@@ -30,14 +60,16 @@ npx -y @oevery/rsp doctor
 
 ```text
 .rsp/
-├── rules/
-│   ├── rsp-rules.md
-│   └── project-rules.md      # optional
+├── rsp-rules.md              # minimal fallback protocol
 ├── specs/
 │   ├── INDEX.md              # auto-generated
-│   └── design.md
+│   ├── design.md
+│   └── decisions/            # authoritative Decision Records by default
 ├── changes/
-│   └── <name>.md
+│   ├── <name>.md
+│   └── <group>/
+│       ├── 00-brief.md
+│       └── <change>.md
 ├── focus.d/
 │   └── <name>
 └── archives/
@@ -47,11 +79,22 @@ npx -y @oevery/rsp doctor
 ## Concepts
 
 - `specs/` describes durable project facts and current agreed design.
+- Decision Records describe lasting rationale, alternatives, tradeoffs, and consequences for hard-to-reverse choices. They default to `.rsp/specs/decisions/` or use one configured external path.
 - `changes/` captures open work, including features, fixes, refactors, docs, ops, and research.
 - A change is always a single Markdown file with explicit sections for proposal, spec, design, tasks, verification, and blockers.
-- Completed changes move to `archives/`, while durable outcomes should be reflected in `specs/` or `rules/` before archiving.
-- Durable outcomes mean stable facts only. Do not promote task history, debugging notes, or one-off implementation context into `specs/` or `rules/`.
-- Change `Spec` delta markers (`### ADDED`, `### MODIFIED`, `### REMOVED`) are planning aids only. `rsp archive` does not automatically merge them into durable specs or rules. Durable writeback remains an explicit semantic decision.
+- Keep each Change as a current-plan and final-evidence snapshot: choose the smallest decisive verification, retain new tests only when they add lasting value, and keep temporary probes and execution chronology out of persistent artifacts. Persistent prose names the real domain, system, user, or operator; it mentions AI or agents only when they are actual product participants or constraints.
+- An exact blocker line, `- requires \`<change-work-ref>\`: <reason>`, declares a dependency on another executable Change. Free-form blockers stay external; RSP never guesses edges from prose. Archived prerequisites resolve automatically.
+- Change names are either flat (`<change>`) or one direct grouped child (`<group>/<change>`). Recursive work directories are rejected.
+- A Change Group is optional and is the only composite work shape. Its non-executable, non-focusable logical identity `<group>/brief`, physically stored as `<group>/00-brief.md`, owns the shared goal, constraints, declared slices, completion conditions, durable outcomes, and blockers for at least two direct child Changes.
+- Create a group before its children. Every grouped Change must be declared by the brief, is focused and archived independently, and includes the brief in its context. With no focus, `status` uses Brief declaration order and current blockers to recommend the first executable slice. `status`, `check`, and `doctor` derive group health and completion without persisting another state; `rsp group close` archives only a completed brief. Archived Group identities cannot be reopened.
+- A Group Brief blocker is inherited by its direct children as an external blocker in the derived execution plan; it does not create guessed dependency edges.
+- A Markdown file and directory cannot claim the same work identity.
+- `rsp status`, `rsp check`, and `rsp doctor` inspect the same complete work tree and dependency facts. `status` derives exact edges with their reasons, ready work, blockers, and stable waves without a graph file; `check` and `doctor` reject incomplete archive inspection, malformed or missing targets, self-dependencies, and cycles. The `changes/` root must exist as a real directory, and existing focus/archive roots and group prefixes must also be real directories. Unsupported directories, non-Markdown entries, symlinks, missing or unreadable current work, incomplete reads, and identity collisions are visible errors. `status` exits non-zero instead of hiding invalid work.
+- `rsp init`, `rsp update`, `rsp add spec`, and generated index builders apply the same no-follow managed-path checks. Archive discovery accepts only flat archive files or one real group directory; recursively organized Specs accept only real directories and regular files.
+- Final managed files—such as the project `AGENTS.md`, focus markers, fallback/config files, generated indexes, and placeholders—must also be regular files; RSP rejects static symlink targets before reading or writing them.
+- Completed changes move to `archives/`. Stable current facts belong in Specs; lasting rationale belongs in Decision Records; stable scoped operating instructions belong in nearest project-owned `AGENTS.md`.
+- Do not promote task history, debugging notes, or one-off implementation context into Specs, Decision Records, or project instructions.
+- Change `Spec` delta markers (`### ADDED`, `### MODIFIED`, `### REMOVED`) are planning aids only. `rsp archive` does not automatically promote them into Specs or Decision Records. Durable writeback remains an explicit semantic decision.
 - `rsp check` performs deterministic hygiene checks. It warns about unfinished template placeholders and unresolved clarification markers, but those warnings do not replace the semantic durable-update decision.
 
 ## File ownership
@@ -60,10 +103,22 @@ npx -y @oevery/rsp doctor
 - `.rsp/specs/INDEX.md`: auto-generated index of additional spec files beyond `design.md`. Rebuild with `rsp update`.
 - `.rsp/archives/INDEX.md`: auto-generated. Rebuild with `rsp update`.
 - `.rsp/specs/design.md`: created by `rsp init`, then owned by the project.
-- `.rsp/rules/project-rules.md`: optional; create only when the project has durable local rules.
+- `.rsp/specs/decisions/`: the default authoritative Decision Record directory; configure `decisions.path` only when the Host Project already owns one external ADR directory.
+- `.rsp/rsp-rules.md`: generated minimal fallback protocol; use the `rsp` skill when available.
 - Keep durable architecture, boundaries, and cross-cutting technical constraints in `.rsp/specs/design.md`.
 - Treat `.rsp/specs/INDEX.md` as a directory for additional spec files; it does not list `design.md`.
-- Keep stable workflow rules, validation expectations, and local operating constraints in `.rsp/rules/project-rules.md`.
+- Keep stable scoped workflow and validation instructions in the nearest project-owned `AGENTS.md`, outside the managed RSP block.
+
+## Decision Record path
+
+The default authoritative directory is `.rsp/specs/decisions/`. If the Host Project already owns ADRs elsewhere, configure exactly one project-relative external path:
+
+```yaml
+decisions:
+  path: docs/adr
+```
+
+The path cannot be absolute, escape the Host Project, or point at another `.rsp/` core location. `rsp init` and `rsp update` validate routing before managed writes and ensure the directory exists; `rsp show` and `rsp ready` refuse unsafe routing; `rsp doctor` validates directory readability and migration health. These commands never create a Decision Record. Switching to an external path does not migrate existing default records: `rsp doctor` reports inactive `.rsp/specs/decisions/*.md` files until they are moved or deliberately removed.
 
 ## AGENTS integration
 
@@ -73,19 +128,17 @@ Managed block example:
 <!-- rsp:begin -->
 ## RSP Entry
 
-RSP keeps durable rules, specs, and current work under `.rsp/`.
-Treat AGENTS.md as navigation only; keep durable rules and design in `.rsp/`.
+RSP tracks current work, stable specs, and archives under `.rsp/`.
 
 Read in order:
-1. .rsp/rules/rsp-rules.md
-2. .rsp/focus.d/
-3. matching .rsp/changes/*.md for the focused entries
-4. .rsp/specs/design.md
-5. .rsp/specs/INDEX.md
-6. only the relevant additional .rsp/rules/*.md and .rsp/specs/*.md files
+1. Nearest `AGENTS.md` for project or module instructions.
+2. Root `CONTEXT-MAP.md` if present, then the relevant nearest `CONTEXT.md`.
+3. The `rsp` skill; if unavailable, read `.rsp/rsp-rules.md` as the fallback protocol.
+4. `.rsp/focus.d/`; for grouped work read the sibling Group Brief, then the explicitly selected focused Change.
+5. Only the relevant Specs and Decision Records under the configured authoritative path.
 
 If `.rsp/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.
-If your agent supports Agent Skills, load `rsp` for setup, repair, and durable-decision tasks.
+Do not treat `.rsp/specs/` or `.rsp/changes/` as replacements for nearest `AGENTS.md` or `CONTEXT.md`.
 <!-- rsp:end -->
 ```
 
@@ -94,43 +147,96 @@ If your agent supports Agent Skills, load `rsp` for setup, repair, and durable-d
 - `managed`: create `AGENTS.md` when needed and insert/update the managed block.
 - `print`: initialize normally and also print the resulting `AGENTS.md` content.
 
-## Skill
+## Skills
+
+RSP publishes ten host-neutral Skills for on-demand loading:
+
+- `rsp`: setup, workflow, durable review, and archive guidance.
+- `rsp-shape`: shape unclear non-trivial work into one ready Change or justified shallow Group without implementing it; progressively load deep clarification for an explicit rigorous challenge or unresolved high-risk decision, and return material design questions to the same WorkRef.
+- `rsp-design`: resolve one tracked domain-model, module/seam, or reversible-exploration question from project evidence, writing only authorized planned design back to the selected Change.
+- `rsp-implement`: implement one selected, ready Change within explicit mutation authority and return truthful Tasks, Blockers, and fresh verification evidence.
+- `rsp-diagnose`: establish a confirmed cause or truthful unresolved diagnosis before production correction.
+- `rsp-tdd`: drive one clear behavior through observed RED, minimal GREEN, optional safe REFACTOR, and fresh verification.
+- `rsp-review`: read-only review of code, document, or mixed Changes against fixed scope and project authority.
+- `rsp-address-review`: dispose fixed review findings, apply only authorized accepted corrections, require fresh verification and report-only re-review, and return a recoverable artifact-scoped continuation when work remains.
+- `rsp-release-docs`: prepare or audit evidence-based changelogs, release notes, and migration notes while adapting to user requirements and repository conventions.
+- `rsp-manage`: continue one explicitly requested focused Change across genuinely independent slices or interruption recovery, while keeping ordinary work direct and orchestration state transient.
+
+Each Skill is independently invocable and returns results to existing project or RSP artifact owners. The suite adds no hidden workflow state or recursive Skill orchestration, and no Skill infers commit, push, or publication authority.
 
-Use `skills/rsp/SKILL.md` for step-by-step setup, workflow, and auditing guidance. It is intended for on-demand loading rather than always-on core rules.
+Response language and artifact language are independent. Human-facing response headings, labels, explanations, and conclusions follow the requested response language, response-specific project instructions, then the conversation language. Authorized artifact prose follows the requested artifact language, artifact-specific project instructions, then the existing artifact language, and only then the conversation language. Canonical RSP artifact headings, WorkRef values, paths, commands, identifiers, and machine-consumed values remain unchanged; response labels may retain technical tokens in parentheses but never use them as untranslated labels.
+
+The 3.1 beta product surface contains these ten Skills. The optional `rsp-manage` capability activates only on explicit request and only for a focused ready Change with genuinely independent slices, long continuation, or interruption recovery. Small or coupled work returns directly to Core or the selected Discipline without a dispatch envelope. Managed runs keep authority in current project and RSP artifacts, keep process chronology transient, use bounded verification, and stop at mutation, lifecycle, Git, publication, environment, or human-decision boundaries.
+
+For a complete tracked change, compose the suite as evidence requires: `rsp-shape` returns an executable Change and sends one material design question to `rsp-design`; `rsp-design` returns its evidence, recommendation, alternatives, and any authorized planned-design update to the same WorkRef; Core routes unexplained failures to `rsp-diagnose`, explicit or concrete-risk test-first work to `rsp-tdd`, and ordinary evidenced edits to `rsp-implement`; `rsp-review` returns a read-only report; `rsp-address-review` disposes findings and returns accepted corrections through fresh verification and re-review; when a selected Change explicitly owns a confirmed release identity or range and unfinished release documentation, Core routes that work to `rsp-release-docs`, which turns one evidence ledger into distinct changelog, release-note, and migration surfaces without inferring publication authority; and `rsp` routes implemented current facts, lasting rationale, project-owned context or instructions, and temporary continuation to their existing semantic owners before archive. Use `rsp-manage` only when the user explicitly requests managed continuation and the work qualifies for bounded independent dispatch. Each discipline returns to its existing owner. Ambiguity, failed gates, missing authority, and out-of-scope Git conflicts stop at that owner; no Skill infers Git continuation, commit, delivery, or an automatic retry loop.
 
 Reading guidance:
 
 - `README.md`: human-oriented overview and examples
-- `.rsp/rules/rsp-rules.md`: canonical rules source
-- `skills/rsp/SKILL.md`: operational guide for applying those rules with an agent
+- `.rsp/rsp-rules.md`: minimal fallback protocol when the skill is unavailable
+- `skills/rsp/SKILL.md`: preferred operational guide for agents
+- `skills/rsp-shape/SKILL.md`: bounded shaping and slicing guidance
+- `skills/rsp-design/SKILL.md`: tracked domain, module/seam, and reversible-exploration design guidance
+- `skills/rsp-implement/SKILL.md`: bounded implementation and fresh verification guidance
+- `skills/rsp-diagnose/SKILL.md`: evidence-backed cause isolation before correction
+- `skills/rsp-tdd/SKILL.md`: bounded red-green-refactor guidance
+- `skills/rsp-review/SKILL.md`: read-only review guidance
+- `skills/rsp-address-review/SKILL.md`: review finding disposition, correction, re-review, and recovery guidance
+- `skills/rsp-release-docs/SKILL.md`: evidence-based changelog, release-note, and migration guidance
+- `skills/rsp-manage/SKILL.md`: explicit bounded continuation across independent slices
 
 Surface matrix:
 
 | Surface | Primary audience | Role |
 |---|---|---|
 | `README.md` | Humans | Overview, onboarding, examples |
-| `.rsp/rules/rsp-rules.md` | Agents | Canonical normative rules source |
-| `skills/rsp/SKILL.md` | Agents | Operational guide for applying the rules |
-| `AGENTS.md` | Humans and agents | Navigation entrypoint into the right files |
+| `.rsp/rsp-rules.md` | Agents without the skill | Minimal tool-agnostic fallback protocol |
+| `skills/rsp/SKILL.md` | Agents | Preferred operational guide |
+| `skills/rsp-shape/SKILL.md` | Agents | Shape one executable Change or justified shallow Group |
+| `skills/rsp-design/SKILL.md` | Agents | Resolve one tracked design question and return it to the same WorkRef |
+| `skills/rsp-implement/SKILL.md` | Agents | Implement one ready Change with fresh verification evidence |
+| `skills/rsp-diagnose/SKILL.md` | Agents | Confirm a cause before production correction |
+| `skills/rsp-tdd/SKILL.md` | Agents | Implement one clear behavior test-first |
+| `skills/rsp-review/SKILL.md` | Agents | Read-only Code and Document review |
+| `skills/rsp-address-review/SKILL.md` | Agents | Resolve review findings and return a recoverable continuation |
+| `skills/rsp-release-docs/SKILL.md` | Agents | Prepare or audit convention-compatible release documentation |
+| `skills/rsp-manage/SKILL.md` | Agents | Continue eligible independent slices only after explicit invocation |
+| `AGENTS.md` | Humans and agents | Scoped project instructions and RSP navigation |
 
-Humans should usually start with `README.md`; agents should treat `.rsp/rules/rsp-rules.md` as normative.
+Humans should usually start with `README.md`; agents should follow nearest `AGENTS.md`, load the `rsp` skill when available, and use `.rsp/rsp-rules.md` only as fallback.
 
-When this README shows `rsp <command>`, it assumes the command is already available in your environment. Otherwise use `npx -y @oevery/rsp <command>`.
+When this README shows `rsp <command>`, it assumes the command is already available in your environment. For this opt-in beta, otherwise use the exact `npx -y @oevery/rsp@3.1.0-beta.0 <command>` identity after publication; stable users can keep using the unversioned package entrypoint for npm `latest`.
 
-Example optional installation flow:
+Install the exact package-bundled suite into the current project:
 
 ```bash
-npx skills add oevery/rsp
+rsp skills install --dry-run
+rsp skills install
 ```
 
-This repository publishes a skill named `rsp` under `skills/rsp/`.
-
-`rsp update` refreshes project-local RSP files only. If you use the published RSP skill, refresh it separately after upgrading:
+The command preflights all ten package-owned targets, leaves unrelated `.agents/skills` entries untouched, and requires explicit `--force` before replacing a divergent package-owned directory. It installs from the package that invoked `rsp`, so prerelease dogfooding can use one exact npm identity after publication:
 
 ```bash
-npx skills add oevery/rsp
+npx -y @oevery/rsp@3.1.0-beta.0 skills install --dry-run
+npx -y @oevery/rsp@3.1.0-beta.0 skills install
 ```
 
+These registry commands remain unavailable until `3.1.0-beta.0` is published. `rsp update` refreshes RSP-managed project files only; run `rsp skills install` separately to refresh the package-owned Skill suite.
+
+## Migrating from 2.x
+
+Version 3 uses `.rsp/rsp-rules.md` as the only runtime fallback path and removes project rules from the RSP model:
+
+See the [complete 3.0 migration guide](https://github.com/oevery/rsp/blob/v3.0.0/docs/migrations/3.0.md) for compatibility, recovery, and validation details.
+
+1. Upgrade the RSP CLI.
+2. Run `rsp update` to create the canonical fallback and remove the obsolete generated `.rsp/rules/rsp-rules.md`.
+3. If `.rsp/rules/` remains, move only stable scoped instructions from its residual entries into the nearest project-owned `AGENTS.md`, then remove the obsolete entries.
+4. Flatten any work path deeper than `.rsp/changes/<group>/<change>.md`, and resolve any `.rsp/changes/<name>.md` versus `.rsp/changes/<name>/` collision manually.
+5. Run `rsp doctor` and resolve every remaining migration issue.
+
+Repository maintainers can track external skill and workflow sources as offline review inputs. This tooling is intentionally excluded from the published package; see the [source-checkout maintainer guide](https://github.com/oevery/rsp/blob/main/docs/upstreams.md).
+
 ## Work Model
 
 ```text
@@ -156,38 +262,38 @@ During implementation, keep the change file and the actual work in sync: complet
 
 Agents should treat only entries in `focus.d/` as current work. Unfocused files in `changes/` are still open, but should not be treated as the current target unless the user explicitly asks for them or they are re-focused.
 
-The durable update decision (whether the change produced knowledge that belongs in `.rsp/specs/` or `.rsp/rules/`) is a semantic choice made by the RSP skill or a human reviewer.
+Durable review makes two independent semantic choices: whether current facts or scoped instructions need an update, and whether lasting rationale needs a Decision Record. The RSP skill or a human reviewer owns both judgments.
 
-`rsp ready` and `rsp show` expose both deterministic readiness and semantic-review signals. Deterministic readiness comes from checkboxes, blockers, and scenarios; semantic review remains required for durable-update decisions.
+`rsp ready` and `rsp show` expose deterministic readiness and semantic-review signals without turning deterministic success into an archive action. Deterministic readiness comes from checkboxes, blockers, and scenarios; Core or a human still owns the durable-update decision and the advisory archive recommendation.
 
-`rsp ready --json` and `rsp show --json` also include `durableReview` guidance with fixed decision options and candidate durable targets. This is review guidance only; RSP does not auto-merge change `Spec` deltas into durable files.
+`rsp ready --json` and `rsp show --json` include `durableReview.factDecisions`, `rationaleDecisions`, `factCandidateTargets`, and the one authoritative `decisionRecordsPath`. This is routing guidance only; RSP does not fabricate filenames or promote Change content automatically.
 
 ## Recommended workflow
 
 New project:
 
-1. `npx -y @oevery/rsp init`
-2. Prefer `npx -y @oevery/rsp init --with-project-setup`, or run `rsp create project-setup` manually
+1. `npx -y @oevery/rsp@3.1.0-beta.0 init`
+2. Prefer `npx -y @oevery/rsp@3.1.0-beta.0 init --with-project-setup`, or run `rsp create project-setup` manually
 3. Fill `.rsp/specs/design.md`
 4. Use `rsp add spec <name>` only when a new durable project doc is needed
-5. Use `rsp add rules project-rules` only when the project has stable local rules
+5. Keep lasting rationale in the configured Decision Record directory and stable scoped operating instructions in the nearest project-owned `AGENTS.md`
 6. For tracked open work, start with `rsp create <name>`
 7. If you want an existing open change to become current work, use `rsp focus <name>`
 8. Use `rsp unfocus <name>` when you want to remove a change from the current focus set
 9. Edit the change file directly to implement the work and mark tasks complete
 10. Use the RSP skill or a human review to decide whether durable updates are needed
-11. Finish with `rsp archive <name>`
+11. After Core recommends archive, run `rsp archive <name>` before final Git delivery; inspect the complete resulting worktree and obtain Git authority separately
 
 Existing project with a rich `AGENTS.md`:
 
-1. `npx -y @oevery/rsp init`
+1. `npx -y @oevery/rsp@3.1.0-beta.0 init`
 2. Keep the managed block thin
 3. Move durable design into `.rsp/specs/design.md`
-4. Use `rsp add spec <name>` or `rsp add rules <name>` only when needed
+4. Use `rsp add spec <name>` only when another durable current-fact document is needed
 
 AI-assisted setup:
 
-1. `npx -y @oevery/rsp init --agents-mode print --with-project-setup`
+1. `npx -y @oevery/rsp@3.1.0-beta.0 init --agents-mode print --with-project-setup`
 2. Keep the managed block as generated and adapt only the surrounding human-owned content if needed
 3. Have the AI review and fill `.rsp/changes/project-setup.md`
 4. Have the AI fill `.rsp/specs/design.md`
@@ -198,34 +304,61 @@ AI-assisted setup:
 ```text
 rsp init --agents-mode <mode>   Scaffold .rsp/ and ensure AGENTS.md contains the RSP entry block
 rsp init --with-project-setup   Also create .rsp/changes/project-setup.md
-rsp update                      Refresh rules, repair the AGENTS block, and rebuild indices after upgrade
-rsp add rules <name>            Create .rsp/rules/<name>.md
+rsp update                      Refresh the fallback protocol, repair the AGENTS block, and rebuild indices
+rsp ui [--lang auto|en|zh-CN]   Open the read-only interactive dashboard
+rsp skills install [--dry-run] [--force]
+                                  Install the invoking package's ten Skills into .agents/skills
 rsp add spec <name>             Create .rsp/specs/<name>.md and rebuild specs index
 rsp create <name> [summary]     Create .rsp/changes/<name>.md; add --lite for a shorter template
+rsp group create <name> [goal] Create an unfocused .rsp/changes/<name>/00-brief.md
+rsp group close <name>         Archive a completed Group Brief after every child is archived
 rsp focus <name>                Mark an open change as currently focused
 rsp unfocus <name>              Remove an open change from the current focus set
 rsp archive <name>              Archive to .rsp/archives/ + update archive index
 rsp archive --dry-run <name>    Preview archive readiness without moving the change
-rsp ready <name> [--json] [--verbose]
+rsp ready <name> [--json [--compact]] [--verbose]
                                   Preview archive readiness (same as archive --dry-run)
-rsp show <name|--focused> [--json] [--verbose]
+rsp show <name|--focused> [--json [--compact]] [--verbose]
                                   Show change context with readiness signals and context paths
-rsp status [--focused|--blocked|--stale <days>] [--json] [--verbose]
-                                  Show project status summary with focus-aware filters
-rsp check [--focused] [--json] [--verbose]
+rsp history [--limit <n>] [--since <date>] [--until <date>] [--kind <kind>] [--group <group>] [--json [--compact]]
+                                  List bounded archived Change summaries (default 20, maximum 100)
+rsp history <work-ref> [--json [--compact]]
+                                  Show bounded evidence detail for one exact archived Change
+rsp status [--focused|--blocked|--stale <days>] [--json [--compact]] [--verbose]
+                                  Show project status plus derived dependency plan with focus-aware filters
+rsp check [--focused] [--json [--compact]] [--verbose]
                                   Validate change files and lightly lint template/scenario structure
-rsp doctor [--fix] [--json] [--verbose]
+rsp doctor [--fix] [--json [--compact]] [--verbose]
                                   Check setup health and common issues
 ```
 
-For exact rules, use `.rsp/rules/rsp-rules.md`. For operational durable-decision guidance, use `skills/rsp/SKILL.md`.
+Use `skills/rsp/SKILL.md` for operations. When the skill is unavailable, use `.rsp/rsp-rules.md` as the minimal fallback protocol.
+
+On a real interactive terminal, bare `rsp` opens the same read-only dashboard as `rsp ui`. CI, pipes, redirected streams, and `TERM=dumb` stay on static command output; use `rsp status` for a human snapshot or `rsp status --json` for automation. The dashboard never creates, focuses, or archives work.
+
+Dashboard keys: `Tab` cycles Changes/Groups/History, arrows or `j`/`k` move, `/` filters the active scope, `Enter` opens full-width detail, `r` refreshes the active scope, `?` shows help, and `q`, `Ctrl-C`, or top-level `Esc` exits. History is loaded only when first visited, uses the default bounded recent result, and loads one selected record's structured detail by its unique archive path only after `Enter`; use `rsp history` filters for older work. Set `RSP_UI_LANG=en|zh-CN` or pass `rsp ui --lang`; only dashboard-owned labels are localized. Existing CLI help, plain output, JSON, WorkRefs, paths, commands, Skills, and RSP artifacts remain English.
 
 When there is no focused change, `rsp status` and `rsp show --focused --json` print `nextActions` instead of guessing which open change is current.
 
+Human-readable `rsp status` renders its execution guidance as a dependency forest: each parent requires its children, shared prerequisites are referenced instead of expanded repeatedly, and `Next action` names the currently executable Change or Changes.
+
+`rsp status --json` returns the same dependency graph under `plan.nodes`, `plan.ready`, `plan.edges`, `plan.blocked`, and `plan.waves`. Nodes distinguish filter-selected Changes from prerequisite context, while filtered plans retain the transitive prerequisite closure needed to explain the result. JSON stays flat rather than nesting children because prerequisites may be shared by multiple Changes. Each edge reads as “`change` requires `requires`”. These are derived navigation facts, not execution authority or persisted workflow state.
+
+`rsp history` inspects authoritative archive files directly instead of trusting the generated archive index. List results are ordered by archive date descending, WorkRef, then source path; inclusive date, exact kind, and exact Group filters are applied before the 1–100 record bound. Each record includes its project-relative archive path as a stable identity. `rsp history <work-ref>` returns bounded summary, scenario and checkbox counts, and bounded Tasks/Verify/Blockers evidence. It never returns raw Markdown; duplicate generations of one WorkRef fail with candidate archive paths instead of choosing implicitly. Unreadable, malformed, path-inconsistent, missing-root, or reserved executable Group Brief identities fail the complete query even when filters would exclude them. Archived Group Briefs are validated but are not list records. The command accepts at most one positional WorkRef. Diagnostics and ambiguous candidates are capped at 20 entries with total/returned/`hasMore` metadata, and human errors report how many entries were omitted.
+
+Examples:
+
+```sh
+rsp history --since 2026-07-01 --kind fix --limit 10 --json
+rsp history cli-machine-output/add-bounded-history-query --json --compact
+```
+
+The JSON-producing inspection commands `status`, `show`, `ready`, `check`, `doctor`, and `history` accept `--json --compact` for the same parsed value as `--json`, serialized on one LF-terminated line. `--compact` requires `--json`; other commands reject it before running command behavior.
+
 `rsp create --lite` is a shorter template for explicitly tracked small changes; simple current-session tasks should not create RSP changes unless tracking is intentionally needed.
 
 `rsp doctor --fix` runs only safe deterministic repairs. Its `fixed` JSON entries report actual filesystem changes; a healthy project returns `fixed: []` and the human output says no safe fixes are needed.
 
 ## Platform-agnostic
 
-`.rsp/` is a plain file convention. It works with Kilo Code, Cursor, Claude Code, Cline, GitHub Copilot, or any assistant that reads project files. Requires Node.js 18+.
+`.rsp/` is a plain file convention. It works with Kilo Code, Cursor, Claude Code, Cline, GitHub Copilot, or any assistant that reads project files. RSP 3.1 requires Node.js 22+; users upgrading from 3.0 must update Node before installing.