skill-family-engineering-kit 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.19.0 locale=en baseline=sha256:d3b79ce1564df3e0dc0f0abc1af616817550044de73f9b05b57a5dd65fd47dae -->
+## [0.19.0] - 2026-09-07
+
+Engineering Kit 0.19.0 projects the new batch transport into the official offline Bundle and registers the mechanism-batch capability in the built-in catalog.
+
+### Added
+
+- The official Bundle projection now carries runMechanismCliBatch, the --batch CLI mode, the two mechanism-batch Schemas, and the frozen batch capacity policy with unchanged source identity, digest, and integrity handling.
+- The capability catalog adds foundation.harness.mechanism-batch with since 0.19.0 and stability candidate, together with intent, failure semantics, and direct test references.
+
+### Changed
+
+- Adoption guidance documents batch selection rules: same-process calls keep the existing object entry; independent cross-process canonical-json requests within capacity are batch candidates; dependent or oversized requests keep the original path.
+
+### Upgrade Notes
+
+Pin all three Foundation packages to exactly 0.19.0 and rebuild official Bundles after upgrading per the existing package identity and provenance rules. The catalog entry is candidate: a catalog match is not a stable adoption declaration.
+<!-- release-skill:changelog:end version=0.19.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.18.0 locale=en baseline=sha256:9c6fe9859fb75316937790054ae7d45bfc21d38ce97d8e650d7da18757a462c5 -->
 ## [0.18.0] - 2026-09-05
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,25 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.19.0 locale=zh-CN baseline=sha256:f000b13d13ce11660aaa4c5a1b450af39f99cb62a5177467783d863e7f411296 -->
+## [0.19.0] - 2026-09-07
+
+Engineering Kit 0.19.0 把新批量传输投影进官方离线 Bundle，并在内置能力目录登记 mechanism-batch 能力。
+
+### 新增
+
+- 官方 Bundle 投影携带 runMechanismCliBatch、--batch CLI 模式、两个机制批量 Schema 与冻结的批量容量政策，来源身份、摘要与完整性处理不变。
+- 能力目录新增 foundation.harness.mechanism-batch：since 0.19.0、stability candidate，并登记意图、失败语义与直接测试引用。
+
+### 变更
+
+- 采用指导补充批量选择规则：同进程调用保留既有对象入口；跨进程、相互独立且容量允许的 canonical-json 请求可作为批量候选；有依赖或超限请求保留原路径。
+
+### 升级说明
+
+三个 Foundation 包须一起精确锁定到 0.19.0，升级后按既有包身份与 provenance 规则重建官方 Bundle。该目录条目为候选能力：目录命中不构成稳定采用声明。
+<!-- release-skill:changelog:end version=0.19.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.18.0 locale=zh-CN baseline=sha256:c8c2891b64fc31e1fb3754715da04d6ec0727b31e36e011d38735e45795cdd53 -->
 ## [0.18.0] - 2026-09-05
 

package/README.md

@@ -4,26 +4,27 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.18.0 -->
+<!-- release-skill:release-version: 0.19.0 -->
 
 An engineering toolkit used in development and CI. There are **exactly four** top-level commands, and no fifth:
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.18.0** (2026-09-05)
+**0.19.0** (2026-09-07)
 
-Engineering Kit 0.18.0 projects the stable Harness replaceFixedSetAtomic export into the existing offline Quickstart Bundle.
+Engineering Kit 0.19.0 projects the new batch transport into the official offline Bundle and registers the mechanism-batch capability in the built-in catalog.
 
 **Added**
 
-- The existing candidate Bundle now carries the stable fixed-set replacement source, loader, native closure, and replaceFixedSetAtomic export without adding a parallel implementation or a new Kit command.
+- The official Bundle projection now carries runMechanismCliBatch, the --batch CLI mode, the two mechanism-batch Schemas, and the frozen batch capacity policy with unchanged source identity, digest, and integrity handling.
+- The capability catalog adds foundation.harness.mechanism-batch with since 0.19.0 and stability candidate, together with intent, failure semantics, and direct test references.
 
 **Changed**
 
-- Moves the package version to 0.18.0 together with Contracts and Harness while preserving runProjection as the Bundle write and authorization boundary.
+- Adoption guidance documents batch selection rules: same-process calls keep the existing object entry; independent cross-process canonical-json requests within capacity are batch candidates; dependent or oversized requests keep the original path.
 
 **Upgrade Notes**
 
-Pin all three Foundation packages to exactly 0.18.0 and rebuild managed Bundles from those exact installed package bytes. Bundle consumers receive the same non-idempotent replacement semantics and must not retry post-commit or indeterminate outcomes blindly.
+Pin all three Foundation packages to exactly 0.19.0 and rebuild official Bundles after upgrading per the existing package identity and provenance rules. The catalog entry is candidate: a catalog match is not a stable adoption declaration.
 <!-- release-skill:managed:end id=latest-release -->
 
 ### Foundation 0.15.0 candidate qualification entries
@@ -67,15 +68,15 @@ mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
 After publication, use the registry coordinate:
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.18.0
-npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit --help
-npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
-npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit adopt-plan --root <repo> --list-capabilities --all --scope all --locale en --uses ./uses.json
-npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit projection --root <repo>
-npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit check --root <repo>
+npm install --save-dev skill-family-engineering-kit@0.19.0
+npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit --help
+npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
+npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit adopt-plan --root <repo> --list-capabilities --all --scope all --locale en --uses ./uses.json
+npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit projection --root <repo>
+npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit check --root <repo>
 ```
 
-The four commands above cover skeleton generation, read-only inventory, managed projection, and diagnostics respectively; a zero-install form is available via `npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit --help`.
+The four commands above cover skeleton generation, read-only inventory, managed projection, and diagnostics respectively; a zero-install form is available via `npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit --help`.
 
 ### Three adoption journeys
 

package/README.zh-CN.md

@@ -5,26 +5,27 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.18.0 -->
+<!-- release-skill:release-version: 0.19.0 -->
 
 开发与 CI 阶段使用的工程工具包。**恰好四个**顶层命令，没有第五个：
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.18.0** (2026-09-05)
+**0.19.0** (2026-09-07)
 
-Engineering Kit 0.18.0 将 Harness 稳定的 replaceFixedSetAtomic 导出投影到既有离线 Quickstart Bundle。
+Engineering Kit 0.19.0 把新批量传输投影进官方离线 Bundle，并在内置能力目录登记 mechanism-batch 能力。
 
 **新增**
 
-- 既有 candidate Bundle 携带稳定的固定集合替换源码、加载器、原生闭包与 replaceFixedSetAtomic 导出；不新增平行实现，也不增加 Kit 命令。
+- 官方 Bundle 投影携带 runMechanismCliBatch、--batch CLI 模式、两个机制批量 Schema 与冻结的批量容量政策，来源身份、摘要与完整性处理不变。
+- 能力目录新增 foundation.harness.mechanism-batch：since 0.19.0、stability candidate，并登记意图、失败语义与直接测试引用。
 
 **变更**
 
-- 包版本与 Contracts、Harness 一同升至 0.18.0，runProjection 继续作为 Bundle 的写入与授权边界。
+- 采用指导补充批量选择规则：同进程调用保留既有对象入口；跨进程、相互独立且容量允许的 canonical-json 请求可作为批量候选；有依赖或超限请求保留原路径。
 
 **升级说明**
 
-三个 Foundation 包须一起精确锁定到 0.18.0，并从这些已安装包的精确字节重建受管 Bundle。Bundle 消费者获得相同的非幂等替换语义，不得盲目重试提交后或不确定结果。
+三个 Foundation 包须一起精确锁定到 0.19.0，升级后按既有包身份与 provenance 规则重建官方 Bundle。该目录条目为候选能力：目录命中不构成稳定采用声明。
 <!-- release-skill:managed:end id=latest-release -->
 
 ### Foundation 0.15.0 candidate 资格入口
@@ -68,15 +69,15 @@ mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
 发布后再使用 registry 坐标：
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.18.0
-npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit --help
-npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
-npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit adopt-plan --root <repo> --list-capabilities --all --scope all --locale zh-CN --uses ./uses.json
-npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit projection --root <repo>
-npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit check --root <repo>
+npm install --save-dev skill-family-engineering-kit@0.19.0
+npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit --help
+npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
+npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit adopt-plan --root <repo> --list-capabilities --all --scope all --locale zh-CN --uses ./uses.json
+npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit projection --root <repo>
+npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit check --root <repo>
 ```
 
-以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.18.0 -- skill-family-kit --help`。
+以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.19.0 -- skill-family-kit --help`。
 
 ### 三条采用旅程
 

package/candidate/profile-bundle.mjs

@@ -76,6 +76,16 @@ const ADDITIONAL_FOUNDATION_SCHEMA_FILES = Object.freeze([
   ["fixed-set-publication-receipt.schema.json", "src/schemas/fixed-set-publication-receipt.schema.json", "schemas/foundation/fixed-set-publication-receipt.schema.json"],
   ["schema-validation-batch-request.schema.json", "candidate/foundation-mechanisms/schema-validation-batch-request.schema.json", "schemas/foundation/schema-validation-batch-request.schema.json"],
   ["schema-validation-batch-result.schema.json", "candidate/foundation-mechanisms/schema-validation-batch-result.schema.json", "schemas/foundation/schema-validation-batch-result.schema.json"],
+  ["mechanism-batch-request.schema.json", "candidate/foundation-mechanisms/mechanism-batch-request.schema.json", "schemas/foundation/mechanism-batch-request.schema.json"],
+  ["mechanism-batch-result.schema.json", "candidate/foundation-mechanisms/mechanism-batch-result.schema.json", "schemas/foundation/mechanism-batch-result.schema.json"],
+]);
+
+// Non-Schema Foundation assets projected verbatim. They are deliberately kept
+// out of ADDITIONAL_FOUNDATION_SCHEMA_FILES: the schema graph claims a
+// document.$id for every schema row, while the capacity policy is a plain
+// JSON authority with no Schema identity.
+const ADDITIONAL_FOUNDATION_ASSET_FILES = Object.freeze([
+  ["mechanism-batch-policy.json", "candidate/foundation-mechanisms/mechanism-batch-policy.json", "schemas/foundation/mechanism-batch-policy.json"],
 ]);
 
 const HARNESS_IMPORT_MAP = new Map([
@@ -96,6 +106,7 @@ const HARNESS_STRICT_READ_IMPORT_MAP = new Map([
 
 const HARNESS_CLI_IMPORT_MAP = new Map([
   ["./quickstart-profile.mjs", "./runner.mjs"],
+  ["skill-family-contracts/quickstart-profile", "./runtime/contracts-candidate/index.mjs"],
 ]);
 
 const HARNESS_ATOMIC_IMPORT_MAP = new Map([
@@ -980,13 +991,22 @@ function projectContractsCandidateIndex(sourceText) {
       `schema load path ${fileName}`,
     );
   }
-  for (const [fileName] of ADDITIONAL_FOUNDATION_SCHEMA_FILES.filter(([name]) => name.startsWith("schema-validation-batch-"))) {
+  for (const [fileName] of ADDITIONAL_FOUNDATION_SCHEMA_FILES.filter(
+    ([name]) => name.startsWith("schema-validation-batch-") || name.startsWith("mechanism-batch-"),
+  )) {
     applyOnce(
       `load(new URL("../foundation-mechanisms/${fileName}", import.meta.url))`,
       `load(new URL("../../schemas/foundation/${fileName}", import.meta.url))`,
       `schema load path ${fileName}`,
     );
   }
+  for (const [fileName] of ADDITIONAL_FOUNDATION_ASSET_FILES) {
+    applyOnce(
+      `load(new URL("../foundation-mechanisms/${fileName}", import.meta.url))`,
+      `load(new URL("../../schemas/foundation/${fileName}", import.meta.url))`,
+      `asset load path ${fileName}`,
+    );
+  }
 
   const getCollectionMarker = "function getCollection(";
   const getCollectionHits = projected.split(getCollectionMarker).length - 1;
@@ -1238,6 +1258,10 @@ export async function buildQuickstartProfileProjection({
   for (const [fileName, sourcePath] of ADDITIONAL_FOUNDATION_SCHEMA_FILES) {
     additionalSchemaTexts[fileName] = await readSourceText(contractsRoot, sourcePath);
   }
+  const additionalAssetTexts = {};
+  for (const [fileName, sourcePath] of ADDITIONAL_FOUNDATION_ASSET_FILES) {
+    additionalAssetTexts[fileName] = await readSourceText(contractsRoot, sourcePath);
+  }
   sources.harnessIndex = await readSourceText(harnessRoot, "src/index.mjs");
   sources.harnessCandidate = await readSourceText(harnessRoot, "candidate/quickstart-profile.mjs");
   sources.harnessMechanismsCli = await readSourceText(harnessRoot, "candidate/mechanisms-cli.mjs");
@@ -1453,6 +1477,9 @@ export async function buildQuickstartProfileProjection({
   for (const [fileName, , bundlePath] of ADDITIONAL_FOUNDATION_SCHEMA_FILES) {
     setText(bundlePath, additionalSchemaTexts[fileName]);
   }
+  for (const [fileName, , bundlePath] of ADDITIONAL_FOUNDATION_ASSET_FILES) {
+    setText(bundlePath, additionalAssetTexts[fileName]);
+  }
   setText("schemas/foundation/operation-request.schema.json", sources.operationRequest);
   setText("schemas/foundation/operation-result.schema.json", sources.operationResult);
   setText("schemas/foundation/migration-manifest.schema.json", sources.migrationManifestSchema);
@@ -1591,6 +1618,11 @@ export async function buildQuickstartProfileProjection({
       additionalSchemaTexts[fileName],
       "projected",
     ]),
+    ...ADDITIONAL_FOUNDATION_ASSET_FILES.map(([fileName, sourcePath]) => [
+      `packages/skill-family-contracts/${sourcePath}`,
+      additionalAssetTexts[fileName],
+      "projected",
+    ]),
     ["packages/skill-family-contracts/candidate/quickstart-profile/index.mjs", sources.candidateIndex, "extraction-input"],
     ["packages/skill-family-harness-node/package.json", harnessPackageJsonText, "identity"],
     ["packages/skill-family-harness-node/src/index.mjs", sources.harnessIndex, "imported-surface"],

package/data/capability-catalog/capability-catalog.en.json

@@ -2217,6 +2217,49 @@
     "Malicious-concurrency, kernel-image or signature-proof gaps return to Foundation; do not copy a walker, native addon, Harness, schema, Registry, runner or receipt chain locally"
    ]
   },
+  {
+   "id": "foundation.harness.mechanism-batch",
+   "intent": "Combine mutually independent canonical-json requests that would otherwise need one cross-process invocation each into a single bounded, same-operation, ordered batch transport, reducing repeated process starts and transfer overhead",
+   "useWhen": [
+    "Multiple mutually independent canonical-json requests need per-item cross-process invocation (one process start and transfer each) and item count plus request/response bytes fit the capacity recorded in the capability catalog",
+    "The caller has the same-version official Bundle with a verified source and takes on the caller responsibility of domain grouping and batch splitting"
+   ],
+   "doNotUseWhen": [
+    "Requests already live in the same Node process (reuse the existing invokeFoundationMechanism object entry point; do not introduce a wrapper with no benefit)",
+    "A later item depends on an earlier item's result, or concurrency, caching, retry, automatic splitting, or cross-item references are needed",
+    "The request exceeds the batch capacity, or contains operations outside this batch (such as schema batch validation, self-check, or fixed-set publication writes)"
+   ],
+   "prerequisites": [
+    "Contracts, Harness, and Engineering Kit are pinned to exactly the same version; the official Bundle is generated from same-version packages and keeps source identity, digest, and integrity checks",
+    "The caller supplies the input/output/error streams (process standard streams by default); domain grouping, capacity splitting, and stream acceptance stay with the caller"
+   ],
+   "inputs": [
+    "One JSON document with exactly operation (canonical-json) and inputs (non-empty ordered array; each item is {document}); NDJSON, session protocols, and automatic array detection are unsupported"
+   ],
+   "outputs": [
+    "{results:[{inputIndex,exitCode,response}]}; successful items carry the original mechanism response and failed items the original CLI error object, in input order"
+   ],
+   "sideEffects": [
+    "None (items execute through the existing pure-function dispatcher; only the caller-provided output/error streams are written; no file, network, process, or residual-state side effects)"
+   ],
+   "failureSemantics": [
+    "Whole-batch shape or capacity refusals write one batch error object to the error stream and exit 2 (TypeError projection; details.kind is closed to batch-structure-invalid, batch-item-limit, batch-input-limit, batch-output-limit)",
+    "Per-item mechanism failures are projected into that item's response and later items still run; at least one failure exits 2; partial batch results are never delivered"
+   ],
+   "invariants": [
+    "Outer shape checks for every item complete before the first item runs; item order, duplicates, and the per-item invocation count stay unchanged",
+    "The complete response bytes are not sent until confirmed within the output limit; error objects are neither reordered nor normalized"
+   ],
+   "ownedByCaller": [
+    "Domain grouping and capacity splitting, and judging dependencies between requests",
+    "Version availability and maturity judgment (since 0.19.0 and candidate status live in the catalog and API documentation), the exact pin, and source-identity binding",
+    "Batch adoption completion and domain acceptance judgment"
+   ],
+   "routeElsewhere": [
+    "Concurrency, caching, retry, cross-item references, or automatic splitting: keep them on the original consumer path, or return a real common gap to Foundation as a minimal capability contract",
+    "Mechanisms outside this batch (schema batch validation, self-check, fixed-set publication writes, and so on) keep their existing public entry points"
+   ]
+  },
   {
    "id": "foundation.kit.plugin-verification",
    "intent": "Preserve the complete plugin layout and add dedicated Qoder and WorkBuddy production lifecycle drivers while keeping structure and host semantics separate",

package/data/capability-catalog/capability-catalog.json

@@ -1444,6 +1444,39 @@
    "migration": "none",
    "promotionPolicy": "consumer-transparent"
   },
+  {
+   "id": "foundation.harness.mechanism-batch",
+   "package": "skill-family-harness-node",
+   "layer": "harness",
+   "since": "0.19.0",
+   "stability": "candidate",
+   "adoptionScopes": ["harness"],
+   "entrypoints": [
+    "runMechanismCliBatch (packages/skill-family-harness-node/candidate/mechanisms-cli.mjs)",
+    "mechanisms-cli.mjs --batch (packages/skill-family-harness-node/candidate/mechanisms-cli.mjs)"
+   ],
+   "sourceRefs": [
+    "packages/skill-family-contracts/candidate/foundation-mechanisms/mechanism-batch-policy.json",
+    "packages/skill-family-contracts/candidate/foundation-mechanisms/mechanism-batch-request.schema.json",
+    "packages/skill-family-contracts/candidate/foundation-mechanisms/mechanism-batch-result.schema.json",
+    "packages/skill-family-harness-node/candidate/mechanisms-cli.mjs",
+    "packages/skill-family-engineering-kit/candidate/profile-bundle.mjs"
+   ],
+   "positiveTestRefs": [
+    "packages/skill-family-contracts/test/quickstart-profile.test.mjs",
+    "packages/skill-family-harness-node/test/quickstart-profile.test.mjs",
+    "packages/skill-family-engineering-kit/test/candidate-mechanisms-cli.test.mjs",
+    "packages/skill-family-engineering-kit/test/candidate-profile-bundle.test.mjs"
+   ],
+   "negativeTestRefs": [
+    "packages/skill-family-contracts/test/quickstart-profile.test.mjs",
+    "packages/skill-family-harness-node/test/quickstart-profile.test.mjs",
+    "packages/skill-family-engineering-kit/test/candidate-mechanisms-cli.test.mjs",
+    "packages/skill-family-engineering-kit/test/candidate-profile-bundle.test.mjs"
+   ],
+   "migration": "none",
+   "promotionPolicy": "consumer-transparent"
+  },
   {
    "id": "foundation.kit.plugin-verification",
    "package": "skill-family-engineering-kit",

package/data/capability-catalog/capability-catalog.zh-CN.json

@@ -2216,6 +2216,49 @@
     "恶意并发、内核映像或签名证明缺口交回 Foundation；不得复制 walker、native addon、Harness、schema、Registry、runner 或 receipt 链"
    ]
   },
+  {
+   "id": "foundation.harness.mechanism-batch",
+   "intent": "把相互独立、需逐项跨进程调用的 canonical-json 请求合并为一次有界、同操作、顺序执行的批量传输，减少重复进程启动与传输开销",
+   "useWhen": [
+    "多个相互独立的 canonical-json 请求需要逐项跨进程调用（每项一次进程启动与传输），且项数与请求/响应字节落在能力目录登记的容量内",
+    "调用方已安装来源明确的同版本官方 Bundle，并承担领域分组与批次切分的调用方责任"
+   ],
+   "doNotUseWhen": [
+    "请求已位于同一 Node 进程内（优先复用既有 invokeFoundationMechanism 对象入口，不引入无收益的流包装）",
+    "后项输入依赖前项结果，或需要并发、缓存、重试、自动拆批或跨项引用",
+    "请求超过批次容量，或包含本批未支持的操作（如 schema 批量校验、self-check、固定集合写入）"
+   ],
+   "prerequisites": [
+    "Contracts、Harness 与 Engineering Kit 精确锁定同一版本；官方 Bundle 由同版本三包生成并保留来源身份、摘要与完整性检查",
+    "调用方提供 input/output/error 流（默认进程标准流）；领域分组、容量切分与流接收责任归调用方"
+   ],
+   "inputs": [
+    "恰好包含 operation（canonical-json）与 inputs（非空有序数组，每项 {document}）的一个 JSON 文档；不支持 NDJSON、会话协议或数组自动探测"
+   ],
+   "outputs": [
+    "{results:[{inputIndex,exitCode,response}]}；成功项 response 为原机制结果，失败项为原 CLI 错误对象，顺序与输入一致"
+   ],
+   "sideEffects": [
+    "无（逐项经既有纯函数分派器执行；只写调用方提供的 output/error 流；无文件、网络、进程或残余状态副作用）"
+   ],
+   "failureSemantics": [
+    "整批结构或容量拒绝向 error 流写一个批次错误对象并整体退出 2（TypeError 投影；details.kind 封闭为 batch-structure-invalid、batch-item-limit、batch-input-limit、batch-output-limit）",
+    "单项机制失败按原 CLI 错误投影写入该项 response 并继续执行后续项；至少一项失败整体退出 2；不交付部分批次结果"
+   ],
+   "invariants": [
+    "全部项的外层形状检查先于第一项执行；项顺序、重复项与逐项调用次数保持不变",
+    "完整响应字节在确认未超输出上限前不发送；错误对象不重新排序或规范化"
+   ],
+   "ownedByCaller": [
+    "领域分组与容量切分、请求间依赖关系的判断",
+    "版本可用性与成熟度判断（since 0.19.0、candidate 由目录与 API 文档携带）、精确 pin 与来源身份绑定",
+    "批次采用完成与领域验收判定"
+   ],
+   "routeElsewhere": [
+    "需要并发、缓存、重试、跨项引用或自动拆分：由消费者保留原路径处理，或把真实共性缺口交回 Foundation 形成最小能力合同",
+    "本批未支持的机制（schema 批量校验、self-check、固定集合写入等）保留各自既有公共入口"
+   ]
+  },
   {
    "id": "foundation.kit.plugin-verification",
    "intent": "保留完整插件布局，增加 Qoder 与 WorkBuddy 专属生产生命周期 driver，并把结构合同与宿主语义分开",

package/docs/agents/capability-catalog.en.json

@@ -2217,6 +2217,49 @@
     "Malicious-concurrency, kernel-image or signature-proof gaps return to Foundation; do not copy a walker, native addon, Harness, schema, Registry, runner or receipt chain locally"
    ]
   },
+  {
+   "id": "foundation.harness.mechanism-batch",
+   "intent": "Combine mutually independent canonical-json requests that would otherwise need one cross-process invocation each into a single bounded, same-operation, ordered batch transport, reducing repeated process starts and transfer overhead",
+   "useWhen": [
+    "Multiple mutually independent canonical-json requests need per-item cross-process invocation (one process start and transfer each) and item count plus request/response bytes fit the capacity recorded in the capability catalog",
+    "The caller has the same-version official Bundle with a verified source and takes on the caller responsibility of domain grouping and batch splitting"
+   ],
+   "doNotUseWhen": [
+    "Requests already live in the same Node process (reuse the existing invokeFoundationMechanism object entry point; do not introduce a wrapper with no benefit)",
+    "A later item depends on an earlier item's result, or concurrency, caching, retry, automatic splitting, or cross-item references are needed",
+    "The request exceeds the batch capacity, or contains operations outside this batch (such as schema batch validation, self-check, or fixed-set publication writes)"
+   ],
+   "prerequisites": [
+    "Contracts, Harness, and Engineering Kit are pinned to exactly the same version; the official Bundle is generated from same-version packages and keeps source identity, digest, and integrity checks",
+    "The caller supplies the input/output/error streams (process standard streams by default); domain grouping, capacity splitting, and stream acceptance stay with the caller"
+   ],
+   "inputs": [
+    "One JSON document with exactly operation (canonical-json) and inputs (non-empty ordered array; each item is {document}); NDJSON, session protocols, and automatic array detection are unsupported"
+   ],
+   "outputs": [
+    "{results:[{inputIndex,exitCode,response}]}; successful items carry the original mechanism response and failed items the original CLI error object, in input order"
+   ],
+   "sideEffects": [
+    "None (items execute through the existing pure-function dispatcher; only the caller-provided output/error streams are written; no file, network, process, or residual-state side effects)"
+   ],
+   "failureSemantics": [
+    "Whole-batch shape or capacity refusals write one batch error object to the error stream and exit 2 (TypeError projection; details.kind is closed to batch-structure-invalid, batch-item-limit, batch-input-limit, batch-output-limit)",
+    "Per-item mechanism failures are projected into that item's response and later items still run; at least one failure exits 2; partial batch results are never delivered"
+   ],
+   "invariants": [
+    "Outer shape checks for every item complete before the first item runs; item order, duplicates, and the per-item invocation count stay unchanged",
+    "The complete response bytes are not sent until confirmed within the output limit; error objects are neither reordered nor normalized"
+   ],
+   "ownedByCaller": [
+    "Domain grouping and capacity splitting, and judging dependencies between requests",
+    "Version availability and maturity judgment (since 0.19.0 and candidate status live in the catalog and API documentation), the exact pin, and source-identity binding",
+    "Batch adoption completion and domain acceptance judgment"
+   ],
+   "routeElsewhere": [
+    "Concurrency, caching, retry, cross-item references, or automatic splitting: keep them on the original consumer path, or return a real common gap to Foundation as a minimal capability contract",
+    "Mechanisms outside this batch (schema batch validation, self-check, fixed-set publication writes, and so on) keep their existing public entry points"
+   ]
+  },
   {
    "id": "foundation.kit.plugin-verification",
    "intent": "Preserve the complete plugin layout and add dedicated Qoder and WorkBuddy production lifecycle drivers while keeping structure and host semantics separate",

package/docs/agents/capability-catalog.json

@@ -1444,6 +1444,39 @@
    "migration": "none",
    "promotionPolicy": "consumer-transparent"
   },
+  {
+   "id": "foundation.harness.mechanism-batch",
+   "package": "skill-family-harness-node",
+   "layer": "harness",
+   "since": "0.19.0",
+   "stability": "candidate",
+   "adoptionScopes": ["harness"],
+   "entrypoints": [
+    "runMechanismCliBatch (packages/skill-family-harness-node/candidate/mechanisms-cli.mjs)",
+    "mechanisms-cli.mjs --batch (packages/skill-family-harness-node/candidate/mechanisms-cli.mjs)"
+   ],
+   "sourceRefs": [
+    "packages/skill-family-contracts/candidate/foundation-mechanisms/mechanism-batch-policy.json",
+    "packages/skill-family-contracts/candidate/foundation-mechanisms/mechanism-batch-request.schema.json",
+    "packages/skill-family-contracts/candidate/foundation-mechanisms/mechanism-batch-result.schema.json",
+    "packages/skill-family-harness-node/candidate/mechanisms-cli.mjs",
+    "packages/skill-family-engineering-kit/candidate/profile-bundle.mjs"
+   ],
+   "positiveTestRefs": [
+    "packages/skill-family-contracts/test/quickstart-profile.test.mjs",
+    "packages/skill-family-harness-node/test/quickstart-profile.test.mjs",
+    "packages/skill-family-engineering-kit/test/candidate-mechanisms-cli.test.mjs",
+    "packages/skill-family-engineering-kit/test/candidate-profile-bundle.test.mjs"
+   ],
+   "negativeTestRefs": [
+    "packages/skill-family-contracts/test/quickstart-profile.test.mjs",
+    "packages/skill-family-harness-node/test/quickstart-profile.test.mjs",
+    "packages/skill-family-engineering-kit/test/candidate-mechanisms-cli.test.mjs",
+    "packages/skill-family-engineering-kit/test/candidate-profile-bundle.test.mjs"
+   ],
+   "migration": "none",
+   "promotionPolicy": "consumer-transparent"
+  },
   {
    "id": "foundation.kit.plugin-verification",
    "package": "skill-family-engineering-kit",

package/docs/agents/capability-catalog.zh-CN.json

@@ -2216,6 +2216,49 @@
     "恶意并发、内核映像或签名证明缺口交回 Foundation；不得复制 walker、native addon、Harness、schema、Registry、runner 或 receipt 链"
    ]
   },
+  {
+   "id": "foundation.harness.mechanism-batch",
+   "intent": "把相互独立、需逐项跨进程调用的 canonical-json 请求合并为一次有界、同操作、顺序执行的批量传输，减少重复进程启动与传输开销",
+   "useWhen": [
+    "多个相互独立的 canonical-json 请求需要逐项跨进程调用（每项一次进程启动与传输），且项数与请求/响应字节落在能力目录登记的容量内",
+    "调用方已安装来源明确的同版本官方 Bundle，并承担领域分组与批次切分的调用方责任"
+   ],
+   "doNotUseWhen": [
+    "请求已位于同一 Node 进程内（优先复用既有 invokeFoundationMechanism 对象入口，不引入无收益的流包装）",
+    "后项输入依赖前项结果，或需要并发、缓存、重试、自动拆批或跨项引用",
+    "请求超过批次容量，或包含本批未支持的操作（如 schema 批量校验、self-check、固定集合写入）"
+   ],
+   "prerequisites": [
+    "Contracts、Harness 与 Engineering Kit 精确锁定同一版本；官方 Bundle 由同版本三包生成并保留来源身份、摘要与完整性检查",
+    "调用方提供 input/output/error 流（默认进程标准流）；领域分组、容量切分与流接收责任归调用方"
+   ],
+   "inputs": [
+    "恰好包含 operation（canonical-json）与 inputs（非空有序数组，每项 {document}）的一个 JSON 文档；不支持 NDJSON、会话协议或数组自动探测"
+   ],
+   "outputs": [
+    "{results:[{inputIndex,exitCode,response}]}；成功项 response 为原机制结果，失败项为原 CLI 错误对象，顺序与输入一致"
+   ],
+   "sideEffects": [
+    "无（逐项经既有纯函数分派器执行；只写调用方提供的 output/error 流；无文件、网络、进程或残余状态副作用）"
+   ],
+   "failureSemantics": [
+    "整批结构或容量拒绝向 error 流写一个批次错误对象并整体退出 2（TypeError 投影；details.kind 封闭为 batch-structure-invalid、batch-item-limit、batch-input-limit、batch-output-limit）",
+    "单项机制失败按原 CLI 错误投影写入该项 response 并继续执行后续项；至少一项失败整体退出 2；不交付部分批次结果"
+   ],
+   "invariants": [
+    "全部项的外层形状检查先于第一项执行；项顺序、重复项与逐项调用次数保持不变",
+    "完整响应字节在确认未超输出上限前不发送；错误对象不重新排序或规范化"
+   ],
+   "ownedByCaller": [
+    "领域分组与容量切分、请求间依赖关系的判断",
+    "版本可用性与成熟度判断（since 0.19.0、candidate 由目录与 API 文档携带）、精确 pin 与来源身份绑定",
+    "批次采用完成与领域验收判定"
+   ],
+   "routeElsewhere": [
+    "需要并发、缓存、重试、跨项引用或自动拆分：由消费者保留原路径处理，或把真实共性缺口交回 Foundation 形成最小能力合同",
+    "本批未支持的机制（schema 批量校验、self-check、固定集合写入等）保留各自既有公共入口"
+   ]
+  },
   {
    "id": "foundation.kit.plugin-verification",
    "intent": "保留完整插件布局，增加 Qoder 与 WorkBuddy 专属生产生命周期 driver，并把结构合同与宿主语义分开",

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

@@ -2031,6 +2031,16 @@
 <td>lock file (monotonic fencing)</td>
 <td><code>SFC2004</code></td>
 </tr>
+<tr>
+<td><code>runMechanismCliBatch</code> / <code>mechanisms-cli.mjs --batch</code> (0.19.0 candidate)</td>
+<td>no</td>
+<td>no</td>
+<td>no</td>
+<td>no</td>
+<td>no</td>
+<td>none (only the caller-provided output/error streams are written)</td>
+<td>exit code 0 (all succeeded) / 2 (at least one item failed or whole batch refused); <code>details.kind</code> closed to <code>batch-structure-invalid</code>/<code>batch-item-limit</code>/<code>batch-input-limit</code>/<code>batch-output-limit</code></td>
+</tr>
 </tbody>
 </table>
 <p>Harness's <code>HARNESS_EXCLUSIONS</code> explicitly excludes release-state, remote-network-access, business-semantics, workflow-orchestration, model-calls, git-writes.</p>

package/docs/public/status/index.html

@@ -1792,17 +1792,17 @@
 <tbody>
 <tr>
 <td><code>skill-family-contracts</code></td>
-<td>0.18.0</td>
+<td>0.19.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.18.0</td>
+<td>0.19.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.18.0</td>
+<td>0.19.0</td>
 <td><a href="https://github.com/ifoohoo/skill-family-engineering-kit">ifoohoo/skill-family-engineering-kit</a></td>
 </tr>
 </tbody>