@xenonbyte/req-2-plan 0.3.0 → 0.4.1

package/README.md

@@ -67,13 +67,34 @@ 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"     # start a workflow run
-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
 ```
 
+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).
+
 ### Lifecycle commands
 
 Install all platforms, one platform, or a comma-separated list:
@@ -167,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,13 +61,31 @@ r2p help
 
 ### Quick start
 
+先在终端用生命周期 CLI 安装平台技能并确认安装结果：
+
 ```bash
-r2p install                       # 安装全部平台（默认）
-r2p-start "Add rate limiting"     # 启动一次工作流
-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                                   # 逐阶段推进
 ```
 
+需求可以是内联文本，也可以用 `--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` 可执行文件）。
+
 ### Lifecycle commands
 
 安装全部平台、单个平台，或逗号分隔的列表：
@@ -153,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.3.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

@@ -13,16 +13,18 @@ Run each via Bash using the scripts in `{{R2P_BIN_DIR}}`:
 
 | Command | Purpose |
 |---|---|
-| `{{R2P_BIN_DIR}}/r2p-start [--separate] ("<requirement>" \| --file <path>)` | Start a new workflow run |
+| `{{R2P_BIN_DIR}}/r2p-start [--separate] [--repo-path <dir>] ("<requirement>" \| --file <path>)` | Start a new workflow run; `--repo-path` grounds tier estimation and the Context Pack in real repo facts |
 | `{{R2P_BIN_DIR}}/r2p-continue` | Continue the active run |
 | `{{R2P_BIN_DIR}}/r2p-tier-lock --work-id <id> --base <light\|standard> --confirm` | Lock the tier for a run |
 | `{{R2P_BIN_DIR}}/r2p-status [--all]` | Inspect run state (read-only) |
 | `{{R2P_BIN_DIR}}/r2p-switch --work-id <id>` | Switch active run pointer |
 | `{{R2P_BIN_DIR}}/r2p-reopen --from <work-id> --stage <stage> --reason "<text>"` | Reopen a closed run |
+| `{{R2P_BIN_DIR}}/r2p-gap-open --work-id <id> --owner-stage <stage> --required-action "<text>"` | Route an upstream gap back to its owner stage |
+| `{{R2P_BIN_DIR}}/r2p-gap-resolve --work-id <id> --route-id <route-id>` | Resolve an open upstream-gap route after the owner stage re-passes gate-quality |
 
 ## Usage Pattern
 
-1. `r2p-start ("<requirement>" | --file <path>)` — start a new run
+1. `r2p-start [--repo-path <dir>] ("<requirement>" | --file <path>)` — start a new run; pass `--repo-path` when the requirement targets an existing repo
 2. `r2p-continue` — repeatedly; runs safe automatic steps, stops and suggests the next command when a human action is needed
    - Stops at: tier not locked, needs stage artifact content, needs stage ready mark, needs human checkpoint approval, entry gate failed, needs repair (Quality Gate failed or changes requested)
    - When stopped at `needs_content` or `needs_repair`, write the required artifact content into the printed `content_file`, then run the printed `next:` command exactly
@@ -31,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/gates.py

@@ -22,6 +22,7 @@ from tools.workflow_cli.models import (
 )
 from tools.workflow_cli.markdown import (
     heading_bounded_bodies,
+    heading_level,
     strip_readonly_sections,
     unfenced_markdown_lines,
     unfenced_markdown_text,
@@ -342,6 +343,13 @@ def _plan_task_path_part(raw_path: str) -> str:
     return _strip_markdown_path_wrappers(value.split("::")[0])
 
 
+_NO_FILE_SENTINELS = frozenset({"n/a"})
+
+
+def _is_no_file_sentinel(path_part: str) -> bool:
+    return path_part.strip().lower() in _NO_FILE_SENTINELS
+
+
 def _plan_task_file_paths(files_field: str) -> list[str]:
     paths: list[str] = []
     lines = [line for line, _, _ in unfenced_markdown_lines(files_field)]
@@ -352,7 +360,7 @@ def _plan_task_file_paths(files_field: str) -> list[str]:
     if first:
         raw_path = first[2:].strip() if first.startswith(("- ", "* ")) else first
         path_part = _plan_task_path_part(raw_path)
-        if path_part:
+        if path_part and not _is_no_file_sentinel(path_part):
             paths.append(path_part)
 
     for line in lines[1:]:
@@ -360,29 +368,84 @@ def _plan_task_file_paths(files_field: str) -> list[str]:
         if not stripped.startswith(("- ", "* ")):
             continue
         path_part = _plan_task_path_part(stripped[2:])
-        if path_part:
+        if path_part and not _is_no_file_sentinel(path_part):
             paths.append(path_part)
     return paths
 
 
-def _check_plan_file_refs(run_dir: Path, content: str) -> list[str]:
-    """Hard-check Files paths against the Context Pack repo_root. create-type tasks
-    are exempt; the part after '::' (a symbol) is advisory and not checked (no AST pack yet)."""
+def _context_pack_repo_root(run_dir: Path) -> Path | None:
+    """Usable Context Pack repo_root, or None when the pack is missing,
+    unreadable, invalid JSON, lacks repo_root, or does not point at an existing directory."""
     import json
     pack_json = run_dir / "02-project-context.json"
     if not pack_json.exists():
-        return []  # no ground truth -> advisory only
+        return None
     try:
-        repo_root = Path(json.loads(pack_json.read_text(encoding="utf-8")).get("repo_root", ""))
+        decoded = json.loads(pack_json.read_text(encoding="utf-8"))
     except (ValueError, OSError):
+        return None
+    if not isinstance(decoded, dict):
+        return None
+    raw = decoded.get("repo_root", "")
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    repo_root = Path(raw)
+    if not repo_root.is_dir():
+        return None
+    return repo_root.resolve()
+
+
+def _python_executable() -> str:
+    import shutil
+    import sys
+    if sys.executable:
+        return sys.executable
+    return "python3" if shutil.which("python3") else "python"
+
+
+def _context_pack_remediation_command(run_dir: Path) -> str:
+    import shlex
+    package_root = Path(__file__).resolve().parents[2]
+    pythonpath = f"PYTHONPATH={shlex.quote(str(package_root))}${{PYTHONPATH:+:$PYTHONPATH}}"
+    command = (
+        f"{pythonpath} {shlex.quote(_python_executable())} -m tools.workflow_cli "
+        f"context-build --work-id {run_dir.name}"
+    )
+    if run_dir.parent.name == ".req-to-plan":
+        base_dir = run_dir.parent.parent
+        try:
+            command += f" --base-path {shlex.quote(str(base_dir.resolve()))}"
+        except (OSError, RuntimeError):
+            # Path resolution failed (for example, a symlink loop).
+            command += " --base-path <base-dir>"
+    return command + " --repo-path <repo-dir>"
+
+
+def _check_plan_context_pack(run_dir: Path) -> list[str]:
+    """R11: standard-tier PLAN must anchor file facts to a usable Context Pack.
+
+    Every no-usable-truth-anchor path blocks loudly; after the user replaces
+    <repo-dir>, the remediation command can import the installed workflow modules.
+    """
+    if _context_pack_repo_root(run_dir) is not None:
         return []
-    if not repo_root or not repo_root.exists():
-        return []
-    repo_root = repo_root.resolve()
+    return [
+        "Standard-tier PLAN requires a usable Project Context Pack: "
+        "02-project-context.json is missing, unreadable, invalid, or its "
+        "repo_root is unavailable. Build it with: "
+        f"{_context_pack_remediation_command(run_dir)}"
+    ]
+
+
+def _check_plan_file_refs(run_dir: Path, content: str) -> list[str]:
+    """Hard-check Files paths against the Context Pack repo_root. create-type tasks
+    are exempt; the part after '::' (a symbol) is advisory and not checked (no AST pack yet)."""
+    repo_root = _context_pack_repo_root(run_dir)
+    if repo_root is None:
+        return []  # no usable ground truth; standard tier blocks via _check_plan_context_pack
     issues: list[str] = []
     for body in _iter_plan_task_bodies(content):
-        change_type = _plan_task_field_value(body, "Change Type").strip().lower()
-        skip_missing_path = change_type == "create"
+        skip_missing_path = _normalized_change_type(_task_change_type(body)) == "create"
         files_field = _plan_task_field_body(body, "Files")
         for path_part in _plan_task_file_paths(files_field):
             path = Path(path_part)
@@ -432,6 +495,21 @@ def _check_spec_refs_valid(run_dir: Path, content: str) -> list[str]:
     return issues
 
 
+# R10: Change Type is a closed operation-kind enum; 'new' is a legacy alias.
+_CHANGE_TYPE_VALUES = frozenset({"create", "modify", "delete"})
+_CHANGE_TYPE_ALIASES = {"new": "create"}
+
+
+def _normalized_change_type(raw: str) -> str:
+    value = raw.strip().lower()
+    return _CHANGE_TYPE_ALIASES.get(value, value)
+
+
+def _task_change_type(body: str) -> str:
+    """Whitespace-normalized Change Type field body (same line + continuation lines)."""
+    return " ".join(_plan_task_field_body(body, "Change Type").split())
+
+
 def _check_plan_task_fields(content: str) -> list[str]:
     issues: list[str] = []
     numbers: list[int] = []
@@ -444,6 +522,12 @@ def _check_plan_task_fields(content: str) -> list[str]:
         for field in PLAN_TASK_FIELDS:
             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:
+            issues.append(
+                f"{label} has invalid 'Change Type: {raw_change_type}'; "
+                "allowed: create|modify|delete (alias: new = create)."
+            )
     if numbers:
         if len(set(numbers)) != len(numbers):
             issues.append("PLAN-TASK numbers must be unique.")
@@ -509,23 +593,36 @@ def _check_plan_task_skeleton_placeholders(content: str) -> list[str]:
     return issues
 
 
-def _section_body(content: str, heading: str) -> str:
-    """Return the text of the section under `heading`, stopping at the next same-or-higher heading."""
+def _section_bodies(content: str, heading: str) -> list[str]:
+    """Return all bodies under `heading`, each stopping at the next same-or-higher heading."""
     level = len(heading) - len(heading.lstrip("#"))
-    out, capture = [], False
+    bodies: list[str] = []
+    out: list[str] | None = None
     for line, _, _ in unfenced_markdown_lines(content):
         if line.strip() == heading:
-            capture = True
+            if out is not None:
+                bodies.append("\n".join(out))
+            out = []
             continue
-        if capture:
+        if out is not None:
             stripped = line.lstrip()
             if stripped.startswith("#"):
                 # Count hashes of this line's heading
                 line_level = len(stripped) - len(stripped.lstrip("#"))
                 if line_level <= level:
-                    break
+                    bodies.append("\n".join(out))
+                    out = None
+                    continue
             out.append(line.rstrip("\r\n"))
-    return "\n".join(out)
+    if out is not None:
+        bodies.append("\n".join(out))
+    return bodies
+
+
+def _section_body(content: str, heading: str) -> str:
+    """Return the first section body under `heading`, stopping at the next same-or-higher heading."""
+    bodies = _section_bodies(content, heading)
+    return bodies[0] if bodies else ""
 
 
 def _section_entries_missing_id(content: str, heading: str, id_prefix: str) -> list[str]:
@@ -571,6 +668,132 @@ def _check_elicitation(stage: Stage, tier: TierEstimate, content: str) -> list[s
     return ["Standard-tier brief must record at least one assumption or open question (R8 elicitation)."]
 
 
+# R12: decision-request lifecycle vocabulary. The gate owns ONLY the Status
+# lifecycle (enum, line presence, section non-emptiness, Selected/Rationale
+# when selected); Question/Options/Recommended are template guidance enforced
+# at checkpoint, not here (Agent/CLI boundary).
+_DECISION_SECTION = "## Decision Requests"
+_DECISION_BLOCK_RE = re.compile(r"^###\s+(DECISION-\d+)\b")
+_DECISION_NESTED_MARKER_RE = re.compile(
+    r"^(?:#{1,6}\s+|[-*]\s+(?:\[[ xX]\]\s+)?|(?:\[[ xX]\]\s+)?)DECISION-\d+\b"
+)
+_DECISION_STATUS_VALUES = frozenset({"pending", "selected"})
+
+
+def _decision_field_value(block_lines: list[str], field: str) -> str | None:
+    """Value of a `Field:` line within a DECISION block; None when absent."""
+    field_re = re.compile(rf"^{re.escape(field)}:\s*(.*)$")
+    for line in block_lines:
+        m = field_re.match(line.strip())
+        if m:
+            return m.group(1).strip()
+    return None
+
+
+def _decision_field_count(block_lines: list[str], field: str) -> int:
+    field_re = re.compile(rf"^{re.escape(field)}:")
+    return sum(1 for line in block_lines if field_re.match(line.strip()))
+
+
+def _check_decision_requests(stage: Stage, tier: TierEstimate, content: str) -> list[str]:
+    """R12: standard DESIGN must list pending human decisions or state `none`."""
+    from tools.workflow_cli.models import TierBase
+    if stage != Stage.DESIGN or tier.base != TierBase.STANDARD:
+        return []
+    blocks: list[tuple[str, list[str]]] = []
+    stray: list[str] = []
+    for section_body in _section_bodies(content, _DECISION_SECTION):
+        lines = section_body.splitlines()
+        starts = [
+            (i, m)
+            for i, line in enumerate(lines)
+            if (m := _DECISION_BLOCK_RE.match(line.strip()))
+        ]
+        covered: set[int] = set()
+        for start, match in starts:
+            end = len(lines)
+            for j in range(start + 1, len(lines)):
+                if heading_level(lines[j]) is not None:
+                    end = j
+                    break
+            decision_id = match.group(1)
+            blocks.append((decision_id, lines[start + 1:end]))
+            covered.update(range(start, end))
+        stray.extend(
+            line.strip()
+            for i, line in enumerate(lines)
+            if i not in covered and line.strip() and not line.strip().startswith("<!--")
+        )
+
+    issues: list[str] = []
+    if not blocks:
+        if stray == ["none"]:
+            return []
+        if not stray:
+            issues.append(
+                "## Decision Requests is empty; state exactly `none` or list "
+                "`### DECISION-NNN` blocks (R12)."
+            )
+        else:
+            issues.append(
+                "## Decision Requests must be exactly `none` (sole non-comment "
+                "content) or `### DECISION-NNN` blocks (R12)."
+            )
+        return issues
+    if stray:
+        if "none" in stray:
+            issues.append(
+                "## Decision Requests mixes `none` with DECISION blocks; keep one (R12)."
+            )
+        else:
+            issues.append(
+                "## Decision Requests contains non-comment prose outside DECISION blocks; "
+                "use exactly `none` or `### DECISION-NNN` blocks (R12)."
+            )
+    for dup_id, count in Counter(decision_id for decision_id, _ in blocks).items():
+        if count > 1:
+            issues.append(
+                f"Duplicate decision id {dup_id}; each DECISION-NNN must be unique (R12)."
+            )
+    for decision_id, body in blocks:
+        for line in body:
+            if _DECISION_NESTED_MARKER_RE.match(line.strip()):
+                issues.append(
+                    f"{decision_id} body contains a nested 'DECISION-NNN' marker; "
+                    "each decision must be its own '### DECISION-NNN' block (R12)."
+                )
+                break
+        if _decision_field_count(body, "Status") > 1:
+            issues.append(
+                f"{decision_id} has multiple 'Status:' lines; keep exactly one (R12)."
+            )
+            continue
+        status = _decision_field_value(body, "Status")
+        if status is None:
+            issues.append(
+                f"{decision_id} is missing a 'Status:' line; allowed: pending|selected (R12)."
+            )
+            continue
+        if status.lower() not in _DECISION_STATUS_VALUES:
+            issues.append(
+                f"{decision_id} has invalid 'Status: {status}'; allowed: pending|selected (R12)."
+            )
+            continue
+        if status.lower() == "pending":
+            issues.append(
+                f"Unresolved decision request {decision_id} (Status: pending); "
+                "a human must choose before this gate can pass (R12)."
+            )
+            continue
+        for field in ("Selected", "Rationale"):
+            if not (_decision_field_value(body, field) or "").strip():
+                issues.append(
+                    f"{decision_id} is 'Status: selected' but missing a non-empty "
+                    f"'{field}:' line (R12)."
+                )
+    return issues
+
+
 def _check_scope_freeze(stage: Stage, content: str) -> list[str]:
     """R8: brief's In/Out-of-Scope must carry stable IDs so trace can anchor them."""
     if stage != Stage.REQUIREMENT_BRIEF:
@@ -714,9 +937,12 @@ def check_quality_gate(
                 f"Duplicate ID definition {dup_id!r} found in artifact; each ID must be unique."
             )
 
-        # Check 5 (PLAN, standard tier): TDD-applicable tasks must carry a code block.
+        # Check 5 (PLAN, standard tier): usable Context Pack required (R11);
+        # TDD-applicable tasks must carry a code block.
         from tools.workflow_cli.models import TierBase
         if stage == Stage.PLAN and tier.base == TierBase.STANDARD:
+            # R11: a usable Context Pack is the truth anchor for file-ref checks.
+            issues.extend(_check_plan_context_pack(run_dir))
             if not _plan_task_starts(gate_content):
                 issues.append(
                     "PLAN is missing '### PLAN-TASK-*' sections; standard tier requires "
@@ -762,6 +988,9 @@ def check_quality_gate(
         # Check 9 (R8): elicitation — standard-tier brief must record at least one assumption or open question.
         issues.extend(_check_elicitation(stage, tier, gate_content))
 
+        # Check 10 (R12): standard DESIGN must resolve decision requests.
+        issues.extend(_check_decision_requests(stage, tier, gate_content))
+
     return GateResult(
         passed=len(issues) == 0,
         issues=issues,

package/tools/workflow_cli/stage_schema.py

@@ -33,8 +33,8 @@ STAGE_SCHEMA: dict = {
         TierBase.LIGHT: ["## Design Summary", "## Chosen Design", "## SPEC Handoff"],
         TierBase.STANDARD: [
             "## Design Summary", "## Current Code Evidence", "## Requirements Coverage",
-            "## Options Considered", "## Chosen Design", "## Rollback",
-            "## Observability", "## SPEC Handoff",
+            "## Options Considered", "## Chosen Design", "## Decision Requests",
+            "## Rollback", "## Observability", "## SPEC Handoff",
         ],
     },
     Stage.SPEC: {

package/tools/workflow_cli/stage_templates.py

@@ -22,6 +22,17 @@ _HEADING_BODY = {
     (Stage.REQUIREMENT_BRIEF, "## Out-of-Scope"): "- SCOPE-OUT-001 <!-- fill in -->\n",
     (Stage.RISK_DISCOVERY, "## Risks"): "### RISK-SEC-001 <!-- fill in -->\nStatus: <!-- fill in -->\n",
     (Stage.DESIGN, "## Chosen Design"): "### DES-ARCH-001 <!-- fill in -->\n",
+    (Stage.DESIGN, "## Decision Requests"): (
+        "<!-- fill in -->\n"
+        "<!-- Write exactly `none` when no human decision is needed; otherwise list one `### DECISION-NNN` block per choice (fenced example below; keep guidance comments single-line). -->\n"
+        "```text\n"
+        "### DECISION-001 <short title>\n"
+        "Question: <what must a human choose?>\n"
+        "Options: A) ... / B) ...\n"
+        "Recommended: A\n"
+        "Status: pending\n"
+        "```\n"
+    ),
     (Stage.SPEC, "## Behavior Contracts"): "### SPEC-BEHAVIOR-001 <!-- fill in -->\n",
     (Stage.PLAN, "## Tasks"): (
         "### PLAN-TASK-001 <!-- fill in -->\n"

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
@@ -200,17 +203,72 @@ def spec_ids_not_consumed(run_dir: Path) -> list[str]:
                   if id_.startswith("SPEC-") and id_ not in consumed)
 
 
+_NON_GOALS_TITLE = "non-goals"
+
+
+def _strip_nested_non_goals(block: str) -> str:
+    """Remove Non-goals subsections nested inside a SPEC block (R9).
+
+    Only headings deeper than the block's own heading qualify; an exempt
+    subsection runs to the next same-or-higher heading, so a later sibling
+    section still counts toward scope-overflow scanning. The document-level
+    `## Non-goals` never enters a SPEC block (see `_heading_blocks`), so it
+    needs no handling here.
+    """
+    headings: list[tuple[int, int, bool]] = []  # (offset, level, is_non_goals)
+    block_level: int | None = None
+    offset = 0
+    for line in block.splitlines(keepends=True):
+        level = heading_level(line)
+        if level is not None:
+            if block_level is None:
+                block_level = level  # the SPEC block's own heading
+            else:
+                title = line.strip().strip("#").strip().lower()
+                headings.append((offset, level, title == _NON_GOALS_TITLE))
+        offset += len(line)
+    removals: list[tuple[int, int]] = []
+    for i, (start, level, is_non_goals) in enumerate(headings):
+        if not is_non_goals or (block_level is not None and level <= block_level):
+            continue
+        end = len(block)
+        for next_start, next_level, _ in headings[i + 1:]:
+            if next_level <= level:
+                end = next_start
+                break
+        removals.append((start, end))
+    pieces: list[str] = []
+    cursor = 0
+    for start, end in removals:
+        if start < cursor:
+            continue  # nested inside an already-removed Non-goals section
+        pieces.append(block[cursor:start])
+        cursor = end
+    pieces.append(block[cursor:])
+    return "".join(pieces)
+
+
 def scope_out_violations(run_dir: Path) -> list[str]:
-    """SCOPE-OUT-* ids that executable PLAN-TASK bodies reference — a scope overflow (R8)."""
+    """SCOPE-OUT-* ids that PLAN-TASK bodies reference, directly or via a
+    consumed SPEC block — a scope overflow (R8/R9). Non-goals subsections
+    nested inside a consumed SPEC block are exempt (legitimate exclusion
+    declarations)."""
     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))
-    return sorted(
-        {
+    violations = {
+        m.group(0)
+        for m in _ID_RE.finditer(plan_task_text)
+        if m.group(0).startswith("SCOPE-OUT-")
+    }
+    spec_blocks = _spec_blocks(_artifact_text(run_dir, Stage.SPEC))
+    for spec_id in plan_consumed_spec_ids(run_dir):
+        scanned = _strip_nested_non_goals(spec_blocks.get(spec_id, ""))
+        violations.update(
             m.group(0)
-            for m in _ID_RE.finditer(plan_task_text)
+            for m in _ID_RE.finditer(scanned)
             if m.group(0).startswith("SCOPE-OUT-")
-        }
-    )
+        )
+    return sorted(violations)
 
 
 def check_trace_closure(run_dir: Path) -> list[str]:

package/tools/workflow_cli/version.py

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