@michaelxwb/code-flow 0.5.2 → 0.6.0

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

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""Rule verifier registry and hash-bound Verification Evidence."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import fnmatch
+import hashlib
+import json
+from pathlib import Path
+import subprocess
+from typing import Mapping, Optional, Sequence
+
+from cf_checks import run_regex_verifier
+from cf_spec_metadata import SpecMetadata, SpecRule, SpecVerifier
+
+
+@dataclass(frozen=True)
+class VerificationScope:
+    root: str
+    files: tuple[str, ...]
+    diff_sha256: Optional[str]
+
+
+@dataclass(frozen=True)
+class VerificationEvidence:
+    verifier_ref: str
+    executed_at: str
+    status: str
+    rule_text_sha256: str
+    artifact_sha256: Optional[str]
+    diff_sha256: Optional[str]
+    result_sha256: str
+    error_code: Optional[str]
+    details: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class VerificationResult:
+    evidence: tuple[VerificationEvidence, ...]
+    passed: bool
+
+
+@dataclass(frozen=True)
+class _Outcome:
+    passed: bool
+    error_code: Optional[str]
+    artifact_sha256: Optional[str]
+    details: Mapping[str, object]
+
+
+def _hash_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _result_hash(status: str, error: Optional[str], details: Mapping[str, object]) -> str:
+    payload = {"status": status, "error_code": error, "details": details}
+    encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode()
+    return _hash_bytes(encoded)
+
+
+def _config_string(config: Mapping[str, object], key: str) -> Optional[str]:
+    value = config.get(key)
+    return value if isinstance(value, str) and value else None
+
+
+def _read_scope_files(scope: VerificationScope) -> tuple[dict[str, str], Optional[_Outcome]]:
+    contents: dict[str, str] = {}
+    for relative in scope.files:
+        path = Path(scope.root) / relative
+        try:
+            contents[relative] = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeError) as exc:
+            outcome = _Outcome(False, "file_read_error", None, {"file": relative, "error": str(exc)})
+            return {}, outcome
+    return contents, None
+
+
+def _document(config: Mapping[str, object], scope: VerificationScope) -> _Outcome:
+    relative = _config_string(config, "artifact")
+    section = _config_string(config, "section_id")
+    item = _config_string(config, "item_id")
+    if not relative or not section or not item:
+        return _Outcome(False, "invalid_verifier_config", None, {"required": ["artifact", "section_id", "item_id"]})
+    path = Path(scope.root) / relative
+    try:
+        content = path.read_text(encoding="utf-8")
+        artifact_hash = _hash_bytes(path.read_bytes())
+    except (OSError, UnicodeError) as exc:
+        return _Outcome(False, "artifact_read_error", None, {"artifact": relative, "error": str(exc)})
+    expected = _config_string(config, "artifact_sha256")
+    present = section in content and item in content
+    hash_matches = expected is None or expected == artifact_hash
+    details = {"artifact": relative, "section_present": section in content, "item_present": item in content, "hash_matches": hash_matches}
+    return _Outcome(present and hash_matches, None if present and hash_matches else "document_mismatch", artifact_hash, details)
+
+
+def _regex(config: Mapping[str, object], metadata: SpecMetadata, scope: VerificationScope) -> _Outcome:
+    pattern = _config_string(config, "pattern")
+    files = _config_string(config, "files") or "*"
+    check_id = _config_string(config, "check_id")
+    if check_id:
+        check = next((item for item in metadata.checks if item.get("id") == check_id), None)
+        if check is None:
+            return _Outcome(False, "check_not_found", None, {"check_id": check_id})
+        pattern = check.get("pattern") if isinstance(check.get("pattern"), str) else None
+        files = check.get("files") if isinstance(check.get("files"), str) else "*"
+    if pattern is None:
+        return _Outcome(False, "invalid_verifier_config", None, {"required": ["pattern"]})
+    selected = tuple(
+        relative
+        for relative in scope.files
+        if fnmatch.fnmatch(relative, files) and (Path(scope.root) / relative).is_file()
+    )
+    contents, error = _read_scope_files(VerificationScope(scope.root, selected, scope.diff_sha256))
+    if error is not None:
+        return error
+    violations, skipped = run_regex_verifier(pattern, files, contents)
+    if skipped:
+        return _Outcome(False, "regex_unavailable", None, {"skipped": skipped})
+    details = {"checked_files": len(contents), "violations": violations}
+    return _Outcome(not violations, None if not violations else "regex_violation", None, details)
+
+
+def _call_name(node: ast.Call) -> str:
+    if isinstance(node.func, ast.Name):
+        return node.func.id
+    if isinstance(node.func, ast.Attribute):
+        return node.func.attr
+    return ""
+
+
+def _ast(config: Mapping[str, object], scope: VerificationScope) -> _Outcome:
+    if _config_string(config, "language") != "python":
+        return _Outcome(False, "unsupported_ast_language", None, {"language": config.get("language")})
+    assertion = _config_string(config, "assertion") or "parse"
+    contents, error = _read_scope_files(scope)
+    if error is not None:
+        return error
+    parsed: list[ast.AST] = []
+    try:
+        parsed = [ast.parse(content, filename=relative) for relative, content in contents.items()]
+    except SyntaxError as exc:
+        return _Outcome(False, "ast_parse_error", None, {"error": str(exc)})
+    if assertion == "parse":
+        return _Outcome(True, None, None, {"parsed_files": len(parsed)})
+    if assertion == "forbid_call":
+        call = _config_string(config, "call")
+        hits = sum(_call_name(node) == call for tree in parsed for node in ast.walk(tree) if isinstance(node, ast.Call))
+        return _Outcome(hits == 0, None if hits == 0 else "ast_assertion_failed", None, {"call": call, "hits": hits})
+    return _Outcome(False, "unsupported_ast_assertion", None, {"assertion": assertion})
+
+
+def _argv(config: Mapping[str, object]) -> Optional[list[str]]:
+    value = config.get("argv")
+    if not isinstance(value, list) or not value or not all(isinstance(item, str) for item in value):
+        return None
+    return list(value)
+
+
+def _command(config: Mapping[str, object], scope: VerificationScope) -> _Outcome:
+    argv = _argv(config)
+    if argv is None:
+        return _Outcome(False, "invalid_verifier_config", None, {"required": ["argv"]})
+    cwd = _config_string(config, "cwd") or "."
+    timeout_value = config.get("timeout", 30)
+    timeout = float(timeout_value) if isinstance(timeout_value, (int, float)) else 30.0
+    allowed_value = config.get("allowed_exit_codes", [0])
+    allowed = tuple(item for item in allowed_value if isinstance(item, int)) if isinstance(allowed_value, list) else (0,)
+    try:
+        completed = subprocess.run(
+            argv,
+            cwd=str(Path(scope.root) / cwd),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return _Outcome(False, "verifier_timeout", None, {"timeout": timeout, "argv": argv})
+    except OSError as exc:
+        return _Outcome(False, "command_unavailable", None, {"argv": argv, "error": str(exc)})
+    details = {
+        "argv": argv,
+        "exit_code": completed.returncode,
+        "stdout_sha256": _hash_bytes(completed.stdout.encode()),
+        "stderr_sha256": _hash_bytes(completed.stderr.encode()),
+    }
+    passed = completed.returncode in allowed
+    return _Outcome(passed, None if passed else "command_failed", None, details)
+
+
+def _manual(config: Mapping[str, object], confirmation: Optional[Mapping[str, object]]) -> _Outcome:
+    if confirmation is None:
+        return _Outcome(False, "manual_confirmation_missing", None, {"checklist": config.get("checklist")})
+    required = ("reason", "confirmed_by", "confirmed_at", "source")
+    if not all(isinstance(confirmation.get(key), str) and confirmation.get(key) for key in required):
+        return _Outcome(False, "manual_confirmation_invalid", None, {"required": list(required)})
+    identity = str(confirmation["confirmed_by"]).lower().split(":", 1)[0]
+    if identity in ("agent", "assistant", "codex", "claude", "opencode", "costrict"):
+        return _Outcome(False, "manual_agent_forbidden", None, {"confirmed_by": confirmation["confirmed_by"]})
+    return _Outcome(True, None, None, {"source": confirmation["source"], "owner": config.get("owner")})
+
+
+def _run(
+    verifier: SpecVerifier,
+    metadata: SpecMetadata,
+    scope: VerificationScope,
+    confirmation: Optional[Mapping[str, object]],
+) -> _Outcome:
+    if verifier.type == "document":
+        return _document(verifier.config, scope)
+    if verifier.type == "regex":
+        return _regex(verifier.config, metadata, scope)
+    if verifier.type == "ast":
+        return _ast(verifier.config, scope)
+    if verifier.type in ("command", "test"):
+        return _command(verifier.config, scope)
+    if verifier.type == "manual":
+        return _manual(verifier.config, confirmation)
+    return _Outcome(False, "verifier_type_unimplemented", None, {"type": verifier.type})
+
+
+def _evidence(
+    metadata: SpecMetadata,
+    rule: SpecRule,
+    verifier: SpecVerifier,
+    scope: VerificationScope,
+    confirmation: Optional[Mapping[str, object]],
+) -> VerificationEvidence:
+    outcome = _run(verifier, metadata, scope, confirmation)
+    status = "verified" if outcome.passed else "unverified"
+    diff_hash = None if verifier.type == "document" else scope.diff_sha256
+    return VerificationEvidence(
+        f"{metadata.id}#{rule.ref}",
+        datetime.now(timezone.utc).isoformat(),
+        status,
+        rule.text_sha256,
+        outcome.artifact_sha256,
+        diff_hash,
+        _result_hash(status, outcome.error_code, outcome.details),
+        outcome.error_code,
+        outcome.details,
+    )
+
+
+def run_all_verifiers(
+    metadata: SpecMetadata,
+    scope: VerificationScope,
+    confirmations: Optional[Mapping[str, Mapping[str, object]]] = None,
+) -> VerificationResult:
+    verifier_by_rule = {item.rule: item for item in metadata.verifiers}
+    confirmation_by_rule = confirmations or {}
+    evidence: list[VerificationEvidence] = []
+    for rule in metadata.rules:
+        if rule.enforcement != "required":
+            continue
+        verifier = verifier_by_rule.get(rule.ref)
+        if verifier is None:
+            details = {"rule": rule.ref}
+            evidence.append(
+                VerificationEvidence(
+                    f"{metadata.id}#{rule.ref}",
+                    datetime.now(timezone.utc).isoformat(),
+                    "unverified",
+                    rule.text_sha256,
+                    None,
+                    scope.diff_sha256,
+                    _result_hash("unverified", "verifier_missing", details),
+                    "verifier_missing",
+                    details,
+                )
+            )
+            continue
+        evidence.append(_evidence(metadata, rule, verifier, scope, confirmation_by_rule.get(rule.ref)))
+    result = tuple(evidence)
+    return VerificationResult(result, bool(result) and all(item.status == "verified" for item in result))
+
+
+def evidence_is_fresh(
+    evidence: VerificationEvidence,
+    rule_text_sha256: str,
+    artifact_sha256: Optional[str],
+    diff_sha256: Optional[str],
+) -> bool:
+    return (
+        evidence.status == "verified"
+        and evidence.rule_text_sha256 == rule_text_sha256
+        and evidence.artifact_sha256 == artifact_sha256
+        and evidence.diff_sha256 == diff_sha256
+    )

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

@@ -13,7 +13,6 @@ from cf_core import (
     estimate_tokens,
     load_config,
     non_injectable_specs,
-    resolve_inject_mode,
     resolve_quality_loop,
 )
 
@@ -96,6 +95,41 @@ def quality_loop_summary(project_root: str, config: dict) -> dict:
     return summary
 
 
+def _percent(numerator: int, denominator: int) -> str:
+    return f"{round(numerator * 100 / denominator)}%" if denominator else "n/a"
+
+
+def spec_workflow_summary(project_root: str) -> dict:
+    events = cf_log.read_events(project_root, days=30)
+    candidates = {
+        (str((event.get("data") or {}).get("task")), str((event.get("data") or {}).get("rule")))
+        for event in events if event.get("event") == "spec_candidate"
+    }
+    bound = {
+        (str((event.get("data") or {}).get("task")), str((event.get("data") or {}).get("rule")))
+        for event in events if event.get("event") == "spec_bound"
+    }
+    gates = [event for event in events if event.get("event") == "spec_gate"]
+    first_pass = sum((event.get("data") or {}).get("first_pass") is True for event in gates)
+    late = sum(event.get("event") == "late_violation" for event in events)
+    statuses = {"stale": 0, "conflict": 0, "not_applicable": 0}
+    for event in events:
+        status = (event.get("data") or {}).get("status")
+        if status in statuses:
+            statuses[status] += 1
+    degraded = sum(event.get("event") == "metrics_degraded" for event in events)
+    return {
+        "window_days": 30,
+        "coverage": _percent(len(bound & candidates), len(candidates)),
+        "first_compliance_rate": _percent(first_pass, len(gates)),
+        "late_violation_rate": _percent(late, len(bound)),
+        "statuses": statuses,
+        "data_complete": degraded == 0,
+        "degraded_events": degraded,
+        "read_note": "read 仅表示读取，不代表理解",
+    }
+
+
 def read_text(path: str) -> str:
     try:
         with open(path, "r", encoding="utf-8") as file:
@@ -324,20 +358,20 @@ def main() -> None:
         "total_saved_pct": total_saved_pct,
     }
 
-    inject_mode = resolve_inject_mode(config.get("inject") or {})
     try:
         catalog_max = int(budget_cfg.get("catalog_max", 200))
-    except Exception:
+    except (TypeError, ValueError):
         catalog_max = 200
     catalog_text = build_spec_catalog(project_root, effective_mapping, catalog_max)
     catalog_summary = {
-        "mode": inject_mode,
+        "mode": "context_first",
         "tokens": estimate_tokens(catalog_text),
         "budget": catalog_max,
         "entries": catalog_text.count("\n- `"),
     }
 
     ql_summary = quality_loop_summary(project_root, config)
+    workflow_summary = spec_workflow_summary(project_root)
 
     output = {
         "l0": {"file": "CLAUDE.md", "tokens": l0_tokens, "budget": l0_budget},
@@ -351,6 +385,7 @@ def main() -> None:
         "compression_summary": compression_summary,
         "catalog": catalog_summary,
         "quality_loop": ql_summary,
+        "spec_workflow": workflow_summary,
         "templates": {
             "tokens": templates_tokens,
             "files": sorted(excluded_specs),
@@ -394,7 +429,7 @@ def main() -> None:
     )
     print(
         "CATALOG:",
-        f"mode={inject_mode},",
+        "mode=context_first,",
         f"{catalog_summary['tokens']} / {catalog_max} tokens,",
         f"{catalog_summary['entries']} entries",
     )

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

@@ -18,6 +18,8 @@ import subprocess
 import sys
 
 import cf_log
+from cf_spec_context import load_active_task
+from cf_task_runtime import run_done_gate
 from cf_core import (
     _log,
     ensure_utf8_io,
@@ -243,13 +245,31 @@ def main() -> None:
         if data.get("stop_hook_active"):
             return  # 已因本 hook 续跑过一轮，避免循环
         project_root = os.getcwd()
+        sid = resolve_session_id(data)
+        marker = os.path.join(project_root, ".code-flow", ".active-task.json")
+        has_active = os.path.exists(marker)
+        files = []
+        if has_active:
+            try:
+                active = load_active_task(project_root)
+                task_dir = os.path.join(project_root, active.task_dir)
+                done = run_done_gate(project_root, task_dir)
+            except (OSError, ValueError) as exc:
+                payload = {"decision": "block", "reason": f"SPEC_WORKFLOW_BLOCKED: active task is invalid: {exc}"}
+                sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+                return
+            if done.decision != "pass":
+                payload = {"decision": "block", "reason": "当前 TASK required Spec verifier/Evidence 未通过；修复或重新对齐后再 Done。"}
+                sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+                return
+            files = list(done.files)
         config = load_config(project_root)
         if not config:
             return
         if not resolve_quality_loop(config)["stop_check"]:
             return
-        sid = resolve_session_id(data)
-        files = session_edited_files(project_root, sid)
+        if not has_active:
+            files = session_edited_files(project_root, sid)
         if not files:
             return
         acceptance_failures = task_acceptance_failures(project_root, files)

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

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Active-task scope expansion and hash-bound Done verification."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+import hashlib
+from pathlib import Path
+from typing import Mapping
+
+from cf_spec_context import (
+    BindingInput,
+    RuleBinding,
+    RuleStageStatus,
+    SpecBinding,
+    SpecContext,
+    bind_specs,
+    current_owned_paths,
+    load_active_task,
+    load_context,
+    pause_active_task,
+    save_context,
+)
+from cf_spec_gate import validate_stage
+from cf_spec_metadata import load_spec_metadata
+from cf_spec_resolver import resolve_candidates, SpecCandidate
+from cf_spec_verify import VerificationEvidence, VerificationScope, run_all_verifiers
+
+
+@dataclass(frozen=True)
+class ScopeResult:
+    decision: str
+    files: tuple[str, ...]
+    new_specs: tuple[str, ...]
+    message: str
+
+
+@dataclass(frozen=True)
+class DoneResult:
+    decision: str
+    files: tuple[str, ...]
+    evidence: tuple[Mapping[str, object], ...]
+
+
+def _context_path(task_dir: str) -> str:
+    return str(Path(task_dir) / "spec-context.yml")
+
+
+def _required_candidate(candidate: SpecCandidate) -> bool:
+    metadata = candidate.metadata
+    return metadata.enforcement == "required" and any(
+        rule.enforcement == "required" for rule in metadata.rules
+    )
+
+
+def evaluate_scope(root: str, task_dir: str) -> ScopeResult:
+    active = load_active_task(root)
+    files = current_owned_paths(root, active)
+    context = load_context(_context_path(task_dir))
+    candidates = resolve_candidates(root, "code", files)
+    existing = {binding.spec_id for binding in context.bindings}
+    new = tuple(
+        candidate
+        for candidate in candidates
+        if candidate.scope == "path" and candidate.spec_id not in existing
+    )
+    if not new:
+        return ScopeResult("continue", files, (), "scope unchanged")
+    selections = tuple(
+        BindingInput(candidate, "scope:path", f"Git diff matched {','.join(candidate.matched_paths)}")
+        for candidate in new
+    )
+    save_context(_context_path(task_dir), bind_specs(context, selections))
+    required = tuple(candidate.spec_id for candidate in new if _required_candidate(candidate))
+    if required:
+        pause_active_task(root)
+        message = "新增 required Spec 已暂停 TASK；请选择局部 Plan 或回 Align 更新设计"
+        return ScopeResult("pause", files, required, message)
+    return ScopeResult("continue", files, tuple(candidate.spec_id for candidate in new), "advisory scope expanded")
+
+
+def _diff_hash(root: str, files: tuple[str, ...]) -> str:
+    digest = hashlib.sha256()
+    for relative in files:
+        path = Path(root) / relative
+        digest.update(relative.encode())
+        digest.update(path.read_bytes() if path.is_file() else b"<deleted>")
+    return digest.hexdigest()
+
+
+def _evidence_data(evidence: VerificationEvidence) -> Mapping[str, object]:
+    return {
+        "verifier_ref": evidence.verifier_ref,
+        "executed_at": evidence.executed_at,
+        "status": evidence.status,
+        "rule_text_sha256": evidence.rule_text_sha256,
+        "artifact_sha256": evidence.artifact_sha256,
+        "diff_sha256": evidence.diff_sha256,
+        "result_sha256": evidence.result_sha256,
+        "error_code": evidence.error_code,
+        "details": evidence.details,
+    }
+
+
+def _update_rule(rule: RuleBinding, evidence: Mapping[str, object]) -> RuleBinding:
+    if "code" not in rule.stage_status:
+        return rule
+    statuses = dict(rule.stage_status)
+    current = statuses["code"]
+    status = "verified" if evidence.get("status") == "verified" else "unverified"
+    statuses["code"] = replace(current, status=status, evidence=(*current.evidence, evidence))
+    return replace(rule, stage_status=statuses)
+
+
+def _apply_evidence(context: SpecContext, evidence: tuple[Mapping[str, object], ...]) -> SpecContext:
+    by_ref = {str(item["verifier_ref"]): item for item in evidence}
+    bindings: list[SpecBinding] = []
+    for binding in context.bindings:
+        rules = tuple(
+            _update_rule(rule, by_ref[f"{binding.spec_id}#{rule.ref}"])
+            if f"{binding.spec_id}#{rule.ref}" in by_ref else rule
+            for rule in binding.rules
+        )
+        bindings.append(replace(binding, rules=rules))
+    return replace(context, bindings=tuple(bindings))
+
+
+def run_done_gate(root: str, task_dir: str) -> DoneResult:
+    scope_result = evaluate_scope(root, task_dir)
+    if scope_result.decision == "pause":
+        return DoneResult("block", scope_result.files, ())
+    context = load_context(_context_path(task_dir))
+    diff_hash = _diff_hash(root, scope_result.files)
+    all_evidence: list[Mapping[str, object]] = []
+    for binding in context.bindings:
+        metadata = load_spec_metadata(str(Path(root) / ".code-flow/specs" / binding.path))
+        result = run_all_verifiers(metadata, VerificationScope(root, scope_result.files, diff_hash))
+        all_evidence.extend(_evidence_data(item) for item in result.evidence)
+    updated = _apply_evidence(context, tuple(all_evidence))
+    save_context(_context_path(task_dir), updated)
+    gate = validate_stage(updated, "code")
+    return DoneResult(gate.decision, scope_result.files, tuple(all_evidence))