@xenonbyte/req-2-plan 0.4.4 → 0.5.0

package/tools/workflow_cli/gates.py

@@ -6,7 +6,10 @@ The Agent handles semantic quality; this module handles structural validation.
 """
 from __future__ import annotations
 
+import errno
+import os
 import re
+import stat
 from collections import Counter
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -23,6 +26,8 @@ from tools.workflow_cli.models import (
 from tools.workflow_cli.markdown import (
     heading_bounded_bodies,
     heading_level,
+    plan_task_anchors,
+    PLAN_TASK_ANCHOR_RE as _PLAN_TASK_RE,
     strip_readonly_sections,
     unfenced_markdown_lines,
     unfenced_markdown_text,
@@ -91,7 +96,7 @@ def check_entry_gate(
 # Upstream ID reference pattern
 # ---------------------------------------------------------------------------
 
-_FILL_IN_PLACEHOLDER_RE = re.compile(r"<!--\s*fill in\s*-->", re.IGNORECASE)
+_FILL_IN_PLACEHOLDER_RE = re.compile(r"<!--\s*fill in(?:\s*:.*?)?\s*-->", re.IGNORECASE)
 
 _PLACEHOLDER_PATTERNS = [
     _FILL_IN_PLACEHOLDER_RE,                              # untouched template body
@@ -103,6 +108,9 @@ _PLACEHOLDER_PATTERNS = [
     re.compile(
         r"(?im)^\s*(?:[-*]\s*)?(?:[A-Za-z][A-Za-z0-9 /_-]*:\s*)?FIXME\s*$"
     ),                                                     # FIXME as a placeholder line/field, not prose
+    re.compile(r"\?{3,}"),                                  # ??? unresolved marker
+    re.compile(r"待定"),                                     # zh: undecided / pending
+    re.compile(r"(?i)\bto be (?:decided|determined)\b"),    # english placeholder phrase
 ]
 
 # IDs that represent upstream references: REQ-*, RISK-*, DES-*, SPEC-*
@@ -249,7 +257,6 @@ def _has_external_docs_inventory(content: str) -> bool:
 # PLAN code-block gate helpers
 # ---------------------------------------------------------------------------
 
-_PLAN_TASK_RE = re.compile(r"^### PLAN-TASK-\d+", re.MULTILINE)
 _CODE_FENCE_LINE_RE = re.compile(r"^[ \t]{0,3}(`{3,}|~{3,})(.*)$")
 _INLINE_CODE_VALUE_RE = re.compile(r"^(`+)(.*?)\1$", re.DOTALL)
 _MARKDOWN_LINK_VALUE_RE = re.compile(r"^\[([^\]]+)\]\([^)]+\)$")
@@ -621,6 +628,19 @@ def _check_plan_task_skeleton_placeholders(content: str) -> list[str]:
     return issues
 
 
+def _check_plan_task_verification_placeholders(content: str) -> list[str]:
+    issues: list[str] = []
+    for body in _iter_plan_task_bodies(content):
+        verification = _plan_task_field_body(body, "Verification")
+        if verification.strip() and any(p.search(verification) for p in _PLACEHOLDER_PATTERNS):
+            issues.append(
+                f"{_plan_task_label(body)} Verification contains an unresolved "
+                "placeholder; replace it with an objective pass/fail check "
+                "(command + expected result) before passing the gate."
+            )
+    return issues
+
+
 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("#"))
@@ -994,6 +1014,8 @@ def check_quality_gate(
             issues.extend(_check_spec_refs_valid(run_dir, gate_content))
             # R5.2b: Skeleton is fenced, so detect template placeholders there explicitly.
             issues.extend(_check_plan_task_skeleton_placeholders(gate_content))
+            # R5.2c: Verification must be an objective check, not a placeholder.
+            issues.extend(_check_plan_task_verification_placeholders(gate_content))
             # R5.3: file refs vs Context Pack repo_root
             issues.extend(_check_plan_file_refs(run_dir, gate_content))
 
@@ -1086,3 +1108,128 @@ def check_forced_subagent_review(
         ],
         exit_code=5,
     )
+
+
+# ---------------------------------------------------------------------------
+# Execution Completion Gate
+# ---------------------------------------------------------------------------
+
+_LEDGER_UNCHECKED_RE = re.compile(r"^\s*-\s*\[\s*\]\s*(PLAN-TASK-\d+)\b")
+_LEDGER_CHECKED_RE = re.compile(r"^\s*-\s*\[[xX]\]\s*(PLAN-TASK-\d+)\b")
+
+
+def _read_regular_text_no_symlink(path: Path) -> tuple[str | None, str | None]:
+    """Read a regular file without following a symlink where the OS supports it."""
+    if path.parent.is_symlink() or path.is_symlink():
+        return None, "symlink"
+    # O_NONBLOCK so opening a non-regular file (e.g. a writerless FIFO) returns
+    # immediately and is rejected by the S_ISREG check below instead of blocking.
+    # It has no effect on regular-file reads.
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+    fd: int | None = None
+    try:
+        fd = os.open(path, flags)
+        mode = os.fstat(fd).st_mode
+        if not stat.S_ISREG(mode):
+            return None, "not_regular"
+        with os.fdopen(fd, "r", encoding="utf-8") as fh:
+            fd = None
+            return fh.read(), None
+    except FileNotFoundError:
+        return None, "missing"
+    except OSError as exc:
+        if exc.errno == errno.ELOOP:
+            return None, "symlink"
+        raise
+    finally:
+        if fd is not None:
+            os.close(fd)
+
+
+def _plan_task_ids(run_dir: Path) -> list[str]:
+    """Task IDs declared in the frozen PLAN artifact."""
+    from tools.workflow_cli.artifact import read_artifact
+    plan_text = read_artifact(run_dir, Stage.PLAN)
+    return [tid for tid, _ in plan_task_anchors(strip_readonly_sections(plan_text))]
+
+
+def check_execution_complete(run_dir: Path) -> GateResult:
+    """Completion gate for archiving an EXECUTING run.
+
+    The execution ledger (execution/progress.md, seeded by run-execute-start)
+    is the structural evidence that every PLAN-TASK was implemented. Archiving
+    an executing run requires the ledger to exist and report every task done:
+
+    - missing ledger              -> fail (execution never recorded progress)
+    - any `- [ ] PLAN-TASK-*`     -> fail (unfinished tasks remain)
+    - a frozen PLAN task with no   -> fail (truncated ledger dropped a task line
+      `- [x] PLAN-TASK-*` line             instead of completing it)
+    - no `- [x] PLAN-TASK-*` at all -> fail (cleared/empty ledger asserts nothing)
+
+    This is structural validation only: it trusts the agent's checkbox flips
+    (an audit gate, not a correctness gate). The CLI offers --force to override.
+    """
+    ledger = run_dir / "execution" / "progress.md"
+    ledger_text, ledger_error = _read_regular_text_no_symlink(ledger)
+    if ledger_error == "missing":
+        return GateResult(
+            passed=False,
+            issues=[
+                "Execution ledger execution/progress.md is missing; cannot "
+                "confirm the PLAN was executed."
+            ],
+            exit_code=EXIT_GATE_FAIL,
+        )
+    if ledger_error == "symlink":
+        return GateResult(
+            passed=False,
+            issues=[
+                "Execution ledger execution/progress.md is a symlink; refusing "
+                "to read outside the run directory."
+            ],
+            exit_code=EXIT_GATE_FAIL,
+        )
+    if ledger_error == "not_regular":
+        return GateResult(
+            passed=False,
+            issues=[
+                "Execution ledger execution/progress.md is not a regular file; "
+                "cannot confirm the PLAN was executed."
+            ],
+            exit_code=EXIT_GATE_FAIL,
+        )
+    assert ledger_text is not None
+    lines = [line for line, _, _ in unfenced_markdown_lines(ledger_text)]
+    issues: list[str] = []
+    for line in lines:
+        if _LEDGER_UNCHECKED_RE.match(line):
+            issues.append(f"Unfinished execution task: {line.strip()}")
+    if not issues:
+        checked_ids = {m.group(1) for line in lines if (m := _LEDGER_CHECKED_RE.match(line))}
+        # Cross-check the ledger against the frozen PLAN: every declared PLAN-TASK
+        # must be checked off, so a truncated ledger (a dropped task line) cannot
+        # pass as complete. Both inputs are CLI-owned artifacts; no new trust.
+        try:
+            plan_task_ids = _plan_task_ids(run_dir)
+        except FileNotFoundError:
+            issues.append(
+                "Frozen PLAN artifact 07-plan.md is missing; cannot cross-check "
+                "the execution ledger."
+            )
+        else:
+            for tid in plan_task_ids:
+                if tid not in checked_ids:
+                    issues.append(
+                        f"PLAN task {tid} is not marked complete in the execution ledger "
+                        "(its '- [x] PLAN-TASK-*' line is missing)."
+                    )
+        if not issues and not checked_ids:
+            issues.append(
+                "Execution ledger lists no completed PLAN-TASK entries "
+                "('- [x] PLAN-TASK-*'); nothing to confirm."
+            )
+    return GateResult(
+        passed=len(issues) == 0,
+        issues=issues,
+        exit_code=EXIT_GATE_FAIL if issues else 0,
+    )

package/tools/workflow_cli/install.py

@@ -1,7 +1,7 @@
 """
 InstallService — multi-platform install/uninstall for the r2p skill.
 
-Supports: claude, codex, gemini
+Supports: claude, codex, gemini, opencode
 """
 from __future__ import annotations
 
@@ -25,12 +25,13 @@ from tools.workflow_cli.version import R2P_VERSION
 
 SCHEMA_VERSION = 1
 
-SUPPORTED_PLATFORMS = ("claude", "codex", "gemini")
+SUPPORTED_PLATFORMS = ("claude", "codex", "gemini", "opencode")
 
 DEFAULT_PLATFORM_HOMES = {
     "claude": Path.home() / ".claude",
     "codex": Path.home() / ".codex",
     "gemini": Path.home() / ".gemini",
+    "opencode": Path.home() / ".config" / "opencode",
 }
 
 KNOWN_OBSOLETE_SHARED_WRAPPERS = frozenset({"r2p-adapt"})
@@ -177,6 +178,23 @@ class InstallService:
                         dest, content, backups, installed_paths, written, backup_dir
                     )
 
+            elif platform == "opencode":
+                # opencode custom commands use Markdown files with `description:`
+                # frontmatter and the filename as the command name. Reuse claude's
+                # command bodies, then inject opencode's argument placeholder so
+                # slash-command invocation args are not dropped.
+                cmd_dir = self._opencode_command_source()
+                for src in sorted(cmd_dir.glob("r2p-*.md")):
+                    dest = platform_home / "commands" / src.name
+                    content = _render_opencode_command(
+                        src.read_text(),
+                        R2P_VERSION,
+                        str(bin_dir),
+                    )
+                    self._write_managed_file(
+                        dest, content, backups, installed_paths, written, backup_dir
+                    )
+
             # Write manifest
             manifest: dict[str, Any] = {
                 "backups": backups,
@@ -188,7 +206,13 @@ class InstallService:
             }
             self._validate_install_path(manifest_path, field="manifest")
             manifest_path.parent.mkdir(parents=True, exist_ok=True)
-            manifest_path.write_text(_dump_manifest(manifest), encoding="utf-8")
+            tmp = manifest_path.with_name(manifest_path.name + ".tmp")
+            # The temp sibling shares the (validated) parent, but its own path is
+            # untrusted: reject a planted symlink so the atomic write cannot be
+            # redirected outside the manifest dir.
+            self._validate_install_path(tmp, field="manifest")
+            tmp.write_text(_dump_manifest(manifest), encoding="utf-8")
+            tmp.replace(manifest_path)
             manifest_written = True
 
             # Remove obsolete managed shared wrappers (e.g. a 0.1.2 r2p-adapt) that
@@ -556,9 +580,24 @@ class InstallService:
         elif platform == "gemini":
             for src in sorted((template_dir / "commands").glob("r2p-*.toml")):
                 targets.append(platform_home / "commands" / src.name)
+        elif platform == "opencode":
+            # opencode reuses claude's command templates (see install()).
+            for src in sorted(self._opencode_command_source().glob("r2p-*.md")):
+                targets.append(platform_home / "commands" / src.name)
 
         return targets
 
+    def _opencode_command_source(self) -> Path:
+        """Source dir for opencode commands, shared with claude to avoid drift."""
+        return (
+            self.repo_root
+            / "tools"
+            / "workflow_cli"
+            / "agent_templates"
+            / "claude"
+            / "commands"
+        )
+
     def _cleanup_obsolete_managed_wrappers(
         self, preserve_paths: set[str] | None = None
     ) -> None:
@@ -852,6 +891,20 @@ def _render(content: str, version: str, bin_dir: str) -> str:
     return content
 
 
+def _render_opencode_command(content: str, version: str, bin_dir: str) -> str:
+    """Render a Markdown command with opencode invocation arguments preserved."""
+    rendered = _render(content, version, bin_dir)
+    if "$ARGUMENTS" in rendered:
+        return rendered
+    return (
+        rendered.rstrip()
+        + "\n\n## opencode invocation arguments\n\n"
+        + "Use these arguments when running the wrapper above:\n\n"
+        + "```text\n$ARGUMENTS\n```\n\n"
+        + "If no arguments were supplied, follow the default usage.\n"
+    )
+
+
 def _render_bin_script(content: str, repo_root: Path) -> str:
     """Render an installed wrapper so it imports modules from the source repo."""
     return content.replace(

package/tools/workflow_cli/link_expander.py

@@ -2,14 +2,11 @@ from __future__ import annotations
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from urllib import request, error as urllib_error
 import re
 
 
 class LinkStatus(str, Enum):
-    REACHABLE = "reachable"
-    UNREACHABLE = "unreachable"
-    REQUIRES_AUTH = "requires_auth"
+    EXTERNAL = "external"  # http(s) link recorded as an external reference; not fetched
     LOCAL_FOUND = "local_found"
     LOCAL_MISSING = "local_missing"
 
@@ -45,20 +42,6 @@ def extract_links(text: str) -> list[str]:
     return result
 
 
-def _fetch_url(url: str) -> LinkExpansionResult:
-    try:
-        req = request.Request(url, headers={"User-Agent": "r2p-link-expander/1.0"})
-        with request.urlopen(req, timeout=5) as resp:
-            content = resp.read(500).decode("utf-8", errors="replace")
-            return LinkExpansionResult(url=url, status=LinkStatus.REACHABLE, content_preview=content)
-    except urllib_error.HTTPError as e:
-        if e.code in (401, 403):
-            return LinkExpansionResult(url=url, status=LinkStatus.REQUIRES_AUTH, error=str(e))
-        return LinkExpansionResult(url=url, status=LinkStatus.UNREACHABLE, error=str(e))
-    except Exception as e:
-        return LinkExpansionResult(url=url, status=LinkStatus.UNREACHABLE, error=str(e))
-
-
 def _local_preview_block_reason(path_str: str, candidate: Path, base: Path | None) -> str | None:
     try:
         relative = candidate.relative_to(base) if base is not None else Path(path_str)
@@ -109,8 +92,14 @@ def _expand_local(path_str: str, base_path: Path | None) -> LinkExpansionResult:
 def expand_links(
     text: str,
     base_path: Path | None = None,
-    fetch_urls: bool = True,
 ) -> list[LinkExpansionResult]:
+    """Expand links found in requirement text.
+
+    Local relative links are read for context. http(s) URLs are recorded as
+    external references only: r2p never makes outbound requests for URLs found in
+    (untrusted) requirement text, so a link cannot drive the tool to reach
+    cloud-metadata endpoints, localhost, or internal services.
+    """
     results = []
     links = extract_links(text)
     seen: set[str] = set()
@@ -119,12 +108,7 @@ def expand_links(
             continue
         seen.add(link)
         if link.startswith("http://") or link.startswith("https://"):
-            if fetch_urls:
-                results.append(_fetch_url(link))
-            else:
-                results.append(LinkExpansionResult(
-                    url=link, status=LinkStatus.UNREACHABLE, error="URL fetching disabled"
-                ))
+            results.append(LinkExpansionResult(url=link, status=LinkStatus.EXTERNAL))
         else:
             results.append(_expand_local(link, base_path))
     return results

package/tools/workflow_cli/markdown.py

@@ -130,6 +130,24 @@ def heading_level(line: str) -> int | None:
     return len(stripped) - len(stripped.lstrip("#"))
 
 
+# A PLAN-TASK anchor heading, e.g. "### PLAN-TASK-001: title". Single source of
+# truth shared by gates (task iteration) and cli (ledger seeding).
+PLAN_TASK_ANCHOR_RE = re.compile(r"^### PLAN-TASK-\d+", re.MULTILINE)
+_PLAN_TASK_ANCHOR_LINE_RE = re.compile(r"^###\s+(PLAN-TASK-\d+)\s*:?\s*(.*?)\s*$")
+
+
+def plan_task_anchors(content: str) -> list[tuple[str, str]]:
+    """Return (PLAN-TASK-NNN, title) for each task anchor outside code fences."""
+    anchors: list[tuple[str, str]] = []
+    for line, _, _ in unfenced_markdown_lines(content):
+        if not PLAN_TASK_ANCHOR_RE.match(line):
+            continue
+        m = _PLAN_TASK_ANCHOR_LINE_RE.match(line.rstrip("\n"))
+        if m:
+            anchors.append((m.group(1), m.group(2).strip()))
+    return anchors
+
+
 def heading_bounded_bodies(content: str, is_start):
     """Yield each section whose heading line satisfies `is_start(line)`.
 

package/tools/workflow_cli/models.py

@@ -31,6 +31,8 @@ class RunStatus(str, Enum):
     CHECKPOINT_APPROVED = "checkpoint_approved"
     NEXT_STAGE = "next_stage"
     CLOSED_AT_PLAN_CHECKPOINT = "closed_at_plan_checkpoint"
+    EXECUTING = "executing"     # PLAN closed; implementing tasks in place
+    ARCHIVED = "archived"       # terminal: requirement directory archived
 
 
 class Stage(str, Enum):
@@ -148,7 +150,13 @@ ALLOWED_TRANSITIONS: dict[RunStatus, set[RunStatus]] = {
         RunStatus.ACTIVE_STAGE_DRAFT,
         RunStatus.ENTRY_GATE_FAILED,
     },
-    RunStatus.CLOSED_AT_PLAN_CHECKPOINT: set(),
+    RunStatus.CLOSED_AT_PLAN_CHECKPOINT: {RunStatus.EXECUTING, RunStatus.ARCHIVED},
+    RunStatus.EXECUTING: {
+        RunStatus.EXECUTING,
+        RunStatus.CLOSED_AT_PLAN_CHECKPOINT,
+        RunStatus.ARCHIVED,
+    },
+    RunStatus.ARCHIVED: set(),
 }
 
 
@@ -268,8 +276,18 @@ ALLOWED_COMMANDS_BY_RUN_STATE: dict[RunStatus, set[str]] = {
     },
     RunStatus.CLOSED_AT_PLAN_CHECKPOINT: {
         "CMD-RUN-REOPEN",
+        "CMD-RUN-EXECUTE-START",
+        "CMD-RUN-ARCHIVE",
+        "CMD-TIER-STATUS",
+    },
+    RunStatus.EXECUTING: {
+        "CMD-RUN-REOPEN",
+        "CMD-RUN-ARCHIVE",
         "CMD-TIER-STATUS",
     },
+    # ARCHIVED is terminal: only the always-allowed read-only commands
+    # (see READ_ONLY_COMMANDS) remain reachable.
+    RunStatus.ARCHIVED: set(),
 }
 
 

package/tools/workflow_cli/stage_templates.py

@@ -47,7 +47,8 @@ _HEADING_BODY = {
         "```\n"
         "Steps:\n"
         "- [ ] <!-- fill in -->\n"
-        "Verification: <!-- fill in -->\n"
+        "Verification: <!-- fill in: objective pass/fail check (command + expected result), "
+        "e.g. `pytest tests/x.py::test_y` passes / `GET /foo` returns 429 when over limit -->\n"
     ),
 }
 

package/tools/workflow_cli/state.py

@@ -8,6 +8,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
+from tools.workflow_cli.atomic import atomic_write_text
 from tools.workflow_cli.models import (
     ActiveArtifact,
     BundleAuthorization,
@@ -227,11 +228,6 @@ def _escape_cell(val: str) -> str:
     return val.replace("\\", "\\\\").replace("|", "\\|")
 
 
-def _unescape_cell(val: str) -> str:
-    """Unescape backslashes and pipes in a parsed markdown table cell."""
-    return val.replace("\\|", "|").replace("\\\\", "\\")
-
-
 def _split_cells(row_text: str) -> list[str]:
     """Split pipe-delimited row, honouring \\| and \\\\ escape sequences."""
     cells: list[str] = []
@@ -608,7 +604,10 @@ class RunStateManager:
 
     def save(self, record: RunRecord) -> None:
         self.run_dir.mkdir(parents=True, exist_ok=True)
-        self.run_path.write_text(run_record_to_markdown(record), encoding="utf-8")
+        text = run_record_to_markdown(record)
+        # Atomic write: a crash mid-write must not leave a truncated run.md that
+        # bricks the run. Write a unique sibling temp then atomically replace.
+        atomic_write_text(self.run_path, text)
 
     def load(self) -> RunRecord:
         if not self.run_path.exists():

package/tools/workflow_cli/tier.py

@@ -106,7 +106,7 @@ def compute_floor(
         or repo.is_monorepo
         or repo.module_count > module_threshold
         or _has_multi_repo_refs(requirement_text)
-        or any(r.status in (LinkStatus.UNREACHABLE, LinkStatus.REQUIRES_AUTH) for r in link_results)
+        or any(r.status == LinkStatus.EXTERNAL for r in link_results)
     ):
         base = TierBase.STANDARD
 

package/tools/workflow_cli/version.py

@@ -1 +1 @@
-R2P_VERSION = "0.4.4"
+R2P_VERSION = "0.5.0"

package/tools/workflow_cli/workspace.py

@@ -0,0 +1,112 @@
+"""Workspace-level helpers for the `.req-to-plan/` directory.
+
+Neutral module imported by both cli.py and agent_shortcuts.py (it imports
+neither, so there is no cycle). Owns the workspace `.gitignore` and the
+path-limited git-commit primitive used by run-close (add) and run-archive
+(remove).
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from tools.workflow_cli.atomic import atomic_write_text
+
+_WORKSPACE_GITIGNORE_LINES = ("/archive", "/.workflow-active")
+
+
+def ensure_workspace_gitignore(base_path: Path) -> None:
+    """Ensure `<base>/.req-to-plan/.gitignore` ignores local workspace files.
+
+    Creates the file with required entries if absent; appends missing lines if
+    the file exists; no-op if already complete. Refuses symlinks so this helper
+    never reads external target contents into the workspace file.
+    """
+    r2p_dir = base_path / ".req-to-plan"
+    if r2p_dir.is_symlink():
+        raise ValueError("unsafe_workspace_dir_symlink")
+    r2p_dir.mkdir(parents=True, exist_ok=True)
+    if r2p_dir.is_symlink():
+        raise ValueError("unsafe_workspace_dir_symlink")
+    gitignore = r2p_dir / ".gitignore"
+    if gitignore.is_symlink():
+        raise ValueError("unsafe_workspace_gitignore_symlink")
+    if not gitignore.exists():
+        atomic_write_text(gitignore, "".join(f"{line}\n" for line in _WORKSPACE_GITIGNORE_LINES))
+        return
+    existing = gitignore.read_text(encoding="utf-8")
+    existing_lines = [ln.strip() for ln in existing.splitlines()]
+    missing_lines = [line for line in _WORKSPACE_GITIGNORE_LINES if line not in existing_lines]
+    if not missing_lines:
+        return
+    prefix = existing if existing.endswith("\n") or existing == "" else existing + "\n"
+    atomic_write_text(gitignore, prefix + "".join(f"{line}\n" for line in missing_lines))
+
+
+def _git(base_path: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", str(base_path), *args],
+        capture_output=True,
+        text=True,
+    )
+
+
+def _warn(message: str) -> None:
+    print(f"warning: {message}", file=sys.stderr)
+
+
+def commit_requirement_dir(base_path: Path, work_id: str, message: str) -> None:
+    """Path-limited, best-effort commit of one requirement directory.
+
+    Stages and commits only `.req-to-plan/.gitignore` and `.req-to-plan/<id>`.
+    The same primitive both adds (path present) and removes (path moved/deleted).
+    Best-effort with observable skips; it never raises and never touches paths
+    outside `.req-to-plan/<id>` (no `add -A`, no `-f`, no push).
+    """
+    gitignore_rel = ".req-to-plan/.gitignore"
+    run_rel = f".req-to-plan/{work_id}"
+
+    try:
+        # Guard 1: must be inside a git work tree.
+        inside = _git(base_path, "rev-parse", "--is-inside-work-tree")
+        if inside.returncode != 0 or inside.stdout.strip() != "true":
+            _warn(f"skipped commit for {run_rel}: not a git work tree")
+            return
+
+        # Stage (path-limited). `git add -- <path>` stages an addition/modification
+        # when the path exists, and stages a deletion when it was tracked and is now
+        # gone. A wholesale-gitignored path stages nothing (we never pass -f).
+        _git(base_path, "add", "--", gitignore_rel, run_rel)
+
+        # Guards 2 & 3 (merged): if nothing is staged for these paths, there is
+        # nothing to commit — covers wholesale-ignored, untracked-then-moved, and
+        # no-change. `git diff --cached --quiet` returns 0 when there is no diff.
+        staged = _git(base_path, "diff", "--cached", "--quiet", "--", gitignore_rel, run_rel)
+        if staged.returncode == 0:
+            _warn(f"skipped commit for {run_rel}: nothing staged (ignored or unchanged)")
+            return
+
+        # `--no-verify` does not skip post-commit, so disable hooks for this
+        # best-effort background commit by pointing hooksPath at an empty dir.
+        with tempfile.TemporaryDirectory(prefix="r2p-empty-hooks-") as hooks_path:
+            committed = _git(
+                base_path,
+                "-c",
+                f"core.hooksPath={hooks_path}",
+                "commit",
+                "--no-verify",
+                "-m",
+                message,
+                "--",
+                gitignore_rel,
+                run_rel,
+            )
+        if committed.returncode != 0:
+            unstaged = _git(base_path, "reset", "-q", "--", gitignore_rel, run_rel)
+            _warn(f"git commit failed for {run_rel}: {committed.stderr.strip()}")
+            if unstaged.returncode != 0:
+                _warn(f"failed to unstage {run_rel}: {unstaged.stderr.strip()}")
+    except FileNotFoundError:
+        _warn(f"skipped commit for {run_rel}: git executable not found")