@oevery/rsp 3.1.0-beta.1 → 3.1.0-beta.3

package/README.md

@@ -4,7 +4,7 @@ English | [简体中文](./README.zh-CN.md)
 
 **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.
+RSP helps turn unclear intent into shaped, implemented, reviewed, and verified software changes while keeping project knowledge durable and work recoverable. Its eleven 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**.
 
@@ -15,7 +15,7 @@ The workflow rests on a lightweight artifact foundation of **Rules, Specs, and P
 - 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.
+- Prepare or reconcile release documentation for an explicit confirmed release operation; use a Release Change only when material coordination needs a persistent owner.
 
 ## How the workflow fits together
 
@@ -25,7 +25,7 @@ intent
   → design when needed
   → diagnose | TDD | implement
   → review → address accepted findings
-  → release docs when owned
+  → release docs for an explicit confirmed operation
   → durable review → archive
 ```
 
@@ -34,17 +34,17 @@ RSP derives the next action from the selected Change, repository evidence, verif
 ## Quick start
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.1 init
-npx -y @oevery/rsp@3.1.0-beta.1 doctor
+npx -y @oevery/rsp@3.1.0-beta.3 init
+npx -y @oevery/rsp@3.1.0-beta.3 doctor
 ```
 
 Recommended bootstrap flow:
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.1 init --with-project-setup
+npx -y @oevery/rsp@3.1.0-beta.3 init --with-project-setup
 # fill .rsp/changes/project-setup.md
 # fill .rsp/specs/design.md
-npx -y @oevery/rsp@3.1.0-beta.1 doctor
+npx -y @oevery/rsp@3.1.0-beta.3 doctor
 ```
 
 ## Artifact foundation
@@ -62,9 +62,12 @@ npx -y @oevery/rsp@3.1.0-beta.1 doctor
 .rsp/
 ├── rsp-rules.md              # minimal fallback protocol
 ├── specs/
-│   ├── INDEX.md              # auto-generated
+│   ├── 00-index.md           # auto-generated direct-child navigation
 │   ├── design.md
-│   └── decisions/            # authoritative Decision Records by default
+│   ├── decisions/            # authoritative Decision Records by default; excluded from Specs indexes
+│   └── <domain>/
+│       ├── 00-index.md       # auto-generated direct-child navigation
+│       └── <spec>.md
 ├── changes/
 │   ├── <name>.md
 │   └── <group>/
@@ -73,7 +76,7 @@ npx -y @oevery/rsp@3.1.0-beta.1 doctor
 ├── focus.d/
 │   └── <name>
 └── archives/
-    └── INDEX.md              # auto-generated
+    └── YYYY-MM-DD_<change>.md
 ```
 
 ## Concepts
@@ -90,9 +93,10 @@ npx -y @oevery/rsp@3.1.0-beta.1 doctor
 - 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.
+- `rsp init`, `rsp update`, `rsp add spec`, and the generated Specs index builder 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, the generated Specs index, 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`.
+- When later evidence shows that the original acceptance was not actually met, `rsp reopen <work-ref> --reason <text>` restores the same executable WorkRef as focused open work and retains the selected archive as history. Multiple archives require an exact `--from .rsp/archives/...` path. Use a new corrective Change for genuinely new scope or an independently delivered correction; reopening never rewrites Git or published history.
 - 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.
@@ -100,13 +104,12 @@ npx -y @oevery/rsp@3.1.0-beta.1 doctor
 ## File ownership
 
 - `AGENTS.md`: only the `<!-- rsp:begin --> ... <!-- rsp:end -->` block is managed by RSP.
-- `.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/**/00-index.md`: fully generated direct-child navigation for the root and populated Spec directories. Reconcile all local indexes with `rsp update`; `rsp add spec` refreshes only the affected directory chain.
 - `.rsp/specs/design.md`: created by `rsp init`, then owned by the project.
 - `.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 project-wide boundaries in `.rsp/specs/design.md`; use the nearest `00-index.md` to discover cohesive reusable facts in the smallest domain Spec.
+- Treat every `00-index.md` as generated navigation, never as an editable current-fact or rationale owner. Each index lists only direct child Specs and populated child Spec directories; Decision Records are excluded.
 - Keep stable scoped workflow and validation instructions in the nearest project-owned `AGENTS.md`, outside the managed RSP block.
 
 ## Decision Record path
@@ -149,76 +152,81 @@ Do not treat `.rsp/specs/` or `.rsp/changes/` as replacements for nearest `AGENT
 
 ## Skills
 
-RSP publishes ten host-neutral Skills for on-demand loading:
+RSP publishes eleven default host-neutral lifecycle Skills for on-demand loading, plus one explicitly installed project-level audit Skill:
+
+| Skill | Role |
+|---|---|
+| `rsp` | Derive the next action; guide setup, durable review, and archive decisions. |
+| `rsp-shape` | Shape one executable Change or justified shallow Group without implementation. |
+| `rsp-design` | Resolve one bounded domain, module/seam, or reversible-exploration question before or within tracked work. |
+| `rsp-implement` | Implement one selected ready Change with fresh verification. |
+| `rsp-diagnose` | Confirm a cause, or return a truthful unresolved diagnosis, before correction. |
+| `rsp-tdd` | Drive one clear behavior through RED, GREEN, and safe REFACTOR. |
+| `rsp-review` | Review a fixed code, document, or mixed comparison without mutation. |
+| `rsp-resolve-findings` | Dispose fixed findings, correct accepted ones, verify, and request re-review. |
+| `rsp-commit` | Create one authorized exact-scope local commit with a repository-consistent structured message. |
+| `rsp-release-docs` | Draft, audit, finalize, or reconcile evidence-based release surfaces. |
+| `rsp-manage` | Continue one explicitly requested or project-enabled eligible ready Change or shallow Group. |
+| `rsp-structural-audit` (optional) | Audit one bounded repository or subtree for evidence-backed structural risks without mutation. |
+
+Each lifecycle Skill returns to an existing project or RSP owner. Report-only Pre-Change Design and `rsp-structural-audit` may return one bounded result directly to the user without inventing an artifact owner. The suite adds no hidden workflow state or recursive Skill orchestration. No Skill infers commit, push, publication, deployment, approval, or human-acceptance authority.
 
-- `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.
+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.
 
-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.
+Compose the suite from evidence: an explicit bounded question may enter report-only Pre-Change Design before Shape; otherwise Shape settles the executable owner and Tracked Design returns one material question to it. Core then chooses Diagnose, TDD, or Implement; Review stays report-only; Resolve Findings corrects accepted findings and requests re-review; Core performs the durable decision before archive. An explicit release operation with a confirmed identity or range may enter Release Docs without a Release Change; create one only for material decisions, coordination, recovery, blockers, or acceptance. Manage is optional: it accepts one selected ready Change or shallow Group that needs independent dispatch, long continuation, or recovery, while small or coupled work stays direct. Projects may keep explicit activation or let Core select eligible managed work automatically.
 
-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.
+### Managed automation policy
+
+Configure automatic selection and local closeout independently in `.rsp/config.yaml`:
+
+```yaml
+manage:
+  activation: auto
+  closeout: lifecycle
+```
+
+`activation` is `explicit` or `auto`. `auto` authorizes Core to select Manage for an eligible requested completion or continuation; it does not grant planning, product-mutation, lifecycle, Git, or external authority. `closeout` is one of:
+
+- `manual`: neither archive nor commit is automatic.
+- `lifecycle`: archive may follow durable review, but commit still needs separate authority.
+- `local`: lifecycle closeout plus separately justified recovery checkpoints; after lifecycle closeout, a qualified clean verified terminal non-small boundary routes once to `rsp-commit`, while terminal small work stays uncommitted.
+
+Change granularity follows one observable outcome and its shared acceptance, verification, review, archive, and rollback boundary; it does not prescribe Git commit count. Each `rsp-commit` invocation still creates exactly one local commit.
+
+New `rsp init` config templates use the shown `auto` plus `lifecycle` policy. If `manage` is absent, RSP instead resolves `activation: explicit` and `closeout: local` for compatibility with the previous explicitly requested Manage behavior. Plain `rsp status` and the top-level `manage` object in `rsp status --json` show the resolved values. Nearest scoped restrictions and host enforcement can narrow the configured ceiling. RSP intentionally has no `full` preset: push, tag, publication, deployment, approval, and human acceptance remain explicit and external.
+
+Humans should start with this README. Agents should follow the nearest `AGENTS.md`, prefer `skills/rsp/SKILL.md`, and use `.rsp/rsp-rules.md` only when the Skill is unavailable.
 
-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/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/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 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. For opt-in beta evaluation, pin the exact prerelease identity, such as `npx -y @oevery/rsp@3.1.0-beta.1 <command>`; stable users can keep using the unversioned package entrypoint for npm `latest`.
-
-Install the exact package-bundled suite into the current project:
+When this README shows `rsp <command>`, it assumes the command is already available in your environment. For opt-in beta evaluation, pin the exact prerelease identity, such as `npx -y @oevery/rsp@3.1.0-beta.3 <command>`; stable users can keep using the unversioned package entrypoint for npm `latest`.
+
+Install the exact package's default lifecycle suite into the current project:
 
 ```bash
 rsp skills install --dry-run
 rsp skills install
 ```
 
-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 pin one exact npm identity:
+On a dual TTY, `rsp skills` opens the interactive manager: the default suite is selected and locked, while optional project Skills can be selected before one confirmed atomic install. For scripts, redirected terminals, and CI, use the deterministic discovery and install commands:
+
+```bash
+rsp skills list
+rsp skills list --json
+```
+
+The command preflights the eleven default package-owned targets, leaves unrelated `.agents/skills` entries (including optional Skills) untouched, and requires explicit `--force` before replacing a divergent selected directory. Install the optional project-level audit Skill by exact name:
+
+When upgrading an installation that still contains `rsp-address-review` or `rsp-codebase-audit`, their replacements are `rsp-resolve-findings` and `rsp-structural-audit`. The installer stops without mutation until `--force` explicitly authorizes transactional removal of the obsolete package-owned directory; `--dry-run --force` previews both removal and installation.
+
+```bash
+rsp skills install rsp-structural-audit --dry-run
+rsp skills install rsp-structural-audit
+```
+
+Both forms install from the package that invoked `rsp`, so prerelease dogfooding can pin one exact npm identity:
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.1 skills install --dry-run
-npx -y @oevery/rsp@3.1.0-beta.1 skills install
+npx -y @oevery/rsp@3.1.0-beta.3 skills install --dry-run
+npx -y @oevery/rsp@3.1.0-beta.3 skills install
 ```
 
 Exact prerelease identities avoid depending on a moving dist-tag. `rsp update` refreshes RSP-managed project files only; run `rsp skills install` separately to refresh the package-owned Skill suite.
@@ -272,8 +280,8 @@ Durable review makes two independent semantic choices: whether current facts or
 
 New project:
 
-1. `npx -y @oevery/rsp@3.1.0-beta.1 init`
-2. Prefer `npx -y @oevery/rsp@3.1.0-beta.1 init --with-project-setup`, or run `rsp create project-setup` manually
+1. `npx -y @oevery/rsp@3.1.0-beta.3 init`
+2. Prefer `npx -y @oevery/rsp@3.1.0-beta.3 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. Keep lasting rationale in the configured Decision Record directory and stable scoped operating instructions in the nearest project-owned `AGENTS.md`
@@ -283,17 +291,18 @@ New project:
 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. After Core recommends archive, run `rsp archive <name>` before final Git delivery; inspect the complete resulting worktree and obtain Git authority separately
+12. If later evidence invalidates the original completion, run `rsp reopen <name> --reason <text>` and resolve the restored unfinished Task and Verify evidence under the same WorkRef
 
 Existing project with a rich `AGENTS.md`:
 
-1. `npx -y @oevery/rsp@3.1.0-beta.1 init`
+1. `npx -y @oevery/rsp@3.1.0-beta.3 init`
 2. Keep the managed block thin
-3. Move durable design into `.rsp/specs/design.md`
+3. Keep project-wide boundaries and navigation in `.rsp/specs/design.md`, and route cohesive durable facts to the smallest domain Spec
 4. Use `rsp add spec <name>` only when another durable current-fact document is needed
 
 AI-assisted setup:
 
-1. `npx -y @oevery/rsp@3.1.0-beta.1 init --agents-mode print --with-project-setup`
+1. `npx -y @oevery/rsp@3.1.0-beta.3 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`
@@ -304,23 +313,27 @@ 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 the fallback protocol, repair the AGENTS block, and rebuild indices
+rsp update                      Refresh managed project files, not packaged Skills
 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 skills                      Open the interactive project Skill manager on a dual TTY
+rsp skills list [--json]        List bundled Skills and exact project installation status
+rsp skills install [name] [--dry-run] [--force]
+                                  Install the default eleven Skills or one exact optional Skill 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 archive <name>              Archive to .rsp/archives/
+rsp archive --dry-run <name>    Deprecated compatibility route to rsp ready; never moves the change
+rsp reopen <name> --reason <text> [--from <archive-path>]
+                                  Restore the same WorkRef as focused open work and retain archive history
 rsp ready <name> [--json [--compact]] [--verbose]
-                                  Preview archive readiness (same as archive --dry-run)
+                                  Canonical read-only archive readiness projection
 rsp show <name|--focused> [--json [--compact]] [--verbose]
                                   Show change context with readiness signals and context paths
-rsp history [--limit <n>] [--since <date>] [--until <date>] [--kind <kind>] [--group <group>] [--json [--compact]]
+rsp history [--limit <n>] [--since <date>] [--until <date>] [--kind <kind>] [--group <group>] [--search <text>] [--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
@@ -344,12 +357,13 @@ Human-readable `rsp status` renders its execution guidance as a dependency fores
 
 `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.
+`rsp history` inspects authoritative archive files directly; no generated Archive Index is created or read. List results are ordered by archive date descending, WorkRef, then source path; inclusive date, exact kind, exact Group, and case-insensitive literal WorkRef/summary search 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. `status` archive trends and TUI History use the same validated inspection.
 
 Examples:
 
 ```sh
 rsp history --since 2026-07-01 --kind fix --limit 10 --json
+rsp history --search migration --limit 10 --json
 rsp history cli-machine-output/add-bounded-history-query --json --compact
 ```