@michaelxwb/code-flow 0.6.5 → 0.8.1

package/src/core/code-flow/config.yml

@@ -2,7 +2,7 @@ version: 1
 
 spec_workflow:
     schema_version: 1
-    enforcement: required  # required=全门禁 | warn=门禁仅记录不阻断 | inject=只注入不门禁
+    enforcement: required  # 推荐全门禁；历史 warn/inject 仅兼容部分验证降级，路由完整性错误始终阻断
     drift_check: true
     scope_expansion_check: true
     metrics: true
@@ -92,6 +92,9 @@ path_mapping:
             - path: "shared/_map.md"
               tags: ["*"]
               tier: 0
+            - path: "shared/scenarios-template.md"
+              tags: []          # 永不自动注入，仅 align 显式 Read
+              tier: 1
             - path: "shared/prd-template.md"
               tags: []          # 永不自动注入，仅 cf-task:prd 命令显式 Read
               tier: 1

package/src/core/code-flow/runtime-commands.json

@@ -0,0 +1,259 @@
+{
+  "schema_version": 1,
+  "commands": {
+    "spec budget": {
+      "module": "cf_spec_context",
+      "prefix": ["budget"],
+      "example_args": "--help"
+    },
+    "spec impact": {
+      "module": "cf_spec_context",
+      "prefix": ["impact"],
+      "example_args": "--help"
+    },
+    "spec optimize": {
+      "module": "cf_spec_context",
+      "prefix": ["optimize"],
+      "example_args": "--help"
+    },
+    "spec catalog": {
+      "module": "cf_spec_context",
+      "prefix": [
+        "catalog"
+      ],
+      "example_args": "--help"
+    },
+    "spec decision": {
+      "module": "cf_spec_context",
+      "prefix": [
+        "decision"
+      ],
+      "example_args": "--help"
+    },
+    "spec bind": {
+      "module": "cf_spec_context",
+      "prefix": [
+        "bind"
+      ],
+      "example_args": "--help"
+    },
+    "spec validate": {
+      "module": "cf_spec_context",
+      "prefix": [
+        "validate"
+      ],
+      "example_args": "--task-dir \"<需求目录>\" --json"
+    },
+    "spec status": {
+      "module": "cf_spec_context",
+      "prefix": [
+        "status"
+      ],
+      "example_args": "--task-dir \"<需求目录>\" --root \"$PWD\" --json"
+    },
+    "spec doctor": {
+      "module": "cf_spec_context",
+      "prefix": [
+        "doctor"
+      ],
+      "example_args": "--task-dir \"<需求目录>\" --root \"$PWD\" --json"
+    },
+    "spec refresh": {
+      "module": "cf_spec_context",
+      "prefix": [
+        "refresh"
+      ],
+      "example_args": "--task-dir \"<需求目录>\" --root \"$PWD\" --json"
+    },
+    "spec refresh-missing": {
+      "module": "cf_spec_context",
+      "prefix": [
+        "refresh-missing"
+      ],
+      "example_args": "--help"
+    },
+    "spec active": {
+      "module": "cf_spec_context",
+      "prefix": [
+        "active"
+      ],
+      "example_args": "--help"
+    },
+    "task start": {
+      "module": "cf_spec_context",
+      "prefix": [
+        "start"
+      ],
+      "example_args": "--task-dir \"<需求目录>\" --task-file \"<任务文件>\" --task TASK-001 --root \"$PWD\" --json"
+    },
+    "task finish": {
+      "module": "cf_task_workflow",
+      "prefix": [
+        "finish"
+      ],
+      "example_args": "--task-dir \"<需求目录>\" --task TASK-001 --root \"$PWD\" --json"
+    },
+    "task block": {
+      "module": "cf_task_workflow",
+      "prefix": [
+        "block"
+      ],
+      "example_args": "--help"
+    },
+    "task resume": {
+      "module": "cf_task_workflow",
+      "prefix": [
+        "resume"
+      ],
+      "example_args": "--help"
+    },
+    "task verify": {
+      "module": "cf_task_workflow",
+      "prefix": [
+        "verify"
+      ],
+      "example_args": "--task-dir \"<需求目录>\" --tasks TASK-001,TASK-002 --layers validators,e2e --profile smoke --root \"$PWD\" --json"
+    },
+    "task verify-e2e": {
+      "module": "cf_task_workflow",
+      "prefix": [
+        "verify-e2e"
+      ],
+      "example_args": "--task-dir \"<需求目录>\" --root \"$PWD\" --json"
+    },
+    "task confirm-manual": {
+      "module": "cf_task_workflow",
+      "prefix": [
+        "confirm-manual"
+      ],
+      "example_args": "--help"
+    },
+    "task cleanup-session": {
+      "module": "cf_task_workflow",
+      "prefix": [
+        "cleanup-session"
+      ],
+      "example_args": "--help"
+    },
+    "audit": {
+      "module": "cf_audit",
+      "prefix": [],
+      "example_args": "--task-dir \"<需求目录>\" --root \"$PWD\" --json"
+    },
+    "spec gate": {
+      "module": "cf_spec_gate",
+      "prefix": [],
+      "example_args": "--help"
+    },
+    "spec session": {
+      "module": "cf_spec_session",
+      "prefix": [],
+      "example_args": "--help"
+    },
+    "task index": {
+      "module": "cf_task_index",
+      "prefix": [],
+      "example_args": "--help"
+    },
+    "task parallel": {
+      "module": "cf_task_parallel",
+      "prefix": [],
+      "example_args": "--help"
+    },
+    "acceptance manifest": {
+      "module": "cf_acceptance_manifest",
+      "prefix": [],
+      "example_args": "--task-file \"<任务文件>\" --output \"<需求目录>/.acceptance-manifest.json\""
+    },
+    "acceptance project": {
+      "module": "cf_acceptance_manifest",
+      "prefix": [
+        "--project"
+      ],
+      "example_args": "--task-file \"<任务文件>\" --output \"<需求目录>/.acceptance-manifest.json\""
+    },
+    "acceptance risk": {
+      "module": "cf_acceptance_manifest",
+      "prefix": [
+        "--accept-risk"
+      ],
+      "example_args": "--task-file \"<任务文件>\" --output \"<需求目录>/.acceptance-manifest.json\" --check-id CHK-... --risk-owner \"<owner>\" --risk-reason \"<reason>\" --expires-at 2026-12-31 --confirmed-by \"<user>\" --source \"<user reply>\""
+    },
+    "acceptance run": {
+      "module": "cf_acceptance_runner",
+      "prefix": [],
+      "example_args": "--manifest \"<需求目录>/.acceptance-manifest.json\" --root \"$PWD\" --write-evidence"
+    },
+    "evidence import": {
+      "module": "cf_evidence_import",
+      "prefix": [
+        "import"
+      ],
+      "example_args": "--format junit --file \"<report.xml>\" --commit \"$(git rev-parse HEAD)\" --run-url \"<ci-run-url>\" --json"
+    },
+    "validate": {
+      "module": "cf_validation",
+      "prefix": [],
+      "example_args": "--root \"$PWD\" --json"
+    },
+    "stats": {
+      "module": "cf_stats",
+      "prefix": [],
+      "example_args": "--help"
+    },
+    "feedback ignore": {
+      "module": "cf_feedback",
+      "prefix": [
+        "ignore"
+      ],
+      "example_args": "--help"
+    },
+    "sync check": {
+      "module": "cf_sync",
+      "prefix": [
+        "check"
+      ],
+      "example_args": "--help"
+    },
+    "sync apply": {
+      "module": "cf_sync",
+      "prefix": [
+        "sync"
+      ],
+      "example_args": "--help"
+    },
+    "task archive": {
+      "module": "cf_task_workflow",
+      "prefix": [
+        "archive"
+      ],
+      "example_args": "--task-dir \"<需求目录>\" --root \"$PWD\" --json"
+    },
+    "scenarios parse": {
+      "module": "cf_scenarios",
+      "prefix": [
+        "parse"
+      ],
+      "example_args": "--file \"<需求>.scenarios.md\" --quality --json"
+    },
+    "scenarios merge": {
+      "module": "cf_scenarios",
+      "prefix": [
+        "merge"
+      ],
+      "example_args": "--file a.scenarios.md --file b.scenarios.md --json"
+    },
+    "scenarios migrate": {
+      "module": "cf_scenarios",
+      "prefix": [
+        "migrate"
+      ],
+      "example_args": "--task-file \"<任务文件>\" --output \"<需求>.scenarios.md\" --json"
+    },
+    "design lint": {
+      "module": "cf_design_lint",
+      "prefix": [],
+      "example_args": "--file \"<需求>.design.md\" --scenarios-file \"<需求>.scenarios.md\" --json"
+    }
+  }
+}

package/src/core/code-flow/scripts/cf_acceptance_manifest.py

@@ -1,294 +1,10 @@
 #!/usr/bin/env python3
-"""Lock and validate plan Acceptance Coverage entries."""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import shlex
-from pathlib import Path
-import re
+"""Path-frozen entry shim: implementation lives in codeflow.cli.cf_acceptance_manifest."""
 import sys
-from typing import IO, Callable, Mapping, Optional, Sequence
-
-from cf_acceptance_schema import load_manifest, validate_scenarios
-
-
-_ROW_RE = re.compile(r"^\|\s*([SEB]-\d+)\s*\|(.+?)\|$")
-
-_MANIFEST_SCHEMA = 2
-
-
-def _kind(level: str) -> str:
-    """Map test level to execution kind.
-
-    - functional: auto-executed in Done Gate (unit, integration)
-    - e2e: deferred until explicit --verify-e2e (needs external dependencies)
-    - manual: user confirmation required, never auto-executed
-
-    层级单元格允许带注解（如 `E2E（Playwright）`、`e2e/chrome`、`manual(chrome)`），
-    取分隔符前的词元判定；避免带注解的 E2E 被误判为 functional 而每任务执行。
-    """
-    head = level.strip().lower()
-    for separator in ("(", "（", "[", "/", ",", "，", " ", "—", "-"):
-        head = head.split(separator, 1)[0]
-    head = head.strip()
-    if head in ("manual", "手工", "手动"):
-        return "manual"
-    if head in ("e2e", "端到端", "end"):
-        return "e2e"
-    return "functional"
-
-
-def _parse_command(cell: str, scenario_id: str) -> Optional[list[str]]:
-    """Parse the optional 命令 column: argv JSON array preferred, else shell words.
-
-    Empty / `-` / `planned` → None (not yet registered, not executable).
-    """
-    text = (cell or "").strip()
-    if not text or text in {"-", "planned", "pending", "TBD", "tbd"}:
-        return None
-    if text.startswith("["):
-        try:
-            value = json.loads(text)
-        except json.JSONDecodeError as exc:
-            raise ValueError(f"{scenario_id} 命令列不是合法 argv JSON: {exc}") from exc
-        if not isinstance(value, list) or not value or not all(isinstance(item, str) for item in value):
-            raise ValueError(f"{scenario_id} 命令列必须是 argv 字符串数组")
-        return list(value)
-    return shlex.split(text)
-
-
-def _parse_float(cell: str, default: float) -> float:
-    try:
-        return float((cell or "").strip() or default)
-    except (TypeError, ValueError):
-        return default
-
-
-def _manifest_hash(rows: list[dict[str, object]]) -> str:
-    immutable = [
-        {key: item[key] for key in ("id", "source", "level", "kind", "boundary", "owner", "command", "cwd", "timeout", "depends_on")}
-        for item in rows
-    ]
-    payload = json.dumps(immutable, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
-    return hashlib.sha256(payload).hexdigest()
-
-
-def _legacy_kind(level: str) -> str:
-    """v1 精确匹配：仅用于识别旧版锁定的 manifest，不做新语义判定。"""
-    normalized = level.strip().lower()
-    if normalized == "manual":
-        return "manual"
-    if normalized == "e2e":
-        return "e2e"
-    return "functional"
-
-
-def _extract_rows(task_file: str, kind_fn: Callable[[str], str]) -> dict[str, object]:
-    path = Path(task_file)
-    text = path.read_text(encoding="utf-8")
-    rows: list[dict[str, object]] = []
-    in_table = False
-    seen: set[str] = set()
-    for line in text.splitlines():
-        if line.startswith("## Acceptance Coverage"):
-            in_table = True
-            continue
-        if in_table and line.startswith("## "):
-            break
-        if not in_table:
-            continue
-        match = _ROW_RE.match(line)
-        if not match or set(match.group(2).replace("|", "").strip()) <= {"-", " "}:
-            continue
-        fields = [item.strip() for item in match.group(2).split("|")]
-        if match.group(1) in seen:
-            raise ValueError(f"duplicate scenario id: {match.group(1)}")
-        if len(fields) < 5:
-            raise ValueError(f"Acceptance Coverage missing columns: {match.group(1)}")
-        seen.add(match.group(1))
-        depends = [item.strip() for item in (fields[8] if len(fields) > 8 else "").split(",") if item.strip()]
-        rows.append({
-            "id": match.group(1),
-            "source": fields[0],
-            "level": fields[1],
-            "kind": kind_fn(fields[1]),
-            "boundary": fields[2],
-            "owner": fields[3],
-            "status": fields[4],
-            "command": _parse_command(fields[5], match.group(1)) if len(fields) > 5 else None,
-            "cwd": (fields[6] if len(fields) > 6 else "").strip() or ".",
-            "timeout": _parse_float(fields[7], 60.0) if len(fields) > 7 else 60.0,
-            "depends_on": depends,
-        })
-    if not rows:
-        raise ValueError("Acceptance Coverage 缺失或为空")
-    validate_scenarios(rows)
-    return {"schema": _MANIFEST_SCHEMA, "task_file": str(path), "task_sha256": _manifest_hash(rows), "scenarios": rows}
-
-
-def extract_manifest(task_file: str, kind_fn: Callable[[str], str] = _kind) -> dict[str, object]:
-    return _extract_rows(task_file, kind_fn)
-
-
-def write_manifest(task_file: str, output: str) -> dict[str, object]:
-    manifest = extract_manifest(task_file)
-    target = Path(output)
-    try:
-        manifest["task_file"] = str(Path(task_file).resolve().relative_to(target.parent.resolve()))
-    except ValueError:
-        manifest["task_file"] = str(Path(task_file).resolve())
-    target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-    return manifest
-
-
-_IMMUTABLE_SCENARIO_FIELDS = (
-    "id", "source", "level", "kind", "boundary", "owner", "command", "cwd", "timeout", "depends_on",
-)
-
-
-def _heal_legacy_kinds(manifest_file: Path, manifest: dict[str, object], expected: dict[str, object]) -> None:
-    """旧版 `_kind` 精确匹配把带注解的 E2E 锁成 functional；任务内容未变时
-    原地升级 kind 并重锁哈希，保留 execution evidence 等运行态字段。"""
-    by_id: dict[str, dict[str, object]] = {}
-    scenarios = expected.get("scenarios")
-    if isinstance(scenarios, list):
-        for item in scenarios:
-            if isinstance(item, dict) and isinstance(item.get("id"), str):
-                by_id[item["id"]] = item
-    current = manifest.get("scenarios")
-    if isinstance(current, list):
-        for item in current:
-            if not isinstance(item, dict):
-                continue
-            target = by_id.get(item.get("id")) if isinstance(item.get("id"), str) else None
-            if target is not None:
-                item["kind"] = target.get("kind")
-    manifest["task_sha256"] = expected["task_sha256"]
-    manifest_file.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-
-
-def validate_manifest(task_file: str, manifest_file: str) -> tuple[bool, str]:
-    try:
-        manifest = load_manifest(Path(manifest_file))
-        expected = extract_manifest(task_file)
-    except (OSError, ValueError, json.JSONDecodeError) as exc:
-        return False, f"acceptance_manifest_invalid: {exc}"
-    if manifest.get("schema") != _MANIFEST_SCHEMA:
-        return False, "acceptance_manifest_drift"
-    if manifest.get("task_sha256") != expected["task_sha256"]:
-        legacy = extract_manifest(task_file, _legacy_kind)
-        if manifest.get("task_sha256") != legacy["task_sha256"]:
-            return False, "acceptance_manifest_drift"
-        _heal_legacy_kinds(Path(manifest_file), manifest, expected)
-    stored_task = manifest.get("task_file", "")
-    if not stored_task or (Path(manifest_file).parent / stored_task).resolve() != Path(task_file).resolve():
-        return False, "acceptance_manifest_task_mismatch"
-    if not isinstance(manifest.get("scenarios"), list):
-        return False, "acceptance_manifest_scenarios_changed"
-    stored = {
-        item.get("id"): item
-        for item in manifest["scenarios"]
-        if isinstance(item, Mapping) and isinstance(item.get("id"), str)
-    }
-    required = {item["id"] for item in expected["scenarios"]}
-    if set(stored) != required:
-        return False, "acceptance_manifest_scenarios_changed"
-    for item in expected["scenarios"]:
-        current = stored[item["id"]]
-        for field in _IMMUTABLE_SCENARIO_FIELDS:
-            if current.get(field) != item.get(field):
-                return False, f"acceptance_manifest_field_changed:{item['id']}:{field}"
-    text = Path(task_file).read_text(encoding="utf-8")
-    for scenario in expected["scenarios"]:
-        owner = scenario["owner"]
-        section = re.search(rf"(?ms)^##\s+{re.escape(owner)}:.*?(?=^##\s+TASK-|\Z)", text)
-        refs = re.search(r"(?m)^- \*\*Acceptance-Refs\*\*:[ \t]*([^\n]*)", section.group(0)) if section else None
-        if not refs or scenario["id"] not in re.findall(r"\b[SEB]-\d+\b", refs.group(1)):
-            return False, "acceptance_manifest_owner_missing"
-    return True, ""
-
-
-def record_manual_evidence(manifest_file: str, scenario_id: str, confirmed_by: str, evidence: str) -> None:
-    if not confirmed_by or confirmed_by.lower().split(":", 1)[0] in {"agent", "assistant", "codex", "claude", "opencode", "costrict"}:
-        raise ValueError("manual evidence must be confirmed by a user")
-    path = Path(manifest_file)
-    data = load_manifest(path)
-    scenarios = data.get("scenarios")
-    if not isinstance(scenarios, list):
-        raise ValueError("invalid manifest scenarios")
-    found = False
-    owner = ""
-    task_file = data.get("task_file")
-    for item in scenarios:
-        if isinstance(item, dict) and item.get("id") == scenario_id:
-            if item.get("kind") != "manual":
-                raise ValueError("scenario is not manual")
-            item["status"] = "verified"
-            item["evidence"] = {"confirmed_by": confirmed_by, "evidence": evidence}
-            found = True
-            owner = item.get("owner") if isinstance(item.get("owner"), str) else ""
-    if not found:
-        raise ValueError("scenario not found")
-    path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-    if isinstance(task_file, str) and task_file:
-        task_path = Path(task_file)
-        if not task_path.is_absolute():
-            task_path = path.parent / task_path
-        _sync_task_evidence(task_path, scenario_id, confirmed_by, evidence, owner)
-
-
-def _sync_task_evidence(task_file: Path, scenario_id: str, confirmed_by: str, evidence: str, owner: str = "") -> None:
-    from cf_acceptance_evidence import sync_task_evidence
-    sync_task_evidence(task_file, scenario_id, confirmed_by, evidence, owner)
-
-
-def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--task-file", required=True)
-    parser.add_argument("--output", default="")
-    parser.add_argument("--verify-plan", action="store_true")
-    parser.add_argument("--task-dir", default="")
-    parser.add_argument("--record-manual", action="store_true")
-    parser.add_argument("--scenario-id", default="")
-    parser.add_argument("--confirmed-by", default="")
-    parser.add_argument("--evidence", default="")
-    args = parser.parse_args(argv)
-    try:
-        if args.record_manual:
-            if not args.output or not args.scenario_id or not args.evidence:
-                raise ValueError("--record-manual requires --output, --scenario-id and --evidence")
-            record_manual_evidence(args.output, args.scenario_id, args.confirmed_by, args.evidence)
-            stdout.write(json.dumps({"ok": True, "scenario": args.scenario_id}, ensure_ascii=False))
-            return 0
-        if args.verify_plan:
-            if not args.task_dir:
-                raise ValueError("--verify-plan requires --task-dir")
-            from cf_spec_context import load_context
-            from cf_spec_gate import result_to_data, validate_plan_coverage, validate_stage
-
-            context = load_context(str(Path(args.task_dir) / "spec-context.yml"))
-            gate = validate_stage(context, "plan")
-            coverage = validate_plan_coverage(context, args.task_file)
-            result = {
-                "decision": "block" if gate.decision == "block" or coverage.decision == "block" else "pass",
-                "gate": result_to_data(gate),
-                "coverage": result_to_data(coverage),
-            }
-            stdout.write(json.dumps(result, ensure_ascii=False))
-            return 0 if result["decision"] == "pass" else 3
-        if not args.output:
-            raise ValueError("--output is required unless --verify-plan is used")
-        manifest = write_manifest(args.task_file, args.output)
-        stdout.write(json.dumps({"ok": True, "scenarios": len(manifest["scenarios"])}, ensure_ascii=False))
-        return 0
-    except (OSError, ValueError) as exc:
-        stdout.write(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
-        return 2
 
+from codeflow.cli import cf_acceptance_manifest as _impl
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(_impl.main())
+else:
+    sys.modules[__name__] = _impl