@michaelxwb/code-flow 0.6.1 → 0.6.3

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

@@ -14,12 +14,12 @@ from pathlib import Path
 import subprocess
 import sys
 import tempfile
+import time
 from typing import IO, Mapping, Optional, Sequence
 
-import yaml
-
 from cf_spec_metadata import SpecHashes, SpecMetadata, SpecRule, load_spec_metadata
 from cf_spec_resolver import SpecCandidate, resolve_candidates
+from cf_core import phase_timing
 
 
 CONTEXT_VERSION = 1
@@ -28,12 +28,17 @@ STAGE_STATUSES = frozenset(
 )
 DECISION_KINDS = frozenset(("not_applicable", "waived", "manual_verification"))
 _AGENT_IDENTITIES = frozenset(("agent", "assistant", "codex", "claude", "opencode", "costrict"))
+_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
 ACTIVE_STATUSES = frozenset(("activating", "active", "paused", "blocked", "completed"))
 DEFAULT_ACTIVE_EXCLUDES = (
     ".code-flow/tasks/*",
     ".code-flow/specs/_session/*",
     ".code-flow/migrations/*",
     ".code-flow/.*state*",
+    ".code-flow/.*cache*",
     ".code-flow/.session-log.jsonl",
     ".code-flow/.active-task.json",
     ".code-flow/.active-task.lock",
@@ -154,6 +159,10 @@ class ActiveBaseline:
     head: Optional[str]
     captured_at: str
     preexisting_changes: Mapping[str, PathSnapshot]
+    # head is frozen at start and never rewritten: task scope is the union of
+    # everything committed since head plus all working-tree changes.
+    # last_seen_head is observation-only (diagnostics), never scope input.
+    last_seen_head: Optional[str] = None
 
 
 @dataclass(frozen=True)
@@ -208,7 +217,7 @@ def _active_paths(root: str) -> tuple[Path, Path]:
 def _run_git(root: str, arguments: Sequence[str]) -> str:
     try:
         result = subprocess.run(
-            ("git", *arguments), cwd=root, text=True, capture_output=True, check=False
+            ("git", *arguments), cwd=root, text=True, encoding="utf-8", capture_output=True, check=False
         )
     except OSError as exc:
         raise ContextError("git_unavailable", "git", str(exc), root) from exc
@@ -267,16 +276,6 @@ def _is_excluded(path: str, patterns: Sequence[str]) -> bool:
     return any(fnmatchcase(path, pattern) for pattern in patterns)
 
 
-def _path_hash(root: str, path: str) -> str:
-    target = Path(root) / path
-    digest = hashlib.sha256()
-    if target.is_file():
-        with target.open("rb") as handle:
-            for chunk in iter(lambda: handle.read(65536), b""):
-                digest.update(chunk)
-    return digest.hexdigest()
-
-
 def _active_data(active: ActiveTask) -> dict[str, object]:
     changes = {
         path: {"status": item.status, "content_sha256": item.content_sha256}
@@ -290,6 +289,7 @@ def _active_data(active: ActiveTask) -> dict[str, object]:
         "context_sha256": active.context_sha256,
         "baseline": {
             "head": active.baseline.head,
+            "last_seen_head": active.baseline.last_seen_head,
             "captured_at": active.baseline.captured_at,
             "preexisting_changes": changes,
         },
@@ -300,9 +300,10 @@ def _active_data(active: ActiveTask) -> dict[str, object]:
 
 def _snapshot_from_data(value: object, path: str) -> PathSnapshot:
     data = _mapping(value, "preexisting_changes[]", path)
+    content_hash = data.get("content_sha256")
     return PathSnapshot(
         _string(data.get("status"), "status", path),
-        _string(data.get("content_sha256"), "content_sha256", path),
+        content_hash if isinstance(content_hash, str) else "",
     )
 
 
@@ -323,6 +324,7 @@ def _active_from_data(value: object, path: str) -> ActiveTask:
         head,
         _string(baseline_data.get("captured_at"), "captured_at", path),
         {key: _snapshot_from_data(item, path) for key, item in raw_changes.items()},
+        baseline_data.get("last_seen_head") if isinstance(baseline_data.get("last_seen_head"), str) else None,
     )
     return ActiveTask(
         1,
@@ -355,6 +357,58 @@ def load_active_task(root: str) -> ActiveTask:
         raise ContextError("invalid_active_marker", "active", str(exc), str(marker)) from exc
 
 
+def task_contract_digest(root: str, task_dir: str, task_id: str) -> str:
+    """Digest of the active TASK's acceptance contract (Refs + Contract + Evidence).
+
+    Two TASKs may share one Context hash while owning different scenarios; the
+    digest separates their injection versions so switching TASKs re-injects.
+    Returns "" when the TASK section cannot be located (fail-open to the
+    legacy context-hash-only key rather than crashing the hook hot path).
+    """
+    try:
+        files = sorted((Path(root) / task_dir).glob("*.md"))
+    except OSError:
+        return ""
+    for path in files:
+        if path.name.endswith((".prd.md", ".design.md")):
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeError):
+            continue
+        start = text.find(f"## {task_id}:")
+        if start == -1:
+            continue
+        end = text.find("\n## TASK-", start)
+        section = text[start:] if end == -1 else text[start:end]
+        chunks: list[str] = []
+        for heading in ("Acceptance-Refs", "Acceptance Contract", "Acceptance Evidence"):
+            index = section.find(heading)
+            if index == -1:
+                chunks.append(f"{heading}:missing")
+                continue
+            end = section.find("\n### ", index)
+            chunks.append(section[index:] if end == -1 else section[index:end])
+        return hashlib.sha256("\n".join(chunks).encode("utf-8")).hexdigest()
+    return ""
+
+
+def injection_version(root: str, session_id: str, context_sha: str) -> str:
+    """Version key for hook injection dedup.
+
+    Covers session + task_dir + task_id + context hash + TASK contract digest,
+    so a TASK switch (or an in-place contract edit) always re-injects while a
+    repeated prompt on the same contract stays suppressed.
+    """
+    try:
+        active = load_active_task(root)
+    except (ContextError, OSError, ValueError):
+        return f"none:{session_id}:{context_sha}"
+    digest = task_contract_digest(root, active.task_dir, active.task_id)
+    raw = "\n".join((session_id, active.task_dir, active.task_id, context_sha, digest))
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
 def resync_active_hash(root: str, task_dir: str, current_sha256: str) -> bool:
     """Re-sync the active marker's context hash after toolchain-initiated
     context edits (bind/decision/refresh) so they never surface as
@@ -437,6 +491,42 @@ def _release_active_lock(lock: Path) -> None:
         return
 
 
+def _committed_since(root: str, base_head: Optional[str]) -> Mapping[str, str]:
+    """Paths committed between the frozen baseline head and current HEAD.
+
+    Returns {} when there is no baseline (pre-commit repo) or the range is
+    unresolvable (rewritten/pruned history) — working-tree changes still
+    flow through _business_changes, so scope never goes fully blind.
+    """
+    if not base_head:
+        return {}
+    try:
+        output = _run_git(root, ("diff", "--name-status", "-z", base_head, "HEAD", "--"))
+    except ContextError:
+        return {}
+    names: dict[str, str] = {}
+    tokens = output.split("\0")
+    index = 0
+    while index < len(tokens) and tokens[index]:
+        status, index = tokens[index], index + 1
+        code = status[:1]
+        if code in ("R", "C"):
+            if index + 1 >= len(tokens):
+                break
+            new_path, old_path = tokens[index], tokens[index + 1]
+            index += 2
+            if new_path:
+                names[new_path] = "renamed"
+            if old_path:
+                names[old_path] = "deleted"
+            continue
+        if index >= len(tokens) or not tokens[index]:
+            break
+        names[tokens[index]] = {"M": "modified", "A": "added", "D": "deleted"}.get(code, "changed")
+        index += 1
+    return names
+
+
 def _business_changes(root: str, excludes: Sequence[str]) -> Mapping[str, str]:
     return {
         path: status
@@ -460,10 +550,14 @@ def _new_active(
         raise ContextError("unknown_owned_path", "owned_paths", ", ".join(unknown), root)
     if unowned:
         raise ContextError("unowned_changes", "owned_paths", ", ".join(unowned), root)
+    # content_sha256 was a per-file hash but is never consumed by any gate (only
+    # baseline.head is compared); keep the schema field empty so start never hashes
+    # every uncommitted file.
     snapshots = {
-        path: PathSnapshot(status, _path_hash(root, path)) for path, status in changes.items()
+        path: PathSnapshot(status, "") for path, status in changes.items()
     }
-    baseline = ActiveBaseline(_git_head(root), _now(), snapshots)
+    head = _git_head(root)
+    baseline = ActiveBaseline(head, _now(), snapshots, head)
     return ActiveTask(
         1, task_dir, task_id, "activating", context_sha256, baseline, owned, DEFAULT_ACTIVE_EXCLUDES
     )
@@ -499,9 +593,10 @@ def _transition_active(root: str, expected: Sequence[str], target: str) -> Activ
             raise ContextError("invalid_active_transition", "status", f"{active.status} -> {target}", root)
         current_head = _git_head(root)
         if active.baseline.head != current_head:
-            # Mid-task commits are a normal workflow; re-baseline instead of
-            # bricking pause/resume/complete on any unrelated commit.
-            active = replace(active, baseline=replace(active.baseline, head=current_head))
+            # Mid-task commits are a normal workflow. The baseline head stays
+            # frozen so committed work never drops out of scope; only the
+            # observation field advances for diagnostics.
+            active = replace(active, baseline=replace(active.baseline, last_seen_head=current_head))
         updated = replace(active, status=target)
         save_active_task(root, updated)
         return updated
@@ -523,7 +618,12 @@ def resume_active_task(root: str) -> ActiveTask:
 
 def current_owned_paths(root: str, active: ActiveTask) -> tuple[str, ...]:
     changes = _business_changes(root, active.excluded_paths)
-    return tuple(sorted(set(active.owned_paths).union(changes)))
+    committed = {
+        path: status
+        for path, status in _committed_since(root, active.baseline.head).items()
+        if not _is_excluded(path, active.excluded_paths)
+    }
+    return tuple(sorted(set(active.owned_paths).union(changes).union(committed)))
 
 
 def complete_active_task(root: str, gate_passed: bool) -> ActiveTask:
@@ -822,6 +922,7 @@ def context_sha256(context: SpecContext) -> str:
     Computed from the stable identity projection (never volatile runtime state),
     so evidence timestamps and stage statuses cannot drift the marker.
     """
+    import yaml
     data = yaml.safe_dump(context_to_identity(context), sort_keys=True, allow_unicode=True).encode()
     return hashlib.sha256(data).hexdigest()
 
@@ -834,6 +935,7 @@ def new_context(task: str, sources: Sequence[tuple[str, str]]) -> SpecContext:
 
 
 def load_context(path: str) -> SpecContext:
+    import yaml
     try:
         loaded = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
     except (OSError, UnicodeError, yaml.YAMLError) as exc:
@@ -862,6 +964,7 @@ def load_context(path: str) -> SpecContext:
 
 
 def save_context(path: str, context: SpecContext) -> None:
+    import yaml
     target = Path(path)
     target.parent.mkdir(parents=True, exist_ok=True)
     text = yaml.safe_dump(context_to_data(context), sort_keys=False, allow_unicode=True)
@@ -965,7 +1068,57 @@ def _removed_rule(rule: RuleBinding) -> RuleBinding:
 
 def _file_sha256(path: Path) -> str:
     try:
-        return hashlib.sha256(path.read_bytes()).hexdigest()
+        stat = path.stat()
+        key = str(path)
+        cached = _FILE_HASH_CACHE.get(key)
+        signature = (stat.st_mtime_ns, stat.st_size, stat.st_ino)
+        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,
+        )
+        cache_key = str(cache_path) if cache_path is not None else ""
+        if cache_key and cache_key not in _PERSISTENT_HASH_PATHS:
+            try:
+                loaded = json.loads(cache_path.read_text(encoding="utf-8"))
+                if isinstance(loaded, dict):
+                    _PERSISTENT_HASH_CACHE.update({str(k): v for k, v in loaded.items() if isinstance(v, dict)})
+            except (OSError, ValueError):
+                pass
+            _PERSISTENT_HASH_PATHS.add(cache_key)
+        persistent = _PERSISTENT_HASH_CACHE.get(key)
+        if (
+            isinstance(persistent, dict)
+            and persistent.get("mtime_ns") == stat.st_mtime_ns
+            and persistent.get("size") == stat.st_size
+            and persistent.get("ino") == stat.st_ino
+        ):
+            digest = persistent.get("sha256")
+            if isinstance(digest, str) and digest:
+                _FILE_HASH_CACHE[key] = (signature[0], signature[1], signature[2], digest)
+                return digest
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        _FILE_HASH_CACHE[key] = (signature[0], signature[1], signature[2], digest)
+        if cache_key:
+            _PERSISTENT_HASH_CACHE[key] = {
+                "mtime_ns": stat.st_mtime_ns,
+                "size": stat.st_size,
+                "ino": stat.st_ino,
+                "sha256": 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:
+                pass
+        return digest
     except OSError as exc:
         raise ContextError("artifact_read_error", "artifact", str(exc), str(path)) from exc
 
@@ -1057,15 +1210,19 @@ def _refresh_binding(
 
 
 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(), bindings=tuple(bindings))
+    phase_timing("context.refresh.total", started)
     if refreshed.bindings == context.bindings:
         return DriftResult(context, tuple(changes))
     return DriftResult(refreshed, tuple(changes))
@@ -1281,23 +1438,75 @@ def _bind_command(args: argparse.Namespace, payload: Mapping[str, object]) -> di
 
 
 def _active_command(args: argparse.Namespace, payload: Mapping[str, object]) -> dict[str, object]:
+    from cf_workflow_service import WorkflowError, locate_task_file
+    from cf_workflow_transaction import recover_transition
+
+    recover_transition(args.root)
+    if args.active_action in ("pause", "resume", "block", "complete"):
+        marker, _ = _active_paths(args.root)
+        if marker.exists():
+            current = load_active_task(args.root)
+            if (current.task_id != args.task or
+                    (Path(args.root) / current.task_dir).resolve() != (Path(args.root) / args.task_dir).resolve()):
+                raise ContextError("active_mismatch", "active", "requested TASK does not match marker", str(marker))
+
+    def _directory() -> str:
+        return args.task_dir if Path(args.task_dir).is_absolute() else str(Path(args.root) / args.task_dir)
+
+    def _reraise(exc: WorkflowError) -> ContextError:
+        return ContextError(exc.code, "workflow", str(exc), args.task_dir)
+
+    task_file = locate_task_file(_directory(), args.task)
     if args.active_action == "start":
         owned = tuple(
             _string(item, "owned_paths[]", "")
             for item in _sequence(payload.get("owned_paths", []), "owned_paths", "")
         )
-        active = start_active_task(
-            args.root, args.task_dir, args.task, args.context_sha256, owned
-        )
-        return {"ok": True, "active": _active_data(active)}
+        if task_file is None:
+            active = start_active_task(
+                args.root, args.task_dir, args.task, args.context_sha256, owned
+            )
+            return {"ok": True, "active": _active_data(active)}
+        from cf_workflow_service import start_task
+
+        try:
+            return start_task(args.root, args.task_dir, str(task_file), args.task, owned)
+        except WorkflowError as exc:
+            raise _reraise(exc) from exc
     if args.active_action == "pause":
         active = pause_active_task(args.root)
     elif args.active_action == "resume":
-        active = resume_active_task(args.root)
+        if task_file is None:
+            active = resume_active_task(args.root)
+        else:
+            from cf_workflow_service import resume_task
+
+            try:
+                return resume_task(args.root, _directory(), str(task_file), args.task)
+            except WorkflowError as exc:
+                raise _reraise(exc) from exc
     elif args.active_action == "block":
-        active = block_active_task(args.root)
+        if task_file is None:
+            active = block_active_task(args.root)
+        else:
+            from cf_workflow_service import block_task
+
+            reason = payload.get("reason", "")
+            try:
+                return block_task(args.root, _directory(), str(task_file), args.task, reason if isinstance(reason, str) else "")
+            except WorkflowError as exc:
+                raise _reraise(exc) from exc
     elif args.active_action == "complete":
-        active = complete_active_task(args.root, payload.get("gate_passed") is True)
+        gate = payload.get("gate_passed") is True
+        if task_file is None:
+            active = complete_active_task(args.root, gate)
+        else:
+            from cf_workflow_service import complete_task
+
+            try:
+                return complete_task(args.root, _directory(), str(task_file), args.task, gate)
+            except WorkflowError as exc:
+                raise _reraise(exc) from exc
     else:
         result = doctor_active_task(
             args.root,
@@ -1309,6 +1518,27 @@ def _active_command(args: argparse.Namespace, payload: Mapping[str, object]) ->
     return {"ok": True, "active": _active_data(active)}
 
 
+def _start_command(args: argparse.Namespace, payload: Mapping[str, object]) -> dict[str, object]:
+    """Run refresh, activation and TASK projection in one guarded process.
+
+    Delegates to the unified workflow service: hard preconditions (status,
+    NOTES, depends, marker) are enforced before any state changes, and the
+    Markdown view flips to in-progress in the same call.
+    """
+    from cf_workflow_service import WorkflowError, start_task
+
+    owned = tuple(
+        _string(item, "owned_paths[]", "")
+        for item in _sequence(payload.get("owned_paths", []), "owned_paths", "")
+    )
+    try:
+        return start_task(
+            args.root, args.task_dir, args.task_file, args.task, owned, args.session_output
+        )
+    except WorkflowError as exc:
+        raise ContextError(exc.code, "workflow", str(exc), args.task_dir) from exc
+
+
 def _status_command(args: argparse.Namespace) -> dict[str, object]:
     """Human-readable Spec Context status: task, marker health, gate, rules."""
     from cf_spec_gate import result_to_data, validate_stage  # local import avoids module cycle
@@ -1413,6 +1643,13 @@ def _parser() -> argparse.ArgumentParser:
         command.add_argument("--task", required=True)
         command.add_argument("--context-sha256", required=True)
         command.add_argument("--json", action="store_true")
+    start = commands.add_parser("start")
+    start.add_argument("--task-dir", required=True)
+    start.add_argument("--root", required=True)
+    start.add_argument("--task", required=True)
+    start.add_argument("--task-file", required=True)
+    start.add_argument("--session-output", default="")
+    start.add_argument("--json", action="store_true")
     return parser
 
 
@@ -1421,6 +1658,8 @@ def _execute(args: argparse.Namespace, stdin: IO[str]) -> dict[str, object]:
         return _catalog_command(args)
     if args.command == "active":
         return _active_command(args, _json_payload(stdin))
+    if args.command == "start":
+        return _start_command(args, _json_payload(stdin))
     context_path = Path(args.task_dir) / "spec-context.yml"
     if args.command == "decision":
         return _decision_command(args, _json_payload(stdin))

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

@@ -10,9 +10,11 @@ import json
 from pathlib import Path
 import re
 import sys
+import time
 from typing import IO, Mapping, Optional, Sequence
 
 from cf_spec_context import Decision, RuleBinding, RuleStageStatus, SpecBinding, SpecContext, load_context
+from cf_core import phase_timing
 
 
 @dataclass(frozen=True)
@@ -212,13 +214,21 @@ def _parser() -> argparse.ArgumentParser:
 
 
 def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:
+    started = time.monotonic()
     try:
         args = _parser().parse_args(argv)
+        phase_started = time.monotonic()
         context = load_context(str(Path(args.task_dir) / "spec-context.yml"))
+        phase_timing("gate.load_context", phase_started)
+        phase_started = time.monotonic()
         result = validate_stage(context, args.stage, task_id=args.task)
+        phase_timing("gate.validate_stage", phase_started)
         if args.stage == "plan" and args.artifact:
+            phase_started = time.monotonic()
             result = _merge_results(result, validate_plan_coverage(context, args.artifact))
+            phase_timing("gate.validate_plan", phase_started)
         stdout.write(json.dumps(result_to_data(result), ensure_ascii=False))
+        phase_timing("gate.total", started)
         return 0 if result.decision == "pass" else 3
     except Exception as exc:
         sys.stderr.write(f"cf_spec_gate error: {exc}\n")

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

@@ -10,7 +10,6 @@ from pathlib import Path
 import re
 from typing import Mapping, Optional
 
-import yaml
 
 
 ALLOWED_STAGES = frozenset(("prd", "design", "plan", "code", "review"))
@@ -20,6 +19,8 @@ _ID_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
 _RULE_ID_RE = re.compile(r"^RULE-[a-z0-9]+(?:-[a-z0-9]+)*-\d{3}$")
 _EXPLICIT_RULE_RE = re.compile(r"^\[(RULE-[a-z0-9-]+-\d{3})\]\s+(.+)$")
 _FRONTMATTER_RE = re.compile(r"\A---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|$)", re.DOTALL)
+_FRONTMATTER_OPEN_RE = re.compile(br"---[ \t]*\r?\n")
+_FRONTMATTER_CLOSE_RE = re.compile(br"---[ \t]*(?:\r?\n)?")
 _SECTION_RE = re.compile(r"^##\s+(Rules|Anti-Patterns|Patterns|Examples)\s*$")
 _H2_RE = re.compile(r"^##\s+")
 _BULLET_RE = re.compile(r"^\s*-\s+(.+\S|\S)\s*$")
@@ -63,6 +64,13 @@ class SpecRule:
     line: int
 
 
+@dataclass(frozen=True)
+class SpecHeader:
+    id: str
+    stages: tuple[str, ...]
+    enforcement: str
+
+
 @dataclass(frozen=True)
 class SpecMetadata:
     id: str
@@ -116,6 +124,11 @@ def _split_frontmatter(content: str, path: str) -> tuple[Mapping[str, object], s
     if not match:
         raise SpecMetadataError(path, "frontmatter", 1, "缺失或未闭合 YAML frontmatter")
     raw = match.group(1)
+    return _parse_frontmatter(raw, path), raw, content[match.end():]
+
+
+def _parse_frontmatter(raw: str, path: str) -> Mapping[str, object]:
+    import yaml
     try:
         loaded = yaml.safe_load(raw) or {}
     except yaml.YAMLError as exc:
@@ -126,7 +139,7 @@ def _split_frontmatter(content: str, path: str) -> tuple[Mapping[str, object], s
         raise SpecMetadataError(path, "frontmatter", 2, "顶层必须是 mapping")
     if not all(isinstance(key, str) for key in loaded):
         raise SpecMetadataError(path, "frontmatter", 2, "所有顶层 key 必须是字符串")
-    return loaded, raw, content[match.end():]
+    return loaded
 
 
 def _required_string(meta: Mapping[str, object], key: str, path: str, raw: str) -> str:
@@ -149,6 +162,46 @@ def _validate_stages(meta: Mapping[str, object], path: str, raw: str) -> tuple[s
     return stages
 
 
+def _spec_header(meta: Mapping[str, object], raw: str, path: str) -> SpecHeader:
+    spec_id = _required_string(meta, "id", path, raw)
+    if not _ID_RE.fullmatch(spec_id):
+        raise SpecMetadataError(path, "id", _field_line(raw, "id"), "必须是 kebab-case")
+    stages = _validate_stages(meta, path, raw)
+    enforcement = _required_string(meta, "enforcement", path, raw)
+    if enforcement not in ALLOWED_ENFORCEMENT:
+        line = _field_line(raw, "enforcement")
+        raise SpecMetadataError(path, "enforcement", line, f"必须是 {sorted(ALLOWED_ENFORCEMENT)}")
+    return SpecHeader(spec_id, stages, enforcement)
+
+
+def _read_frontmatter(path: str) -> str:
+    lines: list[bytes] = []
+    try:
+        with Path(path).open("rb") as source:
+            if not _FRONTMATTER_OPEN_RE.fullmatch(source.readline()):
+                raise SpecMetadataError(path, "frontmatter", 1, "缺失或未闭合 YAML frontmatter")
+            for line in source:
+                if _FRONTMATTER_CLOSE_RE.fullmatch(line):
+                    break
+                lines.append(line)
+            else:
+                raise SpecMetadataError(path, "frontmatter", 1, "缺失或未闭合 YAML frontmatter")
+    except OSError as exc:
+        raise SpecMetadataError(path, "file", 1, f"读取失败: {exc}") from exc
+    raw = b"".join(lines)
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        line = raw[:exc.start].count(b"\n") + 2
+        raise SpecMetadataError(path, "encoding", line, f"必须是 UTF-8: {exc}") from exc
+
+
+def load_spec_header(path: str) -> SpecHeader:
+    """Load only routing fields, stopping at the frontmatter delimiter."""
+    raw = _read_frontmatter(path)
+    return _spec_header(_parse_frontmatter(raw, path), raw, path)
+
+
 def _validate_checks(meta: Mapping[str, object], path: str, raw: str) -> tuple[Mapping[str, object], ...]:
     value = meta.get("checks", [])
     if not isinstance(value, list) or not all(isinstance(item, dict) for item in value):
@@ -265,15 +318,8 @@ def _validate_links(
 
 def parse_spec_metadata(content: str, path: str = "<memory>", raw_bytes: Optional[bytes] = None) -> SpecMetadata:
     meta, raw_frontmatter, body = _split_frontmatter(content, path)
-    spec_id = _required_string(meta, "id", path, raw_frontmatter)
-    if not _ID_RE.fullmatch(spec_id):
-        raise SpecMetadataError(path, "id", _field_line(raw_frontmatter, "id"), "必须是 kebab-case")
+    header = _spec_header(meta, raw_frontmatter, path)
     description = _required_string(meta, "description", path, raw_frontmatter)
-    stages = _validate_stages(meta, path, raw_frontmatter)
-    enforcement = _required_string(meta, "enforcement", path, raw_frontmatter)
-    if enforcement not in ALLOWED_ENFORCEMENT:
-        line = _field_line(raw_frontmatter, "enforcement")
-        raise SpecMetadataError(path, "enforcement", line, f"必须是 {sorted(ALLOWED_ENFORCEMENT)}")
     owner = meta.get("owner")
     if owner is not None and (not isinstance(owner, str) or not owner.strip()):
         raise SpecMetadataError(path, "owner", _field_line(raw_frontmatter, "owner"), "必须是非空字符串")
@@ -289,7 +335,10 @@ def parse_spec_metadata(content: str, path: str = "<memory>", raw_bytes: Optiona
         metadata_sha256=_sha256(_canonical_json(meta, path, "frontmatter", 1)),
         rules_sha256=_sha256(_canonical_json(required_rules, path, "rules", 1)),
     )
-    return SpecMetadata(spec_id, description, stages, enforcement, owner, checks, verifiers, rules, hashes, path)
+    return SpecMetadata(
+        header.id, description, header.stages, header.enforcement,
+        owner, checks, verifiers, rules, hashes, path,
+    )
 
 
 def load_spec_metadata(path: str) -> SpecMetadata: