@xenonbyte/req-2-plan 0.2.3 → 0.3.0

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@xenonbyte/req-2-plan",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Requirement-to-PLAN workflow CLI and agent integration installer.",
   "bin": {
     "r2p": "bin/r2p.js"
   },
   "files": [
     "bin/",
-    "docs/*.md",
     "tools/r2p",
     "tools/r2p-*",
     "tools/workflow_cli/**/*.py",
@@ -18,7 +17,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": ".venv/bin/python -m pytest",
+    "test": "python -m pytest",
+    "test:local": ".venv/bin/python -m pytest",
     "prepack": "node bin/r2p.js version >/dev/null"
   },
   "repository": {

package/tools/workflow_cli/agent_shortcuts.py

@@ -224,6 +224,33 @@ def _prepare_input_file(run_dir: Path, stage: str, suffix: str, seed: str = "")
     return path
 
 
+def _prev_stage(stage):
+    """Return the Stage enum member immediately before *stage*, or None if first."""
+    from tools.workflow_cli.models import STAGE_ORDER
+    i = STAGE_ORDER.index(stage)
+    return STAGE_ORDER[i - 1] if i > 0 else None
+
+
+def _seed_for_stage(stage, tier, upstream_summary: str = "", context_summary: str = "") -> str:
+    """Build the seed text for a stage content file: template + upstream summary + context pack."""
+    from tools.workflow_cli.stage_templates import template_for
+    base = tier.base if tier is not None else None
+    text = template_for(stage, base) if base is not None else ""
+    if upstream_summary.strip():
+        text += (
+            "\n## Upstream Summary (read-only)\n"
+            + upstream_summary.strip()
+            + "\n<!-- /r2p-read-only -->\n"
+        )
+    if context_summary.strip():
+        text += (
+            "\n## Project Context (read-only)\n"
+            + context_summary.strip()
+            + "\n<!-- /r2p-read-only -->\n"
+        )
+    return text
+
+
 def _stage_content_command(
     base_path: Path,
     work_id: str,
@@ -367,6 +394,16 @@ def _resolve_start_requirement(ns: argparse.Namespace) -> tuple[str, Path | None
     return raw, None
 
 
+def _build_run_start_args(work_id, requirement, file_path, repo_path=None):
+    if file_path is not None:
+        args = ["run-start", "--work-id", work_id, "--requirement-file", str(file_path)]
+    else:
+        args = ["run-start", "--work-id", work_id, "--requirement", requirement]
+    if repo_path:
+        args += ["--repo-path", str(repo_path)]
+    return args
+
+
 def _cmd_start(ns: argparse.Namespace, base_path: Path) -> None:
     requirement, file_path = _resolve_start_requirement(ns)
 
@@ -387,10 +424,7 @@ def _cmd_start(ns: argparse.Namespace, base_path: Path) -> None:
             sys.exit(1)
 
     work_id = generate_work_id(requirement, base_path)
-    if file_path is not None:
-        run_args = ["run-start", "--work-id", work_id, "--requirement-file", str(file_path)]
-    else:
-        run_args = ["run-start", "--work-id", work_id, "--requirement", requirement]
+    run_args = _build_run_start_args(work_id, requirement, file_path, getattr(ns, "repo_path", None))
     exit_code = _run_cli(run_args, base_path)
     if exit_code != 0:
         sys.exit(exit_code)
@@ -441,7 +475,15 @@ def _cmd_continue(ns: argparse.Namespace, base_path: Path) -> None:
                 body = ""
             open_owner_route = _open_owner_route(record)
             if aa is None or not body:
-                content_file = _prepare_input_file(run_path.parent, stage, "content")
+                prev = _prev_stage(record.current_stage)
+                try:
+                    upstream = read_artifact(run_path.parent, prev) if prev else ""
+                except FileNotFoundError:
+                    upstream = ""
+                pack_md = run_path.parent / "02-project-context.md"
+                context_summary = pack_md.read_text(encoding="utf-8") if pack_md.exists() else ""
+                seed = _seed_for_stage(record.current_stage, record.tier_locked, upstream, context_summary)
+                content_file = _prepare_input_file(run_path.parent, stage, "content", seed)
                 content_cmd = _stage_content_command(
                     base_path,
                     work_id,
@@ -551,7 +593,15 @@ def _cmd_continue(ns: argparse.Namespace, base_path: Path) -> None:
                       f"content_file: {content_file}\n"
                       f"next: {update_cmd}\n")
                 sys.exit(0)
-            content_file = _prepare_input_file(run_path.parent, stage, "content")
+            prev = _prev_stage(record.current_stage)
+            try:
+                upstream = read_artifact(run_path.parent, prev) if prev else ""
+            except FileNotFoundError:
+                upstream = ""
+            pack_md = run_path.parent / "02-project-context.md"
+            context_summary = pack_md.read_text(encoding="utf-8") if pack_md.exists() else ""
+            seed = _seed_for_stage(record.current_stage, record.tier_locked, upstream, context_summary)
+            content_file = _prepare_input_file(run_path.parent, stage, "content", seed)
             produce_cmd = _stage_content_command(
                 base_path,
                 work_id,
@@ -714,6 +764,7 @@ def _build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Read the requirement from a file instead of a positional argument",
     )
+    p_start.add_argument("--repo-path", dest="repo_path", default=None)
 
     sub.add_parser("continue")
 

package/tools/workflow_cli/agent_templates/claude/commands/r2p-start.md

@@ -8,3 +8,5 @@ Usage: `{{R2P_BIN_DIR}}/r2p-start [--separate] ("<raw requirement>" | --file <pa
 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.
 
 Use `--separate` to create an independent run when another open run exists.
+
+Optionally pass `--repo-path <dir>` to ground tier estimation and the Project Context Pack in real repo facts.

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

@@ -12,3 +12,5 @@ Usage: `{{R2P_BIN_DIR}}/r2p-start [--separate] ("<raw requirement>" | --file <pa
 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.
 
 Use `--separate` to create an independent run when another open run exists.
+
+Optionally pass `--repo-path <dir>` to ground tier estimation and the Project Context Pack in real repo facts.

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-start.toml

@@ -1,4 +1,4 @@
 name = "r2p-start"
-description = "Start a new requirement-to-PLAN workflow run"
+description = "Start a new requirement-to-PLAN workflow run. Optionally pass --repo-path <dir> to ground tier estimation and the Project Context Pack in real repo facts."
 command = "{{R2P_BIN_DIR}}/r2p-start"
 version = "{{R2P_VERSION}}"

package/tools/workflow_cli/cli.py

@@ -90,6 +90,20 @@ def _validate_work_id(raw: str) -> WorkId:
         print_and_exit(format_error(str(e), exit_code=EXIT_CLI_ERR), EXIT_CLI_ERR)
 
 
+def _validate_repo_path(raw: str) -> Path:
+    """Return a repo path only when it is an existing directory."""
+    repo_path = Path(raw)
+    if not repo_path.is_dir():
+        print_and_exit(
+            format_error(
+                f"repo path not found or not a directory: {raw}",
+                exit_code=EXIT_CLI_ERR,
+            ),
+            EXIT_CLI_ERR,
+        )
+    return repo_path
+
+
 def _parse_stage(raw: str) -> Stage:
     """Parse Stage enum or exit with CLI error."""
     try:
@@ -180,6 +194,7 @@ def _cmd_run_start(args):
             format_error("Requirement must not be blank", exit_code=EXIT_CLI_ERR),
             EXIT_CLI_ERR,
         )
+    repo_path = _validate_repo_path(args.repo_path) if args.repo_path else None
     run_dir = _get_run_dir(work_id, args.base_path)
     mgr = RunStateManager(run_dir)
 
@@ -212,11 +227,29 @@ def _cmd_run_start(args):
     run_dir.mkdir(parents=True, exist_ok=True)
     write_artifact(run_dir, Stage.RAW_REQUIREMENT, requirement, version=1, status="draft")
 
+    # Tier estimation inputs
+    link_results = []
+    if repo_path is not None:
+        from tools.workflow_cli.link_expander import expand_links
+        # Local relative links expand; HTTP is recorded as not-expanded (needs confirmation).
+        link_results = expand_links(requirement, base_path=repo_path, fetch_urls=False)
+
     # Tier estimation
-    repo_path = Path(args.repo_path) if args.repo_path else None
-    tier_estimate, evidence = estimate_tier(requirement, repo_path=repo_path)
+    tier_estimate, evidence = estimate_tier(requirement, repo_path=repo_path, link_results=link_results)
     record.tier_estimate = tier_estimate
 
+    # Context Pack + link expansion (when repo_path is provided)
+    if repo_path is not None:
+        from tools.workflow_cli.context_pack import build_context_pack, write_context_pack
+        write_context_pack(build_context_pack(repo_path), run_dir)
+        if link_results:
+            evidence.linked_context = "\n".join(
+                f"- {r.url}: {r.status.value}"
+                + (f"\n  preview: {r.content_preview}" if r.content_preview else "")
+                + (f"\n  error: {r.error}" if r.error else "")
+                for r in link_results
+            )
+
     # Update active artifacts in record
     artifact_file = STAGE_ARTIFACT_MAP[Stage.RAW_REQUIREMENT]
     upsert_active_artifact(record, Stage.RAW_REQUIREMENT, artifact_file, 1, "draft")
@@ -421,6 +454,10 @@ def _cmd_run_reopen(args):
             src_path = source_dir / artifact_file
             if src_path.exists():
                 shutil.copy2(src_path, new_run_dir / artifact_file)
+    for context_file in ("02-project-context.json", "02-project-context.md"):
+        src_path = source_dir / context_file
+        if src_path.exists():
+            shutil.copy2(src_path, new_run_dir / context_file)
 
     # Create new run record
     new_record = create_run_record(new_work_id)
@@ -1745,6 +1782,41 @@ def _register_route_commands(subparsers):
     p.set_defaults(func=_cmd_gap_resolve)
 
 
+# ---------------------------------------------------------------------------
+# context-build command
+# ---------------------------------------------------------------------------
+
+
+def _cmd_context_build(args):
+    from tools.workflow_cli.context_pack import build_context_pack, write_context_pack
+
+    work_id = str(_validate_work_id(args.work_id))
+    run_dir = _get_run_dir(work_id, args.base_path)
+    if not run_dir.exists():
+        print_and_exit(
+            format_error(f"run not found: {work_id}", exit_code=EXIT_NOT_FOUND),
+            EXIT_NOT_FOUND,
+        )
+    repo_path = _validate_repo_path(args.repo_path)
+    pack = build_context_pack(repo_path)
+    md_path, json_path = write_context_pack(pack, run_dir)
+    print_and_exit(
+        format_success(
+            {"work_id": work_id, "context_md": str(md_path), "context_json": str(json_path)},
+            message="Context Pack built",
+        ),
+        EXIT_OK,
+    )
+
+
+def _register_context_commands(subparsers):
+    p = subparsers.add_parser("context-build", help="Build Project Context Pack for a run")
+    p.add_argument("--work-id", required=True)
+    p.add_argument("--repo-path", required=True)
+    p.add_argument("--base-path", type=Path, default=argparse.SUPPRESS)
+    p.set_defaults(func=_cmd_context_build)
+
+
 # ---------------------------------------------------------------------------
 # main
 # ---------------------------------------------------------------------------
@@ -1770,6 +1842,7 @@ def main(args=None):
     _register_status_commands(subparsers)
     _register_stage_commands(subparsers)
     _register_checkpoint_commands(subparsers)
+    _register_context_commands(subparsers)
 
     parsed = parser.parse_args(args)
     parsed.func(parsed)

package/tools/workflow_cli/context_pack.py

@@ -0,0 +1,98 @@
+"""Build a lightweight Project Context Pack (v1: no AST symbols)."""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from tools.workflow_cli.repo_baseline import SKIP_DIRS, scan_repo_baseline
+
+_CONFIG_NAMES = {
+    "pyproject.toml", "setup.cfg", "tox.ini", "Cargo.toml", "go.mod",
+    "tsconfig.json", ".env.example", "Dockerfile", "Makefile", "requirements.txt",
+}
+_ENTRYPOINT_HINTS = ("main.py", "__main__.py", "index.ts", "index.js", "app.py", "server.ts")
+
+
+@dataclass
+class ProjectContextPack:
+    repo_root: str = "."
+    languages: dict = field(default_factory=dict)
+    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}]
+    config_files: list = field(default_factory=list)
+    source_dirs: list = field(default_factory=list)
+
+
+def build_context_pack(repo_path: Path) -> ProjectContextPack:
+    repo_path = Path(repo_path).resolve()
+    baseline = scan_repo_baseline(repo_path)
+    pack = ProjectContextPack(repo_root=str(repo_path), languages=dict(baseline.language_breakdown))
+
+    pkg = repo_path / "package.json"
+    if pkg.exists():
+        try:
+            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"})
+        except (ValueError, OSError):
+            pass
+
+    req = repo_path / "requirements.txt"
+    if req.exists():
+        pack.package_managers.append("pip")
+        for line in req.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line and not line.startswith(("#", "-")):
+                pack.dependencies.append({"name": line, "version": "", "ecosystem": "pip"})
+        if not pack.test_commands:
+            pack.test_commands.append("python -m pytest")
+
+    for root, dirs, files in os.walk(repo_path):
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith(".")]
+        rel_root = Path(root).relative_to(repo_path)
+        for fname in files:
+            rel = str(rel_root / fname) if str(rel_root) != "." else fname
+            if fname in _CONFIG_NAMES:
+                pack.config_files.append(rel)
+            if fname in _ENTRYPOINT_HINTS:
+                pack.entrypoints.append(rel)
+
+    pack.source_dirs = sorted(
+        p.name for p in repo_path.iterdir()
+        if p.is_dir() and p.name not in SKIP_DIRS and not p.name.startswith(".")
+    )
+    return pack
+
+
+def to_json(pack: ProjectContextPack) -> str:
+    return json.dumps(asdict(pack), indent=2, ensure_ascii=False)
+
+
+def to_markdown(pack: ProjectContextPack) -> str:
+    return (
+        "# Project Context Pack\n\n"
+        f"- repo_root: `{pack.repo_root}`\n"
+        f"- languages: {pack.languages}\n"
+        f"- package_managers: {', '.join(pack.package_managers) or 'none'}\n"
+        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"- source_dirs: {pack.source_dirs}\n"
+    )
+
+
+def write_context_pack(pack: ProjectContextPack, run_dir: Path) -> tuple[Path, Path]:
+    json_path = run_dir / "02-project-context.json"
+    md_path = run_dir / "02-project-context.md"
+    json_path.write_text(to_json(pack), encoding="utf-8")
+    md_path.write_text(to_markdown(pack), encoding="utf-8")
+    return md_path, json_path