cowork-flow 1.1.3 → 1.2.0

package/template/.cowork-flow/scripts/services/spec_check.py

@@ -0,0 +1,493 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Spec check executor: user-declared checks in spec frontmatter.
+
+Mechanism consumes declarations, never spec prose. Each spec file may carry a
+`checks:` list in its YAML frontmatter; this module parses that minimal subset,
+matches declarations against changed files (directory-prefix or extension
+forms only), and executes the commands with a three-state outcome:
+
+- ``pass``       exit code 0
+- ``violation``  exit code != 0
+- ``unchecked``  command missing / interpreter missing / timeout — never
+  reported as pass (lifecycle gates treat it as its own blocking state)
+
+Editor-phase runs are clamped to a short timeout and only touch declarations
+whose ``files`` match the edited path; slow or unfiltered commands belong to
+the lifecycle phase. Output passed back to agents is normalized to one line;
+full command output is only shown on an explicit ``--file`` query.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+# os.name == "nt" covers Windows without importing sys: the services layer
+# is kept free of CLI/process plumbing concerns by architecture tests.
+IS_WINDOWS = os.name == "nt"
+
+# Editor-phase budget: the zcode/claude PostToolUse hook runs on a 5s hard
+# budget including interpreter startup, so edit-phase commands get 3s and
+# nothing more.
+EDIT_PHASE_TIMEOUT = 3.0
+DEFAULT_TIMEOUT = 30.0
+MAX_TIMEOUT = 120.0
+MAX_FIRST_LINE_CHARS = 200
+
+# Machine-owned spec subtrees; user-declared checks never scan these.
+EXCLUDED_SPEC_SUBDIRS = ("contracts", "runtime", "schemas")
+
+SCHEMA_VERSION = 1
+
+
+class SpecCheckError(Exception):
+    """Raised for structural failures that callers must surface."""
+
+
+@dataclass(frozen=True)
+class CheckDecl:
+    """One user-declared check from a spec frontmatter block."""
+
+    cmd: str
+    files: tuple[str, ...] = ()
+    timeout: float = DEFAULT_TIMEOUT
+    when: str = "both"
+    cmd_win: str | None = None
+
+
+@dataclass(frozen=True)
+class SpecDeclarations:
+    spec: str
+    decls: tuple[CheckDecl, ...] = ()
+    errors: tuple[str, ...] = ()
+
+
+@dataclass
+class CheckResult:
+    spec: str
+    cmd: str
+    status: str  # pass | violation | unchecked
+    exit_code: int | None = None
+    first_violation_line: str = ""
+    reason: str = ""
+    output: list[str] = field(default_factory=list)
+
+    def to_json(self) -> dict:
+        payload = {
+            "spec": self.spec,
+            "cmd": self.cmd,
+            "status": self.status,
+        }
+        if self.exit_code is not None:
+            payload["exitCode"] = self.exit_code
+        if self.first_violation_line:
+            payload["firstViolationLine"] = self.first_violation_line
+        if self.reason:
+            payload["reason"] = self.reason
+        return payload
+
+
+def _strip_quotes(value: str) -> str:
+    value = value.strip()
+    # Only unwrap a true single-pair quoting ("src/"); a command value like
+    # "python" -c "..." quotes twice and must pass through intact.
+    for quote in ("\"", "'"):
+        if (
+            len(value) >= 2
+            and value[0] == quote
+            and value[-1] == quote
+            and value.count(quote) == 2
+        ):
+            return value[1:-1].strip()
+    return value
+
+
+def parse_frontmatter_checks(text: str) -> tuple[list[CheckDecl], list[str]]:
+    """Parse the minimal frontmatter subset this contract supports.
+
+    Returns (declarations, errors). A missing frontmatter block or a block
+    without ``checks:`` is not an error; malformed content inside a declared
+    block is, so doctor can point at the offending spec.
+    """
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return [], []
+    end = None
+    for index in range(1, len(lines)):
+        if lines[index].strip() == "---":
+            end = index
+            break
+    if end is None:
+        return [], ["frontmatter block not closed"]
+
+    decls: list[CheckDecl] = []
+    errors: list[str] = []
+    in_checks = False
+    current: dict[str, str] | None = None
+
+    for raw in lines[1:end]:
+        stripped = raw.strip()
+        if not stripped:
+            continue
+        if not in_checks:
+            if stripped == "checks:":
+                in_checks = True
+            elif stripped.endswith(":") and not stripped.startswith("#"):
+                # Another frontmatter key; ignore its body silently.
+                in_checks = False
+            continue
+        if stripped.startswith("- "):
+            if current is not None:
+                parsed = _decl_from_pairs(current, errors)
+                if parsed is not None:
+                    decls.append(parsed)
+            current = {}
+            stripped = stripped[2:].strip()
+            if not stripped:
+                continue
+        if current is None:
+            errors.append(f"unexpected line outside a check item: {stripped!r}")
+            in_checks = False
+            continue
+        if ":" not in stripped:
+            errors.append(f"malformed check line: {stripped!r}")
+            current = None
+            in_checks = False
+            continue
+        key, _, value = stripped.partition(":")
+        key = key.strip()
+        if not key:
+            errors.append(f"malformed check line: {stripped!r}")
+            continue
+        current[key] = _strip_quotes(value)
+    parsed = _decl_from_pairs(current, errors)
+    if parsed is not None:
+        decls.append(parsed)
+    return decls, errors
+
+
+def _decl_from_pairs(pairs: dict[str, str], errors: list[str]) -> CheckDecl | None:
+    cmd = pairs.pop("cmd", "")
+    if not cmd:
+        errors.append("check item without cmd")
+        return None
+    when = pairs.pop("when", "both") or "both"
+    if when not in {"edit", "lifecycle", "both"}:
+        errors.append(f"unknown when value: {when!r}")
+        when = "both"
+    timeout_raw = pairs.pop("timeout", "")
+    try:
+        timeout = float(timeout_raw) if timeout_raw else DEFAULT_TIMEOUT
+    except ValueError:
+        errors.append(f"non-numeric timeout: {timeout_raw!r}")
+        timeout = DEFAULT_TIMEOUT
+    timeout = min(max(timeout, 0.5), MAX_TIMEOUT)
+    files_raw = pairs.pop("files", "")
+    files, file_errors = _parse_files(files_raw)
+    errors.extend(file_errors)
+    if file_errors:
+        # A declaration whose files filter cannot be honored must not fall
+        # back to "matches everything"; drop it and let doctor surface it.
+        return None
+    cmd_win = pairs.pop("cmd.win", None)
+    unknown = sorted(pairs)
+    if unknown:
+        errors.append(f"unknown check keys ignored: {', '.join(unknown)}")
+    return CheckDecl(
+        cmd=cmd,
+        files=files,
+        timeout=timeout,
+        when=when,
+        cmd_win=cmd_win,
+    )
+
+
+def _parse_files(raw: str) -> tuple[tuple[str, ...], list[str]]:
+    if not raw:
+        return (), []
+    errors: list[str] = []
+    matched: list[str] = []
+    for part in raw.split(","):
+        token = part.strip().replace("\\", "/")
+        while token.startswith("./"):
+            token = token[2:]
+        if not token:
+            continue
+        if token.endswith("/**"):
+            token = token[:-2]
+        if token.startswith("*."):
+            if "*" in token[2:] or "?" in token:
+                errors.append(f"unsupported files form (use dir/ or *.ext): {token!r}")
+                continue
+            matched.append(token)
+            continue
+        if "*" in token or "?" in token or "[" in token:
+            errors.append(f"unsupported files form (use dir/ or *.ext): {token!r}")
+            continue
+        matched.append(token if token.endswith("/") else f"{token}/")
+    return tuple(matched), errors
+
+
+def path_matches_decl_files(relative_path: str, decl: CheckDecl) -> bool:
+    if not decl.files:
+        return True
+    normalized = relative_path.replace("\\", "/")
+    for token in decl.files:
+        if token.startswith("*."):
+            if normalized.endswith(token[1:]):
+                return True
+        elif normalized.startswith(token):
+            return True
+    return False
+
+
+def collect_spec_declarations(repo_root: Path) -> list[SpecDeclarations]:
+    spec_dir = repo_root / ".cowork-flow" / "spec"
+    if not spec_dir.is_dir():
+        return []
+    collected: list[SpecDeclarations] = []
+    for path in sorted(spec_dir.rglob("*.md")):
+        relative = path.relative_to(spec_dir).as_posix()
+        parts = Path(relative).parts
+        if parts and parts[0] in EXCLUDED_SPEC_SUBDIRS:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            collected.append(
+                SpecDeclarations(relative, (), (f"unreadable spec file: {relative}",))
+            )
+            continue
+        decls, errors = parse_frontmatter_checks(text)
+        collected.append(SpecDeclarations(relative, tuple(decls), tuple(errors)))
+    return collected
+
+
+def _decl_for_platform(decl: CheckDecl) -> str:
+    if IS_WINDOWS and decl.cmd_win:
+        return decl.cmd_win
+    return decl.cmd
+
+
+def _first_violation_line(output: Iterable[str]) -> str:
+    for line in output:
+        line = line.strip()
+        if line:
+            return line[:MAX_FIRST_LINE_CHARS]
+    return ""
+
+
+def _run_command(decl: CheckDecl, repo_root: Path) -> tuple[str, int | None, str, list[str]]:
+    """Execute one declaration. Returns (status, exit_code, reason, output)."""
+    command = _decl_for_platform(decl)
+    if IS_WINDOWS:
+        # Windows: newer runtimes refuse to spawn .cmd shims directly
+        # (EINVAL); route through cmd.exe the way npm shims launch. Failure
+        # to find cmd.exe or the entry degrades to unchecked, never pass.
+        argv = ["cmd.exe", "/c", command]
+        popen_kwargs: dict = {}
+    else:
+        try:
+            argv = shlex.split(command)
+        except ValueError as error:
+            return "unchecked", None, f"unparsable command: {error}", []
+        if not argv:
+            return "unchecked", None, "empty command", []
+        resolved = shutil.which(argv[0])
+        if resolved is None:
+            return "unchecked", None, f"command not found: {argv[0]}", []
+        popen_kwargs = {}
+    try:
+        completed = subprocess.run(
+            argv,
+            cwd=str(repo_root),
+            capture_output=True,
+            text=True,
+            timeout=decl.timeout,
+            check=False,
+            **popen_kwargs,
+        )
+    except subprocess.TimeoutExpired:
+        return "unchecked", None, f"timed out after {decl.timeout:g}s", []
+    except OSError as error:
+        # PATH-stripped or otherwise degraded environments degrade to
+        # unchecked; they must never read as a passing check.
+        return "unchecked", None, f"failed to launch: {error}", []
+
+    merged = list(completed.stdout.splitlines()) + list(completed.stderr.splitlines())
+    if completed.returncode == 0:
+        return "pass", 0, "", []
+    return "violation", completed.returncode, "", merged
+
+
+def run_checks(
+    repo_root: Path,
+    *,
+    phase: str,
+    changed_files: Iterable[str] | None = None,
+    file_filter: str | None = None,
+) -> dict:
+    """Run declared checks for one phase and return a JSON-ready report.
+
+    phase: "edit" runs only edit-eligible declarations whose ``files`` match
+    ``changed_files`` (3s clamp); "lifecycle" runs every declaration honoring
+    each ``files`` scope. Parse errors are reported but never block as
+    violations — they surface through doctor.
+    """
+    if phase not in {"edit", "lifecycle"}:
+        raise SpecCheckError(f"unknown phase: {phase!r}")
+    changed = [c.replace("\\", "/") for c in (changed_files or [])]
+    if file_filter:
+        changed = [file_filter.replace("\\", "/")]
+
+    results: list[CheckResult] = []
+    parse_errors: list[dict[str, str]] = []
+    for spec_decls in collect_spec_declarations(repo_root):
+        for message in spec_decls.errors:
+            parse_errors.append({"spec": spec_decls.spec, "error": message})
+        for decl in spec_decls.decls:
+            if phase == "edit":
+                if decl.when == "lifecycle":
+                    continue
+                if not changed:
+                    continue
+                if not any(
+                    path_matches_decl_files(path, decl) for path in changed
+                ):
+                    continue
+                effective = CheckDecl(
+                    cmd=decl.cmd,
+                    files=decl.files,
+                    timeout=min(decl.timeout, EDIT_PHASE_TIMEOUT),
+                    when=decl.when,
+                    cmd_win=decl.cmd_win,
+                )
+            else:
+                if decl.when == "edit":
+                    continue
+                effective = decl
+            status, exit_code, reason, output = _run_command(effective, repo_root)
+            result = CheckResult(
+                spec=spec_decls.spec,
+                cmd=_decl_for_platform(effective),
+                status=status,
+                exit_code=exit_code,
+                first_violation_line=_first_violation_line(output) if output else "",
+                reason=reason,
+            )
+            if output:
+                result.output = output[:20]
+            results.append(result)
+
+    summary = {
+        "pass": sum(1 for r in results if r.status == "pass"),
+        "violation": sum(1 for r in results if r.status == "violation"),
+        "unchecked": sum(1 for r in results if r.status == "unchecked"),
+    }
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "phase": phase,
+        "changedFiles": changed,
+        "results": [r.to_json() for r in results],
+        "parseErrors": parse_errors,
+        "summary": summary,
+    }
+
+
+def normalized_one_line(report: dict) -> str:
+    """Single-line summary for hook injection; never multi-line output."""
+    results = report.get("results") or []
+    for item in results:
+        if item.get("status") == "violation":
+            spec = item.get("spec", "?")
+            line = item.get("firstViolationLine") or item.get("reason") or ""
+            return f"spec-check[{spec}] violation: {line}"
+    for item in results:
+        if item.get("status") == "unchecked":
+            return f"spec-check[{item.get('spec', '?')}] unchecked: {item.get('reason', '')}"
+    return ""
+
+
+# Per-file throttle for editor-phase runs: an edit storm must not multiply
+# the command cost. State lives in the workflow runtime directory because
+# every hook invocation is a fresh process — in-memory maps cannot throttle
+# across invocations.
+EDIT_THROTTLE_INTERVAL_SECONDS = 10.0
+EDIT_THROTTLE_FILE = ".cowork-flow" / Path(".runtime") / "spec-edit-throttle.json"
+
+
+def _read_throttle(root: Path) -> dict:
+    try:
+        data = json.loads((root / EDIT_THROTTLE_FILE).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _write_throttle(root: Path, file_path: str, timestamp: float) -> None:
+    path = root / EDIT_THROTTLE_FILE
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps({"file": file_path, "ts": timestamp}, ensure_ascii=False)
+            + "\n",
+            encoding="utf-8",
+        )
+    except OSError:
+        # Throttle state is best-effort; a failed write just means the next
+        # edit runs its checks again.
+        pass
+
+
+def run_edit_checks(
+    repo_root: Path,
+    file_path: str,
+    *,
+    throttled: bool = True,
+    now: float | None = None,
+) -> str:
+    """Editor-phase single-line result for one changed file.
+
+    Empty string means "nothing to report": no declaration matched, the file
+    was throttled, or checks passed. Violations and unchecked degradations
+    return the normalized one-line summary. Never raises for expected
+    operating conditions — the editor path must not break edits.
+    """
+    import time
+
+    normalized = file_path.replace("\\", "/").strip()
+    if not normalized:
+        return ""
+    # Hosts pass absolute edit paths; declaration filters are repo-relative.
+    try:
+        normalized = (
+            Path(normalized).resolve().relative_to(repo_root.resolve()).as_posix()
+        )
+    except (ValueError, OSError):
+        pass
+    if throttled:
+        state = _read_throttle(repo_root)
+        current = time.time() if now is None else now
+        if (
+            state.get("file") == normalized
+            and isinstance(state.get("ts"), (int, float))
+            and current - state["ts"] < EDIT_THROTTLE_INTERVAL_SECONDS
+        ):
+            return ""
+        _write_throttle(repo_root, normalized, current)
+    try:
+        report = run_checks(repo_root, phase="edit", changed_files=[normalized])
+    except Exception:
+        return ""
+    return normalized_one_line(report)
+
+
+def summary_has(report: dict, key: str) -> bool:
+    return bool((report.get("summary") or {}).get(key))

package/template/.cowork-flow/scripts/services/task_lifecycle.py

@@ -151,6 +151,7 @@ class TaskLifecycleService:
         *,
         completed_at: str | None = None,
         allow_spec_file_modifications: bool | None = None,
+        allow_unchecked_specs: bool = False,
         execution_context: object | None = None,
     ) -> LifecycleResult:
         return self.execute(
@@ -158,6 +159,7 @@ class TaskLifecycleService:
             task,
             completed_at=completed_at,
             allow_spec_file_modifications=allow_spec_file_modifications,
+            allow_unchecked_specs=allow_unchecked_specs,
             execution_context=execution_context,
         )
 
@@ -168,6 +170,7 @@ class TaskLifecycleService:
         *,
         preflight: Preflight | None = None,
         allow_spec_file_modifications: bool | None = None,
+        allow_unchecked_specs: bool = False,
         completed_at: str | None = None,
         execution_context: object | None = None,
         executor: str | None = None,
@@ -179,6 +182,7 @@ class TaskLifecycleService:
             self.repo_root,
             execution_context,
             allow_spec_file_modifications=allow_spec_file_modifications,
+            allow_unchecked_specs=allow_unchecked_specs,
         )
         prepared = self._prepare_transition(
             stage, task_dir, preflight, executor=executor, takeover=takeover
@@ -334,7 +338,12 @@ class TaskLifecycleService:
             task_dir,
             task_data,
             self._persisted_task_data(
-                stage, task_data, completed_at, executor=resolved_executor
+                stage,
+                task_data,
+                completed_at,
+                executor=resolved_executor,
+                check_result=check_result,
+                execution_policy=execution_policy,
             ),
             session_state,
             check_result,
@@ -559,6 +568,8 @@ class TaskLifecycleService:
         task_data: dict,
         completed_at: str | None,
         executor: str | None = None,
+        check_result: object | None = None,
+        execution_policy: LifecycleExecutionPolicy | None = None,
     ) -> dict:
         persisted = dict(task_data)
         persisted["status"] = stage.target_status
@@ -579,6 +590,27 @@ class TaskLifecycleService:
                 if head:
                     meta["baselineCommit"] = head
                     persisted["meta"] = meta
+        if stage.name == COMPLETE_STAGE.name:
+            meta = dict(persisted.get("meta") or {})
+            spec_report = getattr(check_result, "spec_check", None)
+            if isinstance(spec_report, dict):
+                # Overwrite-on-each-completion telemetry: retry loops must
+                # not accumulate, the latest gate result wins.
+                meta["specCheckSummary"] = dict(
+                    spec_report.get("summary") or {}
+                )
+                if (
+                    execution_policy is not None
+                    and execution_policy.allow_unchecked_specs
+                    and int((spec_report.get("summary") or {}).get("unchecked") or 0)
+                ):
+                    meta["specCheckExempt"] = {
+                        "at": datetime.now().strftime("%Y-%m-%dT%H:%M:%S"),
+                        "unchecked": int(
+                            (spec_report.get("summary") or {}).get("unchecked") or 0
+                        ),
+                    }
+                persisted["meta"] = meta
         return persisted
 
     def _resolve_executor(self, executor: str | None) -> str | None:

package/template/.cowork-flow/spec/backend/error-handling.md

@@ -1,5 +1,19 @@
 # 后端异常处理规范
 
+<!--
+本 spec 支持 frontmatter `checks:` 声明检查命令（规范挂命令契约见
+spec/contracts/spec-checks.md）。模板自带的声明由上游维护、sync 会覆盖
+本地修改；请把实际声明写进自建 spec 文件。示例：
+
+---
+checks:
+  - cmd: python scripts/check_error_codes.py
+    files: "src/"
+    when: lifecycle
+---
+
+-->
+
 ## 目标
 
 - 调用方能稳定感知错误

package/template/.cowork-flow/spec/contracts/index.md

@@ -11,3 +11,4 @@
 - `capabilities.md`: 宿主适配器能力模型。
 - `party-mode-v2-board.md`: Party Mode V2 board 协议。
 - `plan-binding.md`: 开发计划轻量绑定、启动前缺失阻断和恢复可见性合同。
+- `spec-checks.md`: 规范挂命令契约——用户规范 frontmatter `checks:` 声明的语法、三态门禁语义、时机与宿主能力矩阵。

package/template/.cowork-flow/spec/contracts/spec-checks.md

@@ -0,0 +1,74 @@
+# Spec Check 契约（规范挂命令）
+
+用户规范（`.cowork-flow/spec/` 下 `backend/`、`frontend/`、自建目录）可通过
+frontmatter 的 `checks:` 声明检查命令。机制只执行声明、不解析规范正文——
+规则变化 = 用户改同一个文件里的命令，天然同步。
+
+## 语法
+
+```markdown
+---
+checks:
+  - cmd: npm run lint --silent
+    files: "src/"          # 可选：适用范围，目录前缀或扩展名（"*.ts"），逗号分隔
+    timeout: 60            # 可选：秒，默认 30，硬顶 120
+    when: both             # 可选：edit | lifecycle | both（默认 both）
+    cmd.win: npm run lint  # 可选：Windows 覆盖命令
+---
+
+# 规范正文（机制不读）
+```
+
+- `files` 只支持两种形式：目录前缀（`src/`，以 `/` 结尾或自动补齐）与
+  扩展名（`*.ts`）。完整 glob 形态（`**`、`[]`）解析为错误，声明不执行，
+  doctor 报告——绝不回退为"匹配一切"。
+- `when: edit` 的声明在编辑期（PostToolUse）对命中 `files` 的改动文件
+  就地执行，超时被钳制到 3 秒；慢命令请声明 `when: lifecycle`。
+- 引号规则：仅值整体为单对引号时去引号；`"python" -c "..."`
+  这类含多对引号的命令值原样保留，由执行器按 shell 规则拆分。
+
+## 三态结果（完成门禁语义）
+
+| 状态 | 含义 | complete 门禁 |
+| --- | --- | --- |
+| `pass` | 退出码 0 | 通过 |
+| `violation` | 退出码非 0 | **阻断**（状态不推进） |
+| `unchecked` | 命令不存在/解释器缺失/超时 | **阻断**；显式 `--allow-unchecked` 可放行，豁免留痕进 task.json `meta.specCheckExempt` |
+
+unchecked 永不冒充 pass（"没跑成"不是"通过"）。frontmatter 畸形视该
+spec 为无检查并进 doctor 报告，不炸流程。
+
+## 时机与单行输出
+
+- **编辑期**（zcode/claude）：违规输出单行
+  `spec-check[<spec>] violation: <首个违规行>`；同一文件 10 秒内只报一次
+  （节流状态在 `.cowork-flow/.runtime/spec-edit-throttle.json`）；执行器
+  缺失或超时静默，绝不阻断编辑流。
+- **收口期**（task complete）：全量执行，结果进 `meta.specCheckSummary`
+  遥测；阻断消息只列未过项摘要。
+- 手动查询：`./.cowork-flow/run spec-check [--file <path>] [--json]
+  [--verbose]`。
+
+## 归属与 sync 策略
+
+- **模板自带 spec**（`spec/backend/` 等随包分发）的 check 声明由
+  cowork-flow 上游维护，属 sync safe 资产——本地修改会被 sync 覆盖。
+- **用户自定义规范**请放自建 spec 文件（如 `spec/team-xxx.md` 或自建
+  子目录），sync 不触碰；check 声明随规范正文一起由用户维护。
+
+## 宿主能力矩阵
+
+| 宿主 | digest 注入 | 编辑期快跑 | 收口强制 |
+| --- | --- | --- | --- |
+| zcode | 有（Specs 行 h2 digest） | 有（PostToolUse 短路径） | 有 |
+| claude-code | 有（Python 单源） | 有（PostToolUse，exit 2 反馈） | 有 |
+| opencode | 有 | **降级：无**（插件无 PostToolUse 短路径） | 有 |
+
+## digest 注入
+
+进入 in_progress 后，stage-contract 的 Specs 行升级为
+`Specs: <spec>(<h2 标题树>); …`：最多 6 个 h2 条目、每条截断 24 字符、
+剔除 `();` 字符；文件缺失不加注解。digest 是条目名索引不是正文，受
+scope-rules.json `stageContract.budget` 硬顶，超预算整行让位
+（Scope/Gates 行永不丢）。格式由三线逐字相等测试锁定
+（`test/stage-contract.test.js` matrix）。