skill-family-engineering-kit 0.2.1 → 0.4.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.
Files changed (41) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/CHANGELOG.zh-CN.md +43 -0
  3. package/README.md +14 -12
  4. package/README.zh-CN.md +14 -12
  5. package/candidate/adoption-cli.mjs +67 -0
  6. package/candidate/adoption-mechanisms.mjs +69 -0
  7. package/candidate/index.mjs +3 -0
  8. package/candidate/profile-bundle.mjs +1503 -172
  9. package/candidate/projection-bundle-cli.mjs +74 -14
  10. package/candidate/skill-naming-cli.mjs +59 -0
  11. package/candidate/skill-naming-policy.json +46 -0
  12. package/candidate/skill-naming.mjs +280 -0
  13. package/docs/agents/capability-catalog.en.json +1746 -1559
  14. package/docs/agents/capability-catalog.json +1029 -929
  15. package/docs/agents/capability-catalog.zh-CN.json +1746 -1559
  16. package/docs/architecture/index.html +10 -3
  17. package/docs/en/architecture/index.html +12 -3
  18. package/docs/en/migration/index.html +4 -3
  19. package/docs/en/recipes/adopt-existing-repository/index.html +2 -1
  20. package/docs/en/recipes/domain-schema-validation/index.html +3 -1
  21. package/docs/en/recipes/index.html +2 -1
  22. package/docs/en/reference/api/index.html +24 -0
  23. package/docs/en/reference/compatibility/index.html +51 -5
  24. package/docs/migration/index.html +4 -3
  25. package/docs/public/status/index.html +3 -3
  26. package/docs/recipes/adopt-existing-repository/index.html +2 -1
  27. package/docs/recipes/domain-schema-validation/index.html +3 -1
  28. package/docs/recipes/index.html +2 -1
  29. package/docs/reference/api/contracts/index.html +26 -0
  30. package/docs/reference/api/engineering-kit/index.html +26 -0
  31. package/docs/reference/api/harness/index.html +423 -2
  32. package/docs/reference/api/index.html +25 -1
  33. package/docs/reference/compatibility/index.html +51 -5
  34. package/docs/search/search_index.json +1 -1
  35. package/package.json +5 -4
  36. package/release-notes/0.3.0.yaml +25 -0
  37. package/release-notes/0.4.0.yaml +23 -0
  38. package/src/adopt-plan.mjs +26 -1
  39. package/src/index.mjs +5 -2
  40. package/src/migration.mjs +121 -1
  41. package/src/projection.mjs +1152 -266
package/docs/agents/capability-catalog.en.json CHANGED
@@ -1,1561 +1,1748 @@
1
1
  {
2
- "schemaVersion": 1,
3
- "kind": "skill-family.documentation-capability-catalog",
4
- "bundle": "locale-overlay",
5
- "locale": "en",
6
- "generatedFrom": [
7
- "package.json",
8
- "packages/skill-family-contracts/package.json",
9
- "packages/skill-family-harness-node/package.json",
10
- "packages/skill-family-engineering-kit/package.json",
11
- "packages/skill-family-contracts/src/index.mjs",
12
- "packages/skill-family-harness-node/src/index.mjs",
13
- "packages/skill-family-engineering-kit/src/index.mjs",
14
- "packages/skill-family-engineering-kit/src/cli.mjs",
15
- "packages/skill-family-contracts/src/registry.json",
16
- "profiles/README.md",
17
- "docs/architecture.md",
18
- "docs/status/current.md"
19
- ],
20
- "capabilities": [
21
- {
22
- "id": "foundation.contracts.object-validation",
23
- "intent": "Compile and validate the 18 registered top-level Foundation contract object documents under both the draft-07 and 2020-12 dialects using Ajv 8.20.0 (exact pin).",
24
- "useWhen": [
25
- "Need to validate registered contract objects such as project-manifest, profile-descriptor, report-model",
26
- "Need to detect the document dialect and select the strict or tolerant validation policy"
27
- ],
28
- "doNotUseWhen": [
29
- "Need to validate consumer-owned business Schemas (which consumers should own themselves; Foundation does not replace them)",
30
- "Need to mix domain semantic validation into the generic contract"
31
- ],
32
- "prerequisites": [
33
- "The document to validate carries the $id of a registered contract object",
34
- "Node >= 22.22.2"
35
- ],
36
- "inputs": [
37
- "Contract document object (any JSON value)",
38
- "Target contract object $id or schema",
39
- "Validation policy (strict | tolerant, default strict)"
40
- ],
41
- "outputs": [
42
- "Validation passes: returns {valid:true} (no errorCode field)",
43
- "Validation fails: returns {valid:false, errorCode, errors}, without throwing",
44
- "The first compilation result is written to the Ajv compile cache and reused for subsequent identical (schemaId,dialect,policy)"
45
- ],
46
- "sideEffects": [
47
- "No filesystem, Git, network, or process side effects (pure function + in-memory cache)"
48
- ],
49
- "failureSemantics": [
50
- "SFC1002: unknown contract object $id not registered (returns valid:false, without throwing)",
51
- "SFC1001: document does not conform to a registered Schema (returns valid:false, errors include Ajv keyword details)",
52
- "Callers judge success via the valid field of the return value, not via try/catch — validateDocument never throws",
53
- "compileSchema throws ContractsError (SFC1012 SCHEMA_COMPILE_FAILED) for an uncompilable schema; detectDialect throws ContractsError (SFC1006) for an unknown dialect"
54
- ],
55
- "invariants": [
56
- "The same (object, dialect, policy) reuses the compile cache; repeated validation does not recompile",
57
- "Only Ajv 8.20.0 is accepted; no other validator is wired in"
58
- ],
59
- "ownedByCaller": [
60
- "Semantic interpretation of concrete business fields",
61
- "Domain-level validation rules"
62
- ],
63
- "routeElsewhere": [
64
- "Consumer business Schema validation: stays with the caller",
65
- "Remote publish writes: route to release-skill"
66
- ]
67
- },
68
- {
69
- "id": "foundation.contracts.registry-protocol",
70
- "intent": "Register and look up contract object Schema $id and protocol names, serving as the single authority for protocol names and Schemas.",
71
- "useWhen": [
72
- "Need to find a registered Schema by object name or $id",
73
- "Need to find a kernel protocol definition by protocol name"
74
- ],
75
- "doNotUseWhen": [
76
- "Need to add a fourth class of registered object (the 18-object set must not be extended without an ADR)"
77
- ],
78
- "prerequisites": [
79
- "registry.json is shipped with the package",
80
- "Node >= 22.22.2"
81
- ],
82
- "inputs": [
83
- "Object name, Schema $id, or protocol name"
84
- ],
85
- "outputs": [
86
- "Registered Schema metadata or protocol definition",
87
- "Returns undefined or throws on a cache miss"
88
- ],
89
- "sideEffects": [
90
- "No filesystem, Git, network, or process side effects (pure function)"
91
- ],
92
- "failureSemantics": [
93
- "SFC1003: duplicate $id registration",
94
- "SFC1004: duplicate protocol registration"
95
- ],
96
- "invariants": [
97
- "registry.json's schemaVersion=1 and contractsVersion=1.4.0 are the single authority",
98
- "The set of 18 top-level objects is fixed; additions require an ADR"
99
- ],
100
- "ownedByCaller": [
101
- "Interpretation of an object's business meaning"
102
- ],
103
- "routeElsewhere": [
104
- "Publish status: route to release-skill"
105
- ]
106
- },
107
- {
108
- "id": "foundation.contracts.kernel-protocol",
109
- "intent": "Load and validate the skill-family.kernel.operation protocol (stable, Contracts 1.4.0), defining the operation request/result structure.",
110
- "useWhen": [
111
- "Need to parse or validate operation-request / operation-result structures",
112
- "Need to look up a parameter contract by operation name"
113
- ],
114
- "doNotUseWhen": [
115
- "Need to define business operation semantics (semantics are owned by the consumer)"
116
- ],
117
- "prerequisites": [
118
- "kernel-protocol.json is shipped with the package"
119
- ],
120
- "inputs": [
121
- "Protocol name, operation name, operation parameters"
122
- ],
123
- "outputs": [
124
- "Protocol definition or operation parameter validation result"
125
- ],
126
- "sideEffects": [
127
- "No side effects (pure function)"
128
- ],
129
- "failureSemantics": [
130
- "SFC2002: unknown operation",
131
- "SFC2003: parameters violate the protocol"
132
- ],
133
- "invariants": [
134
- "The kernel protocol version is bound to the Contracts version"
135
- ],
136
- "ownedByCaller": [
137
- "Concrete business semantics of the operation"
138
- ],
139
- "routeElsewhere": [
140
- "Business state machine / retries / terminal state: route to loop-agent"
141
- ]
142
- },
143
- {
144
- "id": "foundation.contracts.mandatory-checks",
145
- "intent": "Run mechanical checks for the 9 classes of mandatory rule (budget cap 20, absolute cap 30), compiling all Schemas in the registry uniformly.",
146
- "useWhen": [
147
- "Need to confirm the contract set satisfies the mandatory mechanical rules",
148
- "Need to collect unresolved references (unresolved refs)"
149
- ],
150
- "doNotUseWhen": [
151
- "Need semantic-level review (belongs to external independent review; a second gate is not maintained in the repo)"
152
- ],
153
- "prerequisites": [
154
- "registry and rules are loaded"
155
- ],
156
- "inputs": [
157
- "The contract set to check, or a synthetic registry/fixtures"
158
- ],
159
- "outputs": [
160
- "Check conclusion and list of unresolved references"
161
- ],
162
- "sideEffects": [
163
- "No side effects (pure function)"
164
- ],
165
- "failureSemantics": [
166
- "SFC1002/1003/1004/1005/1006/1008/1009/1010: corresponding rule violated"
167
- ],
168
- "invariants": [
169
- "CHECK_TYPES is a closed set of 9 classes",
170
- "RULE_BUDGET bounds firstVersionMax and absoluteMax"
171
- ],
172
- "ownedByCaller": [
173
- "Interpretation of the business rationale behind the rules"
174
- ],
175
- "routeElsewhere": [
176
- "Semantic accept/reject: external independent review"
177
- ]
178
- },
179
- {
180
- "id": "foundation.contracts.fixture-verification",
181
- "intent": "Enumerate and validate public/fictional fixtures, confirming they match the expect declaration of the corresponding contract object.",
182
- "useWhen": [
183
- "Need to prove a contract object is covered by a fixture",
184
- "Need to run positive/negative/dialect-boundary class fixtures"
185
- ],
186
- "doNotUseWhen": [
187
- "Need to treat a fixture as a business oracle (fixtures only prove structure, not semantics)"
188
- ],
189
- "prerequisites": [
190
- "The fixtures directory holds public or entirely fictional data"
191
- ],
192
- "inputs": [
193
- "A fixture class or a single fixture identifier"
194
- ],
195
- "outputs": [
196
- "Per-fixture validation results"
197
- ],
198
- "sideEffects": [
199
- "No side effects (read-only fixtures)"
200
- ],
201
- "failureSemantics": [
202
- "SFC1010: a negative fixture failed to produce the expected failure"
203
- ],
204
- "invariants": [
205
- "Fixtures and the auditor's expected results are not shared"
206
- ],
207
- "ownedByCaller": [
208
- "The business intent behind a fixture"
209
- ],
210
- "routeElsewhere": [
211
- "Domain audit semantics: route to an independent audit consumer"
212
- ]
213
- },
214
- {
215
- "id": "foundation.contracts.error-codes",
216
- "intent": "Define and register a stable error-code system, provide validation and assertion entry points, and guarantee error codes do not drift.",
217
- "useWhen": [
218
- "Need to throw or classify a ContractsError carrying a stable error code",
219
- "Need to assert that an error code is registered"
220
- ],
221
- "doNotUseWhen": [
222
- "Need to define business error semantics outside the Foundation scope"
223
- ],
224
- "prerequisites": [
225
- "error-codes.json is shipped with the package"
226
- ],
227
- "inputs": [
228
- "Error-code string, error context"
229
- ],
230
- "outputs": [
231
- "Error object carrying a stable error code and details"
232
- ],
233
- "sideEffects": [
234
- "No side effects (pure function)"
235
- ],
236
- "failureSemantics": [
237
- "Assertion fails for an unregistered error code",
238
- "Frozen-object immutability violation"
239
- ],
240
- "invariants": [
241
- "The error-code registry is frozen and cannot be added to or removed from at runtime"
242
- ],
243
- "ownedByCaller": [
244
- "Business attribution of an error code"
245
- ],
246
- "routeElsewhere": [
247
- "Semantic review conclusion: external independent review"
248
- ]
249
- },
250
- {
251
- "id": "foundation.contracts.audit-surface",
252
- "intent": "Serialize the contract surface deterministically (canonical JSON + sha256 digest) for read-only projection by audit consumers.",
253
- "useWhen": [
254
- "Need to generate a reproducible digest for the contract surface",
255
- "Need to describe the audit surface structure"
256
- ],
257
- "doNotUseWhen": [
258
- "Need to audit domain semantics (semantics and final accept/reject belong to external review)"
259
- ],
260
- "prerequisites": [
261
- "AUDIT_SURFACE_VERSION=1、AUDIT_DIGEST_ALGORITHMS=[sha256]"
262
- ],
263
- "inputs": [
264
- "Any JSON document"
265
- ],
266
- "outputs": [
267
- "canonical string and sha256 digest"
268
- ],
269
- "sideEffects": [
270
- "No side effects (pure function)"
271
- ],
272
- "failureSemantics": [
273
- "Non-JSON values, unknown algorithms, and freeze violations all throw"
274
- ],
275
- "invariants": [
276
- "The digest algorithm is sha256 only; the version number is fixed"
277
- ],
278
- "ownedByCaller": [
279
- "Audit semantic conclusion"
280
- ],
281
- "routeElsewhere": [
282
- "Domain audit semantics: route to an independent audit consumer"
283
- ]
284
- },
285
- {
286
- "id": "foundation.harness.contract-validation",
287
- "intent": "Resolve the contract context in the Node runtime and reuse the Contracts validator to validate contract documents and cache validator instances.",
288
- "useWhen": [
289
- "Need to validate Foundation contract documents inside Node",
290
- "Need to reuse a validator cache keyed by schema"
291
- ],
292
- "doNotUseWhen": [
293
- "Need to validate in a non-Node runtime (only a Node implementation exists currently)"
294
- ],
295
- "prerequisites": [
296
- "skill-family-contracts is installed"
297
- ],
298
- "inputs": [
299
- "Schema context, contract document"
300
- ],
301
- "outputs": [
302
- "Validation result, reusing the cached Ajv instance"
303
- ],
304
- "sideEffects": [
305
- "In-process in-memory validator cache (no file/Git/network)"
306
- ],
307
- "failureSemantics": [
308
- "Counterexample matrices such as date-time trigger an SFC validation failure"
309
- ],
310
- "invariants": [
311
- "The validator is cached keyed by (schema); the size is queryable"
312
- ],
313
- "ownedByCaller": [
314
- "Semantics of contract business fields"
315
- ],
316
- "routeElsewhere": [
317
- "Contract object definition: route to Contracts"
318
- ]
319
- },
320
- {
321
- "id": "foundation.harness.path-containment",
322
- "intent": "Classify external path inputs and resolve them inside the containment root, rejecting path-traversal, symlink-escape, and realpath-escape.",
323
- "useWhen": [
324
- "Need to confine a user/caller-supplied path within a root directory",
325
- "Need to safely read a contained file"
326
- ],
327
- "doNotUseWhen": [
328
- "Need to put the business rules for file selection into Foundation (business rules are owned by the caller)"
329
- ],
330
- "prerequisites": [
331
- "The caller supplies an explicit root directory (containment boundary)"
332
- ],
333
- "inputs": [
334
- "Root directory, relative/absolute path to resolve"
335
- ],
336
- "outputs": [
337
- "Contained absolute path or the read file content"
338
- ],
339
- "sideEffects": [
340
- "Read-only filesystem access (read/resolve)"
341
- ],
342
- "failureSemantics": [
343
- "SFC2004: path-traversal / symlink-escape / realpath-escape, carrying a stable kind",
344
- "Windows drive-letter/UNC escapes are rejected as well"
345
- ],
346
- "invariants": [
347
- "All resolution results must fall within the root directory"
348
- ],
349
- "ownedByCaller": [
350
- "Which paths are business-permitted selection rules"
351
- ],
352
- "routeElsewhere": [
353
- "Business file-selection semantics: stay with the caller"
354
- ]
355
- },
356
- {
357
- "id": "foundation.harness.atomic-write",
358
- "intent": "Atomically write a regular file within an already-contained path via temp file + fsync + rename, rolling back on failure without leaving residue.",
359
- "useWhen": [
360
- "Need to update a regular text/binary file within a contained directory",
361
- "Need to guarantee the write is either fully visible or invisible"
362
- ],
363
- "doNotUseWhen": [
364
- "Need to write to a non-contained path (out-of-bounds is rejected by path-containment)"
365
- ],
366
- "prerequisites": [
367
- "The target path is verified inside the root directory by path-containment"
368
- ],
369
- "inputs": [
370
- "Contained target path, file content (string or Buffer)"
371
- ],
372
- "outputs": [
373
- "The written file, byte-identical to the input"
374
- ],
375
- "sideEffects": [
376
- "Create a temp file inside the root directory and finally rename to overwrite the target"
377
- ],
378
- "failureSemantics": [
379
- "Out-of-bounds path or illegal data type throws and rolls back the temp file",
380
- "Binary content is preserved byte-for-byte"
381
- ],
382
- "invariants": [
383
- "fsync before rename, guaranteeing crash consistency"
384
- ],
385
- "ownedByCaller": [
386
- "Business correctness of the written content"
387
- ],
388
- "routeElsewhere": [
389
- "Content-selection business rules: stay with the caller"
390
- ]
391
- },
392
- {
393
- "id": "foundation.harness.temporary-workspace",
394
- "intent": "Create and manage a temporary working directory, providing a safe lifecycle via a with syntax that cleans up on exit.",
395
- "useWhen": [
396
- "Need to build intermediate artifacts inside an isolated directory",
397
- "Need to guarantee the temp directory is reclaimed on exceptions"
398
- ],
399
- "doNotUseWhen": [
400
- "Need to persist artifacts (they should be explicitly materialized to a contained path)"
401
- ],
402
- "prerequisites": [
403
- "The host provides a writable temp directory (e.g. os.tmpdir)"
404
- ],
405
- "inputs": [
406
- "Optional prefix/label"
407
- ],
408
- "outputs": [
409
- "Temporary working directory handle"
410
- ],
411
- "sideEffects": [
412
- "Create a subdirectory in the system temp directory, deleted on exit"
413
- ],
414
- "failureSemantics": [
415
- "Creation failure rejects; the temp directory is still cleaned up when the with callback throws"
416
- ],
417
- "invariants": [
418
- "The temp directory path does not escape the host temp root"
419
- ],
420
- "ownedByCaller": [
421
- "Final destination of the temp artifacts"
422
- ],
423
- "routeElsewhere": [
424
- "Persistent state: route to state-store"
425
- ]
426
- },
427
- {
428
- "id": "foundation.harness.resource-closure",
429
- "intent": "Compute a deterministic, deduplicated, ordered resource closure with a sha256 digest, for adapter text closure and build manifests.",
430
- "useWhen": [
431
- "Need to normalize a set of resources into a reproducible closure",
432
- "Need to generate a digest for a build manifest"
433
- ],
434
- "doNotUseWhen": [
435
- "Need to include binary resources (only text closures are supported currently)"
436
- ],
437
- "prerequisites": [
438
- "Resources are serializable text entries"
439
- ],
440
- "inputs": [
441
- "Resource list (path + content)"
442
- ],
443
- "outputs": [
444
- "Deterministic closure object and sha256 digest"
445
- ],
446
- "sideEffects": [
447
- "No side effects (pure function)"
448
- ],
449
- "failureSemantics": [
450
- "Illegal/duplicate resource declarations throw or reject"
451
- ],
452
- "invariants": [
453
- "Deduplication and ordering are fixed; identical input always yields the same digest"
454
- ],
455
- "ownedByCaller": [
456
- "Business meaning of resources"
457
- ],
458
- "routeElsewhere": [
459
- "Binary projection: explicitly unsupported"
460
- ]
461
- },
462
- {
463
- "id": "foundation.harness.request-processing",
464
- "intent": "Parse the operation-request and drive the operation-result pipeline, producing terminal states REJECTED / FAILED / SUCCESS.",
465
- "useWhen": [
466
- "Need to normalize an inbound request into a unified operation-request structure",
467
- "Need to deterministically produce an operation result"
468
- ],
469
- "doNotUseWhen": [
470
- "Need model calls or business orchestration (neither is in the Foundation scope)"
471
- ],
472
- "prerequisites": [
473
- "The request conforms to the kernel protocol structure"
474
- ],
475
- "inputs": [
476
- "Raw request payload"
477
- ],
478
- "outputs": [
479
- "Normalized operation-request and terminal operation-result"
480
- ],
481
- "sideEffects": [
482
- "No side effects (pure-function pipeline)"
483
- ],
484
- "failureSemantics": [
485
- "Parse failure enters the REJECTED/FAILED terminal state carrying a stable error code"
486
- ],
487
- "invariants": [
488
- "The terminal-state set is fixed to REJECTED/FAILED/SUCCESS"
489
- ],
490
- "ownedByCaller": [
491
- "Concrete business semantics of the operation"
492
- ],
493
- "routeElsewhere": [
494
- "Business state machine / retries: route to loop-agent"
495
- ]
496
- },
497
- {
498
- "id": "foundation.harness.report",
499
- "intent": "Validate the report-model, render Markdown, bind digests, and run tiered checks deterministically; the human report is derived from machine results rather than freely authored.",
500
- "useWhen": [
501
- "Need to render machine results into a human-readable report",
502
- "Need to bind the model/result/report triple-digest to prevent tampering"
503
- ],
504
- "doNotUseWhen": [
505
- "Need to freely author a report from open business outputs (forbidden)"
506
- ],
507
- "prerequisites": [
508
- "REPORT_RENDERER_NAME / VERSION come from their respective packages (currently 0.2.1)",
509
- "SUPPORTED_REPORT_LOCALES = [zh-CN, en-US]"
510
- ],
511
- "inputs": [
512
- "report-model, render options (locale/audience/style)"
513
- ],
514
- "outputs": [
515
- "Markdown text, binding object, tiered-check findings"
516
- ],
517
- "sideEffects": [
518
- "No file/Git/network side effects (pure function)"
519
- ],
520
- "failureSemantics": [
521
- "SFC3001/3002/3003: model validation/binding/check hard failure"
522
- ],
523
- "invariants": [
524
- "Markdown is escaped deterministically; the dual outputs are written as a pair, and path aliases and input overwrites are rejected"
525
- ],
526
- "ownedByCaller": [
527
- "Interpretation of the report's business conclusion"
528
- ],
529
- "routeElsewhere": [
530
- "Report generation orchestration: Kit report sub-action"
531
- ]
532
- },
533
- {
534
- "id": "foundation.harness.host-adapter",
535
- "intent": "Implement the generic mechanism layer for host integration: normalize adapter source, compute the build closure, validate the build manifest, materialize the build, probe the version vector (spawn disabled by default).",
536
- "useWhen": [
537
- "Need to turn a host adapter source into a reproducible text closure",
538
- "Need to materialize build artifacts at a contained location",
539
- "Need to probe the host version vector (without auto-executing the host binary)"
540
- ],
541
- "doNotUseWhen": [
542
- "Need host apply/install/update/uninstall (explicitly unsupported)",
543
- "Need a binary adapter source (only text closures are supported)"
544
- ],
545
- "prerequisites": [
546
- "The adapter source is a declared text closure"
547
- ],
548
- "inputs": [
549
- "adapter source, target path"
550
- ],
551
- "outputs": [
552
- "Build closure, validated manifest, materialized artifacts"
553
- ],
554
- "sideEffects": [
555
- "Create a sibling staging area at the contained target and a single rename",
556
- "Probe does not spawn by default and does not use PATH"
557
- ],
558
- "failureSemantics": [
559
- "Mismatched manifest digest, existing target, or untrusted executable all throw"
560
- ],
561
- "invariants": [
562
- "materialize is an atomic sibling + rename"
563
- ],
564
- "ownedByCaller": [
565
- "Concrete host business semantics"
566
- ],
567
- "routeElsewhere": [
568
- "host apply: explicitly unsupported",
569
- "Host diff declaration: route to Profile + Kit host sub-action"
570
- ]
571
- },
572
- {
573
- "id": "foundation.harness.state-store",
574
- "intent": "Provide a persistent state foundation: append-only events, hash chain, derived snapshots, plus lock checks and explicit recovery; event meaning and reducer transitions are owned by the caller.",
575
- "useWhen": [
576
- "Need to persist an event log and guarantee order and integrity",
577
- "Need to rebuild or validate derived snapshots",
578
- "Need to check or recover a cooperative single-writer lock"
579
- ],
580
- "doNotUseWhen": [
581
- "Need to define a workflow state machine in Foundation (forbidden)",
582
- "Need to defend against same-privilege malicious processes (fencing does not promise this scenario)"
583
- ],
584
- "prerequisites": [
585
- "STATE_GENESIS_DIGEST as the chain origin"
586
- ],
587
- "inputs": [
588
- "Event payload, snapshot, lock token"
589
- ],
590
- "outputs": [
591
- "Events, hash-chain validation result, snapshot"
592
- ],
593
- "sideEffects": [
594
- "Read/write the event log and snapshot files at the contained path",
595
- "Write a lock file for the cooperative single-writer"
596
- ],
597
- "failureSemantics": [
598
- "Broken hash chain, lock fencing conflict, or recovery failure throws"
599
- ],
600
- "invariants": [
601
- "The event log is the single authority; the snapshot is a derived cache",
602
- "The local cooperative single-writer uses fencing and explicit recovery"
603
- ],
604
- "ownedByCaller": [
605
- "Business meaning of events, reducer transitions, the confirmOwnerTerminated trust anchor"
606
- ],
607
- "routeElsewhere": [
608
- "Business state machine / terminal state: route to loop-agent"
609
- ]
610
- },
611
- {
612
- "id": "foundation.harness.errors",
613
- "intent": "Define the Harness mechanism error types and stable error classes, unifying error classification.",
614
- "useWhen": [
615
- "Need to throw a HarnessError carrying a stable kind"
616
- ],
617
- "doNotUseWhen": [
618
- "Need to define business error semantics"
619
- ],
620
- "prerequisites": [],
621
- "inputs": [
622
- "Error kind, context"
623
- ],
624
- "outputs": [
625
- "Error object carrying a stable kind"
626
- ],
627
- "sideEffects": [
628
- "No side effects (pure function)"
629
- ],
630
- "failureSemantics": [
631
- "Illegal kind invocation throws"
632
- ],
633
- "invariants": [
634
- "HARNESS_EXCLUSIONS explicitly excludes release-state / remote-network-access / business-semantics / workflow-orchestration / model-calls / git-writes"
635
- ],
636
- "ownedByCaller": [
637
- "Business attribution of the error"
638
- ],
639
- "routeElsewhere": [
640
- "Business semantics: stay with the caller"
641
- ]
642
- },
643
- {
644
- "id": "foundation.kit.scaffold",
645
- "intent": "Generate a precise set of hosted files in a new project skeleton (atomic + path containment), without overwriting a non-empty existing repo.",
646
- "useWhen": [
647
- "Need to generate a minimal verifiable skeleton for a new skill-family project",
648
- "The target directory is empty or contains only containable content"
649
- ],
650
- "doNotUseWhen": [
651
- "Need to overwrite an existing non-empty repo (use adopt-plan instead)"
652
- ],
653
- "prerequisites": [
654
- "The target is a writable empty directory",
655
- "Node >= 22.22.2"
656
- ],
657
- "inputs": [
658
- "Target root, skeleton options (id, etc.)"
659
- ],
660
- "outputs": [
661
- "The precise set of hosted skeleton files"
662
- ],
663
- "sideEffects": [
664
- "Create files at the contained target (atomic + contained)"
665
- ],
666
- "failureSemantics": [
667
- "Non-empty target or illegal kebab id throws"
668
- ],
669
- "invariants": [
670
- "Only write to empty targets, atomic + contained",
671
- "The skeleton set matches the scaffold-conformance fixture"
672
- ],
673
- "ownedByCaller": [
674
- "Business project content"
675
- ],
676
- "routeElsewhere": [
677
- "Existing-repo adoption: route to adopt-plan"
678
- ]
679
- },
680
- {
681
- "id": "foundation.kit.adopt-plan",
682
- "intent": "Perform a strict read-only inventory of an existing repo (classification, nested-repo discovery, migration list, completion judgment), writing no files and migrating nothing automatically.",
683
- "useWhen": [
684
- "Need to classify an existing repo as direct-adoption / compatibility-layer / keep-business / foundation-gap",
685
- "Need to generate a handoff draft or a completion judgment for migration"
686
- ],
687
- "doNotUseWhen": [
688
- "Need to auto-rewrite the existing repo (writing files and auto-migration are forbidden)"
689
- ],
690
- "prerequisites": [
691
- "The target repo exists and is read-only accessible"
692
- ],
693
- "inputs": [
694
- "Target root, migration-list path"
695
- ],
696
- "outputs": [
697
- "Adoption classification, completion judgment, handoff draft (output only, not written to disk)"
698
- ],
699
- "sideEffects": [
700
- "No file writes (strictly read-only)",
701
- "May trigger read-only git probes"
702
- ],
703
- "failureSemantics": [
704
- "Missing fields in an exception, or not having exited the old implementation, makes the completion judgment false"
705
- ],
706
- "invariants": [
707
- "No file writes, no auto-migration"
708
- ],
709
- "ownedByCaller": [
710
- "Migration decisions for existing business code"
711
- ],
712
- "routeElsewhere": [
713
- "Actual migration execution: the caller is responsible"
714
- ]
715
- },
716
- {
717
- "id": "foundation.kit.projection",
718
- "intent": "Mechanically project managed facts to a target (e.g. a public mirror) per the projection manifest; write only after all checks pass, with zero-write/rollback on any failure.",
719
- "useWhen": [
720
- "Need to project authoritative data to a public snapshot or release mirror",
721
- "Need to guarantee the projection matches the target"
722
- ],
723
- "doNotUseWhen": [
724
- "Need to overwrite handwritten files (forbidden)"
725
- ],
726
- "prerequisites": [
727
- "The projection manifest is registered"
728
- ],
729
- "inputs": [
730
- "Projection manifest, target root"
731
- ],
732
- "outputs": [
733
- "Projected files (only when all checks pass)"
734
- ],
735
- "sideEffects": [
736
- "Write projected files at the contained target",
737
- "Two-phase: write only after all checks pass, roll back on failure"
738
- ],
739
- "failureSemantics": [
740
- "Unauthorized, handwritten conflict, out-of-bounds, or content conflict all throw without residue"
741
- ],
742
- "invariants": [
743
- "Never overwrite handwritten files",
744
- "Zero write on any check failure"
745
- ],
746
- "ownedByCaller": [
747
- "Business meaning of the projected content"
748
- ],
749
- "routeElsewhere": [
750
- "Remote publish: route to release-skill"
751
- ]
752
- },
753
- {
754
- "id": "foundation.kit.check",
755
- "intent": "Diagnose only, do not fix: run the seven check classes contracts/drift/closure/version/docs/git/identity and output findings.",
756
- "useWhen": [
757
- "Need to surface engineering inconsistencies without auto-modifying",
758
- "Need to narrow the check scope via --only"
759
- ],
760
- "doNotUseWhen": [
761
- "Need auto-fix (forbidden; check writes no fixes)"
762
- ],
763
- "prerequisites": [],
764
- "inputs": [
765
- "--only values: contracts|drift|closure|version|docs|git|identity"
766
- ],
767
- "outputs": [
768
- "Findings list; exit code findings=1, mechanism=2"
769
- ],
770
- "sideEffects": [
771
- "No file writes (read-only diagnosis)"
772
- ],
773
- "failureSemantics": [
774
- "findings exit code 1; mechanism rejection exit code 2"
775
- ],
776
- "invariants": [
777
- "CHECK_CLASSES is a closed set of seven classes, not expanded"
778
- ],
779
- "ownedByCaller": [
780
- "Business disposition of each finding"
781
- ],
782
- "routeElsewhere": [
783
- "Auto-fix execution: the caller"
784
- ]
785
- },
786
- {
787
- "id": "foundation.kit.report",
788
- "intent": "Orchestrate the human report as a CLI sub-action: projection report rendering, check report tiering, writing to stdout by default.",
789
- "useWhen": [
790
- "Need to produce report text from an already-rendered model",
791
- "Need to run a tiered check on the report"
792
- ],
793
- "doNotUseWhen": [
794
- "Need to freely author a report from open business outputs (forbidden)"
795
- ],
796
- "prerequisites": [
797
- "A Harness report-model already exists"
798
- ],
799
- "inputs": [
800
- "report-model, --out/--binding options"
801
- ],
802
- "outputs": [
803
- "Markdown text; --out/--binding writes to disk"
804
- ],
805
- "sideEffects": [
806
- "Writes to stdout by default; explicit --out/--binding writes the contained file"
807
- ],
808
- "failureSemantics": [
809
- "Hard failure counts as a finding; illegal arguments reject"
810
- ],
811
- "invariants": [
812
- "The report is rendered deterministically from machine results"
813
- ],
814
- "ownedByCaller": [
815
- "Interpretation of the report conclusion"
816
- ],
817
- "routeElsewhere": [
818
- "Report mechanism: route to Harness report"
819
- ]
820
- },
821
- {
822
- "id": "foundation.kit.git-probe",
823
- "intent": "Probe Git status and facts via a read-only allowlist for diagnosis and adoption inventory, performing no Git write operations.",
824
- "useWhen": [
825
- "Need to read-only discover the current Git status (status/ls-files/check-ignore)",
826
- "Need to provide Git facts for adoption inventory"
827
- ],
828
- "doNotUseWhen": [
829
- "Need Git write operations (stage/commit/push/tag, explicitly forbidden)"
830
- ],
831
- "prerequisites": [],
832
- "inputs": [
833
- "Target root"
834
- ],
835
- "outputs": [
836
- "Git status and facts (read-only)"
837
- ],
838
- "sideEffects": [
839
- "Read-only calls to git status/ls-files/check-ignore (parameter vector frozen)"
840
- ],
841
- "failureSemantics": [
842
- "Parameter vectors not in the allowlist are rejected"
843
- ],
844
- "invariants": [
845
- "GIT_READ_ONLY_ALLOWLIST bounds the subcommands that may be called"
846
- ],
847
- "ownedByCaller": [
848
- "Authorization for Git write operations"
849
- ],
850
- "routeElsewhere": [
851
- "Git write operations: see the Git lifecycle guide; Foundation does not own them"
852
- ]
853
- },
854
- {
855
- "id": "foundation.kit.host",
856
- "intent": "Inject a concrete host Profile and trusted driver, providing describe/build/probe/plan; apply is stably rejected, and install/update/uninstall are unimplemented.",
857
- "useWhen": [
858
- "Need to describe a registered host (claude/codex)",
859
- "Need to probe, build, or plan host integration (read-only mechanism layer)"
860
- ],
861
- "doNotUseWhen": [
862
- "Need host apply/install/update/uninstall (explicitly unsupported)",
863
- "Need a full Qoder driver (that host is unsupported)"
864
- ],
865
- "prerequisites": [
866
- "The host Profile is registered in profiles/hosts",
867
- "Trusted drivers are only claude-version-v1 / codex-version-v1"
868
- ],
869
- "inputs": [
870
- "Host identifier, probe/plan options"
871
- ],
872
- "outputs": [
873
- "Host description, probe result, build artifacts, plan"
874
- ],
875
- "sideEffects": [
876
- "build/materialize writes artifacts at the contained target",
877
- "Probe does not spawn by default"
878
- ],
879
- "failureSemantics": [
880
- "An unsupported host (e.g. qoder) throws",
881
- "apply is stably rejected",
882
- "Missing probe facts throws"
883
- ],
884
- "invariants": [
885
- "HOST_DRIVER_IDS contains only the two trusted drivers",
886
- "apply is stably rejected"
887
- ],
888
- "ownedByCaller": [
889
- "Host business semantics"
890
- ],
891
- "routeElsewhere": [
892
- "host apply: explicitly unsupported",
893
- "Full Qoder driver: unsupported"
894
- ]
895
- },
896
- {
897
- "id": "foundation.kit.licensing",
898
- "intent": "Load and validate Profile licensing data, generating license/notice/identity-record content.",
899
- "useWhen": [
900
- "Need to generate LICENSE/NOTICE/identity records per Profile",
901
- "Need to validate the legitimacy of a licensing Profile"
902
- ],
903
- "doNotUseWhen": [
904
- "Need to make business licensing decisions (semantics owned by the caller)"
905
- ],
906
- "prerequisites": [
907
- "profiles/licensing/registry.json + schema.json exist"
908
- ],
909
- "inputs": [
910
- "Profile identifier, variant selection"
911
- ],
912
- "outputs": [
913
- "License/notice/identity-record text"
914
- ],
915
- "sideEffects": [
916
- "No side effects (pure-function generation)"
917
- ],
918
- "failureSemantics": [
919
- "Unspecified variant among many, or illegal Profile, throws"
920
- ],
921
- "invariants": [
922
- "By default the first registry variant is taken; multiple variants must be explicitly selected"
923
- ],
924
- "ownedByCaller": [
925
- "Licensing business semantics"
926
- ],
927
- "routeElsewhere": [
928
- "Licensing decisions: stay with the caller"
929
- ]
930
- },
931
- {
932
- "id": "foundation.kit.identity-check",
933
- "intent": "Load identity records and the manifest, check identity drift, and validate consistency against the Profile.",
934
- "useWhen": [
935
- "Need to detect package/identity drift",
936
- "Need to validate identity against the Profile"
937
- ],
938
- "doNotUseWhen": [
939
- "Need to auto-fix drift (check does not fix)"
940
- ],
941
- "prerequisites": [],
942
- "inputs": [
943
- "Target root, Profile identifier"
944
- ],
945
- "outputs": [
946
- "Drift findings, validation conclusion"
947
- ],
948
- "sideEffects": [
949
- "Read-only read of target files"
950
- ],
951
- "failureSemantics": [
952
- "Drift or validation failure produces findings"
953
- ],
954
- "invariants": [
955
- "Does not modify target files"
956
- ],
957
- "ownedByCaller": [
958
- "Business disposition of drift"
959
- ],
960
- "routeElsewhere": [
961
- "Auto-fix: the caller"
962
- ]
963
- },
964
- {
965
- "id": "foundation.kit.cli",
966
- "intent": "Provide the skill-family-kit CLI entry point, dispatching the four top-level commands and sub-actions, and rejecting mutation flags at the entry point.",
967
- "useWhen": [
968
- "Need to run scaffold/adopt-plan/projection/check from the command line",
969
- "Need to run report/host sub-actions"
970
- ],
971
- "doNotUseWhen": [
972
- "Need a fifth top-level command (the command set is fixed at 4, not expanded)"
973
- ],
974
- "prerequisites": [
975
- "Node >= 22.22.2"
976
- ],
977
- "inputs": [
978
- "argv"
979
- ],
980
- "outputs": [
981
- "Command result; exit code ok=0/findings=1/rejected=2"
982
- ],
983
- "sideEffects": [
984
- "Produces contained file writes or read-only probes depending on the command"
985
- ],
986
- "failureSemantics": [
987
- "Unknown command, or rejected flag (e.g. --apply), exit code 2"
988
- ],
989
- "invariants": [
990
- "TOP_LEVEL_COMMANDS is fixed at 4",
991
- "REFUSED_MUTATION_FLAGS is rejected at the parseOptions entry point"
992
- ],
993
- "ownedByCaller": [
994
- "Business goal of the command"
995
- ],
996
- "routeElsewhere": [
997
- "A fifth command: forbidden to add"
998
- ]
999
- },
1000
- {
1001
- "id": "foundation.profile.extension-spi",
1002
- "intent": "Declare the extension mechanism for host and project-shape differences: differences (adds/overrides/removes) and open extension points (host-projection/artifact-render/surface-scan), validating Profile legitimacy.",
1003
- "useWhen": [
1004
- "Need to declare project-shape differences without changing the common core",
1005
- "Need to inject extension-point data resources into the stable SPI"
1006
- ],
1007
- "doNotUseWhen": [
1008
- "Need to stuff business semantics into the common core (coreOwned targets are off-limits)",
1009
- "Need to place an executable script into the Profile (the entrypoint must be a JSON data resource)"
1010
- ],
1011
- "prerequisites": [
1012
- "The Profile is a declarative diff and does not depend back on the common core"
1013
- ],
1014
- "inputs": [
1015
- "profileRoot、descriptorRelPath"
1016
- ],
1017
- "outputs": [
1018
- "SPI result code (SPE0000/1001..1005)"
1019
- ],
1020
- "sideEffects": [
1021
- "No side effects (read-only Profile validation)"
1022
- ],
1023
- "failureSemantics": [
1024
- "SPE1004: an entrypoint with an executable extension is rejected before any bytes are read",
1025
- "Out-of-bounds target or illegal diff structure throws"
1026
- ],
1027
- "invariants": [
1028
- "coreOwned = packages/commands/namespacePrefixes are off-limits targets",
1029
- "The entrypoint must be a JSON data resource"
1030
- ],
1031
- "ownedByCaller": [
1032
- "Business semantics of the difference"
1033
- ],
1034
- "routeElsewhere": [
1035
- "Common-core changes: must go through Contracts/Harness/Kit"
1036
- ]
1037
- },
1038
- {
1039
- "id": "foundation.profile.public-plugin",
1040
- "intent": "Public sample Profile: declare three adds differences and three SPI data resources via public-plugin, as a readable example of the Profile shape.",
1041
- "useWhen": [
1042
- "Need a reference public Profile instance that conforms to the spec",
1043
- "Need to understand how the Profile descriptor and SPI resources are wired"
1044
- ],
1045
- "doNotUseWhen": [
1046
- "Need to put a private Profile or real business data into public docs (leakage forbidden)"
1047
- ],
1048
- "prerequisites": [
1049
- "base.contractsVersion = 1.4.0"
1050
- ],
1051
- "inputs": [
1052
- "Profile descriptor and each SPI data resource"
1053
- ],
1054
- "outputs": [
1055
- "A public Profile that passes verifyProfile"
1056
- ],
1057
- "sideEffects": [
1058
- "No side effects (declared data)"
1059
- ],
1060
- "failureSemantics": [
1061
- "Throws when the descriptor does not conform to the schema"
1062
- ],
1063
- "invariants": [
1064
- "Only public or entirely fictional samples are used"
1065
- ],
1066
- "ownedByCaller": [
1067
- "Profile business meaning"
1068
- ],
1069
- "routeElsewhere": [
1070
- "Private Profile: does not enter public docs"
1071
- ]
1072
- },
1073
- {
1074
- "id": "foundation.profile.licensing",
1075
- "intent": "Declare the licensing-data authority (registry + schema), executed by the Kit licensing entry through the contract validator, defaulting to the first variant.",
1076
- "useWhen": [
1077
- "Need to define licensing-data variants",
1078
- "Need to provide the data authority for Kit licensing"
1079
- ],
1080
- "doNotUseWhen": [
1081
- "Need to make business licensing decisions (semantics owned by the caller)"
1082
- ],
1083
- "prerequisites": [
1084
- "registry.json + schema.json exist"
1085
- ],
1086
- "inputs": [
1087
- "Licensing variant declaration"
1088
- ],
1089
- "outputs": [
1090
- "Licensing data for Kit to load"
1091
- ],
1092
- "sideEffects": [
1093
- "No side effects (declared data)"
1094
- ],
1095
- "failureSemantics": [
1096
- "Unspecified variant among many fails to load"
1097
- ],
1098
- "invariants": [
1099
- "All commercial payloads are currently disabled"
1100
- ],
1101
- "ownedByCaller": [
1102
- "Licensing business semantics"
1103
- ],
1104
- "routeElsewhere": [
1105
- "Licensing execution: the caller"
1106
- ]
1107
- },
1108
- {
1109
- "id": "foundation.profile.hosts",
1110
- "intent": "Register host diff declarations (claude/codex supported, qoder unsupported), providing the descriptor and registry for the Kit host sub-action.",
1111
- "useWhen": [
1112
- "Need to register diffs for supported hosts (claude/codex)",
1113
- "Need to provide declarative data for host integration"
1114
- ],
1115
- "doNotUseWhen": [
1116
- "Need to register a full Qoder driver (that host is unsupported)"
1117
- ],
1118
- "prerequisites": [
1119
- "The host descriptor is bound to a trusted driverId"
1120
- ],
1121
- "inputs": [
1122
- "Host identifier, descriptor fields"
1123
- ],
1124
- "outputs": [
1125
- "Host registry and descriptor"
1126
- ],
1127
- "sideEffects": [
1128
- "No side effects (declared data)"
1129
- ],
1130
- "failureSemantics": [
1131
- "qoder is marked unsupported and is rejected on reference"
1132
- ],
1133
- "invariants": [
1134
- "claude/codex have support=supported and are bound to a driverId; qoder has support=unsupported"
1135
- ],
1136
- "ownedByCaller": [
1137
- "Host business semantics"
1138
- ],
1139
- "routeElsewhere": [
1140
- "Full Qoder driver: unsupported"
1141
- ]
1142
- },
1143
- {
1144
- "id": "foundation.unsupported.host-apply",
1145
- "intent": "Host apply (applying integration changes to the host runtime environment) is stably rejected in the read-only Phase D slice and is not implemented.",
1146
- "useWhen": [],
1147
- "doNotUseWhen": [
1148
- "Any scenario that truly changes the host runtime environment (currently unavailable)"
1149
- ],
1150
- "prerequisites": [
1151
- "none"
1152
- ],
1153
- "inputs": [
1154
- "none"
1155
- ],
1156
- "outputs": [
1157
- "Throws: host apply is not implemented in the read-only Phase D slice"
1158
- ],
1159
- "sideEffects": [
1160
- "none"
1161
- ],
1162
- "failureSemantics": [
1163
- "Throws on call; the CLI-layer host-apply sub-action rejects as well"
1164
- ],
1165
- "invariants": [
1166
- "apply is stably rejected and is out of scope for the 0.2.x implementation"
1167
- ],
1168
- "ownedByCaller": [
1169
- "Final landing of host integration"
1170
- ],
1171
- "routeElsewhere": [
1172
- "Host application logic: the caller or a later version"
1173
- ]
1174
- },
1175
- {
1176
- "id": "foundation.unsupported.host-install-update-uninstall",
1177
- "intent": "Host install/update/uninstall are all unimplemented and out of scope for Foundation 0.2.x.",
1178
- "useWhen": [],
1179
- "doNotUseWhen": [
1180
- "Any scenario requiring installation/update/uninstallation of host components"
1181
- ],
1182
- "prerequisites": [
1183
- "none"
1184
- ],
1185
- "inputs": [
1186
- "none"
1187
- ],
1188
- "outputs": [
1189
- "none (unimplemented)"
1190
- ],
1191
- "sideEffects": [
1192
- "none"
1193
- ],
1194
- "failureSemantics": [
1195
- "No corresponding entry point exists; calls should turn to external tools"
1196
- ],
1197
- "invariants": [
1198
- "Install/uninstall/update are all unimplemented"
1199
- ],
1200
- "ownedByCaller": [
1201
- "Host lifecycle management"
1202
- ],
1203
- "routeElsewhere": [
1204
- "Host lifecycle: external tools or a later version"
1205
- ]
1206
- },
1207
- {
1208
- "id": "foundation.unsupported.qoder-driver",
1209
- "intent": "The full driver for the Qoder host is not frozen (No auditable non-interactive host driver is frozen), marked unsupported, referenced for structure only.",
1210
- "useWhen": [],
1211
- "doNotUseWhen": [
1212
- "Any scenario requiring actual execution on Qoder"
1213
- ],
1214
- "prerequisites": [
1215
- "none"
1216
- ],
1217
- "inputs": [
1218
- "none"
1219
- ],
1220
- "outputs": [
1221
- "none (unsupported)"
1222
- ],
1223
- "sideEffects": [
1224
- "none"
1225
- ],
1226
- "failureSemantics": [
1227
- "Referencing the qoder driver throws"
1228
- ],
1229
- "invariants": [
1230
- "HOST_DRIVER_IDS contains only claude-version-v1 / codex-version-v1"
1231
- ],
1232
- "ownedByCaller": [
1233
- "Qoder integration"
1234
- ],
1235
- "routeElsewhere": [
1236
- "Qoder support: a later version or external"
1237
- ]
1238
- },
1239
- {
1240
- "id": "foundation.unsupported.binary-adapter-source",
1241
- "intent": "The adapter source content supports only string (utf8 text closure); binary projection is out of scope.",
1242
- "useWhen": [],
1243
- "doNotUseWhen": [
1244
- "Need to include binary resources in the adapter projection"
1245
- ],
1246
- "prerequisites": [
1247
- "none"
1248
- ],
1249
- "inputs": [
1250
- "none"
1251
- ],
1252
- "outputs": [
1253
- "none (binary explicitly unsupported)"
1254
- ],
1255
- "sideEffects": [
1256
- "none"
1257
- ],
1258
- "failureSemantics": [
1259
- "Non-string content fails validation"
1260
- ],
1261
- "invariants": [
1262
- "The adapter source content type is fixed to string, utf8 only"
1263
- ],
1264
- "ownedByCaller": [
1265
- "Binary resource handling"
1266
- ],
1267
- "routeElsewhere": [
1268
- "Binary handling: external tools"
1269
- ]
1270
- },
1271
- {
1272
- "id": "foundation.unsupported.remote-publish",
1273
- "intent": "Remote publish and all remote writes belong to release-skill; Foundation does not own them.",
1274
- "useWhen": [],
1275
- "doNotUseWhen": [
1276
- "Any scenario requiring publishing to npm/GitHub/Registry or remote writes"
1277
- ],
1278
- "prerequisites": [
1279
- "none"
1280
- ],
1281
- "inputs": [
1282
- "none"
1283
- ],
1284
- "outputs": [
1285
- "none (route to release-skill)"
1286
- ],
1287
- "sideEffects": [
1288
- "none"
1289
- ],
1290
- "failureSemantics": [
1291
- "Foundation provides no remote-write entry point"
1292
- ],
1293
- "invariants": [
1294
- "contracts doesNotOwn remote writes; harness HARNESS_EXCLUSIONS contains remote-network-access; kit FORBIDDEN_SIDE_EFFECTS contains publish/remote-write"
1295
- ],
1296
- "ownedByCaller": [
1297
- "Publish process"
1298
- ],
1299
- "routeElsewhere": [
1300
- "Publish: release-skill"
1301
- ]
1302
- },
1303
- {
1304
- "id": "foundation.unsupported.business-state-machine",
1305
- "intent": "Business state machines, task nodes, retries, terminal states, memory, and similar semantics are not part of Foundation; state-store only provides the foundation.",
1306
- "useWhen": [],
1307
- "doNotUseWhen": [
1308
- "Any scenario requiring a workflow state machine or business terminal state to be defined in Foundation"
1309
- ],
1310
- "prerequisites": [
1311
- "none"
1312
- ],
1313
- "inputs": [
1314
- "none"
1315
- ],
1316
- "outputs": [
1317
- "none (route to loop-agent)"
1318
- ],
1319
- "sideEffects": [
1320
- "none"
1321
- ],
1322
- "failureSemantics": [
1323
- "Business state transitions should not be implemented within Foundation"
1324
- ],
1325
- "invariants": [
1326
- "Event meaning and reducer transitions remain consumer-owned"
1327
- ],
1328
- "ownedByCaller": [
1329
- "Business state machine semantics"
1330
- ],
1331
- "routeElsewhere": [
1332
- "Tasks/retries/rework/acceptance: loop-agent"
1333
- ]
1334
- },
1335
- {
1336
- "id": "foundation.unsupported.model-orchestration",
1337
- "intent": "Model orchestration and workflow orchestration are out of the Foundation scope; only business-neutral mechanisms are provided.",
1338
- "useWhen": [],
1339
- "doNotUseWhen": [
1340
- "Any scenario requiring model calls or workflow orchestration"
1341
- ],
1342
- "prerequisites": [
1343
- "none"
1344
- ],
1345
- "inputs": [
1346
- "none"
1347
- ],
1348
- "outputs": [
1349
- "none (route to the corresponding orchestration layer)"
1350
- ],
1351
- "sideEffects": [
1352
- "none"
1353
- ],
1354
- "failureSemantics": [
1355
- "Foundation contains no model calls or workflow engine"
1356
- ],
1357
- "invariants": [
1358
- "harness HARNESS_EXCLUSIONS contains workflow-orchestration / model-calls; contracts doesNotOwn generation"
1359
- ],
1360
- "ownedByCaller": [
1361
- "Orchestration semantics"
1362
- ],
1363
- "routeElsewhere": [
1364
- "Orchestration: the corresponding consumer or orchestration layer"
1365
- ]
1366
- },
1367
- {
1368
- "id": "foundation.unsupported.domain-audit-semantics",
1369
- "intent": "Domain audit semantics and the final accept/reject conclusion belong to external independent review; Foundation only provides the audit surface (canonical + digest).",
1370
- "useWhen": [],
1371
- "doNotUseWhen": [
1372
- "Any scenario requiring Foundation to own a domain audit oracle or semantic conclusion"
1373
- ],
1374
- "prerequisites": [
1375
- "none"
1376
- ],
1377
- "inputs": [
1378
- "none"
1379
- ],
1380
- "outputs": [
1381
- "none (route to an independent audit consumer)"
1382
- ],
1383
- "sideEffects": [
1384
- "none"
1385
- ],
1386
- "failureSemantics": [
1387
- "Foundation does not carry domain audit semantics"
1388
- ],
1389
- "invariants": [
1390
- "audit-surface only performs deterministic serialization and contains no semantics"
1391
- ],
1392
- "ownedByCaller": [
1393
- "Audit semantic conclusion"
1394
- ],
1395
- "routeElsewhere": [
1396
- "Domain audit: independent audit consumer"
1397
- ]
1398
- },
1399
- {
1400
- "id": "foundation.unsupported.git-writes",
1401
- "intent": "Git write operations (stage/commit/push/tag/release) are out of the Foundation scope; only read-only probing is provided.",
1402
- "useWhen": [],
1403
- "doNotUseWhen": [
1404
- "Any scenario requiring Foundation to perform Git write operations"
1405
- ],
1406
- "prerequisites": [
1407
- "none"
1408
- ],
1409
- "inputs": [
1410
- "none"
1411
- ],
1412
- "outputs": [
1413
- "none (route to the Git lifecycle guide authorization flow)"
1414
- ],
1415
- "sideEffects": [
1416
- "none"
1417
- ],
1418
- "failureSemantics": [
1419
- "Foundation provides no Git write entry point"
1420
- ],
1421
- "invariants": [
1422
- "harness HARNESS_EXCLUSIONS contains git-writes; kit git-init/commit/push/tag are write-forbidden"
1423
- ],
1424
- "ownedByCaller": [
1425
- "Authorization for Git write operations"
1426
- ],
1427
- "routeElsewhere": [
1428
- "Git write operations: the Git lifecycle guide"
1429
- ]
1430
- },
1431
- {
1432
- "id": "foundation.contracts.quickstart-profile-candidate",
1433
- "intent": "Expose the candidate Quickstart Resource, Task, and Result schemas through skill-family-contracts/candidate/quickstart-profile for exact-version integration trials.",
1434
- "useWhen": [
1435
- "Need to inspect or validate the candidate Resource, Task, or Result shape before it is proposed for the frozen registry",
1436
- "The consumer can pin the exact skill-family-contracts package version and isolate candidate imports from its stable API"
1437
- ],
1438
- "doNotUseWhen": [
1439
- "Need a registry-listed or compatibility-frozen contract",
1440
- "Need Foundation to interpret domain audit semantics"
1441
- ],
1442
- "prerequisites": [
1443
- "Install an exact skill-family-contracts version that exports skill-family-contracts/candidate/quickstart-profile",
1444
- "Node >= 22.22.2"
1445
- ],
1446
- "inputs": [
1447
- "Document kind: resource, task, or result",
1448
- "Candidate document to validate"
1449
- ],
1450
- "outputs": [
1451
- "Cloned candidate schemas or a validation result containing valid, errors, and normalized data"
1452
- ],
1453
- "sideEffects": [
1454
- "No filesystem, Git, network, or process writes"
1455
- ],
1456
- "failureSemantics": [
1457
- "An unknown document kind throws TypeError",
1458
- "An invalid candidate document returns valid:false with Ajv findings"
1459
- ],
1460
- "invariants": [
1461
- "Candidate schemas remain absent from src/registry.json and do not expand the 18 stable object classes",
1462
- "Stability is candidate: a later minor release may change or remove this subpath"
1463
- ],
1464
- "ownedByCaller": [
1465
- "Domain meaning of method, parameters, evidence, and domainResult",
1466
- "Decision to adopt or wrap the candidate API"
1467
- ],
1468
- "routeElsewhere": [
1469
- "Frozen production contracts: use the stable skill-family-contracts root export",
1470
- "Domain audit conclusions: route to an independent audit consumer"
1471
- ]
1472
- },
1473
- {
1474
- "id": "foundation.harness.quickstart-profile-candidate",
1475
- "intent": "Construct and verify an observation-bound candidate Task/Result exchange through skill-family-harness-node/candidate/quickstart-profile.",
1476
- "useWhen": [
1477
- "Need an early integration trial that binds a contained observation file to a candidate Task and terminal Result",
1478
- "Need a structured non-throwing verification result for an exact-version candidate exchange"
1479
- ],
1480
- "doNotUseWhen": [
1481
- "Need a domain auditor, method selector, retry orchestrator, or lifecycle owner",
1482
- "Need a compatibility-frozen Quickstart API"
1483
- ],
1484
- "prerequisites": [
1485
- "Install exact matching versions of skill-family-harness-node and skill-family-contracts",
1486
- "The observation path is contained under the supplied root"
1487
- ],
1488
- "inputs": [
1489
- "Contained root and observation path",
1490
- "Operation identity, method, parameters, and run/stage/attempt correlation",
1491
- "Candidate Task and Result documents for verification"
1492
- ],
1493
- "outputs": [
1494
- "Observation Resource, candidate Task, terminal Result, or structured exchange verification"
1495
- ],
1496
- "sideEffects": [
1497
- "Reads the contained observation file to compute or verify its sha256 digest",
1498
- "Does not write files or access Git or the network"
1499
- ],
1500
- "failureSemantics": [
1501
- "Throwing APIs fail closed with SFC2004 and details.kind=invalid-result when the profile or binding is invalid",
1502
- "verifyQuickstartExchange converts a failure into {valid:false, code, message, details}"
1503
- ],
1504
- "invariants": [
1505
- "The Result must bind the exact Task digest, observation digest, operation identity, and correlation fields",
1506
- "Stability is candidate: a later minor release may change or remove this subpath"
1507
- ],
1508
- "ownedByCaller": [
1509
- "Audit method semantics and domainResult interpretation",
1510
- "Retry, scheduling, and lifecycle decisions"
1511
- ],
1512
- "routeElsewhere": [
1513
- "Stable generic mechanisms: use the skill-family-harness-node root export",
1514
- "Business orchestration: route to the consumer or orchestration layer"
1515
- ]
1516
- },
1517
- {
1518
- "id": "foundation.kit.quickstart-profile-candidate",
1519
- "intent": "Build a deterministic, self-contained Quickstart projection manifest through skill-family-engineering-kit/candidate/quickstart-profile.",
1520
- "useWhen": [
1521
- "Need to trial the candidate Quickstart schemas and runner in a target using the stable projection authorization boundary",
1522
- "Need provenance and dependency-closure digests for the generated candidate bundle"
1523
- ],
1524
- "doNotUseWhen": [
1525
- "Need a stable Quickstart API or a fifth top-level Kit command",
1526
- "Need to bypass target manifest authorization or handwritten-file protection"
1527
- ],
1528
- "prerequisites": [
1529
- "Install exact matching versions of all three Foundation packages",
1530
- "The target prefix is a contained relative POSIX path"
1531
- ],
1532
- "inputs": [
1533
- "Optional contained targetPrefix",
1534
- "Exact installed Contracts, Harness, and Kit package bytes"
1535
- ],
1536
- "outputs": [
1537
- "A projection manifest and provenance record with source, runtime dependency, and bundle digests"
1538
- ],
1539
- "sideEffects": [
1540
- "Builds the manifest in memory and reads installed package files",
1541
- "Performs no writes; callers pass the manifest to stable runProjection for authorized writes"
1542
- ],
1543
- "failureSemantics": [
1544
- "An invalid targetPrefix throws TypeError",
1545
- "A missing or inconsistent installed dependency closure rejects the build; runProjection reports its own stable projection failures"
1546
- ],
1547
- "invariants": [
1548
- "The helper adds no top-level Kit command and never bypasses runProjection",
1549
- "Stability is candidate: a later minor release may change or remove this subpath"
1550
- ],
1551
- "ownedByCaller": [
1552
- "Review and authorization of the returned manifest",
1553
- "Target file-registry and managed-file declarations"
1554
- ],
1555
- "routeElsewhere": [
1556
- "Ordinary managed projection: use runProjection from the stable Kit root export",
1557
- "Remote publication: route to release-skill"
1558
- ]
1559
- }
1560
- ]
2
+ "schemaVersion": 1,
3
+ "kind": "skill-family.documentation-capability-catalog",
4
+ "bundle": "locale-overlay",
5
+ "locale": "en",
6
+ "generatedFrom": [
7
+ "package.json",
8
+ "packages/skill-family-contracts/package.json",
9
+ "packages/skill-family-harness-node/package.json",
10
+ "packages/skill-family-engineering-kit/package.json",
11
+ "packages/skill-family-contracts/src/index.mjs",
12
+ "packages/skill-family-harness-node/src/index.mjs",
13
+ "packages/skill-family-engineering-kit/src/index.mjs",
14
+ "packages/skill-family-engineering-kit/src/cli.mjs",
15
+ "packages/skill-family-contracts/src/registry.json",
16
+ "profiles/README.md",
17
+ "docs/architecture.md",
18
+ "docs/status/current.md"
19
+ ],
20
+ "capabilities": [
21
+ {
22
+ "id": "foundation.contracts.object-validation",
23
+ "intent": "Compile and validate the 18 registered top-level Foundation contract object documents under both the draft-07 and 2020-12 dialects using Ajv 8.20.0 (exact pin).",
24
+ "useWhen": [
25
+ "Need to validate registered contract objects such as project-manifest, profile-descriptor, report-model",
26
+ "Need to detect the document dialect and select the strict or tolerant validation policy"
27
+ ],
28
+ "doNotUseWhen": [
29
+ "Need to validate consumer-owned business Schemas (which consumers should own themselves; Foundation does not replace them)",
30
+ "Need to mix domain semantic validation into the generic contract"
31
+ ],
32
+ "prerequisites": [
33
+ "The document to validate carries the $id of a registered contract object",
34
+ "Node >= 22.22.2"
35
+ ],
36
+ "inputs": [
37
+ "Contract document object (any JSON value)",
38
+ "Target contract object $id or schema",
39
+ "Validation policy (strict | tolerant, default strict)"
40
+ ],
41
+ "outputs": [
42
+ "Validation passes: returns {valid:true} (no errorCode field)",
43
+ "Validation fails: returns {valid:false, errorCode, errors}, without throwing",
44
+ "The first compilation result is written to the Ajv compile cache and reused for subsequent identical (schemaId,dialect,policy)"
45
+ ],
46
+ "sideEffects": [
47
+ "No filesystem, Git, network, or process side effects (pure function + in-memory cache)"
48
+ ],
49
+ "failureSemantics": [
50
+ "SFC1002: unknown contract object $id not registered (returns valid:false, without throwing)",
51
+ "SFC1001: document does not conform to a registered Schema (returns valid:false, errors include Ajv keyword details)",
52
+ "Callers judge success via the valid field of the return value, not via try/catch — validateDocument never throws",
53
+ "compileSchema throws ContractsError (SFC1012 SCHEMA_COMPILE_FAILED) for an uncompilable schema; detectDialect throws ContractsError (SFC1006) for an unknown dialect"
54
+ ],
55
+ "invariants": [
56
+ "The same (object, dialect, policy) reuses the compile cache; repeated validation does not recompile",
57
+ "Only Ajv 8.20.0 is accepted; no other validator is wired in"
58
+ ],
59
+ "ownedByCaller": [
60
+ "Semantic interpretation of concrete business fields",
61
+ "Domain-level validation rules"
62
+ ],
63
+ "routeElsewhere": [
64
+ "Consumer business Schema validation: stays with the caller",
65
+ "Remote publish writes: route to release-skill"
66
+ ]
67
+ },
68
+ {
69
+ "id": "foundation.contracts.registry-protocol",
70
+ "intent": "Register and look up contract object Schema $id and protocol names, serving as the single authority for protocol names and Schemas.",
71
+ "useWhen": [
72
+ "Need to find a registered Schema by object name or $id",
73
+ "Need to find a kernel protocol definition by protocol name"
74
+ ],
75
+ "doNotUseWhen": [
76
+ "Need to add a fourth class of registered object (the 18-object set must not be extended without an ADR)"
77
+ ],
78
+ "prerequisites": [
79
+ "registry.json is shipped with the package",
80
+ "Node >= 22.22.2"
81
+ ],
82
+ "inputs": [
83
+ "Object name, Schema $id, or protocol name"
84
+ ],
85
+ "outputs": [
86
+ "Registered Schema metadata or protocol definition",
87
+ "Returns undefined or throws on a cache miss"
88
+ ],
89
+ "sideEffects": [
90
+ "No filesystem, Git, network, or process side effects (pure function)"
91
+ ],
92
+ "failureSemantics": [
93
+ "SFC1003: duplicate $id registration",
94
+ "SFC1004: duplicate protocol registration"
95
+ ],
96
+ "invariants": [
97
+ "registry.json's schemaVersion=1 and contractsVersion=1.4.0 are the single authority",
98
+ "The set of 18 top-level objects is fixed; additions require an ADR"
99
+ ],
100
+ "ownedByCaller": [
101
+ "Interpretation of an object's business meaning"
102
+ ],
103
+ "routeElsewhere": [
104
+ "Publish status: route to release-skill"
105
+ ]
106
+ },
107
+ {
108
+ "id": "foundation.contracts.kernel-protocol",
109
+ "intent": "Load and validate the skill-family.kernel.operation protocol (stable, Contracts 1.4.0), defining the operation request/result structure.",
110
+ "useWhen": [
111
+ "Need to parse or validate operation-request / operation-result structures",
112
+ "Need to look up a parameter contract by operation name"
113
+ ],
114
+ "doNotUseWhen": [
115
+ "Need to define business operation semantics (semantics are owned by the consumer)"
116
+ ],
117
+ "prerequisites": [
118
+ "kernel-protocol.json is shipped with the package"
119
+ ],
120
+ "inputs": [
121
+ "Protocol name, operation name, operation parameters"
122
+ ],
123
+ "outputs": [
124
+ "Protocol definition or operation parameter validation result"
125
+ ],
126
+ "sideEffects": [
127
+ "No side effects (pure function)"
128
+ ],
129
+ "failureSemantics": [
130
+ "SFC2002: unknown operation",
131
+ "SFC2003: parameters violate the protocol"
132
+ ],
133
+ "invariants": [
134
+ "The kernel protocol version is bound to the Contracts version"
135
+ ],
136
+ "ownedByCaller": [
137
+ "Concrete business semantics of the operation"
138
+ ],
139
+ "routeElsewhere": [
140
+ "Business state machine / retries / terminal state: route to loop-agent"
141
+ ]
142
+ },
143
+ {
144
+ "id": "foundation.contracts.mandatory-checks",
145
+ "intent": "Run mechanical checks for the 9 classes of mandatory rule (budget cap 20, absolute cap 30), compiling all Schemas in the registry uniformly.",
146
+ "useWhen": [
147
+ "Need to confirm the contract set satisfies the mandatory mechanical rules",
148
+ "Need to collect unresolved references (unresolved refs)"
149
+ ],
150
+ "doNotUseWhen": [
151
+ "Need semantic-level review (belongs to external independent review; a second gate is not maintained in the repo)"
152
+ ],
153
+ "prerequisites": [
154
+ "registry and rules are loaded"
155
+ ],
156
+ "inputs": [
157
+ "The contract set to check, or a synthetic registry/fixtures"
158
+ ],
159
+ "outputs": [
160
+ "Check conclusion and list of unresolved references"
161
+ ],
162
+ "sideEffects": [
163
+ "No side effects (pure function)"
164
+ ],
165
+ "failureSemantics": [
166
+ "SFC1002/1003/1004/1005/1006/1008/1009/1010: corresponding rule violated"
167
+ ],
168
+ "invariants": [
169
+ "CHECK_TYPES is a closed set of 9 classes",
170
+ "RULE_BUDGET bounds firstVersionMax and absoluteMax"
171
+ ],
172
+ "ownedByCaller": [
173
+ "Interpretation of the business rationale behind the rules"
174
+ ],
175
+ "routeElsewhere": [
176
+ "Semantic accept/reject: external independent review"
177
+ ]
178
+ },
179
+ {
180
+ "id": "foundation.contracts.fixture-verification",
181
+ "intent": "Enumerate and validate public/fictional fixtures, confirming they match the expect declaration of the corresponding contract object.",
182
+ "useWhen": [
183
+ "Need to prove a contract object is covered by a fixture",
184
+ "Need to run positive/negative/dialect-boundary class fixtures"
185
+ ],
186
+ "doNotUseWhen": [
187
+ "Need to treat a fixture as a business oracle (fixtures only prove structure, not semantics)"
188
+ ],
189
+ "prerequisites": [
190
+ "The fixtures directory holds public or entirely fictional data"
191
+ ],
192
+ "inputs": [
193
+ "A fixture class or a single fixture identifier"
194
+ ],
195
+ "outputs": [
196
+ "Per-fixture validation results"
197
+ ],
198
+ "sideEffects": [
199
+ "No side effects (read-only fixtures)"
200
+ ],
201
+ "failureSemantics": [
202
+ "SFC1010: a negative fixture failed to produce the expected failure"
203
+ ],
204
+ "invariants": [
205
+ "Fixtures and the auditor's expected results are not shared"
206
+ ],
207
+ "ownedByCaller": [
208
+ "The business intent behind a fixture"
209
+ ],
210
+ "routeElsewhere": [
211
+ "Domain audit semantics: route to an independent audit consumer"
212
+ ]
213
+ },
214
+ {
215
+ "id": "foundation.contracts.error-codes",
216
+ "intent": "Define and register a stable error-code system, provide validation and assertion entry points, and guarantee error codes do not drift.",
217
+ "useWhen": [
218
+ "Need to throw or classify a ContractsError carrying a stable error code",
219
+ "Need to assert that an error code is registered"
220
+ ],
221
+ "doNotUseWhen": [
222
+ "Need to define business error semantics outside the Foundation scope"
223
+ ],
224
+ "prerequisites": [
225
+ "error-codes.json is shipped with the package"
226
+ ],
227
+ "inputs": [
228
+ "Error-code string, error context"
229
+ ],
230
+ "outputs": [
231
+ "Error object carrying a stable error code and details"
232
+ ],
233
+ "sideEffects": [
234
+ "No side effects (pure function)"
235
+ ],
236
+ "failureSemantics": [
237
+ "Assertion fails for an unregistered error code",
238
+ "Frozen-object immutability violation"
239
+ ],
240
+ "invariants": [
241
+ "The error-code registry is frozen and cannot be added to or removed from at runtime"
242
+ ],
243
+ "ownedByCaller": [
244
+ "Business attribution of an error code"
245
+ ],
246
+ "routeElsewhere": [
247
+ "Semantic review conclusion: external independent review"
248
+ ]
249
+ },
250
+ {
251
+ "id": "foundation.contracts.audit-surface",
252
+ "intent": "Serialize the contract surface deterministically (canonical JSON + sha256 digest) for read-only projection by audit consumers.",
253
+ "useWhen": [
254
+ "Need to generate a reproducible digest for the contract surface",
255
+ "Need to describe the audit surface structure"
256
+ ],
257
+ "doNotUseWhen": [
258
+ "Need to audit domain semantics (semantics and final accept/reject belong to external review)"
259
+ ],
260
+ "prerequisites": [
261
+ "AUDIT_SURFACE_VERSION=1、AUDIT_DIGEST_ALGORITHMS=[sha256]"
262
+ ],
263
+ "inputs": [
264
+ "Any JSON document"
265
+ ],
266
+ "outputs": [
267
+ "canonical string and sha256 digest"
268
+ ],
269
+ "sideEffects": [
270
+ "No side effects (pure function)"
271
+ ],
272
+ "failureSemantics": [
273
+ "Non-JSON values, unknown algorithms, and freeze violations all throw"
274
+ ],
275
+ "invariants": [
276
+ "The digest algorithm is sha256 only; the version number is fixed"
277
+ ],
278
+ "ownedByCaller": [
279
+ "Audit semantic conclusion"
280
+ ],
281
+ "routeElsewhere": [
282
+ "Domain audit semantics: route to an independent audit consumer"
283
+ ]
284
+ },
285
+ {
286
+ "id": "foundation.harness.contract-validation",
287
+ "intent": "Resolve the contract context in the Node runtime and reuse the Contracts validator to validate contract documents and cache validator instances.",
288
+ "useWhen": [
289
+ "Need to validate Foundation contract documents inside Node",
290
+ "Need to reuse a validator cache keyed by schema"
291
+ ],
292
+ "doNotUseWhen": [
293
+ "Need to validate in a non-Node runtime (only a Node implementation exists currently)"
294
+ ],
295
+ "prerequisites": [
296
+ "skill-family-contracts is installed"
297
+ ],
298
+ "inputs": [
299
+ "Schema context, contract document"
300
+ ],
301
+ "outputs": [
302
+ "Validation result, reusing the cached Ajv instance"
303
+ ],
304
+ "sideEffects": [
305
+ "In-process in-memory validator cache (no file/Git/network)"
306
+ ],
307
+ "failureSemantics": [
308
+ "Counterexample matrices such as date-time trigger an SFC validation failure"
309
+ ],
310
+ "invariants": [
311
+ "The validator is cached keyed by (schema); the size is queryable"
312
+ ],
313
+ "ownedByCaller": [
314
+ "Semantics of contract business fields"
315
+ ],
316
+ "routeElsewhere": [
317
+ "Contract object definition: route to Contracts"
318
+ ]
319
+ },
320
+ {
321
+ "id": "foundation.harness.path-containment",
322
+ "intent": "Classify external path inputs and resolve them inside the containment root, rejecting path-traversal, symlink-escape, and realpath-escape.",
323
+ "useWhen": [
324
+ "Need to confine a user/caller-supplied path within a root directory",
325
+ "Need to safely read a contained file"
326
+ ],
327
+ "doNotUseWhen": [
328
+ "Need to put the business rules for file selection into Foundation (business rules are owned by the caller)"
329
+ ],
330
+ "prerequisites": [
331
+ "The caller supplies an explicit root directory (containment boundary)"
332
+ ],
333
+ "inputs": [
334
+ "Root directory, relative/absolute path to resolve"
335
+ ],
336
+ "outputs": [
337
+ "Contained absolute path or the read file content"
338
+ ],
339
+ "sideEffects": [
340
+ "Read-only filesystem access (read/resolve)"
341
+ ],
342
+ "failureSemantics": [
343
+ "SFC2004: path-traversal / symlink-escape / realpath-escape, carrying a stable kind",
344
+ "Windows drive-letter/UNC escapes are rejected as well"
345
+ ],
346
+ "invariants": [
347
+ "All resolution results must fall within the root directory"
348
+ ],
349
+ "ownedByCaller": [
350
+ "Which paths are business-permitted selection rules"
351
+ ],
352
+ "routeElsewhere": [
353
+ "Business file-selection semantics: stay with the caller"
354
+ ]
355
+ },
356
+ {
357
+ "id": "foundation.harness.atomic-write",
358
+ "intent": "Atomically write a regular file within an already-contained path via temp file + fsync + rename, rolling back on failure without leaving residue.",
359
+ "useWhen": [
360
+ "Need to update a regular text/binary file within a contained directory",
361
+ "Need to guarantee the write is either fully visible or invisible"
362
+ ],
363
+ "doNotUseWhen": [
364
+ "Need to write to a non-contained path (out-of-bounds is rejected by path-containment)"
365
+ ],
366
+ "prerequisites": [
367
+ "The target path is verified inside the root directory by path-containment"
368
+ ],
369
+ "inputs": [
370
+ "Contained target path, file content (string or Buffer)"
371
+ ],
372
+ "outputs": [
373
+ "The written file, byte-identical to the input"
374
+ ],
375
+ "sideEffects": [
376
+ "Create a temp file inside the root directory and finally rename to overwrite the target"
377
+ ],
378
+ "failureSemantics": [
379
+ "Out-of-bounds path or illegal data type throws and rolls back the temp file",
380
+ "Binary content is preserved byte-for-byte"
381
+ ],
382
+ "invariants": [
383
+ "fsync before rename, guaranteeing crash consistency"
384
+ ],
385
+ "ownedByCaller": [
386
+ "Business correctness of the written content"
387
+ ],
388
+ "routeElsewhere": [
389
+ "Content-selection business rules: stay with the caller"
390
+ ]
391
+ },
392
+ {
393
+ "id": "foundation.harness.temporary-workspace",
394
+ "intent": "Create and manage a temporary working directory, providing a safe lifecycle via a with syntax that cleans up on exit.",
395
+ "useWhen": [
396
+ "Need to build intermediate artifacts inside an isolated directory",
397
+ "Need to guarantee the temp directory is reclaimed on exceptions"
398
+ ],
399
+ "doNotUseWhen": [
400
+ "Need to persist artifacts (they should be explicitly materialized to a contained path)"
401
+ ],
402
+ "prerequisites": [
403
+ "The host provides a writable temp directory (e.g. os.tmpdir)"
404
+ ],
405
+ "inputs": [
406
+ "Optional prefix/label"
407
+ ],
408
+ "outputs": [
409
+ "Temporary working directory handle"
410
+ ],
411
+ "sideEffects": [
412
+ "Create a subdirectory in the system temp directory, deleted on exit"
413
+ ],
414
+ "failureSemantics": [
415
+ "Creation failure rejects; the temp directory is still cleaned up when the with callback throws"
416
+ ],
417
+ "invariants": [
418
+ "The temp directory path does not escape the host temp root"
419
+ ],
420
+ "ownedByCaller": [
421
+ "Final destination of the temp artifacts"
422
+ ],
423
+ "routeElsewhere": [
424
+ "Persistent state: route to state-store"
425
+ ]
426
+ },
427
+ {
428
+ "id": "foundation.harness.resource-closure",
429
+ "intent": "Compute a deterministic, deduplicated, ordered resource closure with a sha256 digest, for adapter text closure and build manifests.",
430
+ "useWhen": [
431
+ "Need to normalize a set of resources into a reproducible closure",
432
+ "Need to generate a digest for a build manifest"
433
+ ],
434
+ "doNotUseWhen": [
435
+ "Need to include binary resources (only text closures are supported currently)"
436
+ ],
437
+ "prerequisites": [
438
+ "Resources are serializable text entries"
439
+ ],
440
+ "inputs": [
441
+ "Resource list (path + content)"
442
+ ],
443
+ "outputs": [
444
+ "Deterministic closure object and sha256 digest"
445
+ ],
446
+ "sideEffects": [
447
+ "No side effects (pure function)"
448
+ ],
449
+ "failureSemantics": [
450
+ "Illegal/duplicate resource declarations throw or reject"
451
+ ],
452
+ "invariants": [
453
+ "Deduplication and ordering are fixed; identical input always yields the same digest"
454
+ ],
455
+ "ownedByCaller": [
456
+ "Business meaning of resources"
457
+ ],
458
+ "routeElsewhere": [
459
+ "Binary projection: explicitly unsupported"
460
+ ]
461
+ },
462
+ {
463
+ "id": "foundation.harness.request-processing",
464
+ "intent": "Parse the operation-request and drive the operation-result pipeline, producing terminal states REJECTED / FAILED / SUCCESS.",
465
+ "useWhen": [
466
+ "Need to normalize an inbound request into a unified operation-request structure",
467
+ "Need to deterministically produce an operation result"
468
+ ],
469
+ "doNotUseWhen": [
470
+ "Need model calls or business orchestration (neither is in the Foundation scope)"
471
+ ],
472
+ "prerequisites": [
473
+ "The request conforms to the kernel protocol structure"
474
+ ],
475
+ "inputs": [
476
+ "Raw request payload"
477
+ ],
478
+ "outputs": [
479
+ "Normalized operation-request and terminal operation-result"
480
+ ],
481
+ "sideEffects": [
482
+ "No side effects (pure-function pipeline)"
483
+ ],
484
+ "failureSemantics": [
485
+ "Parse failure enters the REJECTED/FAILED terminal state carrying a stable error code"
486
+ ],
487
+ "invariants": [
488
+ "The terminal-state set is fixed to REJECTED/FAILED/SUCCESS"
489
+ ],
490
+ "ownedByCaller": [
491
+ "Concrete business semantics of the operation"
492
+ ],
493
+ "routeElsewhere": [
494
+ "Business state machine / retries: route to loop-agent"
495
+ ]
496
+ },
497
+ {
498
+ "id": "foundation.harness.report",
499
+ "intent": "Validate the report-model, render Markdown, bind digests, and run tiered checks deterministically; the human report is derived from machine results rather than freely authored.",
500
+ "useWhen": [
501
+ "Need to render machine results into a human-readable report",
502
+ "Need to bind the model/result/report triple-digest to prevent tampering"
503
+ ],
504
+ "doNotUseWhen": [
505
+ "Need to freely author a report from open business outputs (forbidden)"
506
+ ],
507
+ "prerequisites": [
508
+ "REPORT_RENDERER_NAME / VERSION come from their respective packages (currently 0.3.0)",
509
+ "SUPPORTED_REPORT_LOCALES = [zh-CN, en-US]"
510
+ ],
511
+ "inputs": [
512
+ "report-model, render options (locale/audience/style)"
513
+ ],
514
+ "outputs": [
515
+ "Markdown text, binding object, tiered-check findings"
516
+ ],
517
+ "sideEffects": [
518
+ "No file/Git/network side effects (pure function)"
519
+ ],
520
+ "failureSemantics": [
521
+ "SFC3001/3002/3003: model validation/binding/check hard failure"
522
+ ],
523
+ "invariants": [
524
+ "Markdown is escaped deterministically; the dual outputs are written as a pair, and path aliases and input overwrites are rejected"
525
+ ],
526
+ "ownedByCaller": [
527
+ "Interpretation of the report's business conclusion"
528
+ ],
529
+ "routeElsewhere": [
530
+ "Report generation orchestration: Kit report sub-action"
531
+ ]
532
+ },
533
+ {
534
+ "id": "foundation.harness.host-adapter",
535
+ "intent": "Implement the generic mechanism layer for host integration: normalize adapter source, compute the build closure, validate the build manifest, materialize the build, probe the version vector (spawn disabled by default).",
536
+ "useWhen": [
537
+ "Need to turn a host adapter source into a reproducible text closure",
538
+ "Need to materialize build artifacts at a contained location",
539
+ "Need to probe the host version vector (without auto-executing the host binary)"
540
+ ],
541
+ "doNotUseWhen": [
542
+ "Need host apply/install/update/uninstall (explicitly unsupported)",
543
+ "Need a binary adapter source (only text closures are supported)"
544
+ ],
545
+ "prerequisites": [
546
+ "The adapter source is a declared text closure"
547
+ ],
548
+ "inputs": [
549
+ "adapter source, target path"
550
+ ],
551
+ "outputs": [
552
+ "Build closure, validated manifest, materialized artifacts"
553
+ ],
554
+ "sideEffects": [
555
+ "Create a sibling staging area at the contained target and a single rename",
556
+ "Probe does not spawn by default and does not use PATH"
557
+ ],
558
+ "failureSemantics": [
559
+ "Mismatched manifest digest, existing target, or untrusted executable all throw"
560
+ ],
561
+ "invariants": [
562
+ "materialize is an atomic sibling + rename"
563
+ ],
564
+ "ownedByCaller": [
565
+ "Concrete host business semantics"
566
+ ],
567
+ "routeElsewhere": [
568
+ "host apply: explicitly unsupported",
569
+ "Host diff declaration: route to Profile + Kit host sub-action"
570
+ ]
571
+ },
572
+ {
573
+ "id": "foundation.harness.state-store",
574
+ "intent": "Provide a persistent state foundation: append-only events, hash chain, derived snapshots, plus lock checks and explicit recovery; event meaning and reducer transitions are owned by the caller.",
575
+ "useWhen": [
576
+ "Need to persist an event log and guarantee order and integrity",
577
+ "Need to rebuild or validate derived snapshots",
578
+ "Need to check or recover a cooperative single-writer lock"
579
+ ],
580
+ "doNotUseWhen": [
581
+ "Need to define a workflow state machine in Foundation (forbidden)",
582
+ "Need to defend against same-privilege malicious processes (fencing does not promise this scenario)"
583
+ ],
584
+ "prerequisites": [
585
+ "STATE_GENESIS_DIGEST as the chain origin"
586
+ ],
587
+ "inputs": [
588
+ "Event payload, snapshot, lock token"
589
+ ],
590
+ "outputs": [
591
+ "Events, hash-chain validation result, snapshot"
592
+ ],
593
+ "sideEffects": [
594
+ "Read/write the event log and snapshot files at the contained path",
595
+ "Write a lock file for the cooperative single-writer"
596
+ ],
597
+ "failureSemantics": [
598
+ "Broken hash chain, lock fencing conflict, or recovery failure throws"
599
+ ],
600
+ "invariants": [
601
+ "The event log is the single authority; the snapshot is a derived cache",
602
+ "The local cooperative single-writer uses fencing and explicit recovery"
603
+ ],
604
+ "ownedByCaller": [
605
+ "Business meaning of events, reducer transitions, the confirmOwnerTerminated trust anchor"
606
+ ],
607
+ "routeElsewhere": [
608
+ "Business state machine / terminal state: route to loop-agent"
609
+ ]
610
+ },
611
+ {
612
+ "id": "foundation.harness.baseline-materialization",
613
+ "intent": "Materialize a frozen baseline as a byte-faithful temporary copy with bidirectional digest verification; mid-materialization changes and guard rejections fail closed",
614
+ "useWhen": [
615
+ "Need a writable isolated copy of a baseline directory whose digest is frozen",
616
+ "Need to prove the copy is byte-identical to the source baseline"
617
+ ],
618
+ "doNotUseWhen": [
619
+ "Need to keep artifacts (persist them explicitly to a contained path)",
620
+ "The baseline directory contains symbolic links (the mechanism rejects them outright)"
621
+ ],
622
+ "prerequisites": [
623
+ "The caller holds the frozen 64-char sha256 digest of the baseline"
624
+ ],
625
+ "inputs": [
626
+ "Baseline directory, frozen digest, optional temporary-directory prefix"
627
+ ],
628
+ "outputs": [
629
+ "The materialized temporary workspace root path"
630
+ ],
631
+ "sideEffects": [
632
+ "Creates a subdirectory in the system temporary directory and cleans it up on failure",
633
+ "Reads the source baseline only"
634
+ ],
635
+ "failureSemantics": [
636
+ "Digest mismatch, mid-materialization source or copy change, or guard rejection throws baseline-mismatch or content-guard-rejected; no half-finished copy is delivered"
637
+ ],
638
+ "invariants": [
639
+ "The materialized copy is byte-identical to the frozen digest",
640
+ "Symbolic links inside the baseline are always rejected"
641
+ ],
642
+ "ownedByCaller": [
643
+ "Residual-content judgment (the contentGuard predicate) and the final destination of the copy"
644
+ ],
645
+ "routeElsewhere": [
646
+ "Persisting artifacts: route to state-store or the consumer's own persistence"
647
+ ]
648
+ },
649
+ {
650
+ "id": "foundation.harness.read-chokepoint",
651
+ "intent": "Concentrate every consumer read of a protected area into one admission check: an allowed-root set plus an optional identity predicate; out-of-bounds and unauthorized reads are stably refused",
652
+ "useWhen": [
653
+ "Need to guarantee reads of a protected area stay inside the declared allowed-root set",
654
+ "Need to concentrate identity judgment and path containment into a single entry point"
655
+ ],
656
+ "doNotUseWhen": [
657
+ "Need the mechanism to understand the business meaning of identities or paths (owned by the consumer predicate)"
658
+ ],
659
+ "prerequisites": [
660
+ "The caller declares a non-empty allowed-root set"
661
+ ],
662
+ "inputs": [
663
+ "An absolute path or { root, relPath }, optionally an identity object"
664
+ ],
665
+ "outputs": [
666
+ "The admitted { root, relPath, absolute } or the contained read result"
667
+ ],
668
+ "sideEffects": [
669
+ "Read-only filesystem access (realpath / contained read)"
670
+ ],
671
+ "failureSemantics": [
672
+ "Out-of-bounds targets, link escapes, and unauthorized identities throw read-chokepoint-rejected; missing resources throw missing-resource"
673
+ ],
674
+ "invariants": [
675
+ "String inputs and { root, relPath } inputs share the same containment classification",
676
+ "The mechanism never interprets private identity or path semantics"
677
+ ],
678
+ "ownedByCaller": [
679
+ "The allowed-root set, the identity predicate, and the semantics of admitted reads"
680
+ ],
681
+ "routeElsewhere": [
682
+ "Identity systems and authorization policy: keep with the consumer"
683
+ ]
684
+ },
685
+ {
686
+ "id": "foundation.harness.surface-scan",
687
+ "intent": "Scan a declared surface for path and content patterns according to a policy contract document; the first hit fails closed, and an invalid policy also fails closed",
688
+ "useWhen": [
689
+ "Need to scan a set of contained files for path or content patterns under a configurable policy",
690
+ "Need an injection self-test with byte-recoverable results to prove the scanner is stateless"
691
+ ],
692
+ "doNotUseWhen": [
693
+ "Need the mechanism to interpret allowed-use exemptions (implement them at the consumer layer)"
694
+ ],
695
+ "prerequisites": [
696
+ "A policy document that passes the surface-scan-policy contract validation"
697
+ ],
698
+ "inputs": [
699
+ "Scan root, relative-path list, policy document"
700
+ ],
701
+ "outputs": [
702
+ "A { scanned, bytes, policy } result object"
703
+ ],
704
+ "sideEffects": [
705
+ "Read-only filesystem access",
706
+ "Policy patterns are compiled as regular expressions in-process; no persistent state"
707
+ ],
708
+ "failureSemantics": [
709
+ "Path or content hits throw surface-scan-violation; invalid policy or uncompilable patterns throw scan-policy-invalid; missing files throw missing-resource"
710
+ ],
711
+ "invariants": [
712
+ "A hit fails closed and is never silently skipped",
713
+ "allowedUses is carried but never interpreted; a hit is never exempted"
714
+ ],
715
+ "ownedByCaller": [
716
+ "Policy content, allowed-use semantics, and post-hit disposition"
717
+ ],
718
+ "routeElsewhere": [
719
+ "Business forbidden words and exemption decisions: keep with the consumer"
720
+ ]
721
+ },
722
+ {
723
+ "id": "foundation.harness.token-estimation",
724
+ "intent": "Provide a deterministic upper-bound estimate for text: a pure UTF-8 byte-count function with no model, network, or tokenizer dependency",
725
+ "useWhen": [
726
+ "Need an upper bound on text consumption without calling a model",
727
+ "Need a contractual, verifiable, timestamp-free estimation result object"
728
+ ],
729
+ "doNotUseWhen": [
730
+ "Need real token counts or semantic estimates (the primitive does not promise precision)"
731
+ ],
732
+ "prerequisites": [
733
+ "Input is a JavaScript string"
734
+ ],
735
+ "inputs": [
736
+ "A text string"
737
+ ],
738
+ "outputs": [
739
+ "A token-estimate-result contract object (inputBytes equals upperBound)"
740
+ ],
741
+ "sideEffects": [
742
+ "None: pure function with zero dependencies"
743
+ ],
744
+ "failureSemantics": [
745
+ "Non-string input throws TypeError"
746
+ ],
747
+ "invariants": [
748
+ "Identical input produces identical output; deterministic byte counting",
749
+ "guarantees is a closed enumeration and the result carries no timestamp"
750
+ ],
751
+ "ownedByCaller": [
752
+ "Interpretation of the estimate and consumer-side conversion"
753
+ ],
754
+ "routeElsewhere": [
755
+ "Model calls and real token counting: not in Foundation"
756
+ ]
757
+ },
758
+ {
759
+ "id": "foundation.harness.upper-bound-guard",
760
+ "intent": "Implement a generic upper-bound guard over the state-store event ledger with explicit token-lock occupancy: over-limit events fail closed and are never written; the bound and over-limit policy are entirely consumer-configured",
761
+ "useWhen": [
762
+ "Need to impose a consumer-side upper bound on a reducible usage event ledger and guarantee over-limit events never land",
763
+ "Need to reuse the existing event ledger and lock mechanisms instead of inventing new state"
764
+ ],
765
+ "doNotUseWhen": [
766
+ "Need Foundation to understand usage categories or pricing semantics (injected by the consumer)"
767
+ ],
768
+ "prerequisites": [
769
+ "The consumer provides event payload schemas, a pure reduction function, and a non-negative upper bound"
770
+ ],
771
+ "inputs": [
772
+ "State root, lock root and lock path, events, consumer configuration"
773
+ ],
774
+ "outputs": [
775
+ "Append results, current usage reading, guard handle"
776
+ ],
777
+ "sideEffects": [
778
+ "Writes the event ledger and lock file at the contained path",
779
+ "Acquires the explicit lock on open and releases it on close"
780
+ ],
781
+ "failureSemantics": [
782
+ "Over-limit appends throw upper-bound-exceeded and are not written; a held lock throws store-locked; a broken chain throws chain-broken"
783
+ ],
784
+ "invariants": [
785
+ "The event ledger is the single authority; over-limit events never land",
786
+ "The module embeds no fixed amount or pricing vocabulary"
787
+ ],
788
+ "ownedByCaller": [
789
+ "Event meaning, the reduction function, the upper-bound value, and post-overrun business handling"
790
+ ],
791
+ "routeElsewhere": [
792
+ "Pricing and billing semantics: keep with the consumer"
793
+ ]
794
+ },
795
+ {
796
+ "id": "foundation.harness.errors",
797
+ "intent": "Define the Harness mechanism error types and stable error classes, unifying error classification.",
798
+ "useWhen": [
799
+ "Need to throw a HarnessError carrying a stable kind"
800
+ ],
801
+ "doNotUseWhen": [
802
+ "Need to define business error semantics"
803
+ ],
804
+ "prerequisites": [],
805
+ "inputs": [
806
+ "Error kind, context"
807
+ ],
808
+ "outputs": [
809
+ "Error object carrying a stable kind"
810
+ ],
811
+ "sideEffects": [
812
+ "No side effects (pure function)"
813
+ ],
814
+ "failureSemantics": [
815
+ "Illegal kind invocation throws"
816
+ ],
817
+ "invariants": [
818
+ "HARNESS_EXCLUSIONS explicitly excludes release-state / remote-network-access / business-semantics / workflow-orchestration / model-calls / git-writes"
819
+ ],
820
+ "ownedByCaller": [
821
+ "Business attribution of the error"
822
+ ],
823
+ "routeElsewhere": [
824
+ "Business semantics: stay with the caller"
825
+ ]
826
+ },
827
+ {
828
+ "id": "foundation.kit.scaffold",
829
+ "intent": "Generate a precise set of hosted files in a new project skeleton (atomic + path containment), without overwriting a non-empty existing repo.",
830
+ "useWhen": [
831
+ "Need to generate a minimal verifiable skeleton for a new skill-family project",
832
+ "The target directory is empty or contains only containable content"
833
+ ],
834
+ "doNotUseWhen": [
835
+ "Need to overwrite an existing non-empty repo (use adopt-plan instead)"
836
+ ],
837
+ "prerequisites": [
838
+ "The target is a writable empty directory",
839
+ "Node >= 22.22.2"
840
+ ],
841
+ "inputs": [
842
+ "Target root, skeleton options (id, etc.)"
843
+ ],
844
+ "outputs": [
845
+ "The precise set of hosted skeleton files"
846
+ ],
847
+ "sideEffects": [
848
+ "Create files at the contained target (atomic + contained)"
849
+ ],
850
+ "failureSemantics": [
851
+ "Non-empty target or illegal kebab id throws"
852
+ ],
853
+ "invariants": [
854
+ "Only write to empty targets, atomic + contained",
855
+ "The skeleton set matches the scaffold-conformance fixture"
856
+ ],
857
+ "ownedByCaller": [
858
+ "Business project content"
859
+ ],
860
+ "routeElsewhere": [
861
+ "Existing-repo adoption: route to adopt-plan"
862
+ ]
863
+ },
864
+ {
865
+ "id": "foundation.kit.adopt-plan",
866
+ "intent": "Perform a strict read-only inventory of an existing repo (classification, nested-repo discovery, migration list, completion judgment), writing no files and migrating nothing automatically.",
867
+ "useWhen": [
868
+ "Need to classify an existing repo as direct-adoption / compatibility-layer / keep-business / foundation-gap",
869
+ "Need to generate a handoff draft or a completion judgment for migration"
870
+ ],
871
+ "doNotUseWhen": [
872
+ "Need to auto-rewrite the existing repo (writing files and auto-migration are forbidden)"
873
+ ],
874
+ "prerequisites": [
875
+ "The target repo exists and is read-only accessible"
876
+ ],
877
+ "inputs": [
878
+ "Target root, migration-list path"
879
+ ],
880
+ "outputs": [
881
+ "Adoption classification, completion judgment, handoff draft (output only, not written to disk)"
882
+ ],
883
+ "sideEffects": [
884
+ "No file writes (strictly read-only)",
885
+ "May trigger read-only git probes"
886
+ ],
887
+ "failureSemantics": [
888
+ "Missing fields in an exception, or not having exited the old implementation, makes the completion judgment false"
889
+ ],
890
+ "invariants": [
891
+ "No file writes, no auto-migration"
892
+ ],
893
+ "ownedByCaller": [
894
+ "Migration decisions for existing business code"
895
+ ],
896
+ "routeElsewhere": [
897
+ "Actual migration execution: the caller is responsible"
898
+ ]
899
+ },
900
+ {
901
+ "id": "foundation.kit.projection",
902
+ "intent": "Mechanically project managed facts to a target (e.g. a public mirror) per the projection manifest; write only after all checks pass, with zero-write/rollback on any failure.",
903
+ "useWhen": [
904
+ "Need to project authoritative data to a public snapshot or release mirror",
905
+ "Need to guarantee the projection matches the target"
906
+ ],
907
+ "doNotUseWhen": [
908
+ "Need to overwrite handwritten files (forbidden)"
909
+ ],
910
+ "prerequisites": [
911
+ "The projection manifest is registered"
912
+ ],
913
+ "inputs": [
914
+ "Projection manifest, target root"
915
+ ],
916
+ "outputs": [
917
+ "Projected files (only when all checks pass)"
918
+ ],
919
+ "sideEffects": [
920
+ "Write projected files at the contained target",
921
+ "Two-phase: write only after all checks pass, roll back on failure"
922
+ ],
923
+ "failureSemantics": [
924
+ "Unauthorized, handwritten conflict, out-of-bounds, or content conflict all throw without residue"
925
+ ],
926
+ "invariants": [
927
+ "Never overwrite handwritten files",
928
+ "Zero write on any check failure"
929
+ ],
930
+ "ownedByCaller": [
931
+ "Business meaning of the projected content"
932
+ ],
933
+ "routeElsewhere": [
934
+ "Remote publish: route to release-skill"
935
+ ]
936
+ },
937
+ {
938
+ "id": "foundation.kit.check",
939
+ "intent": "Diagnose only, do not fix: run the seven check classes contracts/drift/closure/version/docs/git/identity and output findings.",
940
+ "useWhen": [
941
+ "Need to surface engineering inconsistencies without auto-modifying",
942
+ "Need to narrow the check scope via --only"
943
+ ],
944
+ "doNotUseWhen": [
945
+ "Need auto-fix (forbidden; check writes no fixes)"
946
+ ],
947
+ "prerequisites": [],
948
+ "inputs": [
949
+ "--only values: contracts|drift|closure|version|docs|git|identity"
950
+ ],
951
+ "outputs": [
952
+ "Findings list; exit code findings=1, mechanism=2"
953
+ ],
954
+ "sideEffects": [
955
+ "No file writes (read-only diagnosis)"
956
+ ],
957
+ "failureSemantics": [
958
+ "findings exit code 1; mechanism rejection exit code 2"
959
+ ],
960
+ "invariants": [
961
+ "CHECK_CLASSES is a closed set of seven classes, not expanded"
962
+ ],
963
+ "ownedByCaller": [
964
+ "Business disposition of each finding"
965
+ ],
966
+ "routeElsewhere": [
967
+ "Auto-fix execution: the caller"
968
+ ]
969
+ },
970
+ {
971
+ "id": "foundation.kit.report",
972
+ "intent": "Orchestrate the human report as a CLI sub-action: projection report rendering, check report tiering, writing to stdout by default.",
973
+ "useWhen": [
974
+ "Need to produce report text from an already-rendered model",
975
+ "Need to run a tiered check on the report"
976
+ ],
977
+ "doNotUseWhen": [
978
+ "Need to freely author a report from open business outputs (forbidden)"
979
+ ],
980
+ "prerequisites": [
981
+ "A Harness report-model already exists"
982
+ ],
983
+ "inputs": [
984
+ "report-model, --out/--binding options"
985
+ ],
986
+ "outputs": [
987
+ "Markdown text; --out/--binding writes to disk"
988
+ ],
989
+ "sideEffects": [
990
+ "Writes to stdout by default; explicit --out/--binding writes the contained file"
991
+ ],
992
+ "failureSemantics": [
993
+ "Hard failure counts as a finding; illegal arguments reject"
994
+ ],
995
+ "invariants": [
996
+ "The report is rendered deterministically from machine results"
997
+ ],
998
+ "ownedByCaller": [
999
+ "Interpretation of the report conclusion"
1000
+ ],
1001
+ "routeElsewhere": [
1002
+ "Report mechanism: route to Harness report"
1003
+ ]
1004
+ },
1005
+ {
1006
+ "id": "foundation.kit.git-probe",
1007
+ "intent": "Probe Git status and facts via a read-only allowlist for diagnosis and adoption inventory, performing no Git write operations.",
1008
+ "useWhen": [
1009
+ "Need to read-only discover the current Git status (status/ls-files/check-ignore)",
1010
+ "Need to provide Git facts for adoption inventory"
1011
+ ],
1012
+ "doNotUseWhen": [
1013
+ "Need Git write operations (stage/commit/push/tag, explicitly forbidden)"
1014
+ ],
1015
+ "prerequisites": [],
1016
+ "inputs": [
1017
+ "Target root"
1018
+ ],
1019
+ "outputs": [
1020
+ "Git status and facts (read-only)"
1021
+ ],
1022
+ "sideEffects": [
1023
+ "Read-only calls to git status/ls-files/check-ignore (parameter vector frozen)"
1024
+ ],
1025
+ "failureSemantics": [
1026
+ "Parameter vectors not in the allowlist are rejected"
1027
+ ],
1028
+ "invariants": [
1029
+ "GIT_READ_ONLY_ALLOWLIST bounds the subcommands that may be called"
1030
+ ],
1031
+ "ownedByCaller": [
1032
+ "Authorization for Git write operations"
1033
+ ],
1034
+ "routeElsewhere": [
1035
+ "Git write operations: see the Git lifecycle guide; Foundation does not own them"
1036
+ ]
1037
+ },
1038
+ {
1039
+ "id": "foundation.kit.host",
1040
+ "intent": "Inject a concrete host Profile and trusted driver, providing describe/build/probe/plan; apply is stably rejected, and install/update/uninstall are unimplemented.",
1041
+ "useWhen": [
1042
+ "Need to describe a registered host (claude/codex)",
1043
+ "Need to probe, build, or plan host integration (read-only mechanism layer)"
1044
+ ],
1045
+ "doNotUseWhen": [
1046
+ "Need host apply/install/update/uninstall (explicitly unsupported)",
1047
+ "Need a full Qoder driver (that host is unsupported)"
1048
+ ],
1049
+ "prerequisites": [
1050
+ "The host Profile is registered in profiles/hosts",
1051
+ "Trusted drivers are only claude-version-v1 / codex-version-v1"
1052
+ ],
1053
+ "inputs": [
1054
+ "Host identifier, probe/plan options"
1055
+ ],
1056
+ "outputs": [
1057
+ "Host description, probe result, build artifacts, plan"
1058
+ ],
1059
+ "sideEffects": [
1060
+ "build/materialize writes artifacts at the contained target",
1061
+ "Probe does not spawn by default"
1062
+ ],
1063
+ "failureSemantics": [
1064
+ "An unsupported host (e.g. qoder) throws",
1065
+ "apply is stably rejected",
1066
+ "Missing probe facts throws"
1067
+ ],
1068
+ "invariants": [
1069
+ "HOST_DRIVER_IDS contains only the two trusted drivers",
1070
+ "apply is stably rejected"
1071
+ ],
1072
+ "ownedByCaller": [
1073
+ "Host business semantics"
1074
+ ],
1075
+ "routeElsewhere": [
1076
+ "host apply: explicitly unsupported",
1077
+ "Full Qoder driver: unsupported"
1078
+ ]
1079
+ },
1080
+ {
1081
+ "id": "foundation.kit.licensing",
1082
+ "intent": "Load and validate Profile licensing data, generating license/notice/identity-record content.",
1083
+ "useWhen": [
1084
+ "Need to generate LICENSE/NOTICE/identity records per Profile",
1085
+ "Need to validate the legitimacy of a licensing Profile"
1086
+ ],
1087
+ "doNotUseWhen": [
1088
+ "Need to make business licensing decisions (semantics owned by the caller)"
1089
+ ],
1090
+ "prerequisites": [
1091
+ "profiles/licensing/registry.json + schema.json exist"
1092
+ ],
1093
+ "inputs": [
1094
+ "Profile identifier, variant selection"
1095
+ ],
1096
+ "outputs": [
1097
+ "License/notice/identity-record text"
1098
+ ],
1099
+ "sideEffects": [
1100
+ "No side effects (pure-function generation)"
1101
+ ],
1102
+ "failureSemantics": [
1103
+ "Unspecified variant among many, or illegal Profile, throws"
1104
+ ],
1105
+ "invariants": [
1106
+ "By default the first registry variant is taken; multiple variants must be explicitly selected"
1107
+ ],
1108
+ "ownedByCaller": [
1109
+ "Licensing business semantics"
1110
+ ],
1111
+ "routeElsewhere": [
1112
+ "Licensing decisions: stay with the caller"
1113
+ ]
1114
+ },
1115
+ {
1116
+ "id": "foundation.kit.identity-check",
1117
+ "intent": "Load identity records and the manifest, check identity drift, and validate consistency against the Profile.",
1118
+ "useWhen": [
1119
+ "Need to detect package/identity drift",
1120
+ "Need to validate identity against the Profile"
1121
+ ],
1122
+ "doNotUseWhen": [
1123
+ "Need to auto-fix drift (check does not fix)"
1124
+ ],
1125
+ "prerequisites": [],
1126
+ "inputs": [
1127
+ "Target root, Profile identifier"
1128
+ ],
1129
+ "outputs": [
1130
+ "Drift findings, validation conclusion"
1131
+ ],
1132
+ "sideEffects": [
1133
+ "Read-only read of target files"
1134
+ ],
1135
+ "failureSemantics": [
1136
+ "Drift or validation failure produces findings"
1137
+ ],
1138
+ "invariants": [
1139
+ "Does not modify target files"
1140
+ ],
1141
+ "ownedByCaller": [
1142
+ "Business disposition of drift"
1143
+ ],
1144
+ "routeElsewhere": [
1145
+ "Auto-fix: the caller"
1146
+ ]
1147
+ },
1148
+ {
1149
+ "id": "foundation.kit.cli",
1150
+ "intent": "Provide the skill-family-kit CLI entry point, dispatching the four top-level commands and sub-actions, and rejecting mutation flags at the entry point.",
1151
+ "useWhen": [
1152
+ "Need to run scaffold/adopt-plan/projection/check from the command line",
1153
+ "Need to run report/host sub-actions"
1154
+ ],
1155
+ "doNotUseWhen": [
1156
+ "Need a fifth top-level command (the command set is fixed at 4, not expanded)"
1157
+ ],
1158
+ "prerequisites": [
1159
+ "Node >= 22.22.2"
1160
+ ],
1161
+ "inputs": [
1162
+ "argv"
1163
+ ],
1164
+ "outputs": [
1165
+ "Command result; exit code ok=0/findings=1/rejected=2"
1166
+ ],
1167
+ "sideEffects": [
1168
+ "Produces contained file writes or read-only probes depending on the command"
1169
+ ],
1170
+ "failureSemantics": [
1171
+ "Unknown command, or rejected flag (e.g. --apply), exit code 2"
1172
+ ],
1173
+ "invariants": [
1174
+ "TOP_LEVEL_COMMANDS is fixed at 4",
1175
+ "REFUSED_MUTATION_FLAGS is rejected at the parseOptions entry point"
1176
+ ],
1177
+ "ownedByCaller": [
1178
+ "Business goal of the command"
1179
+ ],
1180
+ "routeElsewhere": [
1181
+ "A fifth command: forbidden to add"
1182
+ ]
1183
+ },
1184
+ {
1185
+ "id": "foundation.profile.extension-spi",
1186
+ "intent": "Declare the extension mechanism for host and project-shape differences: differences (adds/overrides/removes) and open extension points (host-projection/artifact-render/surface-scan), validating Profile legitimacy.",
1187
+ "useWhen": [
1188
+ "Need to declare project-shape differences without changing the common core",
1189
+ "Need to inject extension-point data resources into the stable SPI"
1190
+ ],
1191
+ "doNotUseWhen": [
1192
+ "Need to stuff business semantics into the common core (coreOwned targets are off-limits)",
1193
+ "Need to place an executable script into the Profile (the entrypoint must be a JSON data resource)"
1194
+ ],
1195
+ "prerequisites": [
1196
+ "The Profile is a declarative diff and does not depend back on the common core"
1197
+ ],
1198
+ "inputs": [
1199
+ "profileRoot、descriptorRelPath"
1200
+ ],
1201
+ "outputs": [
1202
+ "SPI result code (SPE0000/1001..1005)"
1203
+ ],
1204
+ "sideEffects": [
1205
+ "No side effects (read-only Profile validation)"
1206
+ ],
1207
+ "failureSemantics": [
1208
+ "SPE1004: an entrypoint with an executable extension is rejected before any bytes are read",
1209
+ "Out-of-bounds target or illegal diff structure throws"
1210
+ ],
1211
+ "invariants": [
1212
+ "coreOwned = packages/commands/namespacePrefixes are off-limits targets",
1213
+ "The entrypoint must be a JSON data resource"
1214
+ ],
1215
+ "ownedByCaller": [
1216
+ "Business semantics of the difference"
1217
+ ],
1218
+ "routeElsewhere": [
1219
+ "Common-core changes: must go through Contracts/Harness/Kit"
1220
+ ]
1221
+ },
1222
+ {
1223
+ "id": "foundation.profile.public-plugin",
1224
+ "intent": "Public sample Profile: declare three adds differences and three SPI data resources via public-plugin, as a readable example of the Profile shape.",
1225
+ "useWhen": [
1226
+ "Need a reference public Profile instance that conforms to the spec",
1227
+ "Need to understand how the Profile descriptor and SPI resources are wired"
1228
+ ],
1229
+ "doNotUseWhen": [
1230
+ "Need to put a private Profile or real business data into public docs (leakage forbidden)"
1231
+ ],
1232
+ "prerequisites": [
1233
+ "base.contractsVersion = 1.4.0"
1234
+ ],
1235
+ "inputs": [
1236
+ "Profile descriptor and each SPI data resource"
1237
+ ],
1238
+ "outputs": [
1239
+ "A public Profile that passes verifyProfile"
1240
+ ],
1241
+ "sideEffects": [
1242
+ "No side effects (declared data)"
1243
+ ],
1244
+ "failureSemantics": [
1245
+ "Throws when the descriptor does not conform to the schema"
1246
+ ],
1247
+ "invariants": [
1248
+ "Only public or entirely fictional samples are used"
1249
+ ],
1250
+ "ownedByCaller": [
1251
+ "Profile business meaning"
1252
+ ],
1253
+ "routeElsewhere": [
1254
+ "Private Profile: does not enter public docs"
1255
+ ]
1256
+ },
1257
+ {
1258
+ "id": "foundation.profile.licensing",
1259
+ "intent": "Declare the licensing-data authority (registry + schema), executed by the Kit licensing entry through the contract validator, defaulting to the first variant.",
1260
+ "useWhen": [
1261
+ "Need to define licensing-data variants",
1262
+ "Need to provide the data authority for Kit licensing"
1263
+ ],
1264
+ "doNotUseWhen": [
1265
+ "Need to make business licensing decisions (semantics owned by the caller)"
1266
+ ],
1267
+ "prerequisites": [
1268
+ "registry.json + schema.json exist"
1269
+ ],
1270
+ "inputs": [
1271
+ "Licensing variant declaration"
1272
+ ],
1273
+ "outputs": [
1274
+ "Licensing data for Kit to load"
1275
+ ],
1276
+ "sideEffects": [
1277
+ "No side effects (declared data)"
1278
+ ],
1279
+ "failureSemantics": [
1280
+ "Unspecified variant among many fails to load"
1281
+ ],
1282
+ "invariants": [
1283
+ "All commercial payloads are currently disabled"
1284
+ ],
1285
+ "ownedByCaller": [
1286
+ "Licensing business semantics"
1287
+ ],
1288
+ "routeElsewhere": [
1289
+ "Licensing execution: the caller"
1290
+ ]
1291
+ },
1292
+ {
1293
+ "id": "foundation.profile.hosts",
1294
+ "intent": "Register host diff declarations (claude/codex supported, qoder unsupported), providing the descriptor and registry for the Kit host sub-action.",
1295
+ "useWhen": [
1296
+ "Need to register diffs for supported hosts (claude/codex)",
1297
+ "Need to provide declarative data for host integration"
1298
+ ],
1299
+ "doNotUseWhen": [
1300
+ "Need to register a full Qoder driver (that host is unsupported)"
1301
+ ],
1302
+ "prerequisites": [
1303
+ "The host descriptor is bound to a trusted driverId"
1304
+ ],
1305
+ "inputs": [
1306
+ "Host identifier, descriptor fields"
1307
+ ],
1308
+ "outputs": [
1309
+ "Host registry and descriptor"
1310
+ ],
1311
+ "sideEffects": [
1312
+ "No side effects (declared data)"
1313
+ ],
1314
+ "failureSemantics": [
1315
+ "qoder is marked unsupported and is rejected on reference"
1316
+ ],
1317
+ "invariants": [
1318
+ "claude/codex have support=supported and are bound to a driverId; qoder has support=unsupported"
1319
+ ],
1320
+ "ownedByCaller": [
1321
+ "Host business semantics"
1322
+ ],
1323
+ "routeElsewhere": [
1324
+ "Full Qoder driver: unsupported"
1325
+ ]
1326
+ },
1327
+ {
1328
+ "id": "foundation.unsupported.host-apply",
1329
+ "intent": "Host apply (applying integration changes to the host runtime environment) is stably rejected in the read-only Phase D slice and is not implemented.",
1330
+ "useWhen": [],
1331
+ "doNotUseWhen": [
1332
+ "Any scenario that truly changes the host runtime environment (currently unavailable)"
1333
+ ],
1334
+ "prerequisites": [
1335
+ "none"
1336
+ ],
1337
+ "inputs": [
1338
+ "none"
1339
+ ],
1340
+ "outputs": [
1341
+ "Throws: host apply is not implemented in the read-only Phase D slice"
1342
+ ],
1343
+ "sideEffects": [
1344
+ "none"
1345
+ ],
1346
+ "failureSemantics": [
1347
+ "Throws on call; the CLI-layer host-apply sub-action rejects as well"
1348
+ ],
1349
+ "invariants": [
1350
+ "apply is stably rejected and is out of scope for the 0.2.x implementation"
1351
+ ],
1352
+ "ownedByCaller": [
1353
+ "Final landing of host integration"
1354
+ ],
1355
+ "routeElsewhere": [
1356
+ "Host application logic: the caller or a later version"
1357
+ ]
1358
+ },
1359
+ {
1360
+ "id": "foundation.unsupported.host-install-update-uninstall",
1361
+ "intent": "Host install/update/uninstall are all unimplemented and out of scope for Foundation 0.2.x.",
1362
+ "useWhen": [],
1363
+ "doNotUseWhen": [
1364
+ "Any scenario requiring installation/update/uninstallation of host components"
1365
+ ],
1366
+ "prerequisites": [
1367
+ "none"
1368
+ ],
1369
+ "inputs": [
1370
+ "none"
1371
+ ],
1372
+ "outputs": [
1373
+ "none (unimplemented)"
1374
+ ],
1375
+ "sideEffects": [
1376
+ "none"
1377
+ ],
1378
+ "failureSemantics": [
1379
+ "No corresponding entry point exists; calls should turn to external tools"
1380
+ ],
1381
+ "invariants": [
1382
+ "Install/uninstall/update are all unimplemented"
1383
+ ],
1384
+ "ownedByCaller": [
1385
+ "Host lifecycle management"
1386
+ ],
1387
+ "routeElsewhere": [
1388
+ "Host lifecycle: external tools or a later version"
1389
+ ]
1390
+ },
1391
+ {
1392
+ "id": "foundation.unsupported.qoder-driver",
1393
+ "intent": "The full driver for the Qoder host is not frozen (No auditable non-interactive host driver is frozen), marked unsupported, referenced for structure only.",
1394
+ "useWhen": [],
1395
+ "doNotUseWhen": [
1396
+ "Any scenario requiring actual execution on Qoder"
1397
+ ],
1398
+ "prerequisites": [
1399
+ "none"
1400
+ ],
1401
+ "inputs": [
1402
+ "none"
1403
+ ],
1404
+ "outputs": [
1405
+ "none (unsupported)"
1406
+ ],
1407
+ "sideEffects": [
1408
+ "none"
1409
+ ],
1410
+ "failureSemantics": [
1411
+ "Referencing the qoder driver throws"
1412
+ ],
1413
+ "invariants": [
1414
+ "HOST_DRIVER_IDS contains only claude-version-v1 / codex-version-v1"
1415
+ ],
1416
+ "ownedByCaller": [
1417
+ "Qoder integration"
1418
+ ],
1419
+ "routeElsewhere": [
1420
+ "Qoder support: a later version or external"
1421
+ ]
1422
+ },
1423
+ {
1424
+ "id": "foundation.unsupported.binary-adapter-source",
1425
+ "intent": "The adapter source content supports only string (utf8 text closure); binary projection is out of scope.",
1426
+ "useWhen": [],
1427
+ "doNotUseWhen": [
1428
+ "Need to include binary resources in the adapter projection"
1429
+ ],
1430
+ "prerequisites": [
1431
+ "none"
1432
+ ],
1433
+ "inputs": [
1434
+ "none"
1435
+ ],
1436
+ "outputs": [
1437
+ "none (binary explicitly unsupported)"
1438
+ ],
1439
+ "sideEffects": [
1440
+ "none"
1441
+ ],
1442
+ "failureSemantics": [
1443
+ "Non-string content fails validation"
1444
+ ],
1445
+ "invariants": [
1446
+ "The adapter source content type is fixed to string, utf8 only"
1447
+ ],
1448
+ "ownedByCaller": [
1449
+ "Binary resource handling"
1450
+ ],
1451
+ "routeElsewhere": [
1452
+ "Binary handling: external tools"
1453
+ ]
1454
+ },
1455
+ {
1456
+ "id": "foundation.unsupported.remote-publish",
1457
+ "intent": "Remote publish and all remote writes belong to release-skill; Foundation does not own them.",
1458
+ "useWhen": [],
1459
+ "doNotUseWhen": [
1460
+ "Any scenario requiring publishing to npm/GitHub/Registry or remote writes"
1461
+ ],
1462
+ "prerequisites": [
1463
+ "none"
1464
+ ],
1465
+ "inputs": [
1466
+ "none"
1467
+ ],
1468
+ "outputs": [
1469
+ "none (route to release-skill)"
1470
+ ],
1471
+ "sideEffects": [
1472
+ "none"
1473
+ ],
1474
+ "failureSemantics": [
1475
+ "Foundation provides no remote-write entry point"
1476
+ ],
1477
+ "invariants": [
1478
+ "contracts doesNotOwn remote writes; harness HARNESS_EXCLUSIONS contains remote-network-access; kit FORBIDDEN_SIDE_EFFECTS contains publish/remote-write"
1479
+ ],
1480
+ "ownedByCaller": [
1481
+ "Publish process"
1482
+ ],
1483
+ "routeElsewhere": [
1484
+ "Publish: release-skill"
1485
+ ]
1486
+ },
1487
+ {
1488
+ "id": "foundation.unsupported.business-state-machine",
1489
+ "intent": "Business state machines, task nodes, retries, terminal states, memory, and similar semantics are not part of Foundation; state-store only provides the foundation.",
1490
+ "useWhen": [],
1491
+ "doNotUseWhen": [
1492
+ "Any scenario requiring a workflow state machine or business terminal state to be defined in Foundation"
1493
+ ],
1494
+ "prerequisites": [
1495
+ "none"
1496
+ ],
1497
+ "inputs": [
1498
+ "none"
1499
+ ],
1500
+ "outputs": [
1501
+ "none (route to loop-agent)"
1502
+ ],
1503
+ "sideEffects": [
1504
+ "none"
1505
+ ],
1506
+ "failureSemantics": [
1507
+ "Business state transitions should not be implemented within Foundation"
1508
+ ],
1509
+ "invariants": [
1510
+ "Event meaning and reducer transitions remain consumer-owned"
1511
+ ],
1512
+ "ownedByCaller": [
1513
+ "Business state machine semantics"
1514
+ ],
1515
+ "routeElsewhere": [
1516
+ "Tasks/retries/rework/acceptance: loop-agent"
1517
+ ]
1518
+ },
1519
+ {
1520
+ "id": "foundation.unsupported.model-orchestration",
1521
+ "intent": "Model orchestration and workflow orchestration are out of the Foundation scope; only business-neutral mechanisms are provided.",
1522
+ "useWhen": [],
1523
+ "doNotUseWhen": [
1524
+ "Any scenario requiring model calls or workflow orchestration"
1525
+ ],
1526
+ "prerequisites": [
1527
+ "none"
1528
+ ],
1529
+ "inputs": [
1530
+ "none"
1531
+ ],
1532
+ "outputs": [
1533
+ "none (route to the corresponding orchestration layer)"
1534
+ ],
1535
+ "sideEffects": [
1536
+ "none"
1537
+ ],
1538
+ "failureSemantics": [
1539
+ "Foundation contains no model calls or workflow engine"
1540
+ ],
1541
+ "invariants": [
1542
+ "harness HARNESS_EXCLUSIONS contains workflow-orchestration / model-calls; contracts doesNotOwn generation"
1543
+ ],
1544
+ "ownedByCaller": [
1545
+ "Orchestration semantics"
1546
+ ],
1547
+ "routeElsewhere": [
1548
+ "Orchestration: the corresponding consumer or orchestration layer"
1549
+ ]
1550
+ },
1551
+ {
1552
+ "id": "foundation.unsupported.domain-audit-semantics",
1553
+ "intent": "Domain audit semantics and the final accept/reject conclusion belong to external independent review; Foundation only provides the audit surface (canonical + digest).",
1554
+ "useWhen": [],
1555
+ "doNotUseWhen": [
1556
+ "Any scenario requiring Foundation to own a domain audit oracle or semantic conclusion"
1557
+ ],
1558
+ "prerequisites": [
1559
+ "none"
1560
+ ],
1561
+ "inputs": [
1562
+ "none"
1563
+ ],
1564
+ "outputs": [
1565
+ "none (route to an independent audit consumer)"
1566
+ ],
1567
+ "sideEffects": [
1568
+ "none"
1569
+ ],
1570
+ "failureSemantics": [
1571
+ "Foundation does not carry domain audit semantics"
1572
+ ],
1573
+ "invariants": [
1574
+ "audit-surface only performs deterministic serialization and contains no semantics"
1575
+ ],
1576
+ "ownedByCaller": [
1577
+ "Audit semantic conclusion"
1578
+ ],
1579
+ "routeElsewhere": [
1580
+ "Domain audit: independent audit consumer"
1581
+ ]
1582
+ },
1583
+ {
1584
+ "id": "foundation.unsupported.git-writes",
1585
+ "intent": "Git write operations (stage/commit/push/tag/release) are out of the Foundation scope; only read-only probing is provided.",
1586
+ "useWhen": [],
1587
+ "doNotUseWhen": [
1588
+ "Any scenario requiring Foundation to perform Git write operations"
1589
+ ],
1590
+ "prerequisites": [
1591
+ "none"
1592
+ ],
1593
+ "inputs": [
1594
+ "none"
1595
+ ],
1596
+ "outputs": [
1597
+ "none (route to the Git lifecycle guide authorization flow)"
1598
+ ],
1599
+ "sideEffects": [
1600
+ "none"
1601
+ ],
1602
+ "failureSemantics": [
1603
+ "Foundation provides no Git write entry point"
1604
+ ],
1605
+ "invariants": [
1606
+ "harness HARNESS_EXCLUSIONS contains git-writes; kit git-init/commit/push/tag are write-forbidden"
1607
+ ],
1608
+ "ownedByCaller": [
1609
+ "Authorization for Git write operations"
1610
+ ],
1611
+ "routeElsewhere": [
1612
+ "Git write operations: the Git lifecycle guide"
1613
+ ]
1614
+ },
1615
+ {
1616
+ "id": "foundation.contracts.quickstart-profile-candidate",
1617
+ "intent": "Expose the Quickstart Profile v2 protocol and real-$id Resource, Task, and Result schema collection through skill-family-contracts/candidate/quickstart-profile for exact-version integration trials.",
1618
+ "useWhen": [
1619
+ "Need to inspect or validate the candidate Resource, Task, or Result shape before it is proposed for the frozen registry",
1620
+ "The consumer can pin the exact skill-family-contracts package version and isolate candidate imports from its stable API"
1621
+ ],
1622
+ "doNotUseWhen": [
1623
+ "Need a registry-listed or compatibility-frozen contract",
1624
+ "Need Foundation to interpret domain audit semantics"
1625
+ ],
1626
+ "prerequisites": [
1627
+ "Install an exact skill-family-contracts version that exports skill-family-contracts/candidate/quickstart-profile",
1628
+ "Node >= 22.22.2"
1629
+ ],
1630
+ "inputs": [
1631
+ "Document kind: resource, task, or result",
1632
+ "Candidate document to validate"
1633
+ ],
1634
+ "outputs": [
1635
+ "Cloned candidate schemas or a validation result containing valid, errors, and normalized data"
1636
+ ],
1637
+ "sideEffects": [
1638
+ "No filesystem, Git, network, or process writes"
1639
+ ],
1640
+ "failureSemantics": [
1641
+ "An unknown document kind throws TypeError",
1642
+ "An invalid candidate document returns valid:false with Ajv findings"
1643
+ ],
1644
+ "invariants": [
1645
+ "The sole business-neutral operation is execute-method; method identifiers and domain schemas remain consumer-owned",
1646
+ "Candidate schemas remain absent from src/registry.json and do not expand the 18 stable object classes",
1647
+ "Stability is candidate: a later minor release may change or remove this subpath"
1648
+ ],
1649
+ "ownedByCaller": [
1650
+ "Domain meaning of method, parameters, evidence, and domainResult",
1651
+ "Decision to adopt or wrap the candidate API"
1652
+ ],
1653
+ "routeElsewhere": [
1654
+ "Frozen production contracts: use the stable skill-family-contracts root export",
1655
+ "Domain audit conclusions: route to an independent audit consumer"
1656
+ ]
1657
+ },
1658
+ {
1659
+ "id": "foundation.harness.quickstart-profile-candidate",
1660
+ "intent": "Construct and verify an observation-bound candidate Task/Result exchange through skill-family-harness-node/candidate/quickstart-profile.",
1661
+ "useWhen": [
1662
+ "Need an early integration trial that binds a contained observation file to a candidate Task and terminal Result",
1663
+ "Need a structured non-throwing verification result for an exact-version candidate exchange"
1664
+ ],
1665
+ "doNotUseWhen": [
1666
+ "Need a domain auditor, method selector, retry orchestrator, or lifecycle owner",
1667
+ "Need a compatibility-frozen Quickstart API"
1668
+ ],
1669
+ "prerequisites": [
1670
+ "Install exact matching versions of skill-family-harness-node and skill-family-contracts",
1671
+ "The observation path is contained under the supplied root"
1672
+ ],
1673
+ "inputs": [
1674
+ "Contained root and observation path",
1675
+ "Operation identity, method, parameters, and run/stage/attempt correlation",
1676
+ "Candidate Task and Result documents for verification"
1677
+ ],
1678
+ "outputs": [
1679
+ "Observation Resource, candidate Task, terminal Result, or structured exchange verification"
1680
+ ],
1681
+ "sideEffects": [
1682
+ "Reads the contained observation file to compute or verify its sha256 digest",
1683
+ "Does not write files or access Git or the network"
1684
+ ],
1685
+ "failureSemantics": [
1686
+ "Throwing APIs fail closed with SFC2004 and details.kind=invalid-result when the profile or binding is invalid",
1687
+ "verifyQuickstartExchange converts a failure into {valid:false, code, message, details}"
1688
+ ],
1689
+ "invariants": [
1690
+ "The Result must bind the exact Task digest, real Resource bytes, globally unique Resource ids, operation identity, correlation fields, and the complete evidence-binding set",
1691
+ "Stability is candidate: a later minor release may change or remove this subpath"
1692
+ ],
1693
+ "ownedByCaller": [
1694
+ "Audit method semantics and domainResult interpretation",
1695
+ "Retry, scheduling, and lifecycle decisions"
1696
+ ],
1697
+ "routeElsewhere": [
1698
+ "Stable generic mechanisms: use the skill-family-harness-node root export",
1699
+ "Business orchestration: route to the consumer or orchestration layer"
1700
+ ]
1701
+ },
1702
+ {
1703
+ "id": "foundation.kit.quickstart-profile-candidate",
1704
+ "intent": "Build a deterministic Quickstart Profile v2 offline Bundle with standalone validators selected by schema $id through skill-family-engineering-kit/candidate/quickstart-profile.",
1705
+ "useWhen": [
1706
+ "Need to trial the candidate Quickstart schemas and runner in a target using the stable projection authorization boundary",
1707
+ "Need complete source, consumer-schema, payload, tool-version, and license provenance for the generated Bundle"
1708
+ ],
1709
+ "doNotUseWhen": [
1710
+ "Need a stable Quickstart API or a fifth top-level Kit command",
1711
+ "Need to bypass target manifest authorization or handwritten-file protection"
1712
+ ],
1713
+ "prerequisites": [
1714
+ "Install exact matching 0.3.0 versions of all three Foundation packages",
1715
+ "The target prefix is a contained relative POSIX path"
1716
+ ],
1717
+ "inputs": [
1718
+ "Contained targetPrefix, consumerSchemaRoot, and an explicit relative consumer-schema path set",
1719
+ "Frozen sourceRepository and sourceBaseCommit identity",
1720
+ "Exact installed Contracts, Harness, and Kit package bytes"
1721
+ ],
1722
+ "outputs": [
1723
+ "A projection manifest and provenance record with Foundation sources, consumer schemas, payload digests, tool versions, and licenses"
1724
+ ],
1725
+ "sideEffects": [
1726
+ "Builds the manifest in memory and reads installed package plus explicit consumer-schema files",
1727
+ "Performs no writes; callers pass the manifest to stable runProjection for authorized writes"
1728
+ ],
1729
+ "failureSemantics": [
1730
+ "An invalid targetPrefix throws TypeError",
1731
+ "Duplicate schema ids, bad references, mixed dialects, unsupported formats, path escapes, or missing source identity reject the build; runProjection reports its own stable projection failures"
1732
+ ],
1733
+ "invariants": [
1734
+ "The Bundle contains no node_modules or runtime Ajv and runs without installed Foundation packages or network access",
1735
+ "The helper adds no top-level Kit command and never bypasses runProjection",
1736
+ "Stability is candidate: a later minor release may change or remove this subpath"
1737
+ ],
1738
+ "ownedByCaller": [
1739
+ "Review and authorization of the returned manifest",
1740
+ "Target file-registry and managed-file declarations"
1741
+ ],
1742
+ "routeElsewhere": [
1743
+ "Ordinary managed projection: use runProjection from the stable Kit root export",
1744
+ "Remote publication: route to release-skill"
1745
+ ]
1746
+ }
1747
+ ]
1561
1748
  }