skill-family-engineering-kit 0.14.0 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +36 -0
- package/CHANGELOG.zh-CN.md +36 -0
- package/README.md +40 -30
- package/README.zh-CN.md +40 -30
- package/data/capability-catalog/capability-catalog.en.json +151 -34
- package/data/capability-catalog/capability-catalog.json +78 -9
- package/data/capability-catalog/capability-catalog.zh-CN.json +149 -33
- package/docs/agents/capability-catalog.en.json +151 -34
- package/docs/agents/capability-catalog.json +78 -9
- package/docs/agents/capability-catalog.zh-CN.json +149 -33
- package/docs/architecture/index.html +1 -1
- package/docs/en/reference/failure-and-side-effect-matrix/index.html +62 -11
- package/docs/integration/audit/index.html +4 -1
- package/docs/integration/audit/version-compatibility/index.html +5 -2
- package/docs/public/status/index.html +3 -3
- package/docs/quickstart/index.html +3 -3
- package/docs/reference/api/contracts/index.html +76 -3
- package/docs/reference/api/engineering-kit/index.html +100 -19
- package/docs/reference/api/harness/index.html +83 -6
- package/docs/reference/failure-and-side-effect-matrix/index.html +62 -11
- package/docs/search/search_index.json +1 -1
- package/package.json +3 -3
- package/release-notes/0.15.0.yaml +21 -0
- package/release-notes/0.16.0.yaml +17 -0
- package/src/cli.mjs +3 -3
- package/src/host-verification-drivers.mjs +171 -0
- package/src/index.mjs +9 -3
- package/src/plugin-verification.mjs +260 -2
- package/src/qualification.mjs +112 -23
- package/src/skill-family-directory-verification.mjs +283 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,41 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
<!-- release-skill:changelog:start version=0.16.0 locale=en baseline=sha256:47c81698bf9458edc28ec1e198e43ad6f961db4249f606426a4b83664872a5d8 -->
|
|
4
|
+
## [0.16.0] - 2026-08-31
|
|
5
|
+
|
|
6
|
+
Engineering Kit 0.16.0 tightens the candidate host-verification regression around one common workload and consumer answer across five fixed drivers.
|
|
7
|
+
|
|
8
|
+
### Changed
|
|
9
|
+
|
|
10
|
+
- Verifies that all five fixed host drivers consume the same candidate bindings and expose the caller's business answer through the existing runHostVerification path.
|
|
11
|
+
- Keeps host-managed state, domain acceptance, and real-host qualification outside Foundation; no new Kit command or lifecycle capability is added.
|
|
12
|
+
|
|
13
|
+
### Upgrade Notes
|
|
14
|
+
|
|
15
|
+
The five-host check exercises the existing candidate API and does not turn a fixture or test result into real-host qualification. Consumers still own domain assertions and host authorization.
|
|
16
|
+
<!-- release-skill:changelog:end version=0.16.0 locale=en -->
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
<!-- release-skill:changelog:start version=0.15.0 locale=en baseline=sha256:8b3c67e9fe98dd14ad7b43220440311cb046d10070f16dd6c83d47d3351efbf5 -->
|
|
20
|
+
## [0.15.0] - 2026-08-29
|
|
21
|
+
|
|
22
|
+
Engineering Kit 0.15.0 adds fixed native-lifecycle and Kimi directory qualification entries.
|
|
23
|
+
|
|
24
|
+
### Added
|
|
25
|
+
|
|
26
|
+
- Adds closed 12-stage Qoder and WorkBuddy lifecycle fixture parsing.
|
|
27
|
+
- Adds Kimi directory qualification with driverVersion 1.0.0 and CLI 0.39.1 admission.
|
|
28
|
+
|
|
29
|
+
### Changed
|
|
30
|
+
|
|
31
|
+
- Qualification compares Contracts and Harness versions directly with KIT_VERSION.
|
|
32
|
+
|
|
33
|
+
### Upgrade Notes
|
|
34
|
+
|
|
35
|
+
Fixtures prove parser wiring only; consumers own formal process, directory, and domain acceptance observations.
|
|
36
|
+
<!-- release-skill:changelog:end version=0.15.0 locale=en -->
|
|
37
|
+
|
|
38
|
+
|
|
3
39
|
<!-- release-skill:changelog:start version=0.14.0 locale=en baseline=sha256:ae68c432972367cf4f77239dcad446fe4d15fc73e6042f70bd0a7b67041f93b9 -->
|
|
4
40
|
## [0.14.0] - 2026-08-28
|
|
5
41
|
|
package/CHANGELOG.zh-CN.md
CHANGED
|
@@ -1,5 +1,41 @@
|
|
|
1
1
|
# 变更日志
|
|
2
2
|
|
|
3
|
+
<!-- release-skill:changelog:start version=0.16.0 locale=zh-CN baseline=sha256:1db170e8f4ae8ca25301b4e5893d86a0f486218fa75f9bcc0ced2a5eba7d26d6 -->
|
|
4
|
+
## [0.16.0] - 2026-08-31
|
|
5
|
+
|
|
6
|
+
Engineering Kit 0.16.0 收紧五个固定 driver 的候选宿主验证回归,要求共用一个 workload 并核对消费者业务答案。
|
|
7
|
+
|
|
8
|
+
### 变更
|
|
9
|
+
|
|
10
|
+
- 通过既有 `runHostVerification` 路径核对 Claude、Codex、Kimi、Qoder 与 WorkBuddy 使用同一候选绑定,并暴露调用方的业务答案。
|
|
11
|
+
- 保持宿主管理状态、领域接受规则和真实宿主资格归调用方负责;不新增 Kit 命令或生命周期能力。
|
|
12
|
+
|
|
13
|
+
### 升级说明
|
|
14
|
+
|
|
15
|
+
五宿主检查只验证现有候选 API,不会把 fixture 或测试结果升级为真实宿主资格;领域断言与宿主授权仍由消费者负责。
|
|
16
|
+
<!-- release-skill:changelog:end version=0.16.0 locale=zh-CN -->
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
<!-- release-skill:changelog:start version=0.15.0 locale=zh-CN baseline=sha256:c559c91bed872ab70dac2a4836c636b35ed905282f4aa4cdcf56d21a1ce246b9 -->
|
|
20
|
+
## [0.15.0] - 2026-08-29
|
|
21
|
+
|
|
22
|
+
Engineering Kit 0.15.0 增加固定的 native-lifecycle 与 Kimi 目录资格入口。
|
|
23
|
+
|
|
24
|
+
### 新增
|
|
25
|
+
|
|
26
|
+
- 增加 Qoder 与 WorkBuddy 封闭十二阶段生命周期 fixture 解析。
|
|
27
|
+
- 增加 Kimi 目录资格检查,使用 driverVersion 1.0.0 与 CLI 0.39.1 接纳规则。
|
|
28
|
+
|
|
29
|
+
### 变更
|
|
30
|
+
|
|
31
|
+
- 资格检查直接将 Contracts、Harness 版本与 KIT_VERSION 比较。
|
|
32
|
+
|
|
33
|
+
### 升级说明
|
|
34
|
+
|
|
35
|
+
fixture 只证明解析器接线;正式进程、目录和领域接受观察仍由消费者负责。
|
|
36
|
+
<!-- release-skill:changelog:end version=0.15.0 locale=zh-CN -->
|
|
37
|
+
|
|
38
|
+
|
|
3
39
|
<!-- release-skill:changelog:start version=0.14.0 locale=zh-CN baseline=sha256:c3c9e90c2c1e4c06d34871d18ba4062db46e484cbeccbf25867d8b59db32ccc0 -->
|
|
4
40
|
## [0.14.0] - 2026-08-28
|
|
5
41
|
|
package/README.md
CHANGED
|
@@ -4,35 +4,41 @@
|
|
|
4
4
|
|
|
5
5
|
# skill-family-engineering-kit
|
|
6
6
|
|
|
7
|
-
<!-- release-skill:release-version: 0.
|
|
7
|
+
<!-- release-skill:release-version: 0.16.0 -->
|
|
8
8
|
|
|
9
9
|
An engineering toolkit used in development and CI. There are **exactly four** top-level commands, and no fifth:
|
|
10
10
|
|
|
11
11
|
<!-- release-skill:managed:start id=latest-release -->
|
|
12
|
-
**0.
|
|
12
|
+
**0.16.0** (2026-08-31)
|
|
13
13
|
|
|
14
|
-
Engineering Kit 0.
|
|
15
|
-
|
|
16
|
-
**Added**
|
|
17
|
-
|
|
18
|
-
- Adds read-only capability assessment through adopt-plan and the list-capabilities CLI mode.
|
|
19
|
-
- Adds consumer contract-test scaffolding guidance and the explicit qualification command for real-host evidence.
|
|
14
|
+
Engineering Kit 0.16.0 tightens the candidate host-verification regression around one common workload and consumer answer across five fixed drivers.
|
|
20
15
|
|
|
21
16
|
**Changed**
|
|
22
17
|
|
|
23
|
-
-
|
|
18
|
+
- Verifies that all five fixed host drivers consume the same candidate bindings and expose the caller's business answer through the existing runHostVerification path.
|
|
19
|
+
- Keeps host-managed state, domain acceptance, and real-host qualification outside Foundation; no new Kit command or lifecycle capability is added.
|
|
24
20
|
|
|
25
21
|
**Upgrade Notes**
|
|
26
22
|
|
|
27
|
-
|
|
23
|
+
The five-host check exercises the existing candidate API and does not turn a fixture or test result into real-host qualification. Consumers still own domain assertions and host authorization.
|
|
28
24
|
<!-- release-skill:managed:end id=latest-release -->
|
|
29
25
|
|
|
26
|
+
### Foundation 0.15.0 candidate qualification entries
|
|
27
|
+
|
|
28
|
+
The candidate adds two fixed qualification entries: `foundation.kit.plugin-verification` accepts the Qoder and WorkBuddy native-lifecycle branches, and `foundation.kit.skill-family-directory-verification` accepts the Kimi branch. Qoder and WorkBuddy each use a dedicated production driver with its own argv plan and the same twelve ordered semantic stages; executable identity is re-observed before every spawn. Contracts validates only the closed stage structure, order, and stop propagation.
|
|
29
|
+
|
|
30
|
+
`runSkillFamilyDirectoryVerification({ request, bindings })` owns the local Kimi process path. It fixes `-p <prompt> --output-format stream-json --skills-dir <family-root>`, projects a narrow environment, and captures raw output under private evidence. Caller observations are rejected. Because no official typed observation mapping is available, current results remain `indeterminate` with `official-observation-unavailable`, even when a controlled fixture stream proves parser wiring.
|
|
31
|
+
|
|
32
|
+
Consumers bind the executable, directories, source, workload, and domain facts; Kit launches the bounded local process. They must not copy a generic runner, walker, native addon, schema, registry, oracle, cache, state machine, or receipt chain. Controlled fixture protocols are Foundation-owned isolation evidence, not Qoder, WorkBuddy, or Kimi vendor grammar and not real-host qualification. A stable isolated tree is sufficient for Harness record mode; its best-effort boundary does not promise a transaction snapshot, hostile same-UID concurrency, or ABA safety.
|
|
33
|
+
|
|
34
|
+
Foundation itself does not issue network requests, but a bound executable may access the network. Foundation provides no sandbox or egress blocking; callers and the execution environment own that isolation. Qoder, WorkBuddy, and Kimi remain `manual/candidate`, and controlled fixtures do not grant real-host qualification.
|
|
35
|
+
|
|
30
36
|
| Command | Purpose | Side effects |
|
|
31
37
|
| --- | --- | --- |
|
|
32
38
|
| `scaffold` | Generate a Skill Family project skeleton in an empty directory | Only writes skeleton files to the empty target directory (atomic write, path containment); non-empty or conflicting targets are rejected and not touched |
|
|
33
|
-
| `adopt-plan` | Strictly read-only planning of adopting an existing repo | None — writes no files (including temp files)
|
|
39
|
+
| `adopt-plan` | Strictly read-only planning of adopting an existing repo | None — writes no files (including temp files); by default it may spawn one frozen read-only Git status probe; `--no-git-spawn` disables it; no Git write commands; plan output goes to stdout |
|
|
34
40
|
| `projection` | Project managed artifacts | Only writes paths authorized by manifest and declared managed by the target; unauthorized, hand-written, and out-of-bounds paths are all rejected (zero writes on rejection) |
|
|
35
|
-
| `check` | Contract/drift/closure/version/doc-fact/Git-precondition diagnostics |
|
|
41
|
+
| `check` | Contract/drift/closure/version/doc-fact/Git-precondition diagnostics | Ordinary diagnostics are read-only and write no files; by default they may spawn one frozen read-only Git status probe; `--no-git-spawn` disables it; `check relock` is an explicit controlled write transaction; `check qualification` may spawn a bound executable after preflight. Foundation itself does not issue network requests, but that process may access the network. |
|
|
36
42
|
|
|
37
43
|
## Problem It Solves
|
|
38
44
|
|
|
@@ -44,7 +50,7 @@ Kit is the "engineering stage" layer, depending on the Harness and Contracts. It
|
|
|
44
50
|
|
|
45
51
|
## Installation and Minimal Example
|
|
46
52
|
|
|
47
|
-
Version 0.
|
|
53
|
+
Version 0.16.0 is a local candidate. Build all three tarballs into one temporary directory and install those exact files for a candidate check:
|
|
48
54
|
|
|
49
55
|
```sh
|
|
50
56
|
pack_dir="$(mktemp -d)"
|
|
@@ -52,21 +58,21 @@ pack_dir="$(mktemp -d)"
|
|
|
52
58
|
(cd packages/skill-family-harness-node && pnpm pack --pack-destination "$pack_dir")
|
|
53
59
|
(cd packages/skill-family-engineering-kit && pnpm pack --pack-destination "$pack_dir")
|
|
54
60
|
mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
|
|
55
|
-
(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.
|
|
61
|
+
(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.16.0.tgz" "$pack_dir/skill-family-harness-node-0.16.0.tgz" "$pack_dir/skill-family-engineering-kit-0.16.0.tgz")
|
|
56
62
|
```
|
|
57
63
|
|
|
58
64
|
After publication, use the registry coordinate:
|
|
59
65
|
|
|
60
66
|
```sh
|
|
61
|
-
npm install --save-dev skill-family-engineering-kit@0.
|
|
62
|
-
npm exec --package=skill-family-engineering-kit@0.
|
|
63
|
-
npm exec --package=skill-family-engineering-kit@0.
|
|
64
|
-
npm exec --package=skill-family-engineering-kit@0.
|
|
65
|
-
npm exec --package=skill-family-engineering-kit@0.
|
|
66
|
-
npm exec --package=skill-family-engineering-kit@0.
|
|
67
|
+
npm install --save-dev skill-family-engineering-kit@0.16.0
|
|
68
|
+
npm exec --package=skill-family-engineering-kit@0.16.0 -- skill-family-kit --help
|
|
69
|
+
npm exec --package=skill-family-engineering-kit@0.16.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
|
|
70
|
+
npm exec --package=skill-family-engineering-kit@0.16.0 -- skill-family-kit adopt-plan --root <repo> --list-capabilities --all --scope all --locale en --uses ./uses.json
|
|
71
|
+
npm exec --package=skill-family-engineering-kit@0.16.0 -- skill-family-kit projection --root <repo>
|
|
72
|
+
npm exec --package=skill-family-engineering-kit@0.16.0 -- skill-family-kit check --root <repo>
|
|
67
73
|
```
|
|
68
74
|
|
|
69
|
-
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.
|
|
75
|
+
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.16.0 -- skill-family-kit --help`.
|
|
70
76
|
|
|
71
77
|
### Three adoption journeys
|
|
72
78
|
|
|
@@ -150,7 +156,7 @@ npm exec -- skill-family-kit scaffold host-build --root <workspace> --host <id>
|
|
|
150
156
|
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>
|
|
151
157
|
```
|
|
152
158
|
|
|
153
|
-
The Profile must be provided explicitly; Kit does not bind a specific host by default. Canonical host IDs may resolve only aliases declared by the finite registered Profile set. Probe starts no process by default; only when both `--allow-host-spawn --host-executable <absolute-path>` are given is the frozen version vector executed. Local install and update use an explicit authorization reference plus the existing contained publication primitives; uninstall is rejected with `manual-recovery-required` because Foundation has no safe bound deletion primitive. Two registered hosts have trusted version drivers; Kimi Code, WorkBuddy, CodeBuddy, and DeepSeek Harness expose independent manual facts. Qoder
|
|
159
|
+
The Profile must be provided explicitly; Kit does not bind a specific host by default. Canonical host IDs may resolve only aliases declared by the finite registered Profile set. Probe starts no process by default; only when both `--allow-host-spawn --host-executable <absolute-path>` are given is the frozen version vector executed. Local install and update use an explicit authorization reference plus the existing contained publication primitives; uninstall is rejected with `manual-recovery-required` because Foundation has no safe bound deletion primitive. Two registered hosts have trusted version drivers; Kimi Code, WorkBuddy, CodeBuddy, and DeepSeek Harness expose independent manual facts. Qoder remains `manual`; the separate native plugin candidate does not grant generic host build, plan, apply, install/update/uninstall, rollback, or real-host qualification. Adapter source only accepts declared text closures; binary projection is not supported; see the [host capability matrix](../../docs/reference/host-capability-matrix.md) and registered Profiles.
|
|
154
160
|
|
|
155
161
|
### Candidate real-host verification library API
|
|
156
162
|
|
|
@@ -165,14 +171,14 @@ The API keeps consumer workload, domain output checks, domain PASS/FAIL, release
|
|
|
165
171
|
- New project skeleton: `scaffold` (does not overwrite a non-empty existing repo).
|
|
166
172
|
- Existing-repo adoption inventory: `adopt-plan` (strictly read-only, no file writes, no auto-migration).
|
|
167
173
|
- Managed projection: `projection` + Profile (does not overwrite handwritten files).
|
|
168
|
-
- Engineering diagnostics: `check`
|
|
174
|
+
- Engineering diagnostics: ordinary `check` is read-only; `check relock` is an explicit controlled write transaction, and `check qualification` may spawn a bound executable after preflight.
|
|
169
175
|
|
|
170
176
|
## Boundary Mechanisms
|
|
171
177
|
|
|
172
178
|
- `scaffold`'s target must be an **empty directory** (any entry including dotfiles counts as non-empty), or a non-existent path whose parent directory exists (only the last level is created). All writes go through the harness's atomic contained write (`writeFileAtomic`), leaving no half-written artifact on failure, and paths cannot escape the target root.
|
|
173
|
-
- `adopt-plan` is structurally read-only: there is no write call in the implementation, not even a temp file; the plan bytes share the same source as `scaffold` (single source of truth `describeSkeletonFiles`), hence "the plan is the action". A dirty repo has zero byte-level change before and after running.
|
|
179
|
+
- `adopt-plan` is structurally read-only: there is no write call in the implementation, not even a temp file; the plan bytes share the same source as `scaffold` (single source of truth `describeSkeletonFiles`), hence "the plan is the action". By default it may spawn one frozen read-only Git status probe; the CLI `--no-git-spawn` (or API `allowGitSpawn: false`) disables that probe. A dirty repo has zero byte-level change before and after running.
|
|
174
180
|
- `projection` uses two-phase execution: first, for each entry, it performs path classification, containment pre-check, self-projection check, manifest authorization check, hand-written protection, and conflict guard; if any entry violates, the whole is rejected with zero writes. Overwriting an existing file must declare the precise `expect.sha256` precondition; an existing file with identical content is an idempotent no-op. On write failure it best-effort restores the pre-write bytes of already-overwritten files.
|
|
175
|
-
- `check` is
|
|
181
|
+
- Ordinary `check` is read-only and has no write calls or `--fix/--apply/--repair` modes (such flags are rejected at the entry point). By default it may spawn one frozen read-only Git status probe; the CLI `--no-git-spawn` (or API `allowGitSpawn: false`) disables that probe. `check relock` is the explicit controlled write transaction; `check qualification` may spawn a bound executable after preflight. Git precondition state uses only filesystem facts plus at most one read-only `git status --porcelain=2` with a frozen parameter vector (`--no-optional-locks` + `GIT_OPTIONAL_LOCKS=0`, no index refresh).
|
|
176
182
|
|
|
177
183
|
## Error Codes and Exit Codes
|
|
178
184
|
|
|
@@ -195,7 +201,9 @@ Process exit codes: `0` success / no findings; `1` check has findings; `2` rejec
|
|
|
195
201
|
|
|
196
202
|
## Prohibited Items
|
|
197
203
|
|
|
198
|
-
This package must not perform git init, commit, push, tag, stash, branch switch, publish, delete, remote write, or publish-state recital; it does not implement a fifth top-level command; it does no business judgments
|
|
204
|
+
This package must not perform git init, commit, push, tag, stash, branch switch, publish, delete, remote write, or publish-state recital; it does not implement a fifth top-level command; it does no business judgments or model calls.
|
|
205
|
+
|
|
206
|
+
Foundation itself does not issue network requests, but the bound executable may access the network. Foundation provides no sandbox or egress blocking; callers and the execution environment own that isolation. Repository-controlled fixtures are designed not to issue network requests.
|
|
199
207
|
|
|
200
208
|
## Troubleshooting
|
|
201
209
|
|
|
@@ -220,7 +228,7 @@ This package must not perform git init, commit, push, tag, stash, branch switch,
|
|
|
220
228
|
### Do not use when
|
|
221
229
|
|
|
222
230
|
- You need auto-fix (`check` does not fix), or auto-migration (`adopt-plan` writes no files).
|
|
223
|
-
- You need remote host
|
|
231
|
+
- You need generic or remote host lifecycle, automatic trust confirmation, deleting uninstall, or real-host qualification from a controlled fixture.
|
|
224
232
|
- You need a stable Quickstart API or expect the candidate helper to bypass `runProjection` authorization.
|
|
225
233
|
|
|
226
234
|
### Capability selection
|
|
@@ -251,7 +259,7 @@ This package must not perform git init, commit, push, tag, stash, branch switch,
|
|
|
251
259
|
### Side effects
|
|
252
260
|
|
|
253
261
|
- scaffold/projection/host-build write files to the contained target (atomic + contained).
|
|
254
|
-
- adopt-plan and check are strictly read-only; git is read-only whitelisted probe
|
|
262
|
+
- adopt-plan and ordinary check are strictly read-only and write no files; by default they may spawn one frozen read-only Git status probe, disabled by `--no-git-spawn` (or API `allowGitSpawn: false`). check relock is an explicit controlled write transaction; check qualification may spawn a bound executable after preflight. Git is a read-only whitelisted probe for diagnostic checks.
|
|
255
263
|
- `FORBIDDEN_SIDE_EFFECTS` includes git-init/commit/push/tag, publish, remote-write.
|
|
256
264
|
|
|
257
265
|
### Failure semantics
|
|
@@ -279,6 +287,8 @@ This package must not perform git init, commit, push, tag, stash, branch switch,
|
|
|
279
287
|
|
|
280
288
|
## Complete Plugin Candidate
|
|
281
289
|
|
|
282
|
-
The candidate runPluginVerification({ request, bindings, hostsRoot }) preserves a
|
|
290
|
+
The candidate `runPluginVerification({ request, bindings, hostsRoot })` preserves the two legacy goals and adds a local-only `native-lifecycle` branch. Qoder and WorkBuddy use separate production drivers with driver-owned argv plans, exactly twelve semantic stages, and executable identity re-observation before every spawn. Contracts owns only structure; Kit owns the host plan and Oracle. The controlled executable protocol proves isolation wiring and is not vendor grammar. Each actual host/source combination still needs qualification evidence.
|
|
291
|
+
|
|
292
|
+
The separate `runSkillFamilyDirectoryVerification({ request, bindings })` entry fixes the Kimi production argv and narrow environment and rejects caller observation. Its raw parser is exercised through the production process path, but no controlled fixture event is promoted to `observed`; without an official typed mapping, the public result remains `indeterminate` and a manual candidate.
|
|
283
293
|
|
|
284
|
-
Version 0.
|
|
294
|
+
Version 0.16.0 is a local source candidate and is not published. Consume the three locally verified tarballs; a version marker, unit test or successful install is not complete contract integration, migration completion, or real-host qualification.
|
package/README.zh-CN.md
CHANGED
|
@@ -5,35 +5,41 @@
|
|
|
5
5
|
|
|
6
6
|
# skill-family-engineering-kit
|
|
7
7
|
|
|
8
|
-
<!-- release-skill:release-version: 0.
|
|
8
|
+
<!-- release-skill:release-version: 0.16.0 -->
|
|
9
9
|
|
|
10
10
|
开发与 CI 阶段使用的工程工具包。**恰好四个**顶层命令,没有第五个:
|
|
11
11
|
|
|
12
12
|
<!-- release-skill:managed:start id=latest-release -->
|
|
13
|
-
**0.
|
|
13
|
+
**0.16.0** (2026-08-31)
|
|
14
14
|
|
|
15
|
-
Engineering Kit 0.
|
|
16
|
-
|
|
17
|
-
**新增**
|
|
18
|
-
|
|
19
|
-
- 通过 `adopt-plan` 与 `list-capabilities` CLI 模式增加只读能力评估。
|
|
20
|
-
- 增加消费者契约测试脚手架指引,以及生成真实宿主证据的显式资格检查命令。
|
|
15
|
+
Engineering Kit 0.16.0 收紧五个固定 driver 的候选宿主验证回归,要求共用一个 workload 并核对消费者业务答案。
|
|
21
16
|
|
|
22
17
|
**变更**
|
|
23
18
|
|
|
24
|
-
-
|
|
19
|
+
- 通过既有 `runHostVerification` 路径核对 Claude、Codex、Kimi、Qoder 与 WorkBuddy 使用同一候选绑定,并暴露调用方的业务答案。
|
|
20
|
+
- 保持宿主管理状态、领域接受规则和真实宿主资格归调用方负责;不新增 Kit 命令或生命周期能力。
|
|
25
21
|
|
|
26
22
|
**升级说明**
|
|
27
23
|
|
|
28
|
-
|
|
24
|
+
五宿主检查只验证现有候选 API,不会把 fixture 或测试结果升级为真实宿主资格;领域断言与宿主授权仍由消费者负责。
|
|
29
25
|
<!-- release-skill:managed:end id=latest-release -->
|
|
30
26
|
|
|
27
|
+
### Foundation 0.15.0 candidate 资格入口
|
|
28
|
+
|
|
29
|
+
本候选版本增加两个固定资格入口:`foundation.kit.plugin-verification` 接入 Qoder 与 WorkBuddy 的 native-lifecycle 分支,`foundation.kit.skill-family-directory-verification` 接入 Kimi 目录分支。Qoder 与 WorkBuddy 各有一个生产 driver,各自确定 argv 计划,共用十二个有序语义阶段;每次 spawn 前重新观察可执行文件身份。Contracts 只校验闭合阶段结构、顺序与停止传播。
|
|
30
|
+
|
|
31
|
+
`runSkillFamilyDirectoryVerification({ request, bindings })` 负责启动本地 Kimi 进程,固定使用 `-p <prompt> --output-format stream-json --skills-dir <family-root>`,投影窄环境,并把原始输出写入私有证据根。调用方提供的 observation 会被拒绝。当前没有官方 typed observation 映射,因此即使受控 fixture stream 已证明 parser 接线,结果仍保持 `indeterminate`,原因为 `official-observation-unavailable`。
|
|
32
|
+
|
|
33
|
+
消费者绑定可执行文件、目录、来源、工作负载与领域事实,由 Kit 启动有界本地进程。不得复制通用 runner、walker、native addon、Schema、Registry、Oracle、cache、状态机或 receipt 链。受控 fixture 协议是 Foundation 自有的隔离证据,不是 Qoder、WorkBuddy 或 Kimi 的厂商 grammar,也不是真实宿主资格。Harness record 模式适用于稳定隔离树;best-effort 边界不承诺事务快照、同 UID 恶意并发或 ABA 安全。
|
|
34
|
+
|
|
35
|
+
Foundation 本身不发起网络请求,但绑定的 executable 仍可能联网。Foundation 不提供 sandbox 或 egress 阻断,调用方与运行环境负责隔离。Qoder、WorkBuddy 与 Kimi 仍为 `manual/candidate`,受控 fixture 不授予真实宿主资格。
|
|
36
|
+
|
|
31
37
|
| 命令 | 用途 | 副作用 |
|
|
32
38
|
| --- | --- | --- |
|
|
33
39
|
| `scaffold` | 在空目录生成 Skill Family 项目骨架 | 只向空目标目录写入骨架文件(原子写、路径收容);非空或冲突目标被拒绝且不被触碰 |
|
|
34
|
-
| `adopt-plan` | 严格只读地规划存量仓采用 |
|
|
40
|
+
| `adopt-plan` | 严格只读地规划存量仓采用 | 无——不写任何文件(含临时文件);默认可能启动一条冻结参数的只读 Git status 探测;`--no-git-spawn` 可关闭;不运行 Git 写命令;计划输出到 stdout |
|
|
35
41
|
| `projection` | 投影受管生成物 | 只写 manifest 授权且被目标声明为受管的路径;未授权、手写与越界路径一律拒绝(拒绝时零写入) |
|
|
36
|
-
| `check` | 契约/漂移/闭包/版本/文档事实/Git 前置状态诊断 |
|
|
42
|
+
| `check` | 契约/漂移/闭包/版本/文档事实/Git 前置状态诊断 | 普通诊断只读且不写文件;默认可能启动一条冻结参数的只读 Git status 探测;`--no-git-spawn` 可关闭;`check relock` 是显式受控写事务;`check qualification` 预检通过后可能启动绑定的 executable。Foundation 自身不发起网络请求,但该进程可能联网。 |
|
|
37
43
|
|
|
38
44
|
## 解决的问题
|
|
39
45
|
|
|
@@ -45,7 +51,7 @@ Kit 是「工程阶段」层,依赖 Harness 与 Contracts。它只做四件事
|
|
|
45
51
|
|
|
46
52
|
## 安装和最小示例
|
|
47
53
|
|
|
48
|
-
0.
|
|
54
|
+
0.16.0 是本地候选版本。候选验证先把三个包分别打入同一个临时目录,再安装这三个精确 tarball:
|
|
49
55
|
|
|
50
56
|
```sh
|
|
51
57
|
pack_dir="$(mktemp -d)"
|
|
@@ -53,21 +59,21 @@ pack_dir="$(mktemp -d)"
|
|
|
53
59
|
(cd packages/skill-family-harness-node && pnpm pack --pack-destination "$pack_dir")
|
|
54
60
|
(cd packages/skill-family-engineering-kit && pnpm pack --pack-destination "$pack_dir")
|
|
55
61
|
mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
|
|
56
|
-
(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.
|
|
62
|
+
(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.16.0.tgz" "$pack_dir/skill-family-harness-node-0.16.0.tgz" "$pack_dir/skill-family-engineering-kit-0.16.0.tgz")
|
|
57
63
|
```
|
|
58
64
|
|
|
59
65
|
发布后再使用 registry 坐标:
|
|
60
66
|
|
|
61
67
|
```sh
|
|
62
|
-
npm install --save-dev skill-family-engineering-kit@0.
|
|
63
|
-
npm exec --package=skill-family-engineering-kit@0.
|
|
64
|
-
npm exec --package=skill-family-engineering-kit@0.
|
|
65
|
-
npm exec --package=skill-family-engineering-kit@0.
|
|
66
|
-
npm exec --package=skill-family-engineering-kit@0.
|
|
67
|
-
npm exec --package=skill-family-engineering-kit@0.
|
|
68
|
+
npm install --save-dev skill-family-engineering-kit@0.16.0
|
|
69
|
+
npm exec --package=skill-family-engineering-kit@0.16.0 -- skill-family-kit --help
|
|
70
|
+
npm exec --package=skill-family-engineering-kit@0.16.0 -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
|
|
71
|
+
npm exec --package=skill-family-engineering-kit@0.16.0 -- skill-family-kit adopt-plan --root <repo> --list-capabilities --all --scope all --locale zh-CN --uses ./uses.json
|
|
72
|
+
npm exec --package=skill-family-engineering-kit@0.16.0 -- skill-family-kit projection --root <repo>
|
|
73
|
+
npm exec --package=skill-family-engineering-kit@0.16.0 -- skill-family-kit check --root <repo>
|
|
68
74
|
```
|
|
69
75
|
|
|
70
|
-
以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断;零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.
|
|
76
|
+
以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断;零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.16.0 -- skill-family-kit --help`。
|
|
71
77
|
|
|
72
78
|
### 三条采用旅程
|
|
73
79
|
|
|
@@ -151,7 +157,7 @@ npm exec -- skill-family-kit scaffold host-build --root <workspace> --host <id>
|
|
|
151
157
|
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>
|
|
152
158
|
```
|
|
153
159
|
|
|
154
|
-
Profile 必须显式提供,Kit 不默认绑定具体宿主。规范宿主 ID 只能解析已登记有限 Profile 中声明的 alias。probe 默认不启动进程;只有同时给出 `--allow-host-spawn --host-executable <绝对路径>` 才执行冻结版本向量。本地 install/update 通过显式授权引用和既有受收容发布原语执行;uninstall 因没有安全的绑定删除原语而返回 `manual-recovery-required`,不删除文件。Claude/Codex 使用受信版本 driver;Kimi Code、WorkBuddy、CodeBuddy 和 DeepSeek Harness 只提供独立手动事实。Qoder
|
|
160
|
+
Profile 必须显式提供,Kit 不默认绑定具体宿主。规范宿主 ID 只能解析已登记有限 Profile 中声明的 alias。probe 默认不启动进程;只有同时给出 `--allow-host-spawn --host-executable <绝对路径>` 才执行冻结版本向量。本地 install/update 通过显式授权引用和既有受收容发布原语执行;uninstall 因没有安全的绑定删除原语而返回 `manual-recovery-required`,不删除文件。Claude/Codex 使用受信版本 driver;Kimi Code、WorkBuddy、CodeBuddy 和 DeepSeek Harness 只提供独立手动事实。Qoder 仍为 `manual`;独立的原生插件候选不授予通用 host build、plan、apply、install/update/uninstall、rollback 或真实宿主资格。adapter source 只接受已声明的文本闭包,不支持二进制投影;精确宿主支持矩阵见 [宿主能力矩阵](../../docs/reference/host-capability-matrix.md) 与已登记 Profile。
|
|
155
161
|
|
|
156
162
|
### 候选真实宿主验证 API
|
|
157
163
|
|
|
@@ -166,14 +172,14 @@ Profile 必须显式提供,Kit 不默认绑定具体宿主。规范宿主 ID
|
|
|
166
172
|
- 新项目骨架:`scaffold`(不覆盖非空存量仓)。
|
|
167
173
|
- 存量采用盘点:`adopt-plan`(严格只读,不写文件、不自动迁移)。
|
|
168
174
|
- 受管投影:`projection` + Profile(不覆盖 handwritten 文件)。
|
|
169
|
-
-
|
|
175
|
+
- 工程诊断:普通 `check` 只读;`check relock` 执行显式受控写事务,`check qualification` 预检通过后可能启动绑定的 executable。
|
|
170
176
|
|
|
171
177
|
## 边界机制
|
|
172
178
|
|
|
173
179
|
- `scaffold` 的目标必须是**空目录**(任何条目含点文件都算非空),或其父目录已存在的不存在路径(只创建最后一级)。全部写入经 harness 的原子收容写(`writeFileAtomic`),失败不留半成品,路径不能越出目标根。
|
|
174
|
-
- `adopt-plan` 结构性只读:实现中不存在任何写调用,连临时文件都不产生;计划字节与 `scaffold` 同源(`describeSkeletonFiles`
|
|
180
|
+
- `adopt-plan` 结构性只读:实现中不存在任何写调用,连临时文件都不产生;计划字节与 `scaffold` 同源(`describeSkeletonFiles` 单一事实源),因此「计划即动作」。默认可能启动一条冻结参数的只读 Git status 探测;CLI 的 `--no-git-spawn`(或 API 的 `allowGitSpawn: false`)可关闭该探测。dirty 仓运行前后字节级零变化。
|
|
175
181
|
- `projection` 采用两阶段执行:先对每个条目做路径分类、收容预检、自投影检查、manifest 授权检查、手写保护与冲突守卫;任一条目违规则整体拒绝、零写入。覆盖既有文件必须声明精确的 `expect.sha256` 前置状态;内容相同的既有文件是幂等 no-op。写入失败时尽力还原已覆盖文件的前置字节。
|
|
176
|
-
- `check`
|
|
182
|
+
- 普通 `check` 只读且无写调用,也没有 `--fix/--apply/--repair` 模式(此类标志在入口处被拒绝)。默认可能启动一条冻结参数的只读 Git status 探测;CLI 的 `--no-git-spawn`(或 API 的 `allowGitSpawn: false`)可关闭该探测。`check relock` 执行显式受控写事务;`check qualification` 预检通过后可能启动绑定的 executable。Git 前置状态仅用文件系统事实加至多一次冻结参数矢量的只读 `git status --porcelain=2`(`--no-optional-locks` + `GIT_OPTIONAL_LOCKS=0`,不刷新索引)。
|
|
177
183
|
|
|
178
184
|
## 错误码与退出码
|
|
179
185
|
|
|
@@ -196,7 +202,9 @@ projection 只写同时满足两个条件的路径:manifest 列出,且目标
|
|
|
196
202
|
|
|
197
203
|
## 禁止项
|
|
198
204
|
|
|
199
|
-
本包不得执行 git init、commit、push、tag、stash
|
|
205
|
+
本包不得执行 git init、commit、push、tag、stash、分支切换、发布、删除、远端写入或发布状态复述;不实现第五个顶层命令;不做业务判断或模型调用。
|
|
206
|
+
|
|
207
|
+
Foundation 本身不发起网络请求,但绑定的 executable 仍可能联网。Foundation 不提供 sandbox 或 egress 阻断;隔离责任由调用方与运行环境承担。仓内受控 fixture 按设计不发起网络请求。
|
|
200
208
|
|
|
201
209
|
## 故障诊断
|
|
202
210
|
|
|
@@ -221,7 +229,7 @@ projection 只写同时满足两个条件的路径:manifest 列出,且目标
|
|
|
221
229
|
### Do not use when
|
|
222
230
|
|
|
223
231
|
- 需要自动修复(`check` 不修复)、自动迁移(`adopt-plan` 不写文件)。
|
|
224
|
-
-
|
|
232
|
+
- 需要通用或远端宿主生命周期、自动信任、删除式 uninstall,或想用受控 fixture 取得真实宿主资格。
|
|
225
233
|
- 需要稳定 Quickstart API,或希望 candidate 辅助函数绕过 `runProjection` 授权。
|
|
226
234
|
|
|
227
235
|
### Capability selection
|
|
@@ -252,7 +260,7 @@ projection 只写同时满足两个条件的路径:manifest 列出,且目标
|
|
|
252
260
|
### Side effects
|
|
253
261
|
|
|
254
262
|
- scaffold/projection/host-build 在受收容目标写文件(原子 + 收容)。
|
|
255
|
-
- adopt-plan
|
|
263
|
+
- adopt-plan 与普通 check 严格只读且不写文件;默认可能启动一条冻结参数的只读 Git status 探测,可由 `--no-git-spawn`(或 API 的 `allowGitSpawn: false`)关闭。check relock 执行显式受控写事务;check qualification 预检通过后可能启动绑定的 executable。Git 是诊断检查使用的只读白名单探测。
|
|
256
264
|
- `FORBIDDEN_SIDE_EFFECTS` 含 git-init/commit/push/tag、publish、remote-write。
|
|
257
265
|
|
|
258
266
|
### Failure semantics
|
|
@@ -280,6 +288,8 @@ projection 只写同时满足两个条件的路径:manifest 列出,且目标
|
|
|
280
288
|
|
|
281
289
|
## 完整插件候选能力
|
|
282
290
|
|
|
283
|
-
|
|
291
|
+
候选 `runPluginVerification({ request, bindings, hostsRoot })` 保留两个旧目标,并增加只允许本地来源的 `native-lifecycle` 分支。Qoder 与 WorkBuddy 使用不同的生产 driver,由 driver 自己拥有 argv 计划,共用恰好十二个语义阶段;每次 spawn 前重新观察可执行文件身份。Contracts 只拥有结构,宿主计划与 Oracle 归 Kit。受控 executable 协议只证明隔离接线,不是厂商 grammar。真实宿主与来源组合仍需独立资格证据。
|
|
292
|
+
|
|
293
|
+
独立入口 `runSkillFamilyDirectoryVerification({ request, bindings })` 固定 Kimi 生产 argv 与窄环境,并拒绝调用方 observation。原始 parser 通过生产进程路径验证,但受控 fixture 事件不会被提升为 `observed`;缺少官方 typed mapping 时,公共结果保持 `indeterminate` 和 manual candidate。
|
|
284
294
|
|
|
285
|
-
0.
|
|
295
|
+
0.16.0 为本地源码候选,尚未发布。消费本地已验证的三包 tarball;版本标记、单元测试或安装成功都不等于契约接入完成、迁移完成或真实宿主资格。
|