@michaelxwb/code-flow 0.6.5 → 0.8.1

package/src/core/code-flow/scripts/codeflow/spec/cf_context_refresh.py

@@ -0,0 +1,301 @@
+"""Bind and refresh Spec Context against real Specs and task artifacts."""
+from __future__ import annotations
+
+from dataclasses import replace
+import hashlib
+import json
+from pathlib import Path
+import time
+from typing import Optional, Sequence
+
+from codeflow.core.cf_core import phase_timing
+from codeflow.core.cf_log import warn
+from codeflow.spec.cf_spec_context_model import (
+    BindingInput, ContextError, DriftChange, DriftResult, RuleBinding, RuleStageStatus,
+    SpecBinding, SpecContext, now_iso,
+)
+from codeflow.spec.cf_spec_metadata import SpecMetadata, SpecRule, load_spec_metadata
+
+
+FILE_HASH_CACHE: dict[str, tuple[int, int, int, str]] = {}
+_PERSISTENT_HASH_CACHE: dict[str, dict[str, object]] = {}
+_PERSISTENT_HASH_PATHS: set[str] = set()
+_MAX_HASH_CACHE_ENTRIES = 4096
+
+
+def _binding_from_input(selection: BindingInput) -> SpecBinding:
+    if not selection.selected_by.strip() or not selection.reason.strip():
+        raise ContextError("invalid_binding", "selection", "selected_by/reason 必须非空")
+    candidate = selection.candidate
+    verifier_by_rule = {item.rule: item for item in candidate.metadata.verifiers}
+    rules: list[RuleBinding] = []
+    for rule in candidate.metadata.rules:
+        if rule.enforcement == "informational":
+            continue
+        enforcement = "advisory" if candidate.metadata.enforcement == "advisory" else rule.enforcement
+        statuses = {
+            stage: RuleStageStatus("pending", (), None, ()) for stage in candidate.metadata.stages
+        }
+        verifier = verifier_by_rule.get(rule.ref)
+        verifier_ref = f"{candidate.spec_id}#{rule.ref}" if verifier is not None else "advisory:none"
+        rules.append(
+            RuleBinding(
+                rule.ref, rule.text, rule.text_sha256, enforcement, verifier_ref, statuses,
+                verifier.stage if verifier is not None else "code",
+            )
+        )
+    return SpecBinding(
+        candidate.spec_id,
+        candidate.path,
+        candidate.metadata.hashes,
+        selection.selected_by.strip(),
+        selection.reason.strip(),
+        candidate.metadata.enforcement,
+        candidate.metadata.stages,
+        tuple(rules),
+    )
+
+
+def _with_declared_stages(rule: RuleBinding, stages: Sequence[str]) -> RuleBinding:
+    """兼容补齐：绑定旧版本时声明的 stages 缺状态，按声明补 pending。"""
+    missing = [stage for stage in stages if stage not in rule.stage_status]
+    if not missing:
+        return rule
+    statuses = dict(rule.stage_status)
+    for stage in missing:
+        statuses[stage] = RuleStageStatus("pending", (), None, ())
+    return replace(rule, stage_status=statuses)
+
+
+def _rule_from_metadata(spec_id: str, metadata: SpecMetadata, rule: SpecRule) -> RuleBinding:
+    enforcement = "advisory" if metadata.enforcement == "advisory" else rule.enforcement
+    statuses = {stage: RuleStageStatus("pending", (), None, ()) for stage in metadata.stages}
+    verifier = next((item for item in metadata.verifiers if item.rule == rule.ref), None)
+    verifier_ref = f"{spec_id}#{rule.ref}" if verifier is not None else "advisory:none"
+    return RuleBinding(
+        rule.ref, rule.text, rule.text_sha256, enforcement, verifier_ref, statuses,
+        verifier.stage if verifier is not None else "code",
+    )
+
+
+def bind_specs(context: SpecContext, selections: Sequence[BindingInput]) -> SpecContext:
+    bindings = {binding.spec_id: binding for binding in context.bindings}
+    for selection in selections:
+        incoming = _binding_from_input(selection)
+        existing = bindings.get(incoming.spec_id)
+        if existing is not None and existing.hashes != incoming.hashes:
+            raise ContextError(
+                "stale_binding",
+                "selection",
+                f"{incoming.spec_id} 已绑定版本发生变化，请先 refresh",
+            )
+        if existing is not None:
+            incoming = replace(
+                existing,
+                selected_by=incoming.selected_by,
+                reason=incoming.reason,
+                enforcement=incoming.enforcement,
+                stages=incoming.stages,
+            )
+        bindings[incoming.spec_id] = incoming
+    ordered = tuple(bindings[key] for key in sorted(bindings))
+    if ordered == context.bindings:
+        return context
+    return replace(context, updated_at=now_iso(), bindings=ordered)
+
+
+def refresh_missing_specs(context: SpecContext, root: str) -> SpecContext:
+    spec_root = Path(root) / ".code-flow" / "specs"
+    bindings: list[SpecBinding] = []
+    for binding in context.bindings:
+        if (spec_root / binding.path).is_file():
+            bindings.append(binding)
+            continue
+        rules = []
+        for rule in binding.rules:
+            stages = {stage: replace(status, status="stale") for stage, status in rule.stage_status.items()}
+            rules.append(replace(rule, stage_status=stages))
+        bindings.append(replace(binding, status="missing", rules=tuple(rules)))
+    return replace(context, updated_at=now_iso(), bindings=tuple(bindings))
+
+
+def _stale_rule(rule: RuleBinding) -> RuleBinding:
+    statuses = {stage: replace(status, status="stale") for stage, status in rule.stage_status.items()}
+    return replace(rule, stage_status=statuses)
+
+
+def _removed_rule(rule: RuleBinding) -> RuleBinding:
+    statuses = {
+        stage: status
+        if status.status in ("not_applicable", "waived") and status.decision is not None
+        else replace(status, status="stale")
+        for stage, status in rule.stage_status.items()
+    }
+    return replace(rule, stage_status=statuses)
+
+
+def _load_hash_cache(cache_path: Optional[Path]) -> None:
+    if cache_path is None or str(cache_path) in _PERSISTENT_HASH_PATHS:
+        return
+    try:
+        loaded = json.loads(cache_path.read_text(encoding="utf-8"))
+        if not isinstance(loaded, dict):
+            raise ValueError("expected an object")
+        _PERSISTENT_HASH_CACHE.update({str(k): v for k, v in loaded.items() if isinstance(v, dict)})
+    except FileNotFoundError:
+        loaded = {}
+    except (OSError, ValueError) as exc:
+        warn(f"artifact hash cache unavailable; rebuilding: {exc}")
+    _PERSISTENT_HASH_PATHS.add(str(cache_path))
+
+
+def _store_hash_cache(cache_path: Optional[Path], key: str, signature: tuple[int, int, int], digest: str) -> None:
+    if cache_path is None:
+        return
+    _PERSISTENT_HASH_CACHE[key] = dict(zip(("mtime_ns", "size", "ino", "sha256"), (*signature, digest)))
+    while len(_PERSISTENT_HASH_CACHE) > _MAX_HASH_CACHE_ENTRIES:
+        _PERSISTENT_HASH_CACHE.pop(next(iter(_PERSISTENT_HASH_CACHE)))
+    try:
+        temporary = cache_path.with_suffix(".json.tmp")
+        temporary.write_text(json.dumps(_PERSISTENT_HASH_CACHE, ensure_ascii=False, sort_keys=True), encoding="utf-8")
+        temporary.replace(cache_path)
+    except OSError as exc:
+        warn(f"artifact hash cache could not be saved: {exc}")
+
+
+def file_sha256(path: Path) -> str:
+    try:
+        stat = path.stat()
+        key = str(path)
+        signature = (stat.st_mtime_ns, stat.st_size, stat.st_ino)
+        cached = FILE_HASH_CACHE.get(key)
+        if cached is not None and cached[:3] == signature:
+            return cached[3]
+        cache_path = next((parent / ".artifact-hash-cache.json" for parent in path.parents
+                           if parent.name == ".code-flow"), None)
+        _load_hash_cache(cache_path)
+        persistent = _PERSISTENT_HASH_CACHE.get(key)
+        if isinstance(persistent, dict) and tuple(persistent.get(k) for k in ("mtime_ns", "size", "ino")) == signature:
+            digest = persistent.get("sha256")
+            if isinstance(digest, str) and digest:
+                FILE_HASH_CACHE[key] = (*signature, digest)
+                return digest
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        FILE_HASH_CACHE[key] = (*signature, digest)
+        _store_hash_cache(cache_path, key, signature, digest)
+        return digest
+    except OSError as exc:
+        raise ContextError("artifact_read_error", "artifact", str(exc), str(path)) from exc
+
+
+def _refresh_artifacts(
+    spec_id: str, rule: RuleBinding, artifact_root: Path
+) -> tuple[RuleBinding, tuple[DriftChange, ...]]:
+    statuses = dict(rule.stage_status)
+    changes: list[DriftChange] = []
+    for stage, status in rule.stage_status.items():
+        for reference in status.refs:
+            path = artifact_root / reference.artifact
+            current = file_sha256(path) if path.is_file() else "missing"
+            if current == reference.artifact_sha256:
+                continue
+            if status.status == "applied" and current != "missing":
+                statuses[stage] = replace(
+                    status,
+                    refs=tuple(
+                        replace(item, artifact_sha256=current) if item is reference else item
+                        for item in status.refs
+                    ),
+                )
+            else:
+                statuses[stage] = replace(status, status="stale")
+            changes.append(
+                DriftChange("artifact_changed", spec_id, rule.ref, reference.artifact_sha256, current, (stage,))
+            )
+            break
+    return replace(rule, stage_status=statuses), tuple(changes)
+
+
+def _refresh_existing_rule(
+    binding: SpecBinding, existing: RuleBinding, current: SpecRule, metadata: SpecMetadata
+) -> tuple[RuleBinding, Optional[DriftChange]]:
+    enforcement = "advisory" if metadata.enforcement == "advisory" else current.enforcement
+    verifier = next((item for item in metadata.verifiers if item.rule == current.ref), None)
+    verifier_ref = f"{binding.spec_id}#{current.ref}" if verifier is not None else "advisory:none"
+    updated = replace(
+        existing,
+        summary=current.text,
+        text_sha256=current.text_sha256,
+        enforcement=enforcement,
+        verifier_ref=verifier_ref,
+        verifier_stage=verifier.stage if verifier is not None else "code",
+    )
+    if existing.text_sha256 == current.text_sha256:
+        return updated, None
+    change = DriftChange(
+        "rule_changed", binding.spec_id, current.ref, existing.text_sha256, current.text_sha256, tuple(existing.stage_status)
+    )
+    return _stale_rule(updated), change
+
+
+def _refresh_binding(
+    binding: SpecBinding, spec_root: Path, artifact_root: Path
+) -> tuple[SpecBinding, tuple[DriftChange, ...]]:
+    path = spec_root / binding.path
+    if not path.is_file():
+        stale = replace(binding, status="missing", rules=tuple(_stale_rule(rule) for rule in binding.rules))
+        change = DriftChange("spec_missing", binding.spec_id, "", binding.hashes.file_sha256, "missing", binding.stages)
+        return stale, (change,)
+    metadata = load_spec_metadata(str(path))
+    existing = {rule.ref: rule for rule in binding.rules}
+    rules: list[RuleBinding] = []
+    changes: list[DriftChange] = []
+    if metadata.hashes.metadata_sha256 != binding.hashes.metadata_sha256:
+        changes.append(
+            DriftChange("metadata_changed", binding.spec_id, "", binding.hashes.metadata_sha256, metadata.hashes.metadata_sha256, ())
+        )
+    for current in metadata.rules:
+        if current.enforcement == "informational":
+            continue
+        prior = existing.pop(current.ref, None)
+        if prior is None:
+            rule = _rule_from_metadata(binding.spec_id, metadata, current)
+            changes.append(DriftChange("rule_added", binding.spec_id, current.ref, "", current.text_sha256, metadata.stages))
+        else:
+            rule, change = _refresh_existing_rule(binding, prior, current, metadata)
+            if change is not None:
+                changes.append(change)
+        rule = _with_declared_stages(rule, metadata.stages)
+        rule, artifact_changes = _refresh_artifacts(binding.spec_id, rule, artifact_root)
+        rules.append(rule)
+        changes.extend(artifact_changes)
+    for removed in existing.values():
+        rules.append(_removed_rule(removed))
+        changes.append(DriftChange("rule_removed", binding.spec_id, removed.ref, removed.text_sha256, "missing", tuple(removed.stage_status)))
+    updated = replace(binding, hashes=metadata.hashes, enforcement=metadata.enforcement, stages=metadata.stages, rules=tuple(rules), status="active")
+    return updated, tuple(changes)
+
+
+def refresh_context(context: SpecContext, root: str, artifact_root: Optional[str] = None) -> DriftResult:
+    started = time.monotonic()
+    specs = Path(root) / ".code-flow" / "specs"
+    artifacts = Path(artifact_root) if artifact_root is not None else Path(root)
+    bindings: list[SpecBinding] = []
+    changes: list[DriftChange] = []
+    for binding in context.bindings:
+        phase_started = time.monotonic()
+        updated, binding_changes = _refresh_binding(binding, specs, artifacts)
+        phase_timing(f"context.refresh.{binding.spec_id}", phase_started)
+        bindings.append(updated)
+        changes.extend(binding_changes)
+    refreshed = replace(context, updated_at=now_iso(), bindings=tuple(bindings))
+    phase_timing("context.refresh.total", started)
+    if refreshed.bindings == context.bindings:
+        return DriftResult(context, tuple(changes))
+    return DriftResult(refreshed, tuple(changes))
+
+
+def diff_spec_hashes(context: SpecContext, root: str) -> DriftResult:
+    return refresh_context(context, root)
+
+

package/src/core/code-flow/scripts/codeflow/spec/cf_edit_service.py

@@ -0,0 +1,149 @@
+"""Platform-neutral edit routing and compliance services."""
+import os
+from pathlib import Path
+from typing import Sequence
+
+from codeflow.core import cf_log
+from codeflow.acceptance.cf_checks import load_check_state, load_spec_checks, record_hits, run_checks, save_check_state
+from codeflow.core.cf_core import (build_effective_mapping, effective_project_root, is_code_file, load_config,
+                     match_domains, normalize_path, normalize_spec_entry, resolve_enforcement, resolve_quality_loop)
+from codeflow.spec.cf_injection import injection_text
+from codeflow.spec.cf_spec_router import RouterError, route_prompt
+
+FEEDBACK_HINT = '如认为误报，直接告诉我"这是误报"，我会标记忽略。'
+_REPORTED_KEY = "_reported"
+
+
+def _collect_checks(project_root: str, domains: list[str], mapping: dict[str, object]) -> list[dict[str, object]]:
+    """Aggregate checks of all constraint specs in matched domains.
+
+    Each check is annotated with its source spec path. Checks apply whenever
+    their own `files` glob matches — independent of injection tag gating.
+    """
+    specs_root = os.path.join(project_root, ".code-flow", "specs")
+    collected = []
+    seen_specs = set()
+    for domain in domains:
+        for entry in (mapping.get(domain) or {}).get("specs") or []:
+            cfg = normalize_spec_entry(entry)
+            rel = cfg.get("path")
+            if not rel or rel in seen_specs or not cfg.get("tags"):
+                continue
+            seen_specs.add(rel)
+            checks, _ = load_spec_checks(os.path.join(specs_root, rel))
+            for check in checks:
+                item = dict(check)
+                item["spec"] = rel
+                collected.append(item)
+    return collected
+
+
+def _session_reported(state: dict[str, object], sid: str) -> set[str]:
+    session = state.get(_REPORTED_KEY) or {}
+    if session.get("sid") != sid:
+        return set()
+    return set(session.get("keys") or [])
+
+
+def _save_reported(project_root: str, state: dict[str, object], sid: str, keys: set[str]) -> None:
+    state[_REPORTED_KEY] = {"sid": sid, "keys": sorted(keys)}
+    save_check_state(project_root, state)
+
+
+def _feedback_text(violations: list[dict[str, object]]) -> str:
+    lines = ["## Spec 合规反馈 (auto-check)", ""]
+    for v in violations:
+        lines.append(f"⚠ {v['message']}（规则: {v['spec']}#{v['check_id']}）")
+        lines.append(f"  违规行 {v['line_no']}: {v['line']}")
+    lines.append("")
+    lines.append("请修正以上违规后再继续。" + FEEDBACK_HINT)
+    return "\n".join(lines)
+
+
+
+def _routing_result(root: str, relative: str, sid: str) -> tuple[str, tuple[str, ...], bool]:
+    return _route_edits(root, (relative,), sid)
+
+
+def _route_edits(root: str, paths: Sequence[str], sid: str) -> tuple[str, tuple[str, ...], bool]:
+    try:
+        result = route_prompt(root, paths, sid, check_scope=True)
+    except RouterError as exc:
+        return f"SPEC_WORKFLOW_BLOCKED [{exc.code}]: {exc}. Run cf-spec doctor before continuing.", (), True
+    text = injection_text(root, sid, result)
+    emitted = tuple(result.specs) if text else ()
+    if result.expanded_specs:
+        warning = f"⚠ 该路径引入未绑定 required Spec：{', '.join(result.expanded_specs)} — 建议先 refresh Context / Plan 再继续编辑。"
+        text = "\n\n".join(part for part in (warning, text) if part)
+    return text, emitted, False
+
+
+def prepare_edit(session_root: str, path: str, sid: str, tool: str) -> tuple[str, bool]:
+    return prepare_edits(session_root, (path,), sid, tool)
+
+
+def prepare_edits(session_root: str, paths: Sequence[str], sid: str, tool: str) -> tuple[str, bool]:
+    groups: dict[str, list[str]] = {}
+    for path in paths:
+        absolute = path if os.path.isabs(path) else os.path.join(session_root, path)
+        root = effective_project_root(session_root, absolute)
+        relative = normalize_path(os.path.relpath(absolute, root))
+        if relative not in groups.setdefault(root, []):
+            groups[root].append(relative)
+    feedback = []
+    rejected = False
+    for root, relative_paths in groups.items():
+        text, specs, blocked = _route_edits(root, relative_paths, sid)
+        rejected = rejected or blocked
+        if text:
+            feedback.append(text)
+        for relative in relative_paths:
+            cf_log.append_event(root, "edit_intent", {"file": relative, "tool": tool,
+                                "specs": list(specs), "blocked": blocked}, sid)
+    return "\n\n".join(dict.fromkeys(feedback)), rejected
+
+
+def _fresh_violations(root: str, path: str, content: str, checks: list[dict[str, object]], sid: str) -> list[dict[str, object]]:
+    state = load_check_state(root)
+    violations, skipped = run_checks(checks, path, content, state)
+    for item in skipped:
+        cf_log.degrade(root, "post_check", f"{item['check_id']}:{item['reason']}", sid)
+    spec_by_check = {check["id"]: check["spec"] for check in checks}
+    reported = _session_reported(state, sid)
+    fresh = []
+    for violation in violations:
+        key = f"{violation['check_id']}|{violation['file']}"
+        if key not in reported:
+            violation["spec"] = spec_by_check.get(violation["check_id"], "")
+            fresh.append(violation)
+            reported.add(key)
+    if fresh:
+        record_hits(root, sorted({v["check_id"] for v in fresh}))
+        _save_reported(root, load_check_state(root), sid, reported)
+    return fresh
+
+
+def after_edit(session_root: str, path: str, sid: str, tool: str, deleted: bool = False) -> str:
+    absolute = path if os.path.isabs(path) else os.path.join(session_root, path)
+    root = effective_project_root(session_root, absolute)
+    config = load_config(root)
+    if not config or resolve_enforcement(config) == "inject" or not resolve_quality_loop(config)["post_check"]:
+        return ""
+    relative = normalize_path(os.path.relpath(absolute, root))
+    cf_log.append_event(root, "edit", {"file": relative, "tool": tool}, sid)
+    if deleted or not is_code_file(relative, config.get("quality_loop") or {}):
+        return ""
+    mapping = build_effective_mapping(root, config.get("path_mapping") or {})
+    checks = _collect_checks(root, match_domains(relative, mapping), mapping)
+    if not checks:
+        return ""
+    try:
+        content = Path(absolute).read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        cf_log.degrade(root, "post_check", f"read_failed:{relative}:{exc}", sid)
+        return ""
+    fresh = _fresh_violations(root, relative, content, checks, sid)
+    for violation in fresh:
+        cf_log.append_event(root, "violation", {"check_id": violation["check_id"], "spec": violation["spec"],
+                            "file": violation["file"], "severity": violation["severity"]}, sid)
+    return _feedback_text(fresh) if fresh else ""

package/src/core/code-flow/scripts/codeflow/spec/cf_injection.py

@@ -0,0 +1,111 @@
+"""Session-isolated injection deduplication, committed after successful output."""
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Callable, Iterator, TYPE_CHECKING
+
+from codeflow.core import cf_log
+
+if TYPE_CHECKING:
+    from codeflow.spec.cf_spec_router import RouteResult
+
+_PENDING: ContextVar[list[Callable[[], None]] | None] = ContextVar("injection_output", default=None)
+_INTERVAL = 25
+
+
+def defer_commit(action: Callable[[], None]) -> None:
+    pending = _PENDING.get()
+    if pending is None:
+        action()
+    else:
+        pending.append(action)
+
+
+@contextmanager
+def injection_output() -> Iterator[None]:
+    """Discard pending dedup state if building or writing the output fails."""
+    if _PENDING.get() is not None:
+        yield
+        return
+    actions: list[Callable[[], None]] = []
+    token = _PENDING.set(actions)
+    try:
+        yield
+    except BaseException:
+        raise
+    else:
+        for action in actions:
+            action()
+    finally:
+        _PENDING.reset(token)
+
+
+def _state_path(root: str, sid: str) -> Path:
+    name = hashlib.sha256(sid.encode("utf-8")).hexdigest()
+    return Path(root) / ".code-flow/sessions/injection" / f"{name}.json"
+
+
+def _load_state(path: Path) -> dict[str, object]:
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+        return state if isinstance(state, dict) and state.get("version") == 1 else {}
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return {}
+
+
+def _number(state: dict[str, object], key: str) -> int:
+    value = state.get(key, 0)
+    return value if type(value) is int and value >= 0 else 0
+
+
+def _save_state(path: Path, state: dict[str, object]) -> None:
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temporary.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
+        os.replace(temporary, path)
+    except (OSError, UnicodeError, TypeError) as exc:
+        cf_log.warn(f"cf_injection: dedup state unavailable: {exc}")
+    finally:
+        try:
+            temporary.unlink(missing_ok=True)
+        except OSError as exc:
+            cf_log.warn(f"cf_injection: cannot remove temporary dedup state: {exc}")
+
+
+def _commit(root: str, sid: str, result: RouteResult, count: int, fingerprint: str, emitted: bool) -> None:
+    path = _state_path(root, sid)
+    state = _load_state(path)
+    state.update(version=1, prompt_count=count)
+    if emitted:
+        state[f"{result.mode}_fingerprint"] = fingerprint
+        state[f"{result.mode}_last_prompt"] = count
+        cf_log.append_event(root, "inject", {"specs": list(result.specs), "mode": result.mode,
+                            "source": result.mode}, sid)
+    _save_state(path, state)
+
+
+def injection_text(root: str, sid: str, result: RouteResult, *, prompt: bool = False) -> str:
+    if result.mode not in {"task", "path"} or not result.text:
+        return result.text
+    state = _load_state(_state_path(root, sid))
+    count = _number(state, "prompt_count") + int(prompt)
+    fingerprint = hashlib.sha256(
+        (result.mode + "\n" + result.text).encode("utf-8")
+    ).hexdigest()
+    emitted = (state.get(f"{result.mode}_fingerprint") != fingerprint
+               or count - _number(state, f"{result.mode}_last_prompt") >= _INTERVAL)
+    defer_commit(lambda: _commit(root, sid, result, count, fingerprint, emitted))
+    return result.text if emitted else ""
+
+
+def pre_tool_payload(text: str, blocked: bool) -> dict[str, object]:
+    output: dict[str, object] = {"hookEventName": "PreToolUse", "additionalContext": text}
+    if blocked:
+        output.update(permissionDecision="deny", permissionDecisionReason=text)
+    return {"hookSpecificOutput": output}

package/src/core/code-flow/scripts/codeflow/spec/cf_rule_readiness.py

@@ -0,0 +1,114 @@
+"""Resolve artifact references and report unfinished rule applications."""
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+import re
+from typing import Mapping, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from codeflow.spec.cf_spec_context_model import SpecContext
+
+_UNRESOLVED = re.compile(r"\b(?:TBD|TODO)\b|待同步|待确认|待定|需同步\s*spec\s*文本", re.I)
+
+
+def _heading_matches(title: str, section: str, pattern: re.Pattern) -> bool:
+    if pattern.search(title):
+        return True
+    plain = re.sub(r"^\d+(?:\.\d+)*[.)、]?\s+", "", title.strip())
+    slug = re.sub(r"\s+", "-", re.sub(r"[^\w\s-]", "", plain).strip()).casefold()
+    return slug == section.casefold()
+
+
+def referenced_item(text: str, section_id: str, item_id: str) -> str:
+    """Find the item inside its declared section, excluding fenced examples."""
+    clean = re.sub(r"```[^\n]*\n[\s\S]*?```|~~~[^\n]*\n[\s\S]*?~~~", "", text)
+    headings = list(re.finditer(r"(?m)^(#{1,6})[ \t]+([^\n]+)$", clean))
+    section = section_id.lstrip("#§ ").strip()
+    pattern = re.compile(rf"(?<![\w.-]){re.escape(section)}(?![\w.-])", re.I)
+    item_pattern = re.compile(rf"(?<![\w-]){re.escape(item_id)}(?![\w-])", re.I)
+    if not headings:
+        return next((part for part in clean.split("\n\n") if pattern.search(part) and item_pattern.search(part)), "")
+    start = next((entry for entry in headings if _heading_matches(entry.group(2), section, pattern)), None)
+    if start is None:
+        return ""
+    end = next((entry.start() for entry in headings
+                if entry.start() > start.start() and len(entry.group(1)) <= len(start.group(1))), len(clean))
+    lines = clean[start.end():end].splitlines()
+    if re.fullmatch(r"TASK-\d+", section, re.I) and item_id.casefold() == section.casefold():
+        return "\n".join(lines).strip()
+    selected: list[str] = []
+    for line in lines:
+        if item_pattern.search(line):
+            selected.append(line)
+        elif selected and (re.match(r"\s*(?:#{1,6}\s|\|?\s*\[?RULE-|[-*]\s+\[?RULE-)", line)):
+            break
+        elif selected:
+            selected.append(line)
+    return "\n".join(selected).strip()
+
+
+def unresolved_text(text: str) -> bool:
+    # A prohibition mentioning TBD is a valid rule, not an unfinished result.
+    without_prohibitions = re.sub(
+        r"(?:禁止|不得|不能)[^，。;\n]*(?:TBD|TODO|待同步|待确认)[^，。;\n]*", "", text, flags=re.I)
+    return bool(_UNRESOLVED.search(without_prohibitions))
+
+
+def artifact_problem(root: str, artifact: str, section: str, item: str, expected_hash: str = "",
+                     *, task_dir: str = "") -> str:
+    project = Path(root).resolve()
+    base = Path(task_dir).resolve() if task_dir else project
+    target = (base / artifact).resolve()
+    if base not in target.parents or project not in target.parents:
+        return "rule_artifact_outside_project"
+    try:
+        source = target.read_bytes()
+        content = source.decode("utf-8")
+    except (OSError, UnicodeError):
+        return "rule_artifact_missing"
+    if expected_hash and hashlib.sha256(source).hexdigest() != expected_hash:
+        return "rule_artifact_stale"
+    selected = referenced_item(content, section, item)
+    if not selected:
+        return "rule_artifact_reference_missing"
+    return "rule_applied_unresolved" if unresolved_text(selected) else ""
+
+
+def applied_findings(context: SpecContext, root: str, only_stage: str = "",
+                     *, task_dir: str = "") -> list[dict[str, str]]:
+    findings: list[dict[str, str]] = []
+    for binding in context.bindings:
+        for rule in binding.rules:
+            if rule.enforcement != "required":
+                continue
+            for stage, status in rule.stage_status.items():
+                if only_stage and stage != only_stage:
+                    continue
+                if status.status != "applied":
+                    continue
+                for ref in status.refs:
+                    code = artifact_problem(root, ref.artifact, ref.section_id, ref.item_id,
+                                            ref.artifact_sha256, task_dir=task_dir)
+                    if code:
+                        findings.append({"code": code, "severity": "block", "path": ref.artifact,
+                                         "message": f"{binding.spec_id}#{rule.ref} ({stage}): {code}",
+                                         "fix": "完成引用条目并运行 code-flow spec refresh，再执行对应阶段验证"})
+    return findings
+
+
+def convention_findings(root: str, paths: list[str]) -> list[dict[str, str]]:
+    findings: list[dict[str, str]] = []
+    for relative in paths:
+        target = Path(root) / ".code-flow/specs" / relative
+        try:
+            text = target.read_text(encoding="utf-8")
+        except (OSError, UnicodeError) as exc:
+            findings.append({"code": "convention_review_unreadable", "severity": "block", "path": str(target),
+                             "message": str(exc), "fix": "修复绑定 Spec 文件后重跑 doctor"})
+            continue
+        if re.search(r"(?mi)^##\s+(?:Conventions|约定)\s*$", text):
+            findings.append({"code": "convention_review_required", "severity": "warn", "path": str(target),
+                             "message": "Conventions 尚未成为可验证约束；关键条目应提升为有稳定 ID 的 Rules",
+                             "fix": "审查约定与本次设计的一致性；关键约束补充 Rule 和 verifier"})
+    return findings