@michaelxwb/code-flow 0.5.2 → 0.6.1

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

@@ -0,0 +1,340 @@
+#!/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
+import time
+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, timeout_cap: Optional[float] = None) -> _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
+    if timeout_cap is not None:
+        timeout = min(timeout, timeout_cap)
+    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]],
+    timeout_cap: Optional[float] = None,
+) -> _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, timeout_cap)
+    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]],
+    timeout_cap: Optional[float] = None,
+) -> VerificationEvidence:
+    outcome = _run(verifier, metadata, scope, confirmation, timeout_cap)
+    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 _skipped_evidence(metadata: SpecMetadata, rule: SpecRule, scope: VerificationScope) -> VerificationEvidence:
+    details = {"skipped": True}
+    return VerificationEvidence(
+        f"{metadata.id}#{rule.ref}",
+        datetime.now(timezone.utc).isoformat(),
+        "unverified",
+        rule.text_sha256,
+        None,
+        scope.diff_sha256,
+        _result_hash("unverified", "skipped_in_cheap_gate", details),
+        "skipped_in_cheap_gate",
+        details,
+    )
+
+
+def _budget_evidence(metadata: SpecMetadata, rule: SpecRule, scope: VerificationScope, budget: float) -> VerificationEvidence:
+    details = {"budget": budget}
+    return VerificationEvidence(
+        f"{metadata.id}#{rule.ref}",
+        datetime.now(timezone.utc).isoformat(),
+        "unverified",
+        rule.text_sha256,
+        None,
+        scope.diff_sha256,
+        _result_hash("unverified", "verifier_budget_exhausted", details),
+        "verifier_budget_exhausted",
+        details,
+    )
+
+
+def run_all_verifiers(
+    metadata: SpecMetadata,
+    scope: VerificationScope,
+    confirmations: Optional[Mapping[str, Mapping[str, object]]] = None,
+    skip_command: bool = False,
+    timeout_budget: Optional[float] = None,
+) -> VerificationResult:
+    verifier_by_rule = {item.rule: item for item in metadata.verifiers}
+    confirmation_by_rule = confirmations or {}
+    evidence: list[VerificationEvidence] = []
+    started = time.monotonic()
+    for rule in metadata.rules:
+        if rule.enforcement != "required":
+            continue
+        if timeout_budget is not None:
+            remaining = timeout_budget - (time.monotonic() - started)
+            if remaining <= 0:
+                evidence.append(_budget_evidence(metadata, rule, scope, timeout_budget))
+                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
+        if skip_command and verifier.type in ("command", "test"):
+            evidence.append(_skipped_evidence(metadata, rule, scope))
+            continue
+        cap = None if timeout_budget is None else max(0.1, timeout_budget - (time.monotonic() - started))
+        evidence.append(_evidence(metadata, rule, verifier, scope, confirmation_by_rule.get(rule.ref), cap))
+    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,16 +18,20 @@ 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,
     load_config,
     normalize_path,
+    resolve_enforcement,
     resolve_quality_loop,
     resolve_session_id,
 )
 
 TOTAL_BUDGET_SECONDS = 30.0
+GATE_BUDGET_SECONDS = 25.0
 _BRACE_RE = re.compile(r"\{([^{}]+)\}")
 _TASK_SECTION_RE = re.compile(
     r"(?ms)^## (TASK-\d+):.*?(?=^## TASK-\d+:|\Z)"
@@ -243,13 +247,43 @@ def main() -> None:
         if data.get("stop_hook_active"):
             return  # 已因本 hook 续跑过一轮，避免循环
         project_root = os.getcwd()
+        sid = resolve_session_id(data)
         config = load_config(project_root)
         if not config:
             return
+        enforcement = resolve_enforcement(config)
+        if enforcement == "inject":
+            return  # 轻量模式：只注入不门禁，停止会话不受限
+        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, budget=GATE_BUDGET_SECONDS)
+            except (OSError, ValueError) as exc:
+                if enforcement == "required":
+                    payload = {"decision": "block", "reason": f"SPEC_WORKFLOW_BLOCKED: active task is invalid: {exc}"}
+                    sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+                    return
+                cf_log.append_event(project_root, "stop_check", {"gate": "invalid_active_nonfatal", "error": str(exc)}, sid)
+                files = []
+            else:
+                if done.decision != "pass":
+                    reason = done.message or "当前 TASK required Spec verifier/Evidence 未通过；修复或重新对齐后再 Done。"
+                    if any(item.get("error_code") == "verifier_budget_exhausted" for item in done.evidence):
+                        reason += "（验证预算不足，部分 verifier 未运行，请拆分 TASK 或减少验证命令）"
+                    if enforcement == "required":
+                        payload = {"decision": "block", "reason": reason}
+                        sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+                        return
+                    cf_log.append_event(project_root, "stop_check", {"gate": "blocked_nonfatal", "reason": reason}, sid)
+                files = list(done.files)
         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)
@@ -260,6 +294,13 @@ def main() -> None:
         failures = acceptance_failures + failures
         if not failures:
             return  # 全过或无 validation.yml 且无验收缺口时静默
+        if enforcement == "warn":
+            cf_log.append_event(
+                project_root, "stop_check",
+                {"failures": [item["name"] for item in failures], "nonfatal": True},
+                sid,
+            )
+            return
         payload = {"decision": "block", "reason": _reason_text(failures, truncated)}
         sys.stdout.write(json.dumps(payload, ensure_ascii=False))
     except Exception as exc:

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

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""cf-sync: one-command canonical → deploy sync for dual-copy artifacts.
+
+Pairs (canonical source → deployed live copy), each with an explicit include
+prefix list — project-owned trees (specs/, tasks/) and deploy-only files
+(config.toml, CLAUDE.md, opencode.json) are never touched:
+
+  src/core/code-flow         → .code-flow        (scripts/, config.yml, .version, validation.yml, .gitignore)
+  src/adapters/claude        → .claude           (commands/, settings.local.json)
+  src/adapters/codex         → .codex            (hooks.json)
+  src/adapters/codex/skills  → .agents/skills    (everything)
+  src/adapters/costrict      → .costrict         (commands/, settings.local.json)
+  src/adapters/opencode      → .opencode         (commands/, plugins/)
+
+`check` (default) reports drift; `sync` copies canonical → deploy. Deploy-only
+files are never deleted (use --prune to remove files whose source side no
+longer contains them within the include prefixes).
+"""
+
+import argparse
+import filecmp
+import os
+from pathlib import Path
+import shutil
+import sys
+from typing import IO, Optional, Sequence
+
+
+PAIRS = (
+    ("src/core/code-flow", ".code-flow", ("scripts/", ".version", ".gitignore")),
+    ("src/adapters/claude", ".claude", ("commands/",)),
+    ("src/adapters/codex", ".codex", ("hooks.json",)),
+    ("src/adapters/codex/skills", ".agents/skills", ("*",)),
+    ("src/adapters/costrict", ".costrict", ("commands/",)),
+    ("src/adapters/opencode", ".opencode", ("commands/", "plugins/")),
+)
+
+_IGNORED_DIRS = {"__pycache__", ".git", "node_modules", "dist", "build"}
+
+
+def _included(relative: str, prefixes: Sequence[str]) -> bool:
+    return any(prefix == "*" or relative.startswith(prefix) for prefix in prefixes)
+
+
+def _walk(source: Path) -> list[str]:
+    files = []
+    for current, dirs, names in os.walk(source):
+        dirs[:] = sorted(item for item in dirs if item not in _IGNORED_DIRS)
+        base = Path(current)
+        for name in names:
+            files.append(str((base / name).relative_to(source)))
+    return sorted(files)
+
+
+def _relative(relative: str) -> str:
+    return relative.replace("\\", "/")
+
+
+def _pair_diffs(root: Path, source_rel: str, deploy_rel: str, prefixes: Sequence[str]) -> tuple[list[str], list[str], list[str]]:
+    """Return (differ, missing_in_deploy, deploy_only_within_prefixes)."""
+    source = root / source_rel
+    deploy = root / deploy_rel
+    differ: list[str] = []
+    missing: list[str] = []
+    for relative in _walk(source):
+        if not _included(_relative(relative), prefixes):
+            continue
+        source_file = source / relative
+        deploy_file = deploy / relative
+        if not deploy_file.exists():
+            missing.append(relative)
+        elif not filecmp.cmp(source_file, deploy_file, shallow=False):
+            differ.append(relative)
+    deploy_only: list[str] = []
+    if deploy.is_dir():
+        deploy_relative = set(_walk(deploy))
+        source_relative = {_relative(item) for item in _walk(source) if _included(_relative(item), prefixes)}
+        deploy_only = sorted(item for item in deploy_relative if item not in source_relative and _included(item, prefixes))
+    return differ, missing, deploy_only
+
+
+def _report(stdout: IO[str], root: Path, verbose: bool) -> int:
+    drift = 0
+    for source_rel, deploy_rel, prefixes in PAIRS:
+        differ, missing, deploy_only = _pair_diffs(root, source_rel, deploy_rel, prefixes)
+        status = "OK " if not (differ or missing) else "DRIFT"
+        stdout.write(f"{status} {source_rel} -> {deploy_rel}\n")
+        for relative in differ:
+            stdout.write(f"  diff  {deploy_rel}/{relative}\n")
+            drift += 1
+        for relative in missing:
+            stdout.write(f"  miss  {deploy_rel}/{relative}\n")
+            drift += 1
+        if verbose and deploy_only:
+            stdout.write(f"  only-in-deploy ({len(deploy_only)}):\n")
+            for relative in deploy_only[:10]:
+                stdout.write(f"    {deploy_rel}/{relative}\n")
+    return drift
+
+
+def _sync(root: Path, stdout: IO[str]) -> int:
+    copied = 0
+    for source_rel, deploy_rel, prefixes in PAIRS:
+        source = root / source_rel
+        deploy = root / deploy_rel
+        for relative in _walk(source):
+            if not _included(_relative(relative), prefixes):
+                continue
+            source_file = source / relative
+            deploy_file = deploy / relative
+            if deploy_file.exists() and filecmp.cmp(source_file, deploy_file, shallow=False):
+                continue
+            deploy_file.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(source_file, deploy_file)
+            stdout.write(f"sync  {deploy_rel}/{relative}\n")
+            copied += 1
+    return copied
+
+
+def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:
+    parser = argparse.ArgumentParser(prog="cf_sync.py")
+    parser.add_argument("action", choices=("check", "sync"), nargs="?", default="check")
+    parser.add_argument("--root", default=".")
+    parser.add_argument("--verbose", action="store_true")
+    args = parser.parse_args(argv)
+    root = Path(args.root).resolve()
+    if args.action == "check":
+        drift = _report(stdout, root, args.verbose)
+        if drift:
+            stdout.write(f"{drift} file(s) drifted; run `cf_sync.py sync` to deploy.\n")
+            return 1
+        stdout.write("all pairs in sync.\n")
+        return 0
+    copied = _sync(root, stdout)
+    stdout.write(f"{copied} file(s) deployed.\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())