skill-family-engineering-kit 0.1.3 → 0.2.0

package/README.md

@@ -15,7 +15,7 @@
 ## 使用
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.1.3
+npm install --save-dev skill-family-engineering-kit@0.2.0
 npm exec -- skill-family-kit --help
 npm exec -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
 npm exec -- skill-family-kit adopt-plan --root <repo>
@@ -23,10 +23,33 @@ npm exec -- skill-family-kit projection --root <repo>
 npm exec -- skill-family-kit check --root <repo>
 ```
 
+### 报告子动作
+
+```sh
+npm exec -- skill-family-kit projection report --root <repo> --model <report-model.json> --result <operation-result.json> --out <report.md> --binding <binding.json>
+npm exec -- skill-family-kit check report --root <repo> --report <report.md> --model <report-model.json> --result <operation-result.json> --binding <binding.json>
+```
+
+调用方必须先构造合法 report model；Kit 不从开放的业务 `outputs` 推导事实。所有事实文本按字面转义，失败结果的
+完整 errors 必须出现在 model 和中性报告中。
+
+### 宿主子动作
+
+```sh
+npm exec -- skill-family-kit adopt-plan host-describe --host <id> --hosts-root <dir>
+npm exec -- skill-family-kit adopt-plan host-probe --host <id> --hosts-root <dir>
+npm exec -- skill-family-kit scaffold host-build --root <workspace> --host <id> --path-category <id> --input <relpath> --out <relpath> --hosts-root <dir>
+npm exec -- skill-family-kit adopt-plan host-plan --root <workspace> --host <id> --path-category <id> --build-manifest <relpath> --probe-facts <relpath> --hosts-root <dir>
+```
+
+Profile 必须显式提供，Kit 不默认绑定具体宿主。probe 默认不启动进程；只有同时给出
+`--allow-host-spawn --host-executable <绝对路径>` 才执行冻结版本向量。`host-apply` 稳定拒绝，未实现安装、更新或卸载。
+Codex 的技能目标路径固定为 `.agents/skills`；其他受支持宿主只按已登记 Profile 提供；Qoder 为 `unsupported`，本版只参考其结构，不提供完整 driver，也不声称已在 Qoder 运行。adapter source 只接受已声明的文本闭包，不支持二进制投影；精确宿主支持矩阵见本版本 CHANGELOG 与已登记 Profile。
+
 零安装形式（不修改 package.json）：
 
 ```sh
-npm exec --package=skill-family-engineering-kit@0.1.3 -- skill-family-kit --help
+npm exec --package=skill-family-engineering-kit@0.2.0 -- skill-family-kit --help
 ```
 
 ## 边界机制
@@ -73,7 +96,7 @@ projection 只写同时满足两个条件的路径：manifest 列出，且目标
 ## 安装
 
 ```sh
-npm install skill-family-engineering-kit@0.1.3
+npm install skill-family-engineering-kit@0.2.0
 ```
 
 ## 故障诊断

package/docs/architecture/index.html

@@ -433,6 +433,17 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#下一阶段能力线架构-hand-off" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        下一阶段能力线（架构 hand-off）
+      
+    </span>
+  </a>
+  
 </li>
       
         <li class="md-nav__item">
@@ -722,6 +733,17 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#下一阶段能力线架构-hand-off" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        下一阶段能力线（架构 hand-off）
+      
+    </span>
+  </a>
+  
 </li>
       
         <li class="md-nav__item">
@@ -798,11 +820,35 @@
 
 <h1 id="架构边界">架构边界<a class="headerlink" href="#架构边界" title="Permanent link">&para;</a></h1>
 <h2 id="分层">分层<a class="headerlink" href="#分层" title="Permanent link">&para;</a></h2>
-<pre><code class="language-text">Contracts &lt;- Harness Node &lt;- Engineering Kit &lt;- Profile &lt;- Skill Family Project
-    ^
-    └---------------- independent Audit consumer
+<p>2026-08-09 架构 hand-off（FND-ADR-001～007，active，见 <code>artifacts/decisions/</code>）确立的分层：纵向依赖链四层，横向能力挂接，不新增纵层。</p>
+<pre><code class="language-text">技能族业务（各产品仓：release-skill、loop-agent、skill-eval 等）
+        │ 依赖
+        ▼
+Engineering Kit（scaffold / adopt-plan / projection / check）
+        │ 依赖
+        ▼
+Harness Node（Contracts 机制协议实现）
+        │ 依赖
+        ▼
+Contracts（结构、协议、错误码、协议名登记）
+        ▲
+        └---------------- independent Audit consumer
+
+横向（挂接面，不新增纵层）：
+- profiles/       宿主与项目形态差异声明，只实现稳定 SPI
+- 宿主            外部 AI 编码运行环境：拥有语义，Foundation 统一结构性差异
+- release-skill   发布状态与全部远端写入，不进入 Foundation
+- Artifact Graph  `artifacts/` 架构制品体系，门禁为 check:artifacts
 </code></pre>
-<p>箭头表示左侧是右侧的依赖。公共核心不得反向依赖具体 Profile 或具体技能族。</p>
+<p>箭头指向被依赖方。公共核心不得反向依赖具体 Profile 或具体技能族；新能力的依赖方向落位见 <code>artifacts/design/FND-DES-001.md</code>，逐资产归属见 FND-ADR-002。</p>
+<h2 id="下一阶段能力线架构-hand-off">下一阶段能力线（架构 hand-off）<a class="headerlink" href="#下一阶段能力线架构-hand-off" title="Permanent link">&para;</a></h2>
+<p>三条能力线均经 FND-ADR-001 能力纳入门（宿主差异轴/跨技能族共性轴两主轴判定、业务语义一票否决、七项进入门）裁决纳入，全部在上图既有分层内落位：</p>
+<ul>
+<li><strong>宿主接入线</strong>（FND-FR-001/FND-FR-002，FND-ADR-003）：Contracts 登记 descriptor/source/manifest/probe/plan/receipt；Harness 实现通用 source closure、原子 build/materialize 和 probe 分类；Kit 注入具体 Profile 与受信 driver。当前只支持 describe/build/probe/plan，<code>apply</code> 稳定拒绝，安装/卸载/更新均未实现。</li>
+<li><strong>持久状态底座线</strong>（FND-FR-003，FND-ADR-004）：append-only 事件、hash chain、快照与校验恢复；只提供状态底座，状态机、任务节点、重试、终态、记忆等业务语义不纳入 Foundation。</li>
+<li><strong>人类报告线</strong>（FND-FR-004，FND-ADR-005）：双层合同——机器结果是唯一真源，人类报告由机器结果确定性渲染（Markdown + digest 绑定 + 分级检查），不自由撰写。</li>
+</ul>
+<p>三包结构保持、不拆第四包（FND-ADR-007）；制品治理采用 artifact-graph CLI 与版本锁（FND-ADR-006，体系说明见 <code>artifacts/README.md</code>）。</p>
 <h2 id="唯一权威">唯一权威<a class="headerlink" href="#唯一权威" title="Permanent link">&para;</a></h2>
 <ul>
 <li>Contracts：结构、协议、错误码和协议名登记；</li>
@@ -810,16 +856,17 @@
 <li>Kit：四个工程命令及其只读/受限写入边界；</li>
 <li>Profile：项目形态差异；</li>
 <li>Audit：独立 fixture、预期值和裁决；</li>
-<li>Release：发布状态和全部远端写入。</li>
+<li>Release：发布状态和全部远端写入；</li>
+<li>Artifacts：<code>artifacts/</code> 架构制品体系的关系合同与版本锁由 artifact-graph 机械验证（<code>check:artifacts</code>），体系说明见 <code>artifacts/README.md</code>（FND-ADR-006）。</li>
 </ul>
 <h2 id="首版预算">首版预算<a class="headerlink" href="#首版预算" title="Permanent link">&para;</a></h2>
 <ul>
-<li>顶层 Contracts 对象：6 类（project-manifest、profile-descriptor、managed-file-lock、operation-request、operation-result、migration-manifest）；</li>
+<li>顶层 Contracts 对象：18 类（完整清单以 <code>packages/skill-family-contracts/src/registry.json</code> 为唯一真源）：project-manifest、profile-descriptor、managed-file-lock、operation-request、operation-result、migration-manifest、adapter-source、report-model、report-binding、host-descriptor、host-registry、host-capability-fact、host-probe-result、adapter-build-manifest、host-operation-plan、host-operation-receipt、state-event-envelope、state-snapshot-metadata；</li>
 <li>Kit 顶层命令：4 个（scaffold、adopt-plan、projection、check）；</li>
-<li>强制机械规则：当前 13 条，预算不超过 20 条，绝对上限 30 条；</li>
+<li>强制机械规则：当前 9 条，预算不超过 20 条，绝对上限 30 条；CR-001 对登记表内全部 Schema 做统一编译；</li>
 <li>叶子包：3 个（skill-family-contracts、skill-family-harness-node、skill-family-engineering-kit）；</li>
 <li>Schema 校验器：Ajv 8.20.0（精确版本 pin），支持 draft-07 与 2020-12 双方言；</li>
-<li>kernel 协议：skill-family.kernel.operation（stable），Contracts 版本 1.1.1；</li>
+<li>kernel 协议：skill-family.kernel.operation（stable），Contracts 版本 1.4.0；</li>
 <li>默认运行时语言：Node；第二语言实现首版为 0。</li>
 </ul>
 <p>任何新增组件必须说明删除它会导致的两个以上真实消费者重复实现，并通过独立 fixture 验证。</p>
@@ -870,7 +917,7 @@
 </ol>
 <p>两个检查脚本都可直接 <code>node scripts/docs/&lt;name&gt;.mjs</code> 运行：<code>fact-check.mjs</code> 是 Node 脚本，经仓内模块（<code>scripts/engine-floor-check.mjs</code>）消费根目录精确锁定的 <code>semver@7.8.5</code>，运行前必须先完成 <code>pnpm install --frozen-lockfile</code>；<code>link-check.mjs</code> 为纯 Node 实现（无第三方依赖）。职责说明见 <code>scripts/docs/README.md</code>。</p>
 <h2 id="稳定产品门禁">稳定产品门禁<a class="headerlink" href="#稳定产品门禁" title="Permanent link">&para;</a></h2>
-<p>根 <code>pnpm check</code> 只编排 10 个稳定产品 gate ID（<code>check:structure</code>～<code>check:integration</code>，逐 ID 见 当前产品状态），不再锁死原始命令清单；每个稳定 ID 在自己的 package script 内组合少量产品检查。门禁事实由 <code>node scripts/docs/fact-check.mjs</code> 从根 <code>package.json</code> 的 <code>scripts.check</code> 机械推导并逐字核对（setup 投影区块与 <code>scripts.check</code> 逐字一致）。文档与 setup 只调用或列出 10 个稳定 ID 或根 <code>pnpm check</code>，不复制底层命令列表。</p>
+<p>根 <code>pnpm check</code> 只编排 11 个稳定产品 gate ID（<code>check:structure</code>～<code>check:artifacts</code>，逐 ID 见 当前产品状态），不再锁死原始命令清单；每个稳定 ID 在自己的 package script 内组合少量产品检查。门禁事实由 <code>node scripts/docs/fact-check.mjs</code> 从根 <code>package.json</code> 的 <code>scripts.check</code> 机械推导并逐字核对（setup 投影区块与 <code>scripts.check</code> 逐字一致）。文档与 setup 只调用或列出 11 个稳定 ID 或根 <code>pnpm check</code>，不复制底层命令列表。</p>
 <p>仓内检查的诚实边界：结构检查只证明“字节/结构一致性（仓内可证）”；一次性迁移完整性、普通正文语义与最终接受/拒绝结论属于外部审阅职责，不在目标仓内维护第二份门禁 registry、baseline 或命令比较器。</p>
 
 

package/docs/integration/audit/index.html

@@ -770,7 +770,8 @@
   isolation-and-lockfile.md     隔离安装与包锁验证设计
   independence.md               独立性声明与机械证明
   schemas/audit-evidence.schema.json   证据文档的 JSON Schema（审计自有）
-  baseline/contracts-1.1.1.pin.json    Contracts 1.1.1 现行基线 pin（摘要+事实）
+  baseline/contracts-1.4.0.pin.json    Contracts 1.4.0 现行基线 pin（摘要+事实）
+  baseline/contracts-1.1.1.pin.json    Contracts 1.1.1 只读兼容存档 pin
   baseline/contracts-1.1.0.pin.json    Contracts 1.1.0 只读兼容存档 pin
   baseline/contracts-1.0.0.pin.json    Contracts 1.0.0 只读兼容存档 pin
   baseline/audit-codes.json            AUD 码登记表（append-only）

package/docs/integration/audit/version-compatibility/index.html

@@ -743,7 +743,7 @@
 <tbody>
 <tr>
 <td><code>contractsVersion</code></td>
-<td>Contracts 冻结版本（当前 <code>1.1.1</code>）</td>
+<td>Contracts 冻结版本（当前 <code>1.4.0</code>）</td>
 <td>机器契约内容的版本</td>
 </tr>
 <tr>
@@ -758,7 +758,7 @@
 </tr>
 </tbody>
 </table>
-<p>三者都由 <code>describeAuditSurface()</code> 一次性给出，审计侧把它们与基线 pin（当前为 <code>baseline/contracts-1.1.1.pin.json</code>）比对。</p>
+<p>三者都由 <code>describeAuditSurface()</code> 一次性给出，审计侧把它们与基线 pin（当前为 <code>baseline/contracts-1.4.0.pin.json</code>）比对。</p>
 <h2 id="兼容规则">兼容规则<a class="headerlink" href="#兼容规则" title="Permanent link">&para;</a></h2>
 <p>一个被消费的 Contracts 包与某个基线 pin <strong>兼容</strong>，当且仅当同时满足：</p>
 <ol>
@@ -811,6 +811,9 @@
 <li>pin 由产品侧在冻结时刻构造（provenance <code>product-compatibility-fixture</code>）：摘要来自对已冻结产物的 <code>digestAuditSurface()</code> 机械计算，事实清单直接对照合同文档推导，不取自生成器或 oracle；本仓库不存在独立的第二审阅会话，pin 不作任何独立角色声称；</li>
 <li><strong>诚实性修正（2026-08-05）</strong>：旧 pin（1.0.0、1.1.0）曾携带 <code>independent-r2</code> provenance 与独立重签叙事，该声称与本仓事实不符，已就地修正 provenance 与 note；修正只触及 provenance/note 两处诚实性字段，不改变任何 digest 或 facts 字段，旧 pin 继续作为只读兼容存档；</li>
 <li><strong>Contracts 1.1.1（2026-08-05）</strong>：仅描述补丁（migration-manifest schema 三处 description 改写为稳定产品语义；无任何校验关键字、公开 API、错误码、规则或引擎参数变化）。按本生命周期新增 <code>contracts-1.1.1.pin.json</code> 为现行基线，<code>contracts-1.1.0.pin.json</code> 转为只读兼容存档。1.1.1 pin 相对 1.1.0 pin 的准确事实：<strong>校验语义和事实清单不变</strong>（<code>facts</code> 逐项一致）；四个 Contracts 文档（registry、error-codes、rules、kernel-protocol）因内嵌 <code>contractsVersion</code> 从 <code>1.1.0</code> 更新到 <code>1.1.1</code> 而改变摘要；migration-manifest Schema 因上述三处 description 更新而改变摘要；其余五个 Schema（project-manifest、profile-descriptor、managed-file-lock、operation-request、operation-result）摘要不变。<code>proof-independence.mjs</code> 的 P5 强制这套如实声明的 provenance 词汇（pin：<code>product-compatibility-fixture</code>；变异夹具：<code>product-fixture</code>）；</li>
+<li><strong>Contracts 1.2.0（2026-08-09）</strong>：报告能力线增量，不是描述补丁：新增 <code>report-model</code>、<code>report-binding</code> 两个顶层契约和 SFC3001～SFC3003 报告错误码，改变了公开机器合同与审计事实。</li>
+<li><strong>Contracts 1.3.0（2026-08-09）</strong>：宿主接入能力线增量，不是描述补丁：新增 <code>host-descriptor</code>、<code>host-capability-fact</code>、<code>adapter-build-manifest</code>、<code>host-operation-plan</code>、<code>host-operation-receipt</code> 五个顶层契约，改变了公开机器合同与审计事实。</li>
+<li><strong>Contracts 1.4.0（2026-08-09）</strong>：持久状态能力线增量，不是描述补丁：新增 <code>state-event-envelope</code>、<code>state-snapshot-metadata</code> 两个顶层契约，改变了公开机器合同与审计事实。<code>contracts-1.4.0.pin.json</code> 是当前现行基线；1.1.x 及更早 pin 保留为只读兼容存档。该 pin 的摘要与事实均从当前 <code>describeAuditSurface()/digestAuditSurface()</code> 机械投影，provenance 仍为 <code>product-compatibility-fixture</code>。</li>
 <li>审计运行时先做包锁验证（见 isolation-and-lockfile.md），再做变异重放；pin 不匹配时，变异重放结果不得被采信。</li>
 </ul>
 

package/docs/public/status/index.html

@@ -766,30 +766,30 @@
 <tbody>
 <tr>
 <td><code>skill-family-contracts</code></td>
-<td>0.1.3</td>
-<td>ifoohoo/skill-family-contracts（github.com）</td>
+<td>0.2.0</td>
+<td><a href="https://github.com/ifoohoo/skill-family-contracts">ifoohoo/skill-family-contracts</a></td>
 </tr>
 <tr>
 <td><code>skill-family-harness-node</code></td>
-<td>0.1.3</td>
-<td>ifoohoo/skill-family-harness-node（github.com）</td>
+<td>0.2.0</td>
+<td><a href="https://github.com/ifoohoo/skill-family-harness-node">ifoohoo/skill-family-harness-node</a></td>
 </tr>
 <tr>
 <td><code>skill-family-engineering-kit</code></td>
-<td>0.1.3</td>
-<td>ifoohoo/skill-family-engineering-kit（github.com）</td>
+<td>0.2.0</td>
+<td><a href="https://github.com/ifoohoo/skill-family-engineering-kit">ifoohoo/skill-family-engineering-kit</a></td>
 </tr>
 </tbody>
 </table>
 <h2 id="文档">文档<a class="headerlink" href="#文档" title="Permanent link">&para;</a></h2>
 <ul>
-<li>公开文档站：ifoohoo.github.io/skill-family-engineering-kit/</li>
+<li><a href="https://ifoohoo.github.io/skill-family-engineering-kit/">公开文档站</a></li>
 </ul>
 <h2 id="验证入口">验证入口<a class="headerlink" href="#验证入口" title="Permanent link">&para;</a></h2>
 <ul>
 <li>本页：<code>node scripts/render-public-status.mjs --check</code>（零写入重算，与已提交页面逐字节一致）</li>
 <li>静态站与基线：<code>node scripts/render-public-site.mjs --check</code>（冻结 MkDocs 环境重算，与已提交基线逐项一致）</li>
-<li>工作区根门禁：<code>pnpm check</code>（10 个稳定产品门禁按固定顺序串联）</li>
+<li>工作区根门禁：<code>pnpm check</code>（11 个稳定产品门禁按固定顺序串联）</li>
 <li>registry、Pages 与 Release 的实时远端状态：由发布后验证报告证明，不在本页记录</li>
 </ul>
 <h2 id="说明">说明<a class="headerlink" href="#说明" title="Permanent link">&para;</a></h2>