skill-family-engineering-kit 0.5.0 → 0.7.0

package/docs/reference/api/engineering-kit/index.html

@@ -762,10 +762,10 @@
       <ul class="md-nav__list">
 
           <li class="md-nav__item">
-  <a href="#planAdoption--buildHandoffDraft--evaluateMigrationCompletion--validateException--assessLegacyExitList--findNestedRepositories" class="md-nav__link">
+  <a href="#planAdoption--buildProfileDraft--evaluateMigrationCompletion--validateException--assessLegacyExitList--findNestedRepositories" class="md-nav__link">
     <span class="md-ellipsis">
 
-        planAdoption / buildHandoffDraft / evaluateMigrationCompletion / validateException / assessLegacyExitList / findNestedRepositories
+        planAdoption / buildProfileDraft / evaluateMigrationCompletion / validateException / assessLegacyExitList / findNestedRepositories
 
     </span>
   </a>
@@ -798,6 +798,17 @@
     </span>
   </a>
 
+</li>
+
+          <li class="md-nav__item">
+  <a href="#buildProjectionClosure" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        buildProjectionClosure
+
+    </span>
+  </a>
+
 </li>
 
       </ul>
@@ -999,6 +1010,34 @@
       </ul>
     </nav>
 
+</li>
+
+        <li class="md-nav__item">
+  <a href="#Profile-SPI-公共投影" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        Profile SPI 公共投影
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="Profile SPI 公共投影">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#公共入口" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        公共入口
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
 </li>
 
         <li class="md-nav__item">
@@ -2016,10 +2055,10 @@
       <ul class="md-nav__list">
 
           <li class="md-nav__item">
-  <a href="#planAdoption--buildHandoffDraft--evaluateMigrationCompletion--validateException--assessLegacyExitList--findNestedRepositories" class="md-nav__link">
+  <a href="#planAdoption--buildProfileDraft--evaluateMigrationCompletion--validateException--assessLegacyExitList--findNestedRepositories" class="md-nav__link">
     <span class="md-ellipsis">
 
-        planAdoption / buildHandoffDraft / evaluateMigrationCompletion / validateException / assessLegacyExitList / findNestedRepositories
+        planAdoption / buildProfileDraft / evaluateMigrationCompletion / validateException / assessLegacyExitList / findNestedRepositories
 
     </span>
   </a>
@@ -2052,6 +2091,17 @@
     </span>
   </a>
 
+</li>
+
+          <li class="md-nav__item">
+  <a href="#buildProjectionClosure" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        buildProjectionClosure
+
+    </span>
+  </a>
+
 </li>
 
       </ul>
@@ -2253,6 +2303,34 @@
       </ul>
     </nav>
 
+</li>
+
+        <li class="md-nav__item">
+  <a href="#Profile-SPI-公共投影" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        Profile SPI 公共投影
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="Profile SPI 公共投影">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#公共入口" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        公共入口
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
 </li>
 
         <li class="md-nav__item">
@@ -2301,7 +2379,7 @@
 <ul>
 <li><a href="#scaffold-foundationkitscaffold">scaffold</a> → <code>scaffoldTarget</code></li>
 <li><a href="#adopt-plan-foundationkitadopt-plan">adopt-plan</a> → <code>planAdoption</code> / <code>evaluateMigrationCompletion</code></li>
-<li><a href="#projection-foundationkitprojection">projection</a> → <code>runProjection</code> / <code>loadProjectionManifest</code></li>
+<li><a href="#projection-foundationkitprojection">projection</a> → <code>buildProjectionClosure</code> / <code>runProjection</code> / <code>loadProjectionManifest</code></li>
 <li><a href="#check-foundationkitcheck">check</a> → <code>runChecks</code> / <code>runCoreCheck</code></li>
 <li><a href="#report-foundationkitreport">report</a> → <code>renderReportAction</code> / <code>checkReportAction</code></li>
 <li><a href="#git-probe-foundationkitgit-probe">git-probe</a> → <code>probeGitState</code> / <code>probeGitFacts</code></li>
@@ -2319,11 +2397,11 @@
 <li><code>describeSkeletonFiles(inputs)</code>（async）</li>
 <li><code>normalizeSkeletonInputs({ projectId, projectName, profileId, licensingProfile, licensingVariant, rootBasename })</code></li>
 <li>输入：目标根、骨架选项（<code>projectId</code> 等）。</li>
-<li>输出：精确集合的托管骨架文件（原子 + 路径收容）。</li>
+<li>输出：精确集合的托管骨架文件（原子 + 路径收容）。含两个目标侧手写种子（<code>handwritten</code> 类，adopt 永不覆写）：<code>SOURCE-OF-TRUTH.md</code>（唯一声明点、真源清单与生成谱系、运行与证据目录约定）与 <code>profile.json</code>（<code>foundation_profile</code> / <code>foundation_pin</code> 采用字段加只收紧方向的 overrides 示例）；<code>.gitignore</code> / <code>.projenrc.js</code> / file-registry 三处同步携带根级唯一忽略基线 <code>/site/</code>、<code>/.qoder/</code>、<code>/.artifacts/</code>、<code>/.runs/</code>、<code>/.evidence/</code>（嵌套同名目录不被忽略）。</li>
 <li>纯函数：<code>normalizeSkeletonInputs</code> 是；<code>scaffoldTarget</code> 落盘。</li>
 <li>副作用：在受收容目标创建文件（原子 + 收容）；目标非空则拒绝、不覆盖。</li>
 <li>稳定错误码与 <code>details.kind</code>：非法 kebab <code>projectId</code> / 非空目标抛 <code>KitError</code>（<code>KIT_ERROR_KINDS</code> 的 <code>invalid-params</code> / <code>rejected</code>）；非法参数 <code>+ INVALID_PARAMS</code>（<code>SFC2003</code>）。</li>
-<li>前置条件与信任锚：目标为可写空目录；Node &gt;= 22.22.2；骨架集合与 <code>scaffold-conformance</code> fixture 一致。</li>
+<li>前置条件与信任锚：目标为可写空目录；Node &gt;= 22.22.2；骨架集合与 <code>scaffold-conformance</code> fixture 一致（33 个计划文件）。</li>
 <li><code>since</code> / <code>stability</code>：<code>0.2.0</code> / <code>stable</code>。</li>
 <li>源文件：<code>packages/skill-family-engineering-kit/src/scaffold.mjs</code>、<code>skeleton.mjs</code>。</li>
 <li>正例/负例测试：<code>packages/skill-family-engineering-kit/test/scaffold.test.mjs</code>、<code>skeleton-contract.test.mjs</code>。</li>
@@ -2331,17 +2409,17 @@
 </ul>
 <hr />
 <h2 id="adopt-plan-foundationkitadopt-plan">adopt-plan (foundation.kit.adopt-plan)<a class="headerlink" href="#adopt-plan-foundationkitadopt-plan" title="Permanent link">&para;</a></h2>
-<h3 id="planAdoption--buildHandoffDraft--evaluateMigrationCompletion--validateException--assessLegacyExitList--findNestedRepositories">planAdoption / buildHandoffDraft / evaluateMigrationCompletion / validateException / assessLegacyExitList / findNestedRepositories<a class="headerlink" href="#planAdoption--buildHandoffDraft--evaluateMigrationCompletion--validateException--assessLegacyExitList--findNestedRepositories" title="Permanent link">&para;</a></h3>
+<h3 id="planAdoption--buildProfileDraft--evaluateMigrationCompletion--validateException--assessLegacyExitList--findNestedRepositories">planAdoption / buildProfileDraft / evaluateMigrationCompletion / validateException / assessLegacyExitList / findNestedRepositories<a class="headerlink" href="#planAdoption--buildProfileDraft--evaluateMigrationCompletion--validateException--assessLegacyExitList--findNestedRepositories" title="Permanent link">&para;</a></h3>
 <ul>
 <li>签名（节选）：</li>
 <li><code>planAdoption({ root, manifest, ... } = {})</code>（async）</li>
-<li><code>buildHandoffDraft({ ... })</code></li>
+<li><code>buildProfileDraft({ inputs, migrationManifest, writeSet, entries })</code></li>
 <li><code>evaluateMigrationCompletion({ ... })</code></li>
 <li><code>validateException(exception, index, nowMs)</code></li>
 <li><code>assessLegacyExitList(root, legacyItems)</code>（async）</li>
 <li><code>findNestedRepositories(entries)</code></li>
 <li>输入：目标根、迁移清单路径。</li>
-<li>输出：采用分类（<code>direct-adoption</code> / <code>compatibility-layer</code> / <code>keep-business</code> / <code>foundation-gap</code>）、完成判定、handoff 草稿（仅输出，不落盘）。</li>
+<li>输出：采用分类（<code>direct-adoption</code> / <code>compatibility-layer</code> / <code>keep-business</code> / <code>foundation-gap</code>）、完成判定、profile 草稿（kind=<code>skill-family.profile-draft</code>：预填 D-8 最小采用声明 + 空 overrides 示例，仅输出，不落盘；adoption-lock 形态已废弃）。</li>
 <li>纯函数：分类与评估函数为纯函数；<code>planAdoption</code> 含只读探测。</li>
 <li>副作用：<strong>严格只读</strong>——不写文件（临时文件也不写）、不 Git 写、不 rename、不触网；可能触发只读 Git 探测。</li>
 <li>稳定错误码与 <code>details.kind</code>：例外缺字段 / 未退出旧实现则完成判定 <code>false</code>；硬失败抛 <code>KitError</code>（<code>CONTRACTS_VERSION</code> 不一致等）。</li>
@@ -2369,6 +2447,21 @@
 <li>正例/负例测试：<code>packages/skill-family-engineering-kit/test/projection.test.mjs</code>。</li>
 <li>调用方仍拥有的业务语义：投影内容的业务含义（远端发布转 <code>release-skill</code>）。</li>
 </ul>
+<h3 id="buildProjectionClosure">buildProjectionClosure<a class="headerlink" href="#buildProjectionClosure" title="Permanent link">&para;</a></h3>
+<ul>
+<li>签名：<code>buildProjectionClosure(resources)</code></li>
+<li>输入：资源数组，成员为 <code>{path, sha256, mode}</code>（显式 <code>type: "file"</code> 被容忍）。</li>
+<li>输出：规范投影闭包 <code>{digestAlgorithm: "sha256", digest, resourceCount, resources}</code>（成员规范化为 <code>{path, type: "file", sha256, mode}</code>，按 path 确定性排序，<code>digest = sha256(JSON.stringify(resources))</code>），可原样作为 <code>compileProjectionPlan()</code> 的 <code>previousOwnedClosure</code> 或 <code>externalCandidateClosure</code>；空数组是合法空闭包。</li>
+<li>纯函数：是（无文件读写、无网络、无子进程；入参不被改写）。</li>
+<li>副作用：无。</li>
+<li>稳定错误码与 <code>details.kind</code>：非数组输入、重复路径、可移植路径碰撞、非法 path/type/sha256/mode 在既有 <code>projection plan input invalid</code> 错误域内失败关闭（<code>SFC2004</code>，<code>details.kind</code> 为 <code>invalid-manifest</code>）。</li>
+<li>边界：本函数构造的是投影/计划闭包，与 Harness <code>computeResourceClosure()</code> 的资源闭包（成员 <code>{path, role, exists, sha256}</code>、整体信封摘要）形状与用途不同，两者不可互换；与 <code>normalizePlanClosure()</code>、候选枚举闭包共享同一规范化与摘要事实源。</li>
+<li>前置条件与信任锚：无；结果直接满足 <code>compileProjectionPlan()</code> 的闭包合同，不新增第二个编译入口。</li>
+<li><code>since</code> / <code>stability</code>：<code>0.7.0</code> / <code>stable</code>。</li>
+<li>源文件：<code>packages/skill-family-engineering-kit/src/projection.mjs</code>。</li>
+<li>正例/负例测试：<code>packages/skill-family-engineering-kit/test/projection-closure-builder.test.mjs</code>。</li>
+<li>调用方仍拥有的业务语义：投影内容的业务含义与资源字节的来源证明。</li>
+</ul>
 <hr />
 <h2 id="check-foundationkitcheck">check (foundation.kit.check)<a class="headerlink" href="#check-foundationkitcheck" title="Permanent link">&para;</a></h2>
 <h3 id="runChecks--runCoreCheck--isContainedDeclaration">runChecks / runCoreCheck / isContainedDeclaration<a class="headerlink" href="#runChecks--runCoreCheck--isContainedDeclaration" title="Permanent link">&para;</a></h3>
@@ -2377,11 +2470,11 @@
 <li><code>runChecks({ root, allowGitSpawn = true, only, profilesRoot } = {})</code>（async）</li>
 <li><code>runCoreCheck({ root, allowGitSpawn = true, profilesRoot } = {})</code>（async）</li>
 <li><code>isContainedDeclaration(rel)</code></li>
-<li>输入：<code>--only</code> 取值 <code>contracts|drift|closure|version|docs|git|identity</code>。</li>
+<li>输入：<code>--only</code> 取值 <code>contracts|drift|closure|version|docs|git|identity|boundary|platform</code>。</li>
 <li>输出：发现清单；退出码 <code>findings=1</code>（有发现）、<code>mechanism=2</code>（某类检查无法完成）、<code>ok=0</code>。</li>
 <li>纯函数：否（读取目标文件与只读 Git 状态）；但<strong>只诊断、不修复、不写</strong>。</li>
 <li>副作用：无文件写入；只读 Git 探测（至多一次冻结 <code>status</code> 查询）。</li>
-<li>稳定错误码与 <code>details.kind</code>：<code>CHECK_CLASSES</code> 为七类闭集，不扩张；机制失败抛 <code>KitError</code>（<code>mechanism</code> 类）。</li>
+<li>稳定错误码与 <code>details.kind</code>：<code>CHECK_CLASSES</code> 为九类闭集，不扩张（审计整改 C2 依裁决 SG-13/14、SG-17、SFA-PLAT-002 增设 <code>boundary</code>、<code>platform</code> 两类，并为 <code>version</code> 类加装版本单源一致性事实；扩类经治理批准，此后仍不扩张）；机制失败抛 <code>KitError</code>（<code>mechanism</code> 类）。</li>
 <li>前置条件与信任锚：<code>GIT_READ_ONLY_ALLOWLIST</code> 限定可调用子命令。</li>
 <li><code>since</code> / <code>stability</code>：<code>0.2.0</code> / <code>stable</code>。</li>
 <li>源文件：<code>packages/skill-family-engineering-kit/src/check.mjs</code>、<code>core-check.mjs</code>。</li>
@@ -2509,6 +2602,18 @@
 </ul>
 <p>Kit 错误类型：<code>KitError extends ContractsError</code>（构造未登记码立即抛 <code>TypeError</code>）；<code>KIT_ERROR_KINDS</code> 为稳定 kind 枚举；<code>kitError</code> / <code>invalidParamsError</code> / <code>unknownCommandError</code> / <code>mutationModeError</code> / <code>refusalError</code> 为构造辅助。<code>REFUSED_MUTATION_FLAGS</code> 列出入口即拒的变更旗标（如 <code>--apply</code>）。</p>
 <hr />
+<h2 id="Profile-SPI-公共投影">Profile SPI 公共投影<a class="headerlink" href="#Profile-SPI-公共投影" title="Permanent link">&para;</a></h2>
+<p><code>skill-family-engineering-kit/profile-spi</code> 是 Profile SPI v2 的公共数据入口。它由 Profiles 源实现投影生成，包内同时携带三个 SPI JSON 资源与 Contracts 的 <code>profile-descriptor.schema.json</code>；投影脚本只替换两个公共包导入和一个本地 Schema URL，资源字节保持绑定。</p>
+<h3 id="公共入口">公共入口<a class="headerlink" href="#公共入口" title="Permanent link">&para;</a></h3>
+<ul>
+<li><code>loadSpiDefinition()</code>：读取 <code>extension-spi.json</code>，返回开放扩展点、核心所有权和 entrypoint 规则。</li>
+<li><code>loadExtendedDescriptorSchema()</code>：读取 <code>profile-descriptor.schema.json</code>，返回扩展 Profile descriptor Schema。</li>
+<li><code>loadRuleBaselineCatalog()</code>：读取 <code>rule-baseline-catalog.json</code>，返回 overrides-policy 的基线目录。</li>
+<li><code>verifyProfile({ profileRoot, descriptorRelPath = "profile.json" } = {})</code>（async）：只读校验 Profile descriptor、资源收容、核心反向依赖、采用 pin 与 overrides；返回 <code>SPE0000</code> 或 <code>SPE1001</code>–<code>SPE1007</code> 结果码，不执行 Profile entrypoint。</li>
+<li><code>verifyAdoptionDigests({ profileRoot, adoption })</code> 与 <code>assessOverridesPolicy(overrides)</code>：分别校验采用 pin 摘要和只收紧的 overrides。</li>
+</ul>
+<p>公共投影入口没有文件写入、Git、网络或进程副作用。<code>profileRoot</code> 必须是可读取目录，资源 entrypoint 必须留在该目录内且为 JSON 数据文件；符号链接和路径逃逸均失败关闭。Profile 的领域语义仍由调用方拥有。</p>
+<p><code>profiles/spi</code> 是唯一手写真源；<code>packages/skill-family-engineering-kit/profile-spi</code> 由 projen 机械生成，不得直接编辑投影文件。</p>
 <h2 id="Quickstart-Profile-v2-candidate">Quickstart Profile v2 candidate<a class="headerlink" href="#Quickstart-Profile-v2-candidate" title="Permanent link">&para;</a></h2>
 <p><code>skill-family-engineering-kit/candidate/quickstart-profile</code> 导出 <code>buildQuickstartProfileProjection</code> 与 <code>QUICKSTART_PROFILE_TARGET_PREFIX</code>。builder 接收显式消费者 Schema 路径与冻结来源身份，生成按 Schema <code>$id</code> 查询的 standalone validator、机械投影的 Contracts/Harness runtime、许可证和完整 provenance。</p>
 <p>Bundle 离线运行时不需要 Foundation 包、<code>node_modules</code> 或 Ajv。builder 只返回稳定 projection manifest，不写目标文件，也不增加第五个 Kit 顶层命令；调用方仍需把 manifest 交给 <code>runProjection</code> 完成授权写入。0.3.0 的 v2 与 0.2.1 的依赖闭包 Bundle 不兼容，必须精确锁定版本。</p>

package/docs/reference/api/harness/index.html

@@ -1079,6 +1079,28 @@
     </span>
   </a>
 
+</li>
+
+          <li class="md-nav__item">
+  <a href="#estimateTokens--isCjkCodePoint--估算器常量" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        estimateTokens / isCjkCodePoint / 估算器常量
+
+    </span>
+  </a>
+
+</li>
+
+          <li class="md-nav__item">
+  <a href="#CLIskill-family-token-estimate" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        CLI：skill-family-token-estimate
+
+    </span>
+  </a>
+
 </li>
 
       </ul>
@@ -2500,6 +2522,28 @@
     </span>
   </a>
 
+</li>
+
+          <li class="md-nav__item">
+  <a href="#estimateTokens--isCjkCodePoint--估算器常量" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        estimateTokens / isCjkCodePoint / 估算器常量
+
+    </span>
+  </a>
+
+</li>
+
+          <li class="md-nav__item">
+  <a href="#CLIskill-family-token-estimate" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        CLI：skill-family-token-estimate
+
+    </span>
+  </a>
+
 </li>
 
       </ul>
@@ -2576,7 +2620,7 @@
 
 <h1 id="skill-family-harness-node-公共-API-参考">skill-family-harness-node 公共 API 参考<a class="headerlink" href="#skill-family-harness-node-公共-API-参考" title="Permanent link">&para;</a></h1>
 <p>本页从真实导出（<code>src/index.mjs</code> 与各源模块）核对，不手写无法证明新鲜度的全集。每个公共入口按 hand-off §4.3 说明：签名、输入与输出、是否纯函数、文件/进程/Git/网络副作用、稳定错误码与 <code>details.kind</code>、前置条件与信任锚、<code>since</code> 与 <code>stability</code>、源文件与正例/负例测试、调用方仍拥有的业务语义。</p>
-<p>Harness 是薄运行时：消费 Contracts，只实现业务中立机制；不拥有业务语义、编排、Git、网络与第二语言。包级常量：<code>HARNESS_CAPABILITIES</code>（16 项能力，闭集）、<code>HARNESS_EXCLUSIONS</code>（明确排除 <code>business-semantics</code> / <code>workflow-orchestration</code> / <code>git-writes</code> / <code>model-calls</code> / <code>release-state</code> / <code>remote-network-access</code>）。</p>
+<p>Harness 是薄运行时：消费 Contracts，只实现业务中立机制；不拥有业务语义、编排、Git、网络与第二语言。包级常量：<code>HARNESS_CAPABILITIES</code>（19 项能力，闭集）、<code>HARNESS_EXCLUSIONS</code>（明确排除 <code>business-semantics</code> / <code>workflow-orchestration</code> / <code>git-writes</code> / <code>model-calls</code> / <code>release-state</code> / <code>remote-network-access</code>）。</p>
 <p>能力分组（与 <code>docs/agents/capability-catalog.json</code> 对应）：</p>
 <ul>
 <li><a href="#契约校验-foundationharnesscontract-validation">契约校验</a> → <code>validateContractDocument</code> / <code>getValidator</code></li>
@@ -2591,7 +2635,7 @@
 <li><a href="#基线物化-foundationharnessbaseline-materialization">基线物化</a> → <code>computeDirectoryDigest</code> / <code>materializeBaseline</code>（FND-ADR-009）</li>
 <li><a href="#只读-chokepoint-foundationharnessread-chokepoint">只读 chokepoint</a> → <code>createReadChokepoint</code>（FND-ADR-009）</li>
 <li><a href="#策略化表面扫描-foundationharnesssurface-scan">策略化表面扫描</a> → <code>scanSurface</code>（FND-ADR-009）</li>
-<li><a href="#token-上界估算-foundationharnesstoken-estimation">token 上界估算</a> → <code>estimateTokenUpperBound</code>（FND-ADR-009）</li>
+<li><a href="#token-上界估算-foundationharnesstoken-estimation">token 上界估算</a> → <code>estimateTokenUpperBound</code> / <code>estimateTokens</code>（FND-ADR-009）</li>
 <li><a href="#通用上限守卫-foundationharnessupper-bound-guard">通用上限守卫</a> → <code>openUsageGuard</code> / <code>appendUsageEvent</code> / <code>readUsage</code> / <code>closeUsageGuard</code>（FND-ADR-009）</li>
 <li><a href="#机制错误-foundationharnesserrors">机制错误</a> → <code>HarnessError</code> / <code>mechanismError</code> / <code>HARNESS_ERROR_KINDS</code></li>
 </ul>
@@ -2924,7 +2968,7 @@
 <p>注入式自测约定：扫描器无状态——注入模式并扫描后移除注入，再次扫描结果字节一致（自测见测试文件，不冒充独立复核）。</p>
 <hr />
 <h2 id="token-上界估算-foundationharnesstoken-estimation">token 上界估算 (foundation.harness.token-estimation)<a class="headerlink" href="#token-上界估算-foundationharnesstoken-estimation" title="Permanent link">&para;</a></h2>
-<p>FND-ADR-009。确定性领域估算原语：UTF-8 字节数纯函数，无模型、无网络、无 tokenizer 依赖、无持久状态导入；结果符合 <code>token-estimate-result</code> 契约（无时间戳，<code>guarantees</code> 为封闭枚举）。</p>
+<p>FND-ADR-009。确定性领域估算原语，两个互相独立的估算器：UTF-8 字节数上界（<code>estimateTokenUpperBound</code>）与按 CJK 码位/空白切分的词元数估算（<code>estimateTokens</code>，算法 <code>cjk-char-whitespace-split</code>）。两者均为无模型、无网络、无 tokenizer 依赖、无持久状态导入的纯函数；字节上界结果符合 <code>token-estimate-result</code> 契约（无时间戳，<code>guarantees</code> 为封闭枚举）。每条词元估算记录携带估算器 id 与版本（SFA-CONTEXT-028：消费方必须能回答结果出自哪个估算器），两个估算器的结果不得静默混用、不得互相替代。</p>
 <h3 id="estimateTokenUpperBound">estimateTokenUpperBound<a class="headerlink" href="#estimateTokenUpperBound" title="Permanent link">&para;</a></h3>
 <ul>
 <li>签名：<code>estimateTokenUpperBound(text)</code>（纯函数）</li>
@@ -2939,6 +2983,42 @@
 <li>正例/负例测试：<code>packages/skill-family-harness-node/test/token-estimate.test.mjs</code>。</li>
 <li>调用方仍拥有的业务语义：估算结果的解释与消费侧换算（模型调用与真实 token 计数不在 Foundation）。</li>
 </ul>
+<h3 id="estimateTokens--isCjkCodePoint--估算器常量">estimateTokens / isCjkCodePoint / 估算器常量<a class="headerlink" href="#estimateTokens--isCjkCodePoint--估算器常量" title="Permanent link">&para;</a></h3>
+<ul>
+<li>签名：</li>
+<li><code>estimateTokens(text)</code>（纯函数）</li>
+<li><code>isCjkCodePoint(codePoint)</code>（纯函数）</li>
+<li>常量：<code>TOKEN_ESTIMATOR_ID</code>（<code>skill-family.token-estimator</code>）、<code>TOKEN_ESTIMATOR_VERSION</code>（<code>1.0.0</code>）、<code>TOKEN_ESTIMATION_ALGORITHM</code>（<code>cjk-char-whitespace-split</code>）、<code>CJK_CODE_POINT_RANGES</code>（冻结码位区间表）</li>
+<li>输入：文本字符串；<code>isCjkCodePoint</code> 接收整数码位。</li>
+<li>输出：冻结的词元估算记录（<code>kind: skill-family.token-estimate-record</code>，<code>schemaVersion: 1</code>），携带 <code>estimator.id</code> / <code>estimator.version</code> / <code>algorithm</code>、输入统计（<code>codePoints</code> / <code>inputBytes</code>）、切分统计（<code>cjkCharacters</code> / <code>whitespaceSeparators</code> / <code>otherRuns</code>）与 <code>tokens</code>；<code>unit</code> 为 <code>tokens</code>，<code>precision</code> 为 <code>deterministic-heuristic</code>，<code>scope</code> 为 <code>content-text-only</code>。</li>
+<li>算法（<code>cjk-char-whitespace-split</code>，逐码位单遍扫描）：</li>
+<li>CJK 码位区间（冻结）：U+3400–U+4DBF（扩展 A）、U+4E00–U+9FFF（统一表意文字）、U+F900–U+FAFF（兼容表意文字）、U+20000–U+3134F（扩展 B–G）。</li>
+<li>每个 CJK 码位计 1 词元，并立即终结其前尚未闭合的 OTHER 段。</li>
+<li>连续的非 CJK、非空白码位构成 OTHER 段，被空白或 CJK 码位分隔时每段计 1 词元。</li>
+<li>空白（ECMAScript <code>\s</code> 类）只起分隔作用，不贡献词元。</li>
+<li>恒等式：<code>tokens === cjkCharacters + otherRuns</code>；中英混排、纯 CJK、纯 ASCII、空串（0 词元）全部适用。</li>
+<li>纯函数：是；零依赖、零 import（模块纯度由测试复检）。</li>
+<li>副作用：无。</li>
+<li>稳定错误码与 <code>details.kind</code>：非字符串输入抛 <code>TypeError</code>（无 SFC 码）。</li>
+<li>前置条件与信任锚：估算是对目标 tokenizer 的确定性启发式近似，不承诺与任何具体模型 tokenizer 相等；比较阈值时同一批次必须使用同一估算器（记录内的 <code>estimator</code> 与 <code>algorithm</code> 即裁决依据）。</li>
+<li><code>since</code> / <code>stability</code>：<code>0.6.0</code> / <code>stable</code>。</li>
+<li>源文件：<code>packages/skill-family-harness-node/src/token-estimate.mjs</code>。</li>
+<li>正例/负例测试：<code>packages/skill-family-harness-node/test/token-estimator.test.mjs</code>（中英混排、纯 CJK、纯 ASCII、空串与空白串、扩展 B 码位、区间边界、记录封闭键集、恒等式、确定性、CLI 子进程行为）。</li>
+<li>调用方仍拥有的业务语义：阈值策略与超限处置；把启发式词元数换算为目标模型的真实消耗。</li>
+</ul>
+<h3 id="CLIskill-family-token-estimate">CLI：skill-family-token-estimate<a class="headerlink" href="#CLIskill-family-token-estimate" title="Permanent link">&para;</a></h3>
+<ul>
+<li>入口：harness 包 bin <code>skill-family-token-estimate</code>（<code>src/token-estimate-cli.mjs</code>）；与工程 Kit 的四命令互不混用。</li>
+<li>用法：<code>skill-family-token-estimate (--text &lt;s&gt; | --file &lt;p&gt; | --stdin) [--estimator tokens|upper-bound|both]</code>；默认 <code>--estimator tokens</code>。<code>both</code> 输出 <code>{ tokens, upperBound }</code> 两个键，明示两个估算器并存而非混合。</li>
+<li>输出：stdout 打印 JSON 估算记录（<code>tokens</code> 为估算记录，<code>upper-bound</code> 为 <code>token-estimate-result</code>），换行结尾。</li>
+<li>副作用：只读取命令行参数、<code>--file</code> 指定文件或 stdin；只写 stdout。</li>
+<li>稳定退出码：<code>0</code> 成功；<code>2</code> 用法错误（输入源缺失或互斥、未知参数、<code>--file</code> 目标不是普通文件等，stderr 给出原因）；<code>--help</code> 打印用法后退出 0。</li>
+<li>前置条件与信任锚：<code>--file</code> 按调用方给定的路径原样读取，CLI 不做路径收容；需要收容时在库内用 <code>readFileContained</code>。</li>
+<li><code>since</code> / <code>stability</code>：<code>0.6.0</code> / <code>stable</code>。</li>
+<li>源文件：<code>packages/skill-family-harness-node/src/token-estimate-cli.mjs</code>。</li>
+<li>正例/负例测试：<code>packages/skill-family-harness-node/test/token-estimator.test.mjs</code>（子进程 CLI 用例：确定性、<code>--file</code>/<code>--stdin</code>/<code>both</code>、用法错误退出码 2、<code>--help</code>）。</li>
+<li>调用方仍拥有的业务语义：输入文本的采集与裁剪策略、输出记录的归档位置。</li>
+</ul>
 <hr />
 <h2 id="通用上限守卫-foundationharnessupper-bound-guard">通用上限守卫 (foundation.harness.upper-bound-guard)<a class="headerlink" href="#通用上限守卫-foundationharnessupper-bound-guard" title="Permanent link">&para;</a></h2>
 <p>FND-ADR-009。复用 state-store 事件账与 token-lock 显式占用实现通用上限守卫：越限事件失败关闭且不写入；上限值、单位类别与超限策略全部由消费者配置，模块不携带任何固定数额或定价词汇。</p>

package/docs/reference/failure-and-side-effect-matrix/index.html

@@ -2050,7 +2050,7 @@
 <td><code>SFC2004</code>（<code>target-not-empty</code>）</td>
 </tr>
 <tr>
-<td><code>planAdoption</code> / <code>buildHandoffDraft</code></td>
+<td><code>planAdoption</code> / <code>buildProfileDraft</code></td>
 <td>是</td>
 <td>否</td>
 <td>否</td>