| name | spec-anchor |
| description | 工程上下文管理技能——在含有 anchor.yaml 或 .specanchor/ 的项目中必须调用。适用于代码修改、代码审查、Spec/上下文管理、对齐检查、交接、发现记录或沉淀工作之前。加载编码标准、模块合约和活跃任务。当用户提到 spec-anchor、specanchor 脚本、Spec 管理、上下文装配、对齐检查、boot 流程、Assembly Trace 等概念时也应调用本技能。即使是小改动也要先加载，因为 Spec 中包含代码本身看不到的约束。 |
| allowed-tools | ["Bash","Read"] |
If this project has `anchor.yaml` or `.specanchor/`, load SpecAnchor context before code changes or reviews.
Specs contain constraints not visible in code alone — even for small edits, assemble context first.
Read-only mechanical operations (grep, find, git log, running tests) do not require SpecAnchor boot.
If the user explicitly mentions spec-anchor or specanchor scripts but the CWD lacks `anchor.yaml`/`.specanchor/`, skip boot but still use this skill's knowledge to assist — read script files via `$SA_SKILL_DIR/scripts/` or locate them with `find`.
SpecAnchor
SpecAnchor compiles bounded, auditable, sedimentable engineering context for coding agents. It does not own the agent loop.
SpecAnchor 为 AI coding agent 编译有边界、可审计、可沉淀的工程上下文。它不拥有 agent 执行循环。
Spec 是 cold context 来源之一，代码是船，Context Bundle 是 SpecAnchor 的核心交付物。SpecAnchor 把工作记忆显式分为四类产物——Spec / Decision / Evidence / Finding——按 inclusion / budget / freshness / staleness 装配成 Bundle 交给 agent。Agent 在执行中产生的新发现回写为 Finding，经 Sediment Proposal 由人 batch review 后才进入长期 Spec。跨 session 通过 specanchor_handoff 导出 handoff packet 重启。
主 SKILL.md 只负责入口和 boot；详细协议下沉到 references/：
- Context utilities：
references/agents/context-utilities.md
- Workflow gates：
references/workflow-gates.md
- Command quickref：
references/commands-quickref.md
- Reference index：
references/reference-index.md
Script Invocation
Skill 脚本位于 Skill 根目录的 scripts/ 下，运行时必须站在用户项目根目录。
SPECANCHOR_SKILL_DIR="$SA_SKILL_DIR" bash "$SA_SKILL_DIR/scripts/<script-name>.sh" [args]
Keep long options as a single shell argument: use --format=summary, never -- format=summary.
工作流程
- Boot — 运行
specanchor-boot.sh 加载项目配置、模块结构和活跃任务（详见 Boot Requirement）
- 输出 Assembly Trace — Boot 完成后立即输出 Global/Module 加载状态（详见 Assembly Trace）
- 按需装配 — 深入特定模块时运行
specanchor-assemble.sh --files=... --intent=...（详见 Loading Strategy）
- 执行编码任务 — 基于已加载的 Spec 约束进行代码分析或修改
- 对齐检查 — 编码完成后对比变更与 Module Spec 契约（详见 Post-Coding Chain）
- 记录发现 — 若发现新事实、矛盾或漂移，通过
specanchor-finding.sh 记录
- 评估沉淀 — 若发现 Spec 漂移，起草 Sediment Proposal 将热上下文回流为冷 Spec
步骤 1-2 在 session 开始时执行一次；步骤 3-7 在每个编码任务中按需循环。
Boot Requirement
Boot 是进入项目后的第一步，不可跳过。 激活后先运行：
SPECANCHOR_SKILL_DIR="$SA_SKILL_DIR" bash "$SA_SKILL_DIR/scripts/specanchor-boot.sh"
--format=summary：人类可读摘要--format=full：额外附带 Global Spec 正文--format=json：机器可读 JSON
Boot 完成后立即输出 Assembly Trace（见下节），然后再进入任何代码分析或修改。
Boot 是 session-start / preflight，同一 session 原则上只运行一次。 同 session 内后续的上下文需求不要重复 boot——改用 targeted specanchor-assemble.sh --files=...（见 Loading Strategy）。
Assembly Trace
Boot 完成后必须立即输出 Assembly Trace，格式如下：
Assembly Trace:
- Global: summary|full|none|skipped -> <files or reason>
- Module: full|summary|deferred|sources-only|none -> <files or reason>
Assembly Trace 是 boot 的可视确认——没有它，用户无法验证上下文已正确加载。完整规则见 references/assembly-trace.md。
Loading Strategy
full：始终加载 anchor.yaml + 全部 Global Spec；Module Spec 按需加载。parasitic：只加载 anchor.yaml 与外部 sources；不创建 full-only Spec。- 需要判断该读哪些模块时，优先看 boot 输出的
Available Commands: / Available Modules: 段；boot 不可用时 fallback 到 references/commands-quickref.md。
- 复杂编码任务应在 boot 之后运行
specanchor-assemble.sh --files=... --intent=...，先拿到 bounded read plan，再进入编辑。
Post-Coding Chain（编码后必检）
每次完成代码修改后，必须依次执行以下检查链：
-
对齐检查（Alignment Check） — 按下述决策树挑合适入口，不可跳过。verdict tools 与 read-plan tools 分工明确：verdict 走 check，read-plan 走 assemble。
| 手上有什么 | 入口 | 说明 |
|---|
| 一组改动文件路径 | specanchor-check.sh files <path...> | Post-coding verdict 超集：coverage + module freshness + optional task alignment，输出 overall: pass|warning|fail |
| 具体 task spec | specanchor-check.sh task <spec-file> 或 check files <path...> --task-spec=<path> | 前者判定 committed-diff vs plan；后者做 candidate-only 弱声明 |
| 只想知道是否被 Module Spec 覆盖 | specanchor-check.sh coverage <path...> | 纯覆盖查询（不含 freshness / task diff） |
| 需要 bounded context bundle | specanchor-assemble.sh --files=... --intent=... | read-plan 工具，不产 verdict；输出含 Uncovered Targets 段列出未覆盖路径 |
| assemble 超时 / 缺覆盖 | 显式报告 "partial context"，不要伪造 verdict | 缺 module spec 时创建 Task Spec 或跑 specanchor_infer，不要凭空发明业务规则 |
check files --format=json 输出 specanchor.check.v1 envelope（top-level schema_version / mode / status / inputs / warnings / verdict）。- 不要用 assemble 的读文件列表当作 verdict——它只回答"该读什么"，不回答"是否对齐"。
-
记录发现（Record Findings） — 若发现新事实、矛盾、风险或 Spec 漂移，通过以下命令记录：SPECANCHOR_SKILL_DIR="$SA_SKILL_DIR" bash "$SA_SKILL_DIR/scripts/specanchor-finding.sh" new --topic=<slug> --summary=<单行摘要>。无新发现则跳过。
-
评估沉淀（Evaluate Sediment） — 若发现揭示了 Spec 漂移或缺失约束，起草 Sediment Proposal（references/concepts/sediment-proposal.md）将热上下文回流为冷 Spec。无漂移则跳过。
Error Handling & Exit Conditions
脚本失败时：
- Boot 脚本失败（exit ≠ 0）：报告错误信息给用户，不重试超过 2 次。若连续 2 次失败，fallback 到手动读取
anchor.yaml + .specanchor/spec-index.md 获取最小上下文。
- Assemble 脚本失败：向用户说明失败原因，回退到 boot 输出的 Available Modules 信息，不做超过 3 次重试。
迭代上限：
- Post-Coding Chain 的 Alignment Check 若发现不一致，修复后最多再检查 2 轮（共 3 轮）。超过 3 轮仍不通过，停止并报告剩余问题给用户决策。
- Finding 记录和 Sediment Proposal 不做循环——每个发现记录一次即可。
降级策略：
- 若 skill 脚本路径不可达（$SA_SKILL_DIR 无效），跳过脚本依赖的步骤，直接读
.specanchor/ 下的文件作为上下文。
- 若项目无
anchor.yaml 且无 .specanchor/，skill 不激活——这是预期行为，不视为错误。
