SPEC 编写

帮助规格作者和审阅者得到可执行的最小完整方案。裁剪对象是实现手段与重复工作，不是用户要求、真实验收或安全边界。允许结论为“当前方案无需修改”。

生成过程中，在实现方案和任务拆分定型前完成上游能力正向匹配；生成结束后，结合唯一执行计划核对匹配结论是否进入具体任务。已有实现时先判断缺的是行为、证据还是执行环境，不能把缺证直接转成重新开发。

0. 必要前置完成后才编写 SPEC

编写顺序固定为：从用户原始需求与已确认裁决确定行为变化、保留保证、项目和交接；读取各项目当前生效的配置、模板、profile、目录说明和阶段约定，确认迭代是否已经落在文件和调用映射上；按本次影响判断必要制品；实际完成正文、关系与适用评审；之后才输出 SPEC 和执行输入。定义存在或声明已升级不算正文已经齐备。

前置未齐时，只输出需求、具体缺口、实际补齐安排和方案讨论。不给本轮规格命名，不交付 SPEC，也不把补齐写成后续 T0 或“待完善 SPEC”。方法返回 NEEDS_INPUT 时保留该真实缺口，不虚构 worker，不把未评审写成通过。与该缺口没有依赖的准备工作可以继续。不得静默缩小请求范围来产出局部 SPEC。

定义适用时直接进入正文检查。无定义或存在阻断缺口时，按授权衔接 artifact-chain-bootstrap 或项目已经在用的维护入口，并在返回后重读实际文件。其他流程已经生效的结果直接读取，不强制重跑。旧定义仍然适用就继续沿用。不以定义不足裁掉真实需求。迭代仍不足以表达本次必要内容时，报告具体缺口，不输出 SPEC。

0.0 默认测试交接

在必要前置制作过程中确定验证范围、接受与停止时，按references/default-testing.md实际调用默认plan并读取返回的业务计划；任何方向均不得仅提推荐。不要求尚不存在的未来执行结果，执行阶段条件具备后才实际衔接run。TEST负责测试方法，不代替专业制品作者和独立审阅。

0.1 四项判断分开写

对每个受影响项目分别给出四项结论，每项都写依据：

1. 范围依据
2. 正文充分性
3. 必要关系
4. 适用评审

每项写下实际已核实的结论和依据。必要材料、关系与评审都已完成时，已核实结论可以表示为已满足。缺失、未检查、依据不足、不适用 分别表示四种缺口，四词不是穷尽值域。不要把它们混成一个总评。

下列情况分别报告，不能互相抵消：

• 必要前置尚未创建
• 必要前置没有被引用
• 必要前置没有进入图
• 节点只指向一个缺失的附件
• 实际依赖的关系没有建立

文件存在、标题、ID、标记齐全、图校验成功或版本锁成功，都不能掩盖正文或关系缺口。carried_into、SPEC 引用和图影响只作定位线索，不作为范围上限。Schema 无法表达真实需求时保留需求并报告定义缺口，不把未入图自动当成业务缺失。

沿用历史正文或历史评审时，核对适用范围、版本和当前正文。变化部分必须有自己的适用评审，不全量重审未变化的历史。开发前测试规格与开发后真实执行结果分开记录，开发前不索要尚未发生的执行结果。

0.2 独立全文审阅与开发补漏

前置专业评审和完整 SPEC 审阅是两项不同职责，不能互相补签。前置完成后，由不同职责在同一轮集中审阅中先复核范围依据，再核对完整正文和必要附件。作者整理的来源表只是导航，不是审阅范围上限。审阅者必须主动查找作者遗漏的必要来源。

开发补漏或遗留补档仍先了解需求影响和有效定义：

• 事实明确，只缺说明或关系：按授权补齐并复审受影响制品、SPEC 和实现。
• 实现偏离已批准设计：报告冲突，交给相应职责，不在规格里隐性改要求。
• 意图不明：保留待确认。不从代码反推批准需求，不倒填历史。
• 没有真实方法返回时，不报告闭环通过。

0.3 来源索引、增量正文与项目模板

SPEC 由两部分组成：来源索引，加上本轮相对基线的增量正文。完整 PRD、场景和详细设计仍由原制品维护。索引写明制品身份、具体章节、本轮采用的内容和版本依据。版本依据使用项目现有 Git 引用、版本锁或本轮评审记录。引用未提交正文时写明工作树基线，并指向已经核验的评审快照。HEAD 不是未提交正文的版本。不能只凭摘要声称可以恢复全文。

增量正文依据已核实的产品需求与设计，描述规格所定义的产品变更：目标行为、保留要求、关键实现决定、实现涉及的源文件、派生物、外部对象及可观察验收。关键实现指向已评审设计的具体章节。执行计划独立引用，不把完整任务进度复制进 SPEC。不得只放链接，也不得复制整份制品变成第二份日常正文。

默认对照插件 templates/core/spec-entry.starter.md。该模板保留五个生命周期章节和全部合同标记：changes、scope、acceptance、acceptance-record、archive-record。项目已经有实际模板时，以项目模板为准。

1. 限定本次检查

按本次任务选择编写、改稿或只读审阅，并明确关注的风险与阶段。

读取适用的 AGENTS.md、用户原目标及当前 SPEC、执行计划中本次判断所需的完整内容。先从现行入口确认权威关系与读取范围，不默认把原规格、返工规格和全部复审材料一起加载。再按风险阅读直接相关的接口、调用方、测试或证据。缺材料时给出条件结论，不补造项目事实。

不默认检索全部会话、扫描所有项目、运行全量测试或安排多个审阅者。不为本技能建立计划树、评分表、证据登记表或执行器。短小改动只检查实际相关项。

2. 先保护结果，再裁剪手段

从原目标确认用户可观察的结果、真实使用场景、兼容要求、安全边界和完成条件。执行者生成的设计、自测结果与完成报告不能覆盖这些要求。

对拟修改内容逐项询问：

• 删除后，哪一项用户结果、合同或已观察故障会失去保证？没有具体答案时，优先移除或延后该手段。
• 现有实现或上游公共能力能否覆盖？按行为保证归为直接采用、薄层适配、领域实现或上游缺口，不按文件名或所在仓库归类。
• 当前复杂度来自真实必要条件，还是未来预留、对称性、保险检查或验证器自身的要求？

比较能够完成同一目标的完整方案。不能让轻方案省掉安全要求，再据此认定重方案更可靠；也不能用“优化”名义删除原验收。改变目标、合同、权限或权威归属的建议单列，等待所需裁决。

3. 规格阶段完成正向能力匹配

在方案和任务拆分定型前，从本次实际场景出发主动查找可复用能力。优先核对项目已有工具和已声明上游；发现新的共性处理需要时，再查询相关公共能力。匹配结果用于确定实现与验证方式。

在拆写集、估工期和委派之前，读取 上游能力正向匹配，按当前版本的公开能力逐项问“本次哪个场景可以使用”。对命中项读取公共合同与现有接线，再核对 SPEC 的拟建脚本是否重复。通用处理即使被命名为领域脚本，也必须拆开比较。

将结论直接写进权威 SPEC 的“底层能力采用与编排”部分。每个采用项必须明确场景、提供方与精确版本、能力 ID 或公共入口、调用位置和输入输出、项目保留职责、验证方式、产品安全要求和外部动作；任务表引用同一结论，不再维护副本。与方案有关但未采用的候选须给出具体理由；没有相关场景的检索提示无需写入正文。

生成或优化 SPEC 时，按能力匹配参考第 6 节核对本轮 SPEC 与相关制品的双向语义覆盖，并沿用该节的处置表。

缺少会改变接口、写集或验证方式的能力事实时，该切片仍是待决草稿，不能交给执行者“自行选择上游或自建”。已选择的入口允许执行时核对环境和填入由事实确定的参数；更换提供方、版本、机制、职责或测试编排时，先修订同一 SPEC 的受影响决定。

3.1 修改粒度、删除重命名与反例

读取 规格修改与审阅方法，并在语义准备、对照组织和交付核对中实际使用：

• 以完整需求及全部相关场景为修改单位；
• 分别检查删除与重命名；
• 按需求展示基线与目标差异；
• 把配置结构错误交给现有加载与 artifact-chain-setup 诊断；
• 关系配置的结构、取值与诊断按上述参考第 4 节核对；
• 识别遗漏场景、同名异义、空材料和勾选无证据。

需求登记、add/modify/delete 回写和 SPEC 条目创建仍由 artifact-chain-requirements 负责。本技能在材料缺口处引导进入已有制作与评审入口，不汇总审阅结果，不自造审阅控制器。profile 或 worker 未就绪时如实报告未评审，不伪造通过。

3.2 标记合同与独立正文审阅

生成或优化完整 SPEC 时，先确认目标项目实际采用的合同，再对完整新 SPEC 做两层检查。标记通过不等于业务完整；上游 PRD 审阅、已有 prd-feature/review 结论、前置专业评审，以及通用 review 的目录或就绪结果，都不能代替本轮独立的完整 SPEC 正文审阅。前置专业评审与完整 SPEC 审阅不能互相补签。独立审阅先复核范围依据，再核对完整正文和必要附件；作者来源表只是导航，不是审阅范围上限，审阅者必须主动查找遗漏的必要来源。

官方合同身份是 artifact.spec@1，声明源只在 Graph 包 contracts/spec/schema.json。authority 与 namespace 均为 artifact。本技能采用该合同，不在助手参考目录复制另一份同身份 schema，也不新增加载器、导出或注册表。

采用步骤：

1. 读取目标项目实际使用的 SPEC 模板。默认对照插件 templates/core/spec-entry.starter.md；项目另有模板时以项目实际文件为准。SPEC 写来源索引和本轮增量正文。HEAD 不是未提交正文的版本。执行计划独立引用。
2. 用现有 CLI artifact-graph contract explain --contract artifact.spec@1 --contracts-dir <contracts> --format json 读取真实 identity、revisionDigest 和 semanticMarkers。摘要以本次 explain / loadContract 结果为准，不在技能正文维护平行常量。
3. 有效机械采用必须看到非空的必需标记集合，覆盖三个业务槽：changes（行为变更及完整场景）、scope（修改范围与项目边界）、acceptance（可观察验收）。acceptance-record、archive-record 是可选标记，对应正式模板里原有的验收与归档正文；执行草稿不得把未完成项写成 passed 或伪造归档。
4. 对完整新 SPEC 调用现有 artifact-graph contract validate-markers，提供真实参数：--contract artifact.spec@1、--contracts-dir、--revision-digest（与本次 explain 一致）、--markdown（完整 SPEC 路径）、--format json。不得用 contract validate 或 normalize 冒充正文验证。jsonPointer 只描述同一语义槽，本命令不解引用，也不声称已验证指针映射。
5. 标记齐全后，交由不同职责方只读审阅完整正文、业务来源和必要附件。两层都通过，才可完成 SPEC 验收。 独立职责实际读取 <plugin-root>/skills/artifact-review/references/type-methods.md 的 spec 方法；采用 artifact-review spec 路由时，仍须通过原项目 profile 就绪检查并提交真实独立语义 Review Result。缺少 profile、输入或审阅结果时如实保留缺口，不以通用 worker 补签。

拒绝把下列情况写成机械通过：未知合同；合同未定义或 semanticMarkers 为空；只有可选标记、缺少任一必需标记；重复标记；未知标记。内核仍对无标记合同保持兼容（未定义时校验器返回 valid）；宿主必须阅读真实 explain 结果再判断，不能把兼容空集当成本轮有效采用。

采用前确认实际安装的 Graph 包提供 artifact.spec@1，并按正式包或工作树候选的真实来源记录身份。缺少合同或必需标记定义时，报告具体缺口。隔离消费从实际安装包定位合同。

项目可显式采用自身合同，但必须使用自身身份并有项目采用依据，不得冒用 artifact 官方身份。正式 starter 仍保留原五节生命周期规则。

4. 将规格组织为可承接的执行输入

多职责、跨会话或存在任务依赖时，读取 执行编排与分层读取，交付业务规格、独立启动单、唯一公共执行计划和各职责的任务文件。沿用项目现有文件；单职责、窄写集且无跨会话交接的小改动可以保持单文件。

SPEC 定义产品结果、合同、产品实现范围、底层能力采用及验收。公共计划安排产品实施任务的依赖、职责、读写集、交接、验证和进度。启动单明确产品执行目标、首个动作及完成条件，任务文件说明各职责如何交付其完整结果。

从承接者可见的输入顺读主会话启动、代表实现和独立审阅路径，继续展开必读引用。各职责完整取得当前任务所需的业务合同，不默认加载全部领域和历史。具体读取方法与交付核对按执行参考第 3、5 节完成。

评审、方法绑定或业务输入存在真实缺口时，写清受影响任务、缺少的材料及满足条件；任务写集使用实际文件路径。用户限定单文件或局部修改时，交付范围内的结果并说明尚未完成的结构部分。

5. 核对产品实现路径

集中检查事实与复用、依赖与编排、验证与证据、收尾与成本。只展开存在信号的部分。每项验收指出真实入口、输入、应观察的业务结果和最近的既有检查。退出 0、产物存在和模型自报不代替完整业务值验收。

实现和返工使用成组聚焦测试；稳定快照集中审阅、统一裁决和修复，批末运行权威完整门禁。不把完整测试改名为聚焦测试。不为前置检查新增包装器。

6. 按风险补查，不常驻展开

SPEC 涉及测试分组、并行、昂贵初始化或跨阶段复用时，读取宿主可发现的 test-performance-optimizer。没有慢测试证据时，优先沿用既有策略。Foundation 命中项的采用诊断使用可用的 foundation-adoption-review。专项技能不可用时说明限制，只给范围内建议。

遇到阶段循环、入口受限、反复交接、上下文成本、风险裁决或收尾状态混用时，读取 条件检查。

7. 文档生成后优化可读性

本技能生成或修改的各类中文文档，在内容成稿后、最终交付核对前，按插件内已发布公共参考执行拟稿与核收。执行本节前，必须从当前插件安装根完整读取：

• $PLUGIN_ROOT/skills/spec-author/references/shared-writing-workflow.md
• $PLUGIN_ROOT/skills/spec-author/references/expression-service-config.md

两份参考与 Docs 公开发布版本 skill-family-docs-v0.6.7（提交 7433554d2e2995729c2aafee52eb525ca827446d）字节一致。不要改写这两份参考；更新只能来自明确采用的新发布版本。运行时不依赖 Docs 工作树、Docs 已安装或个人技能目录。隔离插件只要带有本技能树，即可定位两份参考和表达脚本。

公共参考按原字节保留。本入口补充本领域边界，不改写参考正文：

• 只读审校可以定位事实、理解和表达问题，但不修改受检正文，也不自动把整份私有材料发给模型。
• 本轮新写的中文报告仍须按已有授权走本节优化，并经宿主核收后交付。
• 材料可以是公开材料，或已有明确外发授权的材料。不得把 Docs 站点的公开材料限制扩到 Artifact。
• 表达优化不能改变验收、依赖、职责、授权、停止条件或规则强度；技术合同、代码、命令、路径、版本、任务 ID 和机器字段保持原值。

脚本路径为 $PLUGIN_ROOT/skills/spec-author/scripts/expression-outbound.mjs。它与 Docs 公开发布版本 skill-family-docs-v0.6.6（提交 084b53a60bf871dd311e3eb62b398a9c48e3821b）字节一致；该脚本与 0.6.7 公开脚本字节相同，本轮保留 0.6.6 来源声明，不升级脚本版本。不要修改该副本。

配置沿用 SKILL_FAMILY_DOCS_ENDPOINT、SKILL_FAMILY_DOCS_MODEL、SKILL_FAMILY_DOCS_CREDENTIAL_ENV（值为存放凭据的环境变量名）。配置检查只通过 artifact-chain-setup → $PLUGIN_ROOT/scripts/setup-checks.mjs 进行。公共配置参考里的示例命令不是第二套检查入口，不自动从 LLM_* 补齐，配置存在不等于服务可用。缺配置、调用失败、候选拒收或材料未获授权时，语义审阅、图查询与机械检查可以继续，但必须报告“可读性优化未完成”。凭据不得进入材料、命令参数、候选或日志。公开产品不得硬编码模型名、服务地址或 API key。

按已读取的公共写作流程执行，不得另建阶段状态、runner 或第二套表达脚本：

1. 先读完全文材料，明确读者、阅读任务和必须保留的机器身份，并写入已纠正失效事实的完整材料。
2. 用同一脚本生成仓外大纲候选；宿主审核大纲后另存审核大纲。
3. 按完整语义单元顺序拟稿；每次只提供当前单元及必要事实。短文传入全部已接受前文，长文传入上一节全文和更早内容的覆盖摘要。第一节写明没有前文。
4. 只有宿主接受的稿可以作为后续小节前文。待审候选不能充当前文。
5. 各节接受后拼接全文，做事实覆盖核对和目标读者冷读。

候选必须写到仓外绝对路径。脚本没有接受权、没有重试、没有语义判断。交付时分别报告外发表达步骤状态与宿主语义核收状态：前者以脚本实际返回为准，后者覆盖大纲审核、各节核收、全文核对和冷读的实际范围。候选产生、失败或退出码 0 都不代表文档通过。

8. 一次收敛并交付

集中输出有依据的修改；每项说明观察、最小调整、保留的验收及预期减少的成本。无实测时不填节省百分比或精确耗时。

允许改稿时更新第 4 节要求的整组执行输入；只读时返回对应缺口，不改文件。交付前按执行编排参考第 5 节完成一次集中核对，并按能力匹配参考第 6 节与 规格修改与审阅方法 再做覆盖与反例核对。风格、链接、图关系或版本锁检查通过，以及图边或 ID 能够对应，都不能代替 SPEC 与相关制品正文的语义覆盖。

文档齐全但仍有覆盖未决时，报告“文档已整理，相关任务暂不可委派”，并写明等待补充评审还是等待用户裁决。只做规格优化就如实声明尚未实施。

完整 SPEC 的前置条件以第 0 节为准；标记合同和独立正文审阅按第 3.2 节完成。