@oevery/rsp 2.0.2 → 2.0.4

package/README.md

@@ -51,6 +51,8 @@ npx -y @oevery/rsp doctor
 - 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.
+- `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
 
@@ -71,6 +73,9 @@ 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/`.
+
 Read in order:
 1. .rsp/rules/rsp-rules.md
 2. .rsp/focus.d/
@@ -78,6 +83,9 @@ Read in order:
 4. .rsp/specs/design.md
 5. .rsp/specs/INDEX.md
 6. only the relevant additional .rsp/rules/*.md and .rsp/specs/*.md files
+
+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.
 <!-- rsp:end -->
 ```
 
@@ -142,12 +150,18 @@ Inside `open`, typical work includes:
 - Edit the change file directly — fill sections, mark tasks, write design decisions.
 - Review whether durable updates are needed before archive.
 
+During implementation, keep the change file and the actual work in sync: complete `## Tasks` checkboxes as code lands, update `## Verify` with the checks actually run, and revise `## Design` if implementation discoveries change the plan.
+
 `archive` moves completed work into history. Archive never blocks — it warns but leaves the final decision to the agent or human.
 
 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.
 
+`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 --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.
+
 ## Recommended workflow
 
 New project:
@@ -157,7 +171,7 @@ New project:
 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
-6. Start work with `rsp create <name>`
+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
@@ -187,19 +201,31 @@ 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 add spec <name>             Create .rsp/specs/<name>.md and rebuild specs index
-rsp create <name> [summary]     Create .rsp/changes/<name>.md
+rsp create <name> [summary]     Create .rsp/changes/<name>.md; add --lite for a shorter template
 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]
+                                  Preview archive readiness (same as archive --dry-run)
+rsp show <name|--focused> [--json] [--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 [--json] [--verbose] Validate change files and lightly lint scenario structure
-rsp doctor [--json] [--verbose]
+rsp check [--focused] [--json] [--verbose]
+                                  Validate change files and lightly lint template/scenario structure
+rsp doctor [--fix] [--json] [--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`.
 
+When there is no focused change, `rsp status` and `rsp show --focused --json` print `nextActions` instead of guessing which open change is current.
+
+`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+.

package/README.zh-CN.md

@@ -51,6 +51,8 @@ npx -y @oevery/rsp doctor
 - 每个 change 始终是单个 Markdown 文件，并包含 proposal、spec、design、tasks、verification 与 blockers 等明确 section。
 - 完成后的 change 会移动到 `archives/`；若变更产出了长期知识，应在归档前同步写入 `specs/` 或 `rules/`。
 - 所谓长期知识，只应包含稳定事实；不要把任务历史、排障笔记或一次性实现上下文提升到 `specs/` 或 `rules/`。
+- Change `Spec` 中的 delta 标记（`### ADDED`、`### MODIFIED`、`### REMOVED`）仅为规划辅助标记。`rsp archive` 不会自动将它们合并到 `specs/` 或 `rules/` 中。长期知识的写入始终是高显式语义决策。
+- `rsp check` 会执行 deterministic 的卫生检查。它会对未完成的模板占位符和未解决的 clarification 标记发出 warning，但这些 warning 不会替代 durable update 的语义判断。
 
 ## 文件所有权
 
@@ -71,6 +73,9 @@ npx -y @oevery/rsp doctor
 <!-- 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/`.
+
 Read in order:
 1. .rsp/rules/rsp-rules.md
 2. .rsp/focus.d/
@@ -78,6 +83,9 @@ Read in order:
 4. .rsp/specs/design.md
 5. .rsp/specs/INDEX.md
 6. only the relevant additional .rsp/rules/*.md and .rsp/specs/*.md files
+
+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.
 <!-- rsp:end -->
 ```
 
@@ -136,12 +144,18 @@ open → archived
 - 直接编辑 change 文件，填写 section、勾选 tasks、记录设计决策。
 - 在归档前判断是否需要 durable updates。
 
+实现过程中，应保持 change 文件与实际工作同步：代码完成后勾选对应的 `## Tasks`，在 `## Verify` 中记录实际运行的检查；如果实现发现设计不成立，应先更新 `## Design` 再继续。
+
 `archive` 会把已完成的工作归档到历史。`archive` 不会阻塞，只会给出 warning，最终判断留给 agent 或人工。
 
 agent 应只把 `focus.d/` 中列出的 change 视为当前工作。`changes/` 中未聚焦的文件仍然是 open，但除非用户明确要求或重新 `focus`，否则不应被当作当前目标。
 
 关于 durable update 的决定，也就是某次变更是否产出了应该写入 `.rsp/specs/` 或 `.rsp/rules/` 的知识，本质上是语义判断，应由 RSP skill 或人工 reviewer 完成。
 
+`rsp ready` 和 `rsp show` 会同时暴露 deterministic readiness 与 semantic-review 信号。deterministic readiness 来自 checkbox、blocker 和 scenario；durable update 仍然需要语义 review。
+
+`rsp ready --json` 和 `rsp show --json` 还会包含 `durableReview` 指导信息，其中包括固定决策选项和候选 durable target。这只是 review 指导；RSP 不会自动把 change `Spec` delta 合并进 durable 文件。
+
 ## 推荐工作流
 
 新项目：
@@ -151,7 +165,7 @@ agent 应只把 `focus.d/` 中列出的 change 视为当前工作。`changes/`
 3. 填写 `.rsp/specs/design.md`
 4. 仅在需要新的长期项目文档时使用 `rsp add spec <name>`
 5. 仅在项目存在稳定本地规则时使用 `rsp add rules project-rules`
-6. 使用 `rsp create <name>` 开始工作
+6. 对需要跟踪的 open work，使用 `rsp create <name>` 开始
 7. 如果要让某个已有 open change 成为当前工作，使用 `rsp focus <name>`
 8. 如果要将某个 change 移出当前焦点集合，使用 `rsp unfocus <name>`
 9. 直接编辑 change 文件并完成实现、勾选 tasks
@@ -181,19 +195,31 @@ rsp init --with-project-setup   同时创建 .rsp/changes/project-setup.md
 rsp update                      升级后刷新 rules、修复 AGENTS 受管块并重建各类索引
 rsp add rules <name>            创建 .rsp/rules/<name>.md
 rsp add spec <name>             创建 .rsp/specs/<name>.md 并重建 specs 索引
-rsp create <name> [summary]     创建 .rsp/changes/<name>.md
+rsp create <name> [summary]     创建 .rsp/changes/<name>.md；可加 --lite 使用更短模板
 rsp focus <name>                将一个 open change 标记为当前聚焦
 rsp unfocus <name>              将一个 open change 移出当前聚焦集合
 rsp archive <name>              归档到 .rsp/archives/ 并更新 archive index
+rsp archive --dry-run <name>    预览归档就绪状态，不移动 change
+rsp ready <name> [--json] [--verbose]
+                                   预览归档就绪状态（与 archive --dry-run 相同）
+rsp show <name|--focused> [--json] [--verbose]
+                                   显示 change 上下文，带就绪信号和上下文路径
 rsp status [--focused|--blocked|--stale <days>] [--json] [--verbose]
                                    查看带有当前聚焦信息的项目状态摘要，并支持轻量筛选
-rsp check [--json] [--verbose] 校验 change 文件，并对 scenario 结构做轻量 lint
-rsp doctor [--json] [--verbose]
+rsp check [--focused] [--json] [--verbose]
+                                   校验 change 文件，并对 template/scenario 结构做轻量 lint
+rsp doctor [--fix] [--json] [--verbose]
                                    检查接入健康和常见问题
 ```
 
 精确规则以 `.rsp/rules/rsp-rules.md` 为准；durable decision 的操作指导以 `skills/rsp/SKILL.md` 为准。
 
+当没有 focused change 时，`rsp status` 和 `rsp show --focused --json` 会输出 `nextActions`，但不会自动猜测哪个 open change 是当前工作。
+
+`rsp create --lite` 是用于显式跟踪小 change 的短模板；简单的当前会话任务默认不应创建 RSP change，除非确实需要跟踪。
+
+`rsp doctor --fix` 只执行安全 deterministic 修复。它的 JSON `fixed` 条目表示实际写入的文件系统变化；健康项目会返回 `fixed: []`，human 输出会说明无需安全修复。
+
 ## 工具无关
 
 `.rsp/` 是纯文件约定，适用于 Kilo Code、Cursor、Claude Code、Cline、GitHub Copilot 或任何能读取项目文件的 AI 助手。需要 Node.js 18+。