@xenonbyte/req-2-plan 0.4.0 → 0.4.2

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.2",
   "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/agent_templates/claude/commands/r2p-start.md

@@ -3,7 +3,7 @@ description: Start a new requirement-to-PLAN workflow run
 ---
 Run `{{R2P_BIN_DIR}}/r2p-start` with the requirement as a positional argument.
 
-Usage: `{{R2P_BIN_DIR}}/r2p-start [--separate] ("<raw requirement>" | --file <path>)`
+Usage: `{{R2P_BIN_DIR}}/r2p-start [--separate] [--repo-path <dir>] ("<raw requirement>" | --file <path>)`
 
 To start from a requirement document, pass `--file <path>` instead of inline text — r2p reads the file contents as the requirement (the path itself is never stored as the requirement): `{{R2P_BIN_DIR}}/r2p-start [--separate] --file ./requirement.md`. `--file` and a positional requirement are mutually exclusive.
 

package/tools/workflow_cli/agent_templates/codex/skills/r2p-start/SKILL.md

@@ -7,7 +7,7 @@ description: Start a new requirement-to-PLAN workflow run from a raw requirement
 
 Run `{{R2P_BIN_DIR}}/r2p-start` with the requirement as a positional argument.
 
-Usage: `{{R2P_BIN_DIR}}/r2p-start [--separate] ("<raw requirement>" | --file <path>)`
+Usage: `{{R2P_BIN_DIR}}/r2p-start [--separate] [--repo-path <dir>] ("<raw requirement>" | --file <path>)`
 
 To start from a requirement document, pass `--file <path>` instead of inline text — r2p reads the file contents as the requirement (the path itself is never stored as the requirement): `{{R2P_BIN_DIR}}/r2p-start [--separate] --file ./requirement.md`. `--file` and a positional requirement are mutually exclusive.
 

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,11 +22,23 @@ 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)
 
 
+def _append_npm_dependencies(pack: ProjectContextPack, dependencies: object, *, dev: bool = False) -> None:
+    if not isinstance(dependencies, dict):
+        return
+    for name, version in dependencies.items():
+        if not isinstance(name, str) or not isinstance(version, str):
+            continue
+        dep = {"name": name, "version": version, "ecosystem": "npm"}
+        if dev:
+            dep["dev"] = True
+        pack.dependencies.append(dep)
+
+
 def build_context_pack(repo_path: Path) -> ProjectContextPack:
     repo_path = Path(repo_path).resolve()
     baseline = scan_repo_baseline(repo_path)
@@ -35,13 +47,14 @@ 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")
+            _append_npm_dependencies(pack, data.get("dependencies"))
+            _append_npm_dependencies(pack, data.get("devDependencies"), dev=True)
         except (ValueError, OSError):
             pass
 
@@ -76,6 +89,25 @@ def to_json(pack: ProjectContextPack) -> str:
     return json.dumps(asdict(pack), indent=2, ensure_ascii=False)
 
 
+_DEP_DISPLAY_CAP = 20
+
+
+def _dependencies_markdown(dependencies: list) -> str:
+    """Itemize dependencies (name, version, ecosystem, dev flag), capped to keep the seed small."""
+    if not dependencies:
+        return "- dependencies (0): none\n"
+    lines = [f"- dependencies ({len(dependencies)}):\n"]
+    for dep in dependencies[:_DEP_DISPLAY_CAP]:
+        label = " ".join(part for part in (dep.get("name", ""), dep.get("version", "")) if part)
+        ecosystem = dep.get("ecosystem", "")
+        suffix = f"{ecosystem}, dev" if dep.get("dev") else ecosystem
+        lines.append(f"  - {label} ({suffix})\n")
+    hidden = len(dependencies) - _DEP_DISPLAY_CAP
+    if hidden > 0:
+        lines.append(f"  - … and {hidden} more\n")
+    return "".join(lines)
+
+
 def to_markdown(pack: ProjectContextPack) -> str:
     return (
         "# Project Context Pack\n\n"
@@ -85,7 +117,7 @@ def to_markdown(pack: ProjectContextPack) -> str:
         f"- test_commands: {pack.test_commands or 'none'}\n"
         f"- entrypoints: {pack.entrypoints or 'none'}\n"
         f"- config_files: {pack.config_files or 'none'}\n"
-        f"- dependencies: {len(pack.dependencies)} found\n"
+        f"{_dependencies_markdown(pack.dependencies)}"
         f"- source_dirs: {pack.source_dirs}\n"
     )
 

package/tools/workflow_cli/gates.py

@@ -290,14 +290,6 @@ def _find_next_plan_task_field_start(task_body: str, after: int) -> int | None:
     return None
 
 
-def _plan_task_field_value(task_body: str, field: str) -> str:
-    found = _find_plan_task_field(task_body, field)
-    if found is None:
-        return ""
-    match, _ = found
-    return match.group(1).strip()
-
-
 def _iter_plan_task_bodies(content: str):
     return heading_bounded_bodies(content, _PLAN_TASK_RE.match)
 
@@ -496,8 +488,10 @@ def _check_spec_refs_valid(run_dir: Path, content: str) -> list[str]:
 
 
 # R10: Change Type is a closed operation-kind enum; 'new' is a legacy alias.
-_CHANGE_TYPE_VALUES = frozenset({"create", "modify", "delete"})
+_FILE_CHANGE_TYPES = frozenset({"create", "modify", "delete"})
+_CHANGE_TYPE_VALUES = _FILE_CHANGE_TYPES | {"non_code"}
 _CHANGE_TYPE_ALIASES = {"new": "create"}
+_TDD_APPLICABLE_VALUES = frozenset({"yes", "no"})
 
 
 def _normalized_change_type(raw: str) -> str:
@@ -510,6 +504,11 @@ def _task_change_type(body: str) -> str:
     return " ".join(_plan_task_field_body(body, "Change Type").split())
 
 
+def _task_tdd_applicable(body: str) -> str:
+    """Whitespace-normalized TDD Applicable field body (same line + continuation lines)."""
+    return " ".join(_plan_task_field_body(body, "TDD Applicable").split())
+
+
 def _check_plan_task_fields(content: str) -> list[str]:
     issues: list[str] = []
     numbers: list[int] = []
@@ -523,10 +522,32 @@ def _check_plan_task_fields(content: str) -> list[str]:
             if not _plan_task_field_body(body, field).strip():
                 issues.append(f"{label} is missing a non-empty '{field}:' field.")
         raw_change_type = _task_change_type(body)
-        if raw_change_type and _normalized_change_type(raw_change_type) not in _CHANGE_TYPE_VALUES:
+        change_type = _normalized_change_type(raw_change_type)
+        if raw_change_type and change_type not in _CHANGE_TYPE_VALUES:
             issues.append(
                 f"{label} has invalid 'Change Type: {raw_change_type}'; "
-                "allowed: create|modify|delete (alias: new = create)."
+                "allowed: create|modify|delete|non_code (alias: new = create)."
+            )
+        # R16: Change Type and Files must agree — file-op types need a real
+        # path; non_code is the only legal shape for no-file tasks.
+        files_body = _plan_task_field_body(body, "Files")
+        if files_body.strip():
+            file_paths = _plan_task_file_paths(files_body)
+            if change_type in _FILE_CHANGE_TYPES and not file_paths:
+                issues.append(
+                    f"{label} has 'Change Type: {raw_change_type}' but 'Files:' lists "
+                    "no real file path; use 'Change Type: non_code' for tasks that "
+                    "touch no files."
+                )
+            elif change_type == "non_code" and file_paths:
+                issues.append(
+                    f"{label} has 'Change Type: non_code' but 'Files:' lists a file path; "
+                    "use create|modify|delete for file-touching tasks."
+                )
+        raw_tdd = _task_tdd_applicable(body)
+        if raw_tdd and raw_tdd.lower() not in _TDD_APPLICABLE_VALUES:
+            issues.append(
+                f"{label} has invalid 'TDD Applicable: {raw_tdd}'; allowed: yes|no."
             )
     if numbers:
         if len(set(numbers)) != len(numbers):
@@ -575,8 +596,7 @@ def _plan_tasks_missing_code(content: str) -> bool:
         return False
     for body in bodies:
         skeleton = _plan_task_field_body(body, "Skeleton")
-        tdd_applicable = _plan_task_field_value(body, "TDD Applicable")
-        if tdd_applicable.lower() == "yes" and not _has_complete_code_fence(skeleton):
+        if _task_tdd_applicable(body).lower() == "yes" and not _has_complete_code_fence(skeleton):
             return True
     return False
 

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.2"