@xenonbyte/req-2-plan 0.4.0 → 0.4.1

package/README.md

@@ -67,17 +67,31 @@ existed beforehand.
 
 ### Quick start
 
+Install the platform skills, then check what landed (terminal, lifecycle CLI):
+
 ```bash
-r2p install                                   # install all platforms (default)
-r2p-start "Add rate limiting" --repo-path .   # start a run grounded in this repo's facts
-r2p-continue                                  # advance it stage by stage
-r2p status                                    # see what is installed
+r2p install   # install all platforms (default)
+r2p status    # see what is installed
+```
+
+Then drive the workflow from your agent — the installed skills call the `r2p-*`
+wrappers (to run them in a terminal instead, add `~/.req-to-plan/bin` to `PATH`,
+see the tip below):
+
+```text
+/r2p-start --repo-path . "Add rate limiting"    # requirement as inline text
+/r2p-start --repo-path . --file change-req.md   # requirement as a document
+/r2p-continue                                   # advance it stage by stage
 ```
 
-Pass `--repo-path .` whenever the requirement targets the current project (use the
-target repo's path for cross-repo work); it generates the Project Context Pack that
-grounds tier estimation and PLAN file-reference checks. If a standard-tier PLAN gate
-later reports a missing or unusable Context Pack, build it mid-run with
+A requirement can be inline text or a document passed with `--file <path>`
+(the two are mutually exclusive). **Whenever a code repository is the
+requirement's context, pass `--repo-path`** — `.` for the current project,
+the target repo's path for cross-repo work; it generates the Project Context
+Pack that grounds tier estimation and PLAN file-reference checks. Keep options
+before the requirement text (as above) so a quoting slip in free-form text can
+never swallow an option. If a standard-tier PLAN gate later reports a missing
+or unusable Context Pack, build it mid-run with
 the `PYTHONPATH=... <python> -m tools.workflow_cli context-build ...` command printed
 by the gate (there is no standalone `context-build` executable).
 
@@ -174,6 +188,16 @@ r2p-gap-resolve --work-id <id> --route-id R-1
 > walks you through both repair flows with `needs_repair` and `needs_gap_resolve`
 > stops.
 
+> [!NOTE]
+> **Human decision points (standard DESIGN).** When a standard-tier DESIGN
+> involves a choice a human must make (new dependency, migration strategy,
+> API compatibility), the agent records it in the `## Decision Requests`
+> section as a `### DECISION-NNN` block with `Question:`, `Options:`,
+> `Recommended:`, and `Status: pending` — and a pending decision fails
+> `gate-quality` until a human chooses and the block becomes
+> `Status: selected` with `Selected:` and `Rationale:` lines.
+> Write exactly `none` in that section when no human decision is needed.
+
 ## License
 
 [MIT](./LICENSE) © xenonbyte

package/README.zh-CN.md

@@ -61,16 +61,28 @@ r2p help
 
 ### Quick start
 
+先在终端用生命周期 CLI 安装平台技能并确认安装结果：
+
 ```bash
-r2p install                                   # 安装全部平台（默认）
-r2p-start "Add rate limiting" --repo-path .   # 启动一次以当前仓库事实为锚点的工作流
-r2p-continue                                  # 逐阶段推进
-r2p status                                    # 查看已安装情况
+r2p install   # 安装全部平台（默认）
+r2p status    # 查看已安装情况
+```
+
+然后在 agent 里驱动工作流——已安装的平台技能会调用 `r2p-*` 包装器
+（如需在终端手动执行，先把 `~/.req-to-plan/bin` 加入 `PATH`，见下方 tip）：
+
+```text
+/r2p-start --repo-path . "Add rate limiting"    # 需求为内联文本
+/r2p-start --repo-path . --file change-req.md   # 需求为文档文件
+/r2p-continue                                   # 逐阶段推进
 ```
 
-需求针对当前项目时必传 `--repo-path .`（跨仓库需求传目标仓库路径）；它生成的
-Project Context Pack 是 tier 估算与 PLAN 文件引用校验的真值锚点。若 standard tier
-的 PLAN gate 提示 Context Pack 缺失/不可用，直接执行 gate 打印的
+需求可以是内联文本，也可以用 `--file <path>` 传入文档（两者互斥）。
+**只要需求以某个代码仓库为上下文，就必须传 `--repo-path`**——当前项目传 `.`，
+跨仓库需求传目标仓库路径；它生成的 Project Context Pack 是 tier 估算与 PLAN
+文件引用校验的真值锚点。选项写在需求文本之前（如上例），这样即使自由文本
+引号写错也不会吞掉选项。若 standard tier 的 PLAN gate 提示 Context Pack
+缺失/不可用，直接执行 gate 打印的
 `PYTHONPATH=... <python> -m tools.workflow_cli context-build ...` 命令中途补建
 （不存在独立的 `context-build` 可执行文件）。
 
@@ -159,6 +171,15 @@ r2p-gap-resolve --work-id <id> --route-id R-1
 > reopen 针对**已关闭**的 run；gap 路由针对**开着**的 run。`r2p-continue` 会用
 > `needs_repair` 和 `needs_gap_resolve` 停点带你走完这两种修复流程。
 
+> [!NOTE]
+> **人工决策点（standard DESIGN）。** 当 standard tier 的 DESIGN 涉及必须由人
+> 决定的选择（引入新依赖、迁移策略、API 兼容性）时，agent 会在 `## Decision
+> Requests` 章节写入 `### DECISION-NNN` block（含 `Question:`/`Options:`/
+> `Recommended:`）并标记 `Status: pending` ——存在 pending 决策时
+> `gate-quality` 会失败，直到人选定方案、block 改为 `Status: selected`
+> 并补上 `Selected:` 与 `Rationale:` 行。
+> 无需人工决策时，该章节须恰好写 `none`。
+
 ## License
 
 [MIT](./LICENSE) © xenonbyte

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/req-2-plan",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Requirement-to-PLAN workflow CLI and agent integration installer.",
   "bin": {
     "r2p": "bin/r2p.js"

package/tools/workflow_cli/agent_templates/claude/SKILL.md

@@ -33,4 +33,5 @@ Run each via Bash using the scripts in `{{R2P_BIN_DIR}}`:
    - Auto-advances: moves to the next stage after non-PLAN checkpoint approval, then runs that stage's entry gate
    - Auto-closes: closes the run when the PLAN checkpoint is approved and no open routes remain
    - Does NOT auto-mark artifacts ready and does NOT auto-approve checkpoints — those are human steps
+   - Standard-tier DESIGN: record any human technical choice in `## Decision Requests` as a `### DECISION-NNN` block (`Question:`/`Options:`/`Recommended:`/`Status: pending`); pending blocks `gate-quality` until a human selects (`Status: selected` + `Selected:`/`Rationale:`), or write exactly `none` when no decision is needed
 3. When the run closes, hand the approved PLAN at `07-plan.md` directly to your executor — the PLAN is executor-neutral and needs no adaptation step.

package/tools/workflow_cli/cli.py

@@ -790,23 +790,22 @@ def _cmd_tier_escalate(args):
     previous_tier = record.tier_locked
     record.tier_locked = record.tier_locked.escalate(modifier)
 
-    plan_gate_passed_statuses = {
+    gate_passed_statuses = {
         RunStatus.READY_FOR_CHECKPOINT_REVIEW,
         RunStatus.CHECKPOINT_REVIEW,
     }
-    standard_plan_gate_became_applicable = (
-        record.current_stage == Stage.PLAN
-        and previous_tier.base != TierBase.STANDARD
+    standard_gate_became_applicable = (
+        previous_tier.base != TierBase.STANDARD
         and record.tier_locked.base == TierBase.STANDARD
-        and record.status in plan_gate_passed_statuses
+        and record.status in gate_passed_statuses
     )
-    if standard_plan_gate_became_applicable:
+    if standard_gate_became_applicable:
         record = update_run_status(record, RunStatus.ACTIVE_STAGE_DRAFT)
         update_resume_context(
             record,
             last_operation=f"tier_escalated_{modifier.value}",
             next_operation="gate_quality",
-            active_item=Stage.PLAN.value,
+            active_item=record.current_stage.value,
         )
 
     # Revoke affected bundle authorizations that cover high-tier stages
@@ -822,14 +821,26 @@ def _cmd_tier_escalate(args):
                 ba.revoked_at = revoke_ts
 
     mgr.save(record)
+    data = {
+        "work_id": str(record.work_id),
+        "tier_base": record.tier_locked.base.value,
+        "modifiers": sorted(m.value for m in record.tier_locked.modifiers),
+        "added_modifier": modifier.value,
+    }
+    if (
+        previous_tier.base != TierBase.STANDARD
+        and record.tier_locked.base == TierBase.STANDARD
+        and STAGE_ORDER.index(record.current_stage) > STAGE_ORDER.index(Stage.DESIGN)
+    ):
+        data["note"] = (
+            "DESIGN was approved under light tier; if this escalation "
+            "changes design decisions, run r2p-gap-open --work-id "
+            f"{record.work_id} --owner-stage design "
+            '--required-action "<describe the design impact>"'
+        )
     print_and_exit(
         format_success(
-            {
-                "work_id": str(record.work_id),
-                "tier_base": record.tier_locked.base.value,
-                "modifiers": sorted(m.value for m in record.tier_locked.modifiers),
-                "added_modifier": modifier.value,
-            },
+            data,
             message=f"Tier escalated with modifier: {modifier.value}",
         ),
         EXIT_OK,

package/tools/workflow_cli/context_pack.py

@@ -22,7 +22,7 @@ class ProjectContextPack:
     package_managers: list = field(default_factory=list)
     test_commands: list = field(default_factory=list)
     entrypoints: list = field(default_factory=list)
-    dependencies: list = field(default_factory=list)  # [{name, version, ecosystem}]
+    dependencies: list = field(default_factory=list)  # [{name, version, ecosystem, dev?}]
     config_files: list = field(default_factory=list)
     source_dirs: list = field(default_factory=list)
 
@@ -35,13 +35,21 @@ def build_context_pack(repo_path: Path) -> ProjectContextPack:
     pkg = repo_path / "package.json"
     if pkg.exists():
         try:
-            data = json.loads(pkg.read_text(encoding="utf-8"))
+            raw_data = json.loads(pkg.read_text(encoding="utf-8"))
             pack.package_managers.append("npm")
-            test = (data.get("scripts") or {}).get("test")
-            if test:
-                pack.test_commands.append(test)
-            for name, ver in (data.get("dependencies") or {}).items():
-                pack.dependencies.append({"name": name, "version": ver, "ecosystem": "npm"})
+            data = raw_data if isinstance(raw_data, dict) else {}
+            scripts = data.get("scripts")
+            if isinstance(scripts, dict) and scripts.get("test"):
+                pack.test_commands.append("npm test")
+            dependencies = data.get("dependencies")
+            if isinstance(dependencies, dict):
+                for name, ver in dependencies.items():
+                    pack.dependencies.append({"name": name, "version": ver, "ecosystem": "npm"})
+            dev_dependencies = data.get("devDependencies")
+            if isinstance(dev_dependencies, dict):
+                for name, ver in dev_dependencies.items():
+                    pack.dependencies.append(
+                        {"name": name, "version": ver, "ecosystem": "npm", "dev": True})
         except (ValueError, OSError):
             pass
 

package/tools/workflow_cli/trace.py

@@ -146,7 +146,9 @@ def _risk_blocks(content: str) -> dict[str, str]:
 
 
 def scope_in_not_closed(run_dir: Path) -> list[str]:
-    """SCOPE-IN closes only when a PLAN-TASK carries it or consumes a SPEC carrying it."""
+    """SCOPE-IN closes only when a PLAN-TASK carries it or consumes a SPEC
+    carrying it outside the SPEC block's nested Non-goals subsections (R14:
+    'explicitly not implemented here' must not close the scope item)."""
     model = build_trace(run_dir)
     plan_text = _artifact_text(run_dir, Stage.PLAN)
     plan_task_text = "\n".join(unfenced_markdown_text(body) for body in _plan_task_bodies(plan_text))
@@ -156,7 +158,8 @@ def scope_in_not_closed(run_dir: Path) -> list[str]:
     for id_ in sorted(i for i in model.defined if i.startswith("SCOPE-IN-")):
         if id_ in plan_task_text:
             continue
-        if any(id_ in spec_blocks.get(spec_id, "") for spec_id in consumed_specs):
+        if any(id_ in _strip_nested_non_goals(spec_blocks.get(spec_id, ""))
+               for spec_id in consumed_specs):
             continue
         issues.append(id_)
     return issues

package/tools/workflow_cli/version.py

@@ -1 +1 @@
-R2P_VERSION = "0.4.0"
+R2P_VERSION = "0.4.1"