@michaelxwb/code-flow 0.6.4 → 0.8.1

package/src/core/code-flow/scripts/{cf_spec_migrate.py → codeflow/spec/cf_spec_migrate.py}

@@ -14,14 +14,17 @@ from typing import IO, Mapping, Optional, Sequence
 
 import yaml
 
-from cf_spec_context import BindingInput, bind_specs, new_context, save_context
-from cf_spec_metadata import SpecMetadata, SpecMetadataError, load_spec_metadata
-from cf_spec_resolver import SCOPE_PRIORITY, SpecCandidate
+if __package__ in (None, ""):
+    sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from codeflow.cli.cf_spec_context import BindingInput, bind_specs, new_context, save_context
+from codeflow.spec.cf_spec_metadata import SpecMetadata, SpecMetadataError, load_spec_metadata
+from codeflow.spec.cf_spec_resolver import SCOPE_PRIORITY, SpecCandidate
 
 
 TARGET_VERSION = "0.6.0"
 TARGET_SCHEMA = 1
-PACKAGE_ROOT = Path(__file__).resolve().parents[4]
+PACKAGE_ROOT = Path(__file__).resolve().parents[6]
 _DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
 _SUFFIXES = (".frontend.design.md", ".backend.design.md", ".design.md", ".prd.md", ".md")
 
@@ -425,17 +428,31 @@ def _write_target_config(staging: Path) -> None:
     path.write_text(yaml.safe_dump(data, sort_keys=False, allow_unicode=True), encoding="utf-8")
 
 
+def _runtime_gitignore() -> tuple[str, list[str], str]:
+    path = Path(__file__).resolve().parents[2] / "runtime-resources.json"
+    data = json.loads(path.read_text(encoding="utf-8"))
+    block = data["gitignore"]
+    return block["start"], list(block["entries"]), block["end"]
+
+
 def _write_target_ignore(staging: Path) -> None:
     path = staging / ".code-flow/.gitignore"
     existing = path.read_text(encoding="utf-8") if path.exists() else ""
-    block = (
-        "# >>> code-flow:runtime schema=1\n.active-task.json\n.active-task.lock\n"
-        ".catalog-state.json\nmigrations/\nspecs/_session/\n"
-        "# <<< code-flow:runtime schema=1\n"
-    )
+    # The packaged runtime-resources.json declaration is the single source shared
+    # with the CLI: migrate must not leave sessions/worktrees/backups/logs
+    # committable after an upgrade.
+    start, entries, end = _runtime_gitignore()
+    block = "\n".join([start, *entries, end]) + "\n"
     lines = [line for line in existing.splitlines() if line != ".inject-state"]
-    if "# >>> code-flow:runtime schema=1" not in existing:
+    if start not in existing:
         path.write_text("\n".join(lines).rstrip() + "\n" + block, encoding="utf-8")
+        return
+    if end in lines:
+        missing = [entry for entry in entries if entry not in lines]
+        if missing:
+            at = lines.index(end)
+            lines[at:at] = missing
+            path.write_text("\n".join(lines) + "\n", encoding="utf-8")
 
 
 def _target_manifest(staging: Path) -> list[dict[str, str]]:

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

@@ -0,0 +1,193 @@
+"""Read-only, input-bound Spec optimization proposals."""
+from __future__ import annotations
+
+import hashlib
+import difflib
+import json
+from pathlib import Path
+import re
+from typing import Sequence
+
+from codeflow.core.cf_core import estimate_tokens, load_config
+from codeflow.spec.cf_spec_budget import measure_path_budget
+from codeflow.spec.cf_spec_impact import scan_impacts
+from codeflow.spec.cf_spec_metadata import parse_spec_metadata
+from codeflow.spec.cf_spec_resolver import resolve_candidates
+
+
+def _selected(root: str, paths: Sequence[str]) -> list:
+    all_candidates = list(resolve_candidates(root, 'code', ()))
+    if not paths:
+        return all_candidates
+    normalized = [item.replace('\\', '/').removeprefix('.code-flow/specs/') for item in paths]
+    direct = {item.path for item in all_candidates if item.path in normalized}
+    code_paths = [path for path in normalized if path not in direct]
+    matched = {item.path for item in resolve_candidates(root, 'code', tuple(code_paths), matched_only=True)} if code_paths else set()
+    selected = [item for item in all_candidates if item.path in direct | matched]
+    if not selected:
+        raise ValueError('no matching specs for requested paths')
+    return selected
+
+
+def _section_tokens(text: str, heading: str) -> int:
+    match = re.search(rf'(?im)^##\s+{re.escape(heading)}\s*$([\s\S]*?)(?=^##\s|\Z)', text)
+    return estimate_tokens(match.group(1)) if match else 0
+
+
+def _spec_data(root: Path, candidate: object, config: dict) -> dict[str, object]:
+    relative = str(candidate.path)
+    base = (root / '.code-flow/specs').resolve()
+    path = (base / relative).resolve()
+    if base not in path.parents or not path.is_file():
+        raise ValueError(f'invalid spec path: {relative}')
+    raw = path.read_bytes()
+    text = raw.decode('utf-8')
+    domain = relative.split('/', 1)[0]
+    mapping = config.get('path_mapping') or {}
+    entry = mapping.get(domain, {}) if isinstance(mapping, dict) else {}
+    patterns = entry.get('patterns', []) if isinstance(entry, dict) else []
+    rules = [rule for rule in candidate.metadata.rules if rule.ref.startswith('RULE-')]
+    tokens = estimate_tokens(text)
+    rule_tokens = _section_tokens(text, 'Rules')
+    convention_tokens = _section_tokens(text, 'Conventions')
+    return {'id': candidate.spec_id, 'path': relative, 'sha256': hashlib.sha256(raw).hexdigest(),
+            'tokens': tokens, 'rule_tokens': rule_tokens, 'convention_tokens': convention_tokens,
+            'rule_percent': round(100 * rule_tokens / tokens, 2) if tokens else 0,
+            'convention_percent': round(100 * convention_tokens / tokens, 2) if tokens else 0,
+            'rule_ids': sorted(rule.ref for rule in rules), 'patterns': patterns,
+            'verifiers': [{'rule': item.rule, 'type': item.type, 'stage': item.stage, 'config': item.config}
+                          for item in candidate.metadata.verifiers]}
+
+
+def _suggestions(specs: list[dict[str, object]], limit: int) -> list[dict[str, object]]:
+    return [{'path': item['path'], 'kind': 'review_conventions_split',
+             'reason': '规范超过单次注入上限；需人工选择目标，规则保持原位'}
+            for item in specs if int(item['tokens']) > limit and int(item['convention_tokens']) > 0]
+
+
+def _overlaps(specs: list[dict[str, object]]) -> list[dict[str, object]]:
+    groups: list[dict[str, object]] = []
+    for index, first in enumerate(specs):
+        for second in specs[index + 1:]:
+            shared = sorted(set(first['patterns']) & set(second['patterns']))
+            if shared:
+                groups.append({'paths': [first['path'], second['path']], 'patterns': shared})
+    return groups
+
+
+def _target_path(root: Path, target: str) -> Path:
+    relative = Path(target)
+    if relative.is_absolute() or '..' in relative.parts or len(relative.parts) < 2 or relative.suffix != '.md':
+        raise ValueError('target must be a relative spec path inside an existing domain')
+    if relative.parts[0] in ('shared', '_session') or relative.parts[0].startswith('.'):
+        raise ValueError('target domain must be an injectable spec domain')
+    base = (root / '.code-flow/specs').resolve()
+    path = base / relative
+    if any((base.joinpath(*relative.parts[:i])).is_symlink() for i in range(1, len(relative.parts) + 1)):
+        raise ValueError('target path must not contain symlinks')
+    if base not in path.resolve().parents or not path.parent.is_dir():
+        raise ValueError('target domain directory must exist within specs')
+    if path.exists() or path.is_symlink():
+        raise ValueError('target already exists')
+    return path
+
+
+def _movement(root: Path, specs: list[dict[str, object]], target: str, config: dict) -> tuple[list[dict], list[dict]]:
+    if len(specs) != 1:
+        raise ValueError('target requires exactly one source spec')
+    destination = _target_path(root, target)
+    source = specs[0]
+    base = root / '.code-flow/specs'
+    relative_source = Path(str(source['path']))
+    if any(base.joinpath(*relative_source.parts[:i]).is_symlink() for i in range(1, len(relative_source.parts) + 1)):
+        raise ValueError('source path must not contain symlinks')
+    text = (base / relative_source).read_text(encoding='utf-8')
+    match = re.search(r'(?im)^##\s+Conventions\s*$([\s\S]*?)(?=^##\s|\Z)', text)
+    if not match or 'RULE-' in match.group(0):
+        raise ValueError('source conventions missing or contain rule references')
+    new_id = str(source['id']) + '-conventions'
+    for stage in ('prd', 'design', 'plan', 'code', 'review'):
+        if any(item.spec_id == new_id for item in resolve_candidates(str(root), stage, ())):
+            raise ValueError('target spec id already exists')
+    relative = destination.relative_to(root / '.code-flow/specs').as_posix()
+    operation = {'kind': 'move_conventions', 'source': source['path'], 'target': relative, 'target_id': new_id}
+    source_after, target_after = render_movement(root, operation)
+    operation.update({'source_after_sha256': hashlib.sha256(source_after).hexdigest(),
+                      'target_after_sha256': hashlib.sha256(target_after).hexdigest(),
+                      'source_after_tokens': estimate_tokens(source_after.decode('utf-8')),
+                      'target_after_tokens': estimate_tokens(target_after.decode('utf-8')),
+                      'source_diff': ''.join(difflib.unified_diff(text.splitlines(keepends=True),
+                          source_after.decode('utf-8').splitlines(keepends=True), fromfile=str(source['path']),
+                          tofile=str(source['path']))),
+                      'target_diff': ''.join(difflib.unified_diff([], target_after.decode('utf-8').splitlines(keepends=True),
+                          fromfile='/dev/null', tofile=relative))})
+    domain = relative.split('/')[0]
+    mapping = config.get('path_mapping') or {}
+    entry = mapping.get(domain, {}) if isinstance(mapping, dict) else {}
+    patterns = entry.get('patterns', []) if isinstance(entry, dict) else []
+    return [operation], [{'kind': 'auto_discovery_add', 'domain': domain, 'path': relative,
+                          'source_patterns': source['patterns'], 'target_patterns': patterns}]
+
+
+def render_movement(root: Path, operation: dict) -> tuple[bytes, bytes]:
+    source = root / '.code-flow/specs' / str(operation['source'])
+    text = source.read_text(encoding='utf-8')
+    match = re.search(r'(?im)^##\s+Conventions\s*$([\s\S]*?)(?=^##\s|\Z)', text)
+    if not match or 'RULE-' in match.group(0):
+        raise ValueError('rule guard: invalid conventions section')
+    updated = text[:match.start()] + text[match.end():]
+    before = parse_spec_metadata(text, path=str(source))
+    target = ('---\nid: ' + str(operation['target_id']) + '\ndescription: Migrated conventions\n'
+              'stages: ' + json.dumps(list(before.stages)) + '\nenforcement: advisory\n---\n\n'
+              '# Conventions\n\n' + match.group(0) + '\n')
+    after = parse_spec_metadata(updated, path=str(source))
+    target_meta = parse_spec_metadata(target, path=str(root / '.code-flow/specs' / str(operation['target'])))
+    signature = lambda meta: [(rule.ref, rule.text_sha256, rule.section, rule.enforcement) for rule in meta.rules]
+    if signature(before) != signature(after) or before.verifiers != after.verifiers or target_meta.verifiers:
+        raise ValueError('rule guard: rule or verifier changed')
+    if any(item.ref.startswith('RULE-') for item in target_meta.rules):
+        raise ValueError('rule guard: target contains rules')
+    return updated.encode('utf-8'), target.encode('utf-8')
+
+
+def build_proposal(root: str, paths: Sequence[str], target: str = '') -> dict[str, object]:
+    project = Path(root).resolve()
+    config = load_config(root)
+    candidates = _selected(root, paths)
+    specs = [_spec_data(project, candidate, config) for candidate in candidates]
+    operations, mapping_diff = _movement(project, specs, target, config) if target else ([], [])
+    identities = {str(item['id']): str(item['path']) for item in specs}
+    for operation in operations:
+        identities[str(operation['target_id'])] = str(operation['target'])
+    impact = scan_impacts(root, identities)
+    if impact['truncated'] or impact['errors']:
+        raise ValueError('impact scan incomplete; proposal cannot assert complete scope')
+    budget = config.get('budget') or {}
+    if not isinstance(budget, dict):
+        raise ValueError('budget must be a mapping')
+    limit = min(int(budget.get('total', 2500)), int(budget.get('l1_max', 1700)))
+    if limit <= 0:
+        raise ValueError('budget limit must be positive')
+    config_hash = hashlib.sha256((project / '.code-flow/config.yml').read_bytes()).hexdigest()
+    code_paths = [path for path in paths if not any(path in (item['path'], '.code-flow/specs/' + str(item['path'])) for item in specs)]
+    measured = measure_path_budget(root, code_paths) if code_paths else None
+    raw_before = sum(int(item['tokens']) for item in specs)
+    raw_after = (raw_before - int(specs[0]['tokens']) + int(operations[0]['source_after_tokens'])
+                 + int(operations[0]['target_after_tokens'])) if operations else raw_before
+    affected_files = {str(row.get('context_path') or row.get('task_path')) for row in impact['references']}
+    affected_hashes = {path: hashlib.sha256((project / path).read_bytes()).hexdigest() for path in sorted(affected_files)}
+    overlap = _overlaps(specs)
+    suggestions = _suggestions(specs, limit)
+    suggestions.extend({'paths': group['paths'], 'kind': 'review_overlap',
+                        'reason': '相同路径模式命中多份规范；人工评估是否合并 Conventions'} for group in overlap)
+    proposal = {'schema': 1, 'config_sha256': config_hash, 'specs': specs,
+                'budget': {'before': {'raw_spec_tokens': raw_before, 'path_measurement': measured},
+                           'after': {'raw_spec_tokens': raw_after, 'path_measurement': None if operations else measured},
+                           'limit': limit, 'note': '变更后单次注入需在应用后重新测量'},
+                'mapping_diff': mapping_diff, 'affected_contexts': impact['references'],
+                'affected_file_hashes': affected_hashes,
+                'scanned_files': impact['scanned_files'], 'path_overlaps': overlap, 'suggestions': suggestions,
+                'operations': operations, 'note': ('请审核提案并交互确认应用。' if target
+                                                     else '未指定迁移目标，提案没有可应用的文件变更。')}
+    proposal['proposal_id'] = hashlib.sha256(json.dumps(proposal, ensure_ascii=False, sort_keys=True).encode()).hexdigest()
+    return proposal

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

@@ -0,0 +1,187 @@
+"""Guarded, recoverable application of a reviewed conventions proposal."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import shutil
+from typing import Mapping
+
+from codeflow.spec.cf_spec_optimize import build_proposal, render_movement
+from codeflow.task.cf_task_doc import TaskDocumentError, parse_task_document
+
+
+def _digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _proposal_hash(proposal: Mapping[str, object]) -> str:
+    unsigned = {key: value for key, value in proposal.items() if key != 'proposal_id'}
+    return _digest(json.dumps(unsigned, ensure_ascii=False, sort_keys=True).encode())
+
+
+def _check_context_tasks(root: Path, directory: str) -> None:
+    task_directory = root / directory
+    statuses: list[str] = []
+    for path in sorted(task_directory.glob('*.md')):
+        if path.name.endswith(('.prd.md', '.design.md', '.scenarios.md')):
+            continue
+        try:
+            document = parse_task_document(path.read_text(encoding='utf-8'), source=str(path))
+        except TaskDocumentError as exc:
+            if exc.code == 'task_document_empty':
+                continue
+            raise
+        statuses.extend(task.status for task in document.tasks)
+    if not statuses or any(status not in ('done', 'verified') for status in statuses):
+        raise ValueError('inflight_context: affected Context has incomplete or unproven tasks')
+
+
+def _check_inflight(root: str, proposal: Mapping[str, object]) -> None:
+    refs = proposal.get('affected_contexts')
+    if not isinstance(refs, list):
+        raise ValueError('proposal impact evidence missing')
+    tasks = [row for row in refs if isinstance(row, dict) and row.get('source') == 'task' and not row.get('archived')]
+    contexts = [row for row in refs if isinstance(row, dict) and row.get('source') == 'context' and not row.get('archived')]
+    if any(row.get('status') not in ('done', 'verified') for row in tasks):
+        raise ValueError('inflight_context: affected task is not complete')
+    directories = {str(Path(str(row.get('context_path', ''))).parent) for row in contexts}
+    for directory in sorted(directories):
+        _check_context_tasks(Path(root), directory)
+
+
+def _validate(root: str, proposal: Mapping[str, object]) -> dict[str, object]:
+    if proposal.get('schema') != 1 or proposal.get('proposal_id') != _proposal_hash(proposal):
+        raise ValueError('proposal guard: invalid proposal identity')
+    operations = proposal.get('operations')
+    if not isinstance(operations, list) or len(operations) != 1 or not isinstance(operations[0], dict):
+        raise ValueError('proposal guard: exactly one explicit operation is required')
+    operation = operations[0]
+    if operation.get('kind') != 'move_conventions' or not isinstance(operation.get('source'), str) or not isinstance(operation.get('target'), str):
+        raise ValueError('proposal guard: invalid operation')
+    try:
+        current = build_proposal(root, (operation['source'],), str(operation['target']))
+    except (OSError, ValueError) as exc:
+        raise ValueError(f'proposal_stale: {exc}') from exc
+    if current != proposal:
+        raise ValueError('proposal_stale: input, impact, or operation changed')
+    _check_inflight(root, proposal)
+    return operation
+
+
+def _write(path: Path, data: bytes, mode: int = 0o600) -> None:
+    descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
+    with os.fdopen(descriptor, 'wb') as handle:
+        os.fchmod(handle.fileno(), mode)
+        handle.write(data)
+        handle.flush()
+        os.fsync(handle.fileno())
+
+
+def _journal(directory: Path, data: dict[str, object]) -> None:
+    temporary = directory / 'journal.tmp'
+    if temporary.exists():
+        raise ValueError('transaction journal temporary file already exists')
+    _write(temporary, (json.dumps(data, ensure_ascii=False, sort_keys=True) + '\n').encode())
+    os.replace(temporary, directory / 'journal.json')
+    descriptor = os.open(directory, os.O_RDONLY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def commit_replace(staged: Path, destination: Path) -> None:
+    """Replace the source; create a new target exclusively without overwriting."""
+    if staged.name == 'target.staged':
+        os.link(staged, destination)
+    else:
+        os.replace(staged, destination)
+
+
+def _rollback(source: Path, target: Path, backup: Path, original_hash: str,
+              source_after_hash: str, target_after_hash: str, target_created: bool) -> None:
+    if target_created:
+        if not target.is_file() or _digest(target.read_bytes()) != target_after_hash:
+            raise ValueError('recovery_required: target changed during rollback')
+        target.unlink()
+    current = _digest(source.read_bytes()) if source.is_file() else ''
+    if current == original_hash:
+        return
+    if current != source_after_hash or _digest(backup.read_bytes()) != original_hash:
+        raise ValueError('recovery_required: source changed during rollback')
+    os.replace(backup, source)
+
+
+def _remove_transaction(directory: Path, parent_existed: bool) -> None:
+    parent = directory.parent
+    shutil.rmtree(directory)
+    if not parent_existed:
+        parent.rmdir()
+
+
+def _transaction(root: Path, proposal: Mapping[str, object], operation: Mapping[str, object]) -> dict[str, object]:
+    base = root / '.code-flow/specs'
+    source = base / str(operation['source'])
+    target = base / str(operation['target'])
+    original = source.read_bytes()
+    after_source, after_target = render_movement(root, dict(operation))
+    specs = proposal.get('specs')
+    if (not isinstance(specs, list) or len(specs) != 1 or not isinstance(specs[0], dict)
+            or _digest(original) != specs[0].get('sha256')
+            or _digest(after_source) != operation.get('source_after_sha256')
+            or _digest(after_target) != operation.get('target_after_sha256')):
+        raise ValueError('proposal_stale: source or proposed result changed')
+    parent = base / '.optimize-transactions'
+    if parent.is_symlink() or (parent.exists() and (not parent.is_dir() or any(parent.iterdir()))):
+        raise ValueError('recovery_required: unfinished optimization transaction')
+    parent_existed = parent.exists()
+    parent.mkdir(exist_ok=True)
+    directory = parent / str(proposal['proposal_id'])
+    directory.mkdir()
+    backup, source_stage, target_stage = directory / 'source.backup', directory / 'source.staged', directory / 'target.staged'
+    target_created = False
+    state = {'schema': 1, 'proposal_id': proposal['proposal_id'], 'source': operation['source'],
+             'target': operation['target'], 'original_sha256': _digest(original),
+             'source_after_sha256': _digest(after_source), 'target_after_sha256': _digest(after_target), 'state': 'prepared'}
+    try:
+        _write(backup, original, source.stat().st_mode & 0o777)
+        _write(source_stage, after_source, source.stat().st_mode & 0o777)
+        _write(target_stage, after_target, 0o644)
+        _journal(directory, state)
+        state['state'] = 'committing'
+        _journal(directory, state)
+        if _digest(source.read_bytes()) != state['original_sha256']:
+            raise ValueError('proposal_stale: source changed before commit')
+        commit_replace(source_stage, source)
+        commit_replace(target_stage, target)
+        target_created = True
+        if _digest(source.read_bytes()) != state['source_after_sha256'] or _digest(target.read_bytes()) != state['target_after_sha256']:
+            raise ValueError('post-write guard: content differs from approved proposal')
+        state['state'] = 'committed'
+        _journal(directory, state)
+    except (OSError, ValueError):
+        _rollback(source, target, backup, _digest(original), _digest(after_source), _digest(after_target), target_created)
+        _remove_transaction(directory, parent_existed)
+        raise
+    _remove_transaction(directory, parent_existed)
+    return {'decision': 'pass', 'proposal_id': proposal['proposal_id'],
+            'changed': [str(operation['source']), str(operation['target'])]}
+
+
+def apply_proposal(root: str, proposal: Mapping[str, object], *, confirmed: bool) -> dict[str, object]:
+    if not confirmed:
+        raise ValueError('explicit confirmation required')
+    project = Path(root).resolve()
+    lock = project / '.code-flow/specs/.optimize.lock'
+    try:
+        descriptor = os.open(lock, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError as exc:
+        raise ValueError('recovery_required: optimization lock exists') from exc
+    os.close(descriptor)
+    try:
+        operation = _validate(root, proposal)
+        return _transaction(project, proposal, operation)
+    finally:
+        lock.unlink()

package/src/core/code-flow/scripts/{cf_spec_resolver.py → codeflow/spec/cf_spec_resolver.py}

@@ -8,7 +8,7 @@ import fnmatch
 from pathlib import Path
 from typing import Mapping, Optional, Sequence
 
-from cf_spec_metadata import (
+from codeflow.spec.cf_spec_metadata import (
     ALLOWED_STAGES,
     SpecHeader,
     SpecMetadata,
@@ -19,8 +19,8 @@ from cf_spec_metadata import (
 
 
 SCOPE_PRIORITY = {"unmatched": 0, "global": 1, "path": 2, "task": 3}
-_config_cache: dict[str, tuple[int, int, Mapping[str, object]]] = {}
-_metadata_cache: dict[str, tuple[int, int, SpecMetadata]] = {}
+_config_cache: dict[str, tuple[int, int, int, Mapping[str, object]]] = {}
+_metadata_cache: dict[str, tuple[int, int, int, SpecMetadata]] = {}
 
 
 class SpecResolutionError(ValueError):
@@ -99,12 +99,12 @@ class _RuleSource:
     enforcement: str
 
 
-def _fingerprint(path: Path, field: str) -> tuple[int, int]:
+def _fingerprint(path: Path, field: str) -> tuple[int, int, int]:
     try:
         stat = path.stat()
     except OSError as exc:
         raise SpecResolutionError(str(path), field, f"读取状态失败: {exc}") from exc
-    return stat.st_mtime_ns, stat.st_size
+    return stat.st_mtime_ns, stat.st_ctime_ns, stat.st_size
 
 
 def _load_config(root: str) -> Mapping[str, object]:
@@ -112,17 +112,17 @@ def _load_config(root: str) -> Mapping[str, object]:
     path = Path(root) / ".code-flow" / "config.yml"
     if not path.is_file():
         raise SpecResolutionError(str(path), "config", "缺失 config.yml")
-    mtime, size = _fingerprint(path, "config")
+    signature = _fingerprint(path, "config")
     cached = _config_cache.get(str(path))
-    if cached and cached[:2] == (mtime, size):
-        return cached[2]
+    if cached and cached[:3] == signature:
+        return cached[3]
     try:
         loaded = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
     except (OSError, UnicodeError, yaml.YAMLError) as exc:
         raise SpecResolutionError(str(path), "config", f"解析失败: {exc}") from exc
     if not isinstance(loaded, dict) or not all(isinstance(key, str) for key in loaded):
         raise SpecResolutionError(str(path), "config", "顶层必须是字符串 key mapping")
-    _config_cache[str(path)] = (mtime, size, loaded)
+    _config_cache[str(path)] = (*signature, loaded)
     return loaded
 
 
@@ -161,12 +161,12 @@ def _non_injectable(mapping: Mapping[str, object], config_path: str) -> set[str]
 
 
 def _load_metadata(path: Path) -> SpecMetadata:
-    mtime, size = _fingerprint(path, "spec")
+    signature = _fingerprint(path, "spec")
     cached = _metadata_cache.get(str(path))
-    if cached and cached[:2] == (mtime, size):
-        return cached[2]
+    if cached and cached[:3] == signature:
+        return cached[3]
     metadata = load_spec_metadata(str(path))
-    _metadata_cache[str(path)] = (mtime, size, metadata)
+    _metadata_cache[str(path)] = (*signature, metadata)
     return metadata
 
 
@@ -231,7 +231,27 @@ def _spec_paths(spec_root: Path, excluded: set[str]) -> tuple[Path, ...]:
     return tuple(result)
 
 
-def resolve_candidates(root: str, stage: str, paths: Sequence[str]) -> tuple[SpecCandidate, ...]:
+def _routing_paths(
+    spec_root: Path, excluded: set[str], mapping: Mapping[str, object],
+    config_path: str, paths: Sequence[str], matched_only: bool,
+) -> tuple[Path, ...]:
+    discovered = _spec_paths(spec_root, excluded)
+    if not matched_only:
+        return discovered
+    relevant = []
+    for path in discovered:
+        relative = path.relative_to(spec_root).as_posix()
+        domain = relative.split("/", 1)[0]
+        patterns = _patterns(_domain_config(mapping, domain, config_path),
+                             f"path_mapping.{domain}.patterns", config_path)
+        if _candidate_scope(relative, patterns, paths)[0] != "unmatched":
+            relevant.append(path)
+    return tuple(relevant)
+
+
+def resolve_candidates(
+    root: str, stage: str, paths: Sequence[str], *, matched_only: bool = False,
+) -> tuple[SpecCandidate, ...]:
     if stage not in ALLOWED_STAGES:
         raise SpecResolutionError(root, "stage", f"不支持 stage: {stage!r}")
     normalized_paths = tuple(path.replace("\\", "/") for path in paths)
@@ -244,7 +264,7 @@ def resolve_candidates(root: str, stage: str, paths: Sequence[str]) -> tuple[Spe
         raise SpecResolutionError(str(spec_root), "specs", "缺失 specs 目录")
     candidates: list[SpecCandidate] = []
     ids: dict[str, str] = {}
-    for path in _spec_paths(spec_root, excluded):
+    for path in _routing_paths(spec_root, excluded, mapping, config_path, normalized_paths, matched_only):
         candidate = _candidate_for(path, spec_root, mapping, config_path, stage, normalized_paths)
         if candidate is None:
             continue
@@ -257,7 +277,8 @@ def resolve_candidates(root: str, stage: str, paths: Sequence[str]) -> tuple[Spe
 
 
 def resolve_candidate_headers(
-    root: str, stage: str, paths: Sequence[str]
+    root: str, stage: str, paths: Sequence[str], *, matched_only: bool = False,
+    excluded_paths: Sequence[str] = (),
 ) -> tuple[SpecCandidateHeader, ...]:
     """Resolve candidates from routing frontmatter without parsing bodies or hashes."""
     if stage not in ALLOWED_STAGES:
@@ -267,12 +288,13 @@ def resolve_candidate_headers(
     config_path = str(Path(root) / ".code-flow" / "config.yml")
     mapping = _path_mapping(config, config_path)
     excluded = _non_injectable(mapping, config_path)
+    excluded.update(excluded_paths)
     spec_root = Path(root) / ".code-flow" / "specs"
     if not spec_root.is_dir():
         raise SpecResolutionError(str(spec_root), "specs", "缺失 specs 目录")
     candidates: list[SpecCandidateHeader] = []
     ids: dict[str, str] = {}
-    for path in _spec_paths(spec_root, excluded):
+    for path in _routing_paths(spec_root, excluded, mapping, config_path, normalized_paths, matched_only):
         candidate = _candidate_header_for(path, spec_root, mapping, config_path, stage, normalized_paths)
         if candidate is None:
             continue