@peterxiaoyang/superspec 0.1.55 → 0.1.57

package/README.md

@@ -4,15 +4,26 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20.19.0-brightgreen?style=flat-square)](https://nodejs.org)
 [![OpenSpec](https://img.shields.io/badge/OpenSpec-compatible-6f42c1?style=flat-square)](https://github.com/Fission-AI/OpenSpec)
 
-SuperSpec 是一套面向 AI 编程代理的需求变更工作流。它在 OpenSpec 材料之上增加阶段控制、审查和验证记录，帮助 AI 从需求理解推进到可回放的交付结果。
+AI 写代码很快。真正慢的是之后：范围悄悄变大、完成全凭一张嘴、review 时问一句「这里为什么要改」它才承认不该改。
+
+SuperSpec 是一套跑在 AI 编程代理（Codex 等）下的需求变更工作流引擎。它把「不要乱改、别过度设计、做完要有证据」从 prompt 劝说升级成**机器门禁**——约束写在 CLI 和数据契约里，不靠模型自觉。
 
 ```text
 Explore → Propose → Apply → Review → Accepted
 ```
 
-SuperSpec 适合跨模块、涉及接口或需要方案审查的变更。简单的单文件修改不必强行使用完整工作流。普通请求也不会自动进入 SuperSpec，只有明确调用对应入口或继续已有 change 时才会启动。
+## 它拦得住什么
+
+| 你遇到的问题 | SuperSpec 的机制 |
+| --- | --- |
+| 「顺手」改了不该改的，加了不该加的方法 | 每个任务绑定五字段执行依据：测试 / 设计 / 来源 / 验收 / 边界，引用可解析性由状态机校验；实现越界必须走结构化的范围说明，而不是一句道歉 |
+| 说自己做完了，测过没有无从考证 | 任务启动即冻结证据要求：该 RED 的先失败、该 GREEN 的真通过，测试证据绑定任务尝试；全程事件日志带摘要，可回放、防篡改 |
+| 审查抓到了问题，修复时又把新架构夹带回来 | 阻塞问题必须标注类型（漏做 / 破坏已有 / 计划外新增）并**锚定到已批准材料**才能受理；修复任务的指令只兑现锚点，审查建议里的架构永远不是授权 |
+| 审查形同虚设，「看起来没问题」就通过 | critic / architect / test-engineer / code-reviewer / verifier 独立角色持密封工作项审查，pass 必须说明覆盖了什么，fail 必须给出可追溯的证据 |
+
+这些约束全部由引擎在提交口强制执行：答不出锚点的阻塞问题直接拒收，而不是等你在对话里追问。
 
-## 安装
+## 快速开始
 
 要求 Node.js `>=20.19.0`。
 
@@ -22,18 +33,17 @@ cd <your-project>
 superspec install
 ```
 
-`superspec install` 会把工作流入口、角色配置和运行时目录同步到当前项目，并准备 OpenSpec 依赖。`superspec init --scope project` 是兼容别名。
+`superspec install` 会把工作流入口、角色配置和运行时目录同步到当前项目，并准备 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 依赖。
 
-检查安装：
+然后在 Codex 里对它说话：
 
-```bash
-superspec version
-superspec status
+```text
+superspec-explore change <change-name>。<你的需求>
 ```
 
-## 工作流入口
+工作流接管之后，每一步该做什么由 `superspec transition next` 决定——AI 不自由发挥流程，只在被授权的范围内干活。
 
-在 Codex 中显式调用对应 Skill。新需求通常从 `superspec-explore` 开始；已有 change 则从当前阶段继续。
+## 工作流入口
 
 | Skill | 作用 |
 | --- | --- |
@@ -42,35 +52,21 @@ superspec status
 | `superspec-apply` | 按已批准任务修改代码并验证 |
 | `superspec-review` | 审查实现并完成最终验证 |
 
-工作流会根据问题性质留在当前阶段修复，或回到计划阶段重新确认需求、验收和技术取舍。
-
-## 配置
+修不动会自己拐弯：能由既有任务解释的问题留在 Apply 内闭环；需要改需求、验收或技术取舍的，回到计划阶段重新确认。
 
-项目级配置位于 `.superspec/config.json`。未创建配置或未声明模式时，默认使用 `normal`：
-
-```json
-{
-  "workflow": {
-    "mode": "normal",
-    "hosts": ["codex"]
-  }
-}
-```
+## 轻量，且知道自己的边界
 
-可选模式为 `minimal`、`normal` 和 `strict`。模式主要影响计划阶段的审查强度；最终代码审查和验证仍由 Review 阶段负责。
+- **三档强度**：`minimal` / `normal` / `strict`（`.superspec/config.json`），按变更风险选择计划阶段的审查强度。
+- **不绑架日常**：简单的单文件修改不必走完整工作流；普通请求也不会自动进入 SuperSpec，只有显式调用入口才启动。
+- **诚实的能力边界**：它是流程与审计辅助，不是安全隔离或发布审批系统；不能替代代码审计、权限控制、合规检查和人工判断。
 
 ## 与 OpenSpec 的关系
 
-OpenSpec 负责变更材料和规格结构；SuperSpec 负责组织 AI 的探索、计划、实现、审查与证据记录。两者互补：
-
-```text
-OpenSpec：这次要改变什么
-SuperSpec：如何在边界内把它交付
-```
+OpenSpec 负责「这次要改变什么」，提供变更材料与规格结构；SuperSpec 负责「如何在边界内把它交付」，组织 AI 的探索、计划、实现、审查与证据记录。
 
-## 设计边界
+## 评测
 
-SuperSpec 是流程和审计辅助工具，不是安全隔离或发布审批系统。它不能替代代码审计、权限控制、合规检查和人工判断。
+仓库自带密封评测考场（隔离工作区 + 真实 Agent 运行 + 硬门禁 + 双模型语义复盘），用于验证工作流行为本身，而不只是 Prompt 文案。见 [`evals/README.md`](evals/README.md)。
 
 ## 致谢
 

package/dist/approved_ref.d.ts

@@ -0,0 +1,26 @@
+import type { CodeReviewClaimKind } from "./types.ts";
+export declare const CODE_REVIEW_CLAIM_KINDS: readonly ["missing_approved", "breaks_existing", "unjustified_addition"];
+export type ApprovedRefKind = "test" | "requirement" | "task" | "design" | "proposal" | "structure";
+export interface ResolvedApprovedRef {
+    raw: string;
+    kind: ApprovedRefKind;
+    short: string;
+}
+export declare function isCodeReviewClaimKind(value: unknown): value is CodeReviewClaimKind;
+export declare function shortApprovedRef(raw: string): string;
+export declare function resolveApprovedRef(changeRoot: string, raw: unknown): {
+    ok: true;
+    value: ResolvedApprovedRef;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function resolveApprovedRefs(changeRoot: string, refs: unknown): {
+    ok: true;
+    values: ResolvedApprovedRef[];
+} | {
+    ok: false;
+    reasons: string[];
+};
+export declare function hasBehaviorAnchor(values: readonly ResolvedApprovedRef[]): boolean;
+export declare function reviewFixReason(claimKind: CodeReviewClaimKind, refs: readonly string[]): string;

package/dist/approved_ref.js

@@ -0,0 +1,159 @@
+// SuperSpec 代码审查 approved_refs：只做存在性解析，不做语义匹配。
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { headingExists, parseTasksMd, parseTestContractEntries, parseStructureChangeLedger } from "./format.js";
+export const CODE_REVIEW_CLAIM_KINDS = [
+    "missing_approved",
+    "breaks_existing",
+    "unjustified_addition",
+];
+const TEST_ID_RE = /^TEST-[A-Za-z0-9_-]+$/;
+const STRUCTURE_LEDGER_ID_RE = /^SC-[A-Za-z0-9_-]+$/;
+const TEST_CONTRACT_REL = join(".superspec", "artifacts", "test-contract.md");
+function isPathInside(root, target) {
+    const rel = relative(root, target);
+    return rel !== "" && !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+function shortTestId(raw) {
+    const trimmed = raw.trim();
+    if (TEST_ID_RE.test(trimmed))
+        return trimmed;
+    const hash = trimmed.lastIndexOf("#");
+    if (hash >= 0) {
+        const id = trimmed.slice(hash + 1).trim();
+        if (TEST_ID_RE.test(id))
+            return id;
+    }
+    return null;
+}
+function readChangeFile(changeRoot, relPath) {
+    const target = resolve(changeRoot, relPath);
+    if (!isPathInside(resolve(changeRoot), target) && resolve(changeRoot) !== target)
+        return null;
+    try {
+        if (!statSync(target).isFile())
+            return null;
+        return readFileSync(target, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function isCodeReviewClaimKind(value) {
+    return typeof value === "string" && CODE_REVIEW_CLAIM_KINDS.includes(value);
+}
+export function shortApprovedRef(raw) {
+    const testId = shortTestId(raw);
+    if (testId)
+        return testId;
+    const req = /#Requirement:\s*(.+)$/.exec(raw.trim());
+    if (req)
+        return `Requirement: ${req[1].trim()}`;
+    const hash = raw.lastIndexOf("#");
+    if (hash >= 0 && hash < raw.length - 1)
+        return raw.slice(hash + 1).trim();
+    return raw.trim();
+}
+export function resolveApprovedRef(changeRoot, raw) {
+    if (typeof raw !== "string" || raw.trim() === "") {
+        return { ok: false, reason: "approved_refs 条目必须是非空字符串" };
+    }
+    const ref = raw.trim();
+    if (/[\u0000-\u001f\u007f]/.test(ref)) {
+        return { ok: false, reason: `approved_refs 条目不能包含换行等控制字符：${JSON.stringify(ref)}` };
+    }
+    const testId = shortTestId(ref);
+    if (testId) {
+        if (ref.includes("#") && !ref.endsWith(`#${testId}`)) {
+            return { ok: false, reason: `TEST 引用只能是裸 TEST-ID 或以 #TEST-ID 结尾指向 test-contract.md：${ref}` };
+        }
+        if (ref.includes("#")) {
+            const path = ref.slice(0, ref.lastIndexOf("#")).replace(/\\/g, "/");
+            const allowed = path === TEST_CONTRACT_REL.replace(/\\/g, "/")
+                || path === "test-contract.md"
+                || path.endsWith("/test-contract.md");
+            if (!allowed)
+                return { ok: false, reason: `TEST 引用只能指向 test-contract.md：${ref}` };
+        }
+        const content = readChangeFile(changeRoot, TEST_CONTRACT_REL);
+        if (content == null)
+            return { ok: false, reason: `无法读取 ${TEST_CONTRACT_REL.replace(/\\/g, "/")}，无法校验 TEST 引用：${ref}` };
+        const parsed = parseTestContractEntries(content);
+        if (!parsed.ok || !parsed.entries.some(entry => entry.test_id === testId)) {
+            return { ok: false, reason: `${TEST_CONTRACT_REL.replace(/\\/g, "/")} 中不存在 ${testId}` };
+        }
+        return { ok: true, value: { raw: ref, kind: "test", short: testId } };
+    }
+    const separator = ref.indexOf("#");
+    if (separator <= 0 || separator === ref.length - 1) {
+        return { ok: false, reason: `锚点格式无法解析，应为 文件#标题 或 TEST-ID：${ref}` };
+    }
+    const path = ref.slice(0, separator).replace(/\\/g, "/");
+    const anchor = ref.slice(separator + 1).trim();
+    const content = readChangeFile(changeRoot, path);
+    if (content == null)
+        return { ok: false, reason: `${path} 在当前 change 中不存在` };
+    if (path === "tasks.md") {
+        const tasks = parseTasksMd(content);
+        if (!tasks.some(task => task.taskId === anchor))
+            return { ok: false, reason: `tasks.md 中不存在任务 ${anchor}` };
+        return { ok: true, value: { raw: ref, kind: "task", short: anchor } };
+    }
+    if (path === "design.md") {
+        if (STRUCTURE_LEDGER_ID_RE.test(anchor)) {
+            const ledger = parseStructureChangeLedger(content);
+            if (ledger.present && ledger.entries.some(entry => entry.id === anchor)) {
+                return { ok: true, value: { raw: ref, kind: "structure", short: anchor } };
+            }
+            return { ok: false, reason: `design.md 结构变更清单中不存在 ${anchor}` };
+        }
+        if (!headingExists(content, anchor))
+            return { ok: false, reason: `design.md 中不存在标题「${anchor}」` };
+        return { ok: true, value: { raw: ref, kind: "design", short: anchor } };
+    }
+    if (path === "proposal.md") {
+        if (!headingExists(content, anchor))
+            return { ok: false, reason: `proposal.md 中不存在标题「${anchor}」` };
+        return { ok: true, value: { raw: ref, kind: "proposal", short: anchor } };
+    }
+    if (/^specs\/[^/]+\/spec\.md$/.test(path)) {
+        const requirementTitle = anchor.startsWith("Requirement:")
+            ? anchor.slice("Requirement:".length).trim()
+            : "";
+        if (!requirementTitle)
+            return { ok: false, reason: `spec 锚点必须以 Requirement: 开头：${ref}` };
+        if (!headingExists(content, `Requirement: ${requirementTitle}`)) {
+            return { ok: false, reason: `${path} 中不存在 Requirement「${requirementTitle}」` };
+        }
+        return {
+            ok: true,
+            value: { raw: ref, kind: "requirement", short: `Requirement: ${requirementTitle}` },
+        };
+    }
+    return { ok: false, reason: `只支持 tasks.md、design.md、proposal.md、specs/*/spec.md 与 test-contract.md 的锚点：${ref}` };
+}
+export function resolveApprovedRefs(changeRoot, refs) {
+    if (!Array.isArray(refs) || refs.length === 0) {
+        return { ok: false, reasons: ["approved_refs 必须是非空字符串数组"] };
+    }
+    const values = [];
+    const reasons = [];
+    for (const raw of refs) {
+        const resolved = resolveApprovedRef(changeRoot, raw);
+        if (!resolved.ok)
+            reasons.push(resolved.reason);
+        else
+            values.push(resolved.value);
+    }
+    if (reasons.length > 0)
+        return { ok: false, reasons };
+    return { ok: true, values };
+}
+export function hasBehaviorAnchor(values) {
+    return values.some(value => value.kind === "test" || value.kind === "requirement");
+}
+export function reviewFixReason(claimKind, refs) {
+    const shorts = refs.map(shortApprovedRef).filter(Boolean);
+    const target = shorts.length > 0 ? shorts.join("、") : "已批准行为";
+    return `兑现 ${target}（${claimKind}）`;
+}

package/dist/cli.js

@@ -557,6 +557,8 @@ function topLevelHelp() {
   update [--hosts codex,omp]        升级 CLI 到 npm latest 并同步已选宿主入口
   version                           版本号
 
+工作流配置见 .superspec/config.json（workflow.mode、workflow.budget）。
+
 transition 子命令：
   init / explore / sync / next / propose-ready / start-apply
   task-start --task <T> / task-complete --task <T> [--input -]

package/dist/code_review.d.ts

@@ -69,12 +69,19 @@ export declare function codeReviewPacketDigest(input: {
     packet_context?: JobPacketContext;
     previous_rejection?: ReviewPreviousRejection;
 }): string;
+export declare function addedCodePathsForScope(projectRoot: string, scope: CodeReviewScope): string[];
 export declare function codeReviewPacketContext(changeRoot: string, projectRoot: string, scope: CodeReviewScope, events: Event[]): JobPacketContext;
 export declare function effectiveCoverageExemptionRefsFromEvents(events: Event[]): CoverageExemptionRef[];
 export declare function missingCoverageExemptionTestIds(changeRoot: string, events: Event[]): string[];
 /** Read-only execution evidence projected for code review and final verification. */
 export declare function taskExecutionIndexForReview(projectRoot: string, events: Event[]): TaskExecutionIndexEntry[];
 export declare function codeReviewDecisionScope(jobId: string, findingId: string): string;
+/** 自当前 Apply round 的 start-apply 起，带 review_fix_of 的 reopen 次数。 */
+export declare function countReviewFixReopensSinceStartApply(events: readonly Event[]): number;
+/** 上限是否生效按 Apply round 在 start-apply 冻结的档位判断（minimal 忽略），未冻结时回落项目配置。 */
+export declare function isReviewFixCapReached(projectRoot: string, events: readonly Event[]): boolean;
+/** spec / mixed 问题始终交使用者决策；implementation 问题只在自动修复触顶后交使用者决策。 */
+export declare function codeReviewFindingNeedsUserDecision(type: string | undefined, reviewFixCapReached: boolean): boolean;
 export interface CodeReviewDecisionScopeRef {
     jobId: string;
     findingId: string;

package/dist/code_review.js

@@ -4,7 +4,9 @@ import { join } from "node:path";
 import { findLatestEvent, sha256File, sha256Text } from "./store.js";
 import { REVIEW_CODE_REVIEW_GATE } from "./review_job_gates.js";
 import { codeFileContentSha, currentGitHead, diffFingerprints, dirtyCodeFiles, dirtyCodePaths, gitLines, isCodeLikePath, projectHasReadableDirectory, walkCodeFiles, } from "./git_state.js";
-import { parseExecutionRequirements, parseTestContractEntries } from "./format.js";
+import { parseExecutionRequirements, parseTestContractEntries, parseStructureChangeLedger } from "./format.js";
+import { planningValidationProfileForCurrentRound } from "./propose_round.js";
+import { workflowBudgetForRisk, workflowRiskForApplyRound, workflowRiskForProject } from "./workflow_config.js";
 export const CODE_REVIEW_REPAIR_SCOPE_PREFIX = "code_reviewer_report_repair:";
 export const CODE_REVIEW_DECISION_SCOPE_PREFIX = "code_review_decision:";
 export const TEST_COVERAGE_EXEMPTION_SCOPE_PREFIX = "test_coverage_exemption:";
@@ -360,6 +362,51 @@ export function codeReviewJobStaleReason(projectRoot, job, currentPaths, events,
 export function codeReviewPacketDigest(input) {
     return sha256Text(JSON.stringify(input));
 }
+export function addedCodePathsForScope(projectRoot, scope) {
+    if (!scope.scope_reliable)
+        return [];
+    const added = new Set();
+    let baseHead = scope.base_head;
+    if (!baseHead && scope.current_head) {
+        // 首轮 start-apply 前仓库还没有提交：以空树为基点，让 Apply 期间产生的首个提交也进入新增清单。
+        const emptyTree = gitLines(projectRoot, ["hash-object", "-t", "tree", "/dev/null"]);
+        if (emptyTree.ok)
+            baseHead = emptyTree.lines[0] ?? null;
+    }
+    if (baseHead && scope.current_head) {
+        const committed = gitLines(projectRoot, [
+            "diff", "--no-renames", "--diff-filter=A", "--name-only", `${baseHead}..${scope.current_head}`,
+        ]);
+        if (committed.ok) {
+            for (const path of committed.lines) {
+                if (isCodeLikePath(path))
+                    added.add(path);
+            }
+        }
+    }
+    const dirty = dirtyCodeFiles(projectRoot);
+    if (dirty.ok) {
+        for (const file of dirty.files) {
+            if (file.status === "added" && isCodeLikePath(file.path))
+                added.add(file.path);
+        }
+    }
+    for (const path of scope.untracked_paths) {
+        if (isCodeLikePath(path))
+            added.add(path);
+    }
+    return [...added].sort();
+}
+function structureLedgerForCodeReview(changeRoot, events) {
+    // 只有 v2 planning round 才有清单契约；v1 change 不写该字段，保持旧 packet 形态。
+    if (planningValidationProfileForCurrentRound(events)?.design?.schema_version !== 2)
+        return undefined;
+    const designPath = join(changeRoot, "design.md");
+    if (!existsSync(designPath))
+        return undefined;
+    const ledger = parseStructureChangeLedger(readFileSync(designPath, "utf8"));
+    return ledger.present ? ledger : undefined;
+}
 export function codeReviewPacketContext(changeRoot, projectRoot, scope, events) {
     const taskExecutionIndex = taskExecutionIndexFromEvents(projectRoot, events);
     // changed_paths 未知（快照缺失）或不完整（committed 段 diff 失败）的 task
@@ -373,12 +420,15 @@ export function codeReviewPacketContext(changeRoot, projectRoot, scope, events)
         for (const path of item.changed_paths ?? [])
             attributedPaths.add(path);
     }
+    const structureLedger = structureLedgerForCodeReview(changeRoot, events);
     return {
         code_review_scope: scope,
         coverage_exemption_refs: coverageExemptionRefs(changeRoot, events),
         task_execution_index: taskExecutionIndex,
         unattributed_paths: scope.review_paths.filter(path => !attributedPaths.has(path)).sort(),
         unknown_attribution_tasks: unknownAttributionTasks,
+        added_code_paths: addedCodePathsForScope(projectRoot, scope),
+        ...(structureLedger ? { structure_ledger: structureLedger } : {}),
     };
 }
 export function effectiveCoverageExemptionRefsFromEvents(events) {
@@ -571,6 +621,47 @@ function codeReviewResultKind(value) {
 export function codeReviewDecisionScope(jobId, findingId) {
     return `${CODE_REVIEW_DECISION_SCOPE_PREFIX}${jobId}#${findingId}`;
 }
+// ===== review-fix 自动修复上限 =====
+//
+// next / reopen --review-fix / record user-decision 三处必须得出同一个结论，
+// 否则会出现 next 要求使用者决策而 CLI 直调仍自动放行的分叉。这里是唯一判定入口。
+/** 自当前 Apply round 的 start-apply 起，带 review_fix_of 的 reopen 次数。 */
+export function countReviewFixReopensSinceStartApply(events) {
+    let startIndex = -1;
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        if (payload.transition === "start-apply" && payload.to_state === "apply") {
+            startIndex = i;
+            break;
+        }
+    }
+    if (startIndex < 0)
+        return 0;
+    let count = 0;
+    for (const ev of events.slice(startIndex + 1)) {
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        if (typeof payload.review_fix_of === "string" && payload.review_fix_of.trim() !== "")
+            count++;
+    }
+    return count;
+}
+/** 上限是否生效按 Apply round 在 start-apply 冻结的档位判断（minimal 忽略），未冻结时回落项目配置。 */
+export function isReviewFixCapReached(projectRoot, events) {
+    const risk = workflowRiskForApplyRound(events, workflowRiskForProject(projectRoot));
+    const budget = workflowBudgetForRisk(projectRoot, risk);
+    if (!budget || budget.review_fix_rounds === null)
+        return false;
+    return countReviewFixReopensSinceStartApply(events) >= budget.review_fix_rounds;
+}
+/** spec / mixed 问题始终交使用者决策；implementation 问题只在自动修复触顶后交使用者决策。 */
+export function codeReviewFindingNeedsUserDecision(type, reviewFixCapReached) {
+    return type === "spec" || type === "mixed" || (type === "implementation" && reviewFixCapReached);
+}
 /** 只接受状态机生成的 <job>#<finding> 决策范围。 */
 export function parseCodeReviewDecisionScope(scope) {
     if (!scope.startsWith(CODE_REVIEW_DECISION_SCOPE_PREFIX))

package/dist/format.d.ts

@@ -1,4 +1,4 @@
-import { type ExecutionContract, type ExecutionPolicy } from "./types.ts";
+import { type ExecutionContract, type ExecutionPolicy, type StructureChangeLedger } from "./types.ts";
 export declare const EXPLORE_OPEN_QUESTION_SCOPE_PREFIX = "explore_open_question:";
 /**
  * Discovery 的未确认项是用户决策的唯一候选来源。这里保留原有的“仅指定段落内
@@ -93,6 +93,30 @@ export declare function collectProposeOpenQuestions(changeRoot: string): {
     openCount: number;
     files: ProposeOpenQuestionFile[];
 };
+export declare const STRUCTURE_CHANGE_CATEGORIES: readonly ["新增持久化结构", "迁移或回填", "功能开关", "新增公共接口", "删除既有路径", "改既有公共签名", "改变既有数据语义", "新增公共类型"];
+export type StructureChangeCategory = (typeof STRUCTURE_CHANGE_CATEGORIES)[number];
+export declare const STRUCTURE_DECISION_REQUIRED_CATEGORIES: ReadonlySet<string>;
+export declare function isStructureChangeCategory(value: string): value is StructureChangeCategory;
+export declare function parseStructureChangeLedger(content: string): StructureChangeLedger;
+export interface StructureChangeLedgerValidation {
+    ok: boolean;
+    errors: string[];
+}
+/** Markdown 标题是否存在（任意层级，允许闭合 #）。供文档引用解析共用。 */
+export declare function headingExists(content: string, title: string): boolean;
+/**
+ * 结构变更清单"需求依据"的唯一解析入口。与 approved_refs 的解析分开：
+ * 这里接受 discovery 标题、拒绝 proposal.md#Impact，且按类别收紧允许集。
+ */
+export declare function resolveStructureBasisRef(changeRoot: string, raw: unknown, category: string): {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function validateStructureChangeLedger(changeRoot: string, ledger: StructureChangeLedger): StructureChangeLedgerValidation;
+export declare function formatStructureChangeLedgerSummary(ledger: StructureChangeLedger): string | null;
 export interface ParsedTask {
     taskId: string;
     lineIdx: number;