@oscaner-skills/cdd-engine 1.0.0 → 2.0.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 (99) hide show
  1. package/README.md +9 -8
  2. package/README.zh-CN.md +9 -8
  3. package/package.json +15 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/smoke.integration.test.ts +202 -0
  6. package/src-next/__tests__/zero-dep.test.ts +134 -0
  7. package/src-next/bin.ts +61 -0
  8. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
  9. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
  10. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
  12. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
  16. package/src-next/contract/__tests__/declare.test.ts +242 -0
  17. package/src-next/contract/__tests__/doc.test.ts +358 -0
  18. package/src-next/contract/__tests__/judge.test.ts +873 -0
  19. package/src-next/contract/__tests__/lint.test.ts +314 -0
  20. package/src-next/contract/__tests__/project.test.ts +419 -0
  21. package/src-next/contract/__tests__/translate.test.ts +96 -0
  22. package/src-next/contract/declare.ts +983 -0
  23. package/src-next/contract/doc.ts +753 -0
  24. package/src-next/contract/invariants.ts +1268 -0
  25. package/src-next/contract/judge.ts +142 -0
  26. package/src-next/contract/lint.ts +275 -0
  27. package/src-next/contract/project.ts +596 -0
  28. package/src-next/contract/skill-anatomy.ts +273 -0
  29. package/src-next/contract/translate.ts +113 -0
  30. package/src-next/face/__tests__/board-view.test.ts +948 -0
  31. package/src-next/face/__tests__/capsule.test.ts +276 -0
  32. package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
  33. package/src-next/face/__tests__/cli.test.ts +4643 -0
  34. package/src-next/face/__tests__/face.test.ts +289 -0
  35. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  36. package/src-next/face/__tests__/host.test.ts +24 -0
  37. package/src-next/face/__tests__/negation.ts +6 -0
  38. package/src-next/face/__tests__/projection.test.ts +301 -0
  39. package/src-next/face/__tests__/sync-runner.test.ts +70 -0
  40. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  41. package/src-next/face/artifacts.ts +195 -0
  42. package/src-next/face/board-view.ts +662 -0
  43. package/src-next/face/capsule.ts +149 -0
  44. package/src-next/face/cli.ts +819 -0
  45. package/src-next/face/declare.ts +326 -0
  46. package/src-next/face/gate.ts +170 -0
  47. package/src-next/face/graph-view.ts +74 -0
  48. package/src-next/face/host.ts +326 -0
  49. package/src-next/face/lifecycle.ts +700 -0
  50. package/src-next/face/projection.ts +282 -0
  51. package/src-next/face/route-render.ts +160 -0
  52. package/src-next/face/words.ts +296 -0
  53. package/src-next/infra/__tests__/infra.test.ts +287 -0
  54. package/src-next/infra/config.ts +42 -0
  55. package/src-next/infra/git.ts +39 -0
  56. package/src-next/infra/process.ts +34 -0
  57. package/src-next/infra/runtime.ts +185 -0
  58. package/src-next/infra/workspace.ts +232 -0
  59. package/src-next/render/__tests__/render.test.ts +499 -0
  60. package/src-next/render/__tests__/skeleton.test.ts +466 -0
  61. package/src-next/render/brief.ts +121 -0
  62. package/src-next/render/issue-body.ts +159 -0
  63. package/src-next/render/skeleton.ts +437 -0
  64. package/src-next/render/templates.ts +650 -0
  65. package/src-next/session/__tests__/graph.test.ts +270 -0
  66. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  67. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  68. package/src-next/session/__tests__/ledger.test.ts +744 -0
  69. package/src-next/session/__tests__/next.test.ts +368 -0
  70. package/src-next/session/__tests__/preflight.test.ts +491 -0
  71. package/src-next/session/__tests__/run.test.ts +1014 -0
  72. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  73. package/src-next/session/__tests__/wave.test.ts +469 -0
  74. package/src-next/session/faces.ts +110 -0
  75. package/src-next/session/graph.ts +411 -0
  76. package/src-next/session/handoff-schema.ts +373 -0
  77. package/src-next/session/ledger.ts +1004 -0
  78. package/src-next/session/next.ts +192 -0
  79. package/src-next/session/preflight.ts +240 -0
  80. package/src-next/session/run.ts +606 -0
  81. package/src-next/session/state.ts +30 -0
  82. package/src-next/session/wave.ts +139 -0
  83. package/templates/report/issue-body.json +18 -20
  84. package/dist/chunks/branch.mjs +0 -480
  85. package/dist/chunks/docs.mjs +0 -253
  86. package/dist/chunks/task.mjs +0 -913
  87. package/dist/cli.mjs +0 -5457
  88. package/dist/documents/schema/add-phase-protocol.json +0 -126
  89. package/dist/documents/schema/overall.json +0 -361
  90. package/dist/documents/schema/phase-spec.json +0 -145
  91. package/dist/documents/schema/plan.json +0 -191
  92. package/dist/documents/schema/skill-anatomy.json +0 -233
  93. package/dist/resources/harness-registry.json +0 -49
  94. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  95. package/templates/engine-config.json +0 -302
  96. package/templates/schema/cache-profile-schema.json +0 -23
  97. package/templates/schema/docs-handoff-schema.json +0 -129
  98. package/templates/schema/task-handoff-schema.json +0 -332
  99. package/templates/template-contract.json +0 -231
@@ -1,184 +0,0 @@
1
- import { O as ConfigLoader, j as CddExitError, Q as resolvePackageRoot, V as DEFAULT_IDLE_WINDOW_MS, W as DEFAULT_SAMPLE_INTERVAL_MS, X as spawnManaged, Y as markAllDispatchesDone, i as invariant } from '../cli.mjs';
2
- import { readFileSync, statSync, existsSync } from 'node:fs';
3
- import path from 'node:path';
4
- import { fileURLToPath } from 'node:url';
5
-
6
- function loadContract() {
7
- return new ConfigLoader().contextContract();
8
- }
9
-
10
- function resolveRegistryPath(fromDir = path.dirname(fileURLToPath(import.meta.url))) {
11
- const root = resolvePackageRoot(fromDir);
12
- const published = path.join(root, "dist", "resources", "harness-registry.json");
13
- if (existsSync(published)) return published;
14
- return path.join(root, "src", "infra", "harness-registry.json");
15
- }
16
- const REG_PATH = resolveRegistryPath();
17
- class CddBlockedError extends CddExitError {
18
- constructor(message, { exitCode = 1, kind = "blocked" } = {}) {
19
- super(message, { exitCode, kind });
20
- this.name = "CddBlockedError";
21
- }
22
- }
23
- class Registry {
24
- /** Parse the shipped registry JSON (regPath default = the canonical REG_PATH). */
25
- load(regPath) {
26
- return JSON.parse(readFileSync(regPath, "utf8"));
27
- }
28
- field(reg, harness, field) {
29
- const entry = reg?.[harness];
30
- if (!entry) return "";
31
- return entry[field] ?? "";
32
- }
33
- #resolveInjectionField(entry, field, op, type) {
34
- const v = entry?.[field]?.[op] ?? "";
35
- if (v && typeof v === "object") return type ? v[type] ?? "" : "";
36
- return typeof v === "string" ? v : "";
37
- }
38
- resolveInjection(entry, op, type) {
39
- return this.#resolveInjectionField(entry, "prefix", op, type);
40
- }
41
- resolveSuffix(entry, op, type) {
42
- return this.#resolveInjectionField(entry, "suffix", op, type);
43
- }
44
- cliInPath(cli) {
45
- const pathDirs = (process.env.PATH ?? "").split(path.delimiter);
46
- for (const dir of pathDirs) {
47
- if (!dir) continue;
48
- try {
49
- const st = statSync(path.join(dir, cli));
50
- if (st.isFile() && (st.mode & 73) !== 0) return true;
51
- } catch {
52
- }
53
- }
54
- return false;
55
- }
56
- checkHarness(reg, harness, opts = {}) {
57
- const { dryRun = false } = opts ?? {};
58
- const entry = reg?.[harness];
59
- if (!entry) throw new CddBlockedError(`unknown harness: ${harness}`, { exitCode: 1 });
60
- if (entry.ship !== "full")
61
- throw new CddBlockedError(`harness not supported: ${harness}`, { exitCode: 1 });
62
- const cli = entry.cli;
63
- if (!cli) throw new CddBlockedError(`unknown harness: ${harness}`, { exitCode: 1 });
64
- if (!dryRun && !this.cliInPath(cli)) {
65
- throw new CddBlockedError(`${cli} not found in PATH`, { exitCode: 2, kind: "cli-missing" });
66
- }
67
- return entry;
68
- }
69
- // ---- spec D-3 C7: per-harness cache profile (capability as data) ----
70
- // The `cache` profile rides the registry row (mechanism / minTokens / readMultiplier /
71
- // writeMultiplier / ttlMinutes / observable), validated against templates/schema/
72
- // cache-profile-schema.json — adding a harness = one registry row, contract unchanged.
73
- cacheProfileFor(entry) {
74
- return entry?.cache ?? null;
75
- }
76
- }
77
-
78
- const CONTRACT = loadContract();
79
- const DEFAULT_TIMEOUTS = CONTRACT.timeouts.defaults;
80
- const LIVENESS_DEFAULTS = CONTRACT.timeouts.liveness ?? {};
81
- class EngineInvoker {
82
- #registry;
83
- constructor(registry = new Registry()) {
84
- this.#registry = registry;
85
- }
86
- /** resolveTerminationConfig — the single resolver for the unified termination param (T26:
87
- * replaces resolveTimeoutMs + resolveLivenessConfig). Returns the full TerminationConfig the
88
- * three dispatch islands (task / docs / branch) thread into invokeCli/spawnManaged:
89
- * budgetMs = overrides?.budgetMs ?? canonical default for mode (no env reads);
90
- * progressPath = overrides?.progressPath ?? progressPath arg (the workspace tree signal);
91
- * sampleInterval = overrides?.sampleIntervalMs ?? canonical timeouts.liveness;
92
- * idleWindowMs = overrides?.idleWindowMs ?? canonical timeouts.liveness. */
93
- resolveTerminationConfig(mode, overrides = void 0, progressPath = void 0) {
94
- return {
95
- budgetMs: overrides?.budgetMs ?? DEFAULT_TIMEOUTS[mode],
96
- progressPath: overrides?.progressPath ?? progressPath,
97
- sampleIntervalMs: overrides?.sampleIntervalMs ?? LIVENESS_DEFAULTS.sampleIntervalMs ?? DEFAULT_SAMPLE_INTERVAL_MS,
98
- idleWindowMs: overrides?.idleWindowMs ?? LIVENESS_DEFAULTS.idleWindowMs ?? DEFAULT_IDLE_WINDOW_MS
99
- };
100
- }
101
- // Credentials stripping lives at the single spawn choke point in proc.ts (spawnManaged) — invoke.ts
102
- // keeps no duplicate cleanEnv (branch-review warn 1 of the .mjs era: double stripping is dead code).
103
- /** [registry prefix, prompt, suffix] joined on newlines (C1: prefix precedes the prompt). */
104
- promptArgText(prefix, prompt, suffix) {
105
- return [prefix, prompt, suffix].filter(Boolean).join("\n");
106
- }
107
- /** invoke-spec words + the prompt arg last (the exact legacy args shape). */
108
- buildInvokeArgs(invokeSpec, promptArg) {
109
- return [...invokeSpec.split(/\s+/).filter(Boolean), promptArg];
110
- }
111
- /** Resolve the op×type prefix/suffix and compose the full dispatch set. */
112
- composeDispatchSet(entry, params, prompt, cwd, env) {
113
- const paramsObj = typeof params === "string" ? { op: params } : params ?? {};
114
- const { op, type } = paramsObj;
115
- const p = this.#registry.resolveInjection(entry, op, type);
116
- const s = this.#registry.resolveSuffix(entry, op, type);
117
- const promptArg = this.promptArgText(p, prompt, s);
118
- return { cli: entry.cli, args: this.buildInvokeArgs(entry.invoke, promptArg), cwd, env };
119
- }
120
- // Invoke CLI: build args from entry, handle stream-json output mode.
121
- // params = { op, type? } — operation×type injection replaces the positional mode arg. op:
122
- // implement|review|fix (review carries type: task|branch|spec|plan). Resolution happens in
123
- // registry.ts resolveInjection/resolveSuffix (entry.{prefix,suffix}[op][type?]), never inlined here.
124
- // Legacy compat: a flat string mode key hits directly through the same resolver.
125
- async invokeCli(entry, prompt, params, env, cwd, termination) {
126
- const set = this.composeDispatchSet(entry, params, prompt, cwd, env);
127
- const res = await spawnManaged(set.cli, set.args, { cwd: set.cwd, env: set.env, termination });
128
- markAllDispatchesDone();
129
- if (res.ok && entry.output === "stream-json") {
130
- const finalText = extractStreamJsonFinal(res.stdout);
131
- if (!finalText) {
132
- return {
133
- ok: false,
134
- code: 1,
135
- stdout: res.stdout,
136
- stderr: "stream-json produced no completion finalText",
137
- timedOut: res.timedOut === true,
138
- cause: res.cause
139
- };
140
- }
141
- return {
142
- ok: true,
143
- code: 0,
144
- stdout: finalText,
145
- stderr: res.stderr,
146
- timedOut: res.timedOut === true,
147
- cause: res.cause
148
- };
149
- }
150
- return res;
151
- }
152
- // Transient retry wrapper for invokeCli (#109 fix). Retries only overloaded/rate_limit/529 stderr,
153
- // never on timeout. params { op, type? } threads the same signature as invokeCli.
154
- async invokeCliWithRetry(entry, prompt, params, env, cwd, termination) {
155
- const MAX_RETRIES = RETRY_DELAYS_MS.length;
156
- for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
157
- const result = await this.invokeCli(entry, prompt, params, env, cwd, termination);
158
- if (result.ok || result.timedOut) return result;
159
- const isTransient = /overloaded|rate_limit|529/.test(result.stderr ?? "");
160
- if (isTransient && attempt < MAX_RETRIES) {
161
- await new Promise((r) => setTimeout(r, RETRY_DELAYS_MS[attempt]));
162
- continue;
163
- }
164
- return result;
165
- }
166
- invariant(false, "unreachable: retry loop always returns");
167
- }
168
- }
169
- const RETRY_DELAYS_MS = [5e3, 15e3];
170
- function extractStreamJsonFinal(raw) {
171
- let last = null;
172
- for (const line of String(raw).split("\n")) {
173
- const trimmed = line.trim();
174
- if (!trimmed) continue;
175
- try {
176
- const ev = JSON.parse(trimmed);
177
- if (ev.type === "completion" && ev.finalText != null) last = ev.finalText;
178
- } catch {
179
- }
180
- }
181
- return last;
182
- }
183
-
184
- export { CddBlockedError as C, EngineInvoker as E, Registry as R, REG_PATH as a };
@@ -1,302 +0,0 @@
1
- {
2
- "$schema": "http://json-schema.org/draft-07/schema#",
3
- "$version": 1,
4
- "contextContract": {
5
- "channels": {
6
- "argv": {
7
- "plan": {
8
- "flag": "--plan",
9
- "type": "path"
10
- },
11
- "spec": {
12
- "flag": "--spec",
13
- "type": "path"
14
- },
15
- "findings": {
16
- "flag": "--findings",
17
- "type": "path"
18
- },
19
- "tasks": {
20
- "flag": "--tasks",
21
- "type": "int-list"
22
- },
23
- "type": {
24
- "flag": "--type",
25
- "type": "enum",
26
- "values": [
27
- "task",
28
- "branch",
29
- "spec",
30
- "plan"
31
- ]
32
- },
33
- "base": {
34
- "flag": "--base",
35
- "type": "sha"
36
- },
37
- "head": {
38
- "flag": "--head",
39
- "type": "sha"
40
- },
41
- "round": {
42
- "flag": "--round",
43
- "type": "int"
44
- },
45
- "source": {
46
- "flag": "--source",
47
- "type": "enum",
48
- "values": [
49
- "plan-field",
50
- "branch-upstream",
51
- "conversation-context",
52
- "user-confirmed"
53
- ]
54
- },
55
- "force": {
56
- "flag": "--force",
57
- "type": "bool"
58
- },
59
- "dryRun": {
60
- "flag": "--dry-run",
61
- "type": "bool",
62
- "scope": "program"
63
- },
64
- "help": {
65
- "flag": "--help",
66
- "alias": "-h",
67
- "type": "bool",
68
- "scope": "program"
69
- }
70
- },
71
- "git": {
72
- "root": {
73
- "derivation": "gitToplevel(cwd)"
74
- }
75
- },
76
- "env": {
77
- "hostHarness": {
78
- "markers": [
79
- "CURSOR_TRACE_ID",
80
- "CLAUDE_CODE_SESSION_ID",
81
- "AI_AGENT"
82
- ]
83
- },
84
- "path": {
85
- "var": "PATH"
86
- }
87
- }
88
- },
89
- "derived": {
90
- "root": {
91
- "from": [
92
- "git.root"
93
- ]
94
- },
95
- "slug": {
96
- "from": [
97
- "plan"
98
- ]
99
- },
100
- "workspace": {
101
- "from": [
102
- "root",
103
- "slug"
104
- ]
105
- },
106
- "handoffPath": {
107
- "from": [
108
- "workspace",
109
- "mode",
110
- "tasks",
111
- "round"
112
- ]
113
- },
114
- "briefPath": {
115
- "from": [
116
- "workspace",
117
- "tasks"
118
- ]
119
- },
120
- "ledgerPath": {
121
- "from": [
122
- "workspace"
123
- ]
124
- },
125
- "constraintsPath": {
126
- "from": [
127
- "workspace"
128
- ]
129
- },
130
- "findingsPath": {
131
- "from": [
132
- "workspace",
133
- "tasks"
134
- ]
135
- },
136
- "fixedPoint": {
137
- "from": [
138
- "prevHandoff",
139
- "commits.base"
140
- ]
141
- }
142
- },
143
- "transport": {
144
- "childEnv": {
145
- "policy": "host-env-minus-credentials",
146
- "cddVarsInjected": []
147
- }
148
- },
149
- "timeouts": {
150
- "defaults": {
151
- "task": 10800000,
152
- "review": 3600000
153
- },
154
- "liveness": {
155
- "sampleIntervalMs": 60000,
156
- "idleWindowMs": 900000
157
- }
158
- }
159
- },
160
- "failureCategories": {
161
- "categories": [
162
- {
163
- "id": "TIMEOUT",
164
- "countsTowardConvergence": false,
165
- "counter": "timeoutCount",
166
- "returnMarker": "timeout",
167
- "terminal": "BLOCKED: dispatch-timeout-cap"
168
- },
169
- {
170
- "id": "CONTRACT_VIOLATION",
171
- "countsTowardConvergence": false,
172
- "counter": "contractViolationCount",
173
- "returnMarker": "contract-violation",
174
- "terminal": "BLOCKED: contract-violation-exhausted",
175
- "dispatchIncomplete": true
176
- },
177
- {
178
- "id": "ENGINE_SELF_WRITTEN",
179
- "countsTowardConvergence": false,
180
- "counter": "engineSelfWrittenCount",
181
- "returnMarker": "engine-self-written",
182
- "terminal": "BLOCKED: engine-self-written-exhausted",
183
- "dispatchIncomplete": true
184
- },
185
- {
186
- "id": "EXECUTION_FAILURE",
187
- "countsTowardConvergence": false,
188
- "counter": "engineRecoveryCount",
189
- "returnMarker": "recovery",
190
- "terminal": "BLOCKED: engine-error"
191
- },
192
- {
193
- "id": "UNVERIFIABLE",
194
- "countsTowardConvergence": false
195
- },
196
- {
197
- "id": "PLAN_CONFLICT",
198
- "countsTowardConvergence": false
199
- }
200
- ]
201
- },
202
- "handoffNamespace": {
203
- "schema": 1,
204
- "workspaceRoot": ".osuperpowers/cdd",
205
- "slugRule": "strip .md, then a single trailing -design or -plan suffix",
206
- "families": {
207
- "implement.task": {
208
- "name": "tasks-{tasks}-implement.json",
209
- "round": "fixed",
210
- "status": "contract",
211
- "schema": "task",
212
- "phase": "implement"
213
- },
214
- "review.task": {
215
- "name": "tasks-{tasks}-review-{round}.json",
216
- "round": "increment",
217
- "status": "rollup",
218
- "schema": "task",
219
- "returnFormat": "RETURN_STDOUT_BLOCK",
220
- "phase": "review",
221
- "fixFamily": "fix.task",
222
- "prev": {
223
- "round1": "implement.task",
224
- "roundR": "fix.task:R-1"
225
- }
226
- },
227
- "fix.task": {
228
- "name": "tasks-{tasks}-fix-{round}.json",
229
- "round": "source",
230
- "status": "contract",
231
- "schema": "task",
232
- "fixTemplate": "fix",
233
- "phase": "fix",
234
- "prev": {
235
- "roundR": "review.task:R"
236
- }
237
- },
238
- "review.spec": {
239
- "name": "spec-review-{round}.json",
240
- "round": "increment",
241
- "status": "rollup",
242
- "schema": "docs",
243
- "returnFormat": "RETURN_JSON",
244
- "phase": "review",
245
- "fixFamily": "fix.spec"
246
- },
247
- "fix.spec": {
248
- "name": "spec-fix-{round}.json",
249
- "round": "source",
250
- "status": "contract",
251
- "schema": "docs",
252
- "fixTemplate": "docs",
253
- "returnFormat": "RETURN_JSON",
254
- "phase": "fix",
255
- "prev": {
256
- "roundR": "review.spec:R"
257
- }
258
- },
259
- "review.plan": {
260
- "name": "plan-review-{round}.json",
261
- "round": "increment",
262
- "status": "rollup",
263
- "schema": "docs",
264
- "returnFormat": "RETURN_JSON",
265
- "phase": "review",
266
- "fixFamily": "fix.plan"
267
- },
268
- "fix.plan": {
269
- "name": "plan-fix-{round}.json",
270
- "round": "source",
271
- "status": "contract",
272
- "schema": "docs",
273
- "fixTemplate": "docs",
274
- "returnFormat": "RETURN_JSON",
275
- "phase": "fix",
276
- "prev": {
277
- "roundR": "review.plan:R"
278
- }
279
- },
280
- "review.branch": {
281
- "name": "branch-review-{base7}..{head7}-r{round}.json",
282
- "round": "increment",
283
- "status": "rollup",
284
- "schema": "task",
285
- "returnFormat": "RETURN_STDOUT_BLOCK",
286
- "phase": "branch-review"
287
- },
288
- "fix.branch": {
289
- "name": "branch-fix-{base7}..{head7}-r{round}.json",
290
- "round": "source",
291
- "status": "contract",
292
- "schema": "task",
293
- "fixTemplate": "fix",
294
- "returnFormat": "RETURN_STDOUT_BLOCK",
295
- "phase": "fix",
296
- "prev": {
297
- "roundR": "review.branch:R"
298
- }
299
- }
300
- }
301
- }
302
- }
@@ -1,23 +0,0 @@
1
- {
2
- "$schema": "http://json-schema.org/draft-07/schema#",
3
- "title": "CDD harness cache profile (harness-registry.json#cache)",
4
- "description": "Per-harness prompt-cache capability profile (spec D-3 C7). New harness = append a registry row + profile; capability is data, zero contract changes.",
5
- "type": "object",
6
- "required": ["mechanism", "minTokens"],
7
- "properties": {
8
- "mechanism": {
9
- "enum": ["explicit", "auto-prefix", "implicit"]
10
- },
11
- "minTokens": {
12
- "oneOf": [
13
- { "type": "integer", "minimum": 1 },
14
- { "enum": ["pending"] }
15
- ]
16
- },
17
- "readMultiplier": { "type": "number", "exclusiveMinimum": 0 },
18
- "writeMultiplier": { "type": "number", "exclusiveMinimum": 0 },
19
- "ttlMinutes": { "type": "integer", "minimum": 0 },
20
- "observable": { "type": "boolean" }
21
- },
22
- "additionalProperties": false
23
- }
@@ -1,129 +0,0 @@
1
- {
2
- "$schema": "http://json-schema.org/draft-07/schema#",
3
- "description": "Docs-family handoff contract (spec / plan review + fix rounds; the docs-family shell + return constants live in template-contract.json#sections). Doc identity is doc_path + doc_hash; write findings, not status — the engine derives status from findings (review) or trusts the declared status (fix). Each property below documents its rule. Breaking change (engine major): the docs handoff carries the same lifecycle contract core as the task family — status gains TIMEOUT and commits{base,head} lands (the reverse of the legacy 'Docs rounds carry no commits field' declaration); docs consumers that relied on the commits-free docs handoff must migrate to the unified core.",
4
- "type": "object",
5
- "required": ["phase", "findings", "artifacts", "doc_path"],
6
- "properties": {
7
- "phase": { "type": "string", "enum": ["review", "fix"], "description": "dispatch phase (review / fix); determined by the engine, not authored." },
8
- "status": { "type": "string", "enum": ["APPROVED", "BLOCKED", "CHANGES_REQUESTED", "REVIEW_FIX", "TIMEOUT"], "description": "The round conclusion (this dispatch's terminal result) — APPROVED: done; CHANGES_REQUESTED: fix the findings (terminal conclusion of a review round; the fix loop runs as its own dispatch); REVIEW_FIX: the warn/nit-only review conclusion (收口态 — the review closed and its fix round routes the task to complete without a re-review, #278); BLOCKED: the round cannot proceed — the failure mechanism lives in failure_category, the reason in blocker; TIMEOUT: budget or liveness exceeded (engine-written attribution; the docs channel declares the same status enum as the task family). Orthogonal surfaces: failure_category (mechanism channel) and unverifiable[]/plan_conflicts[] (content-level notes) never fold into status. Review may omit this field — the engine derives it from findings; fix (work type) declares it and the engine passes it through. Write findings, not status." },
9
- "failure_category": {
10
- "type": "string",
11
- "enum": [
12
- "TIMEOUT",
13
- "CONTRACT_VIOLATION",
14
- "ENGINE_SELF_WRITTEN",
15
- "EXECUTION_FAILURE",
16
- "UNVERIFIABLE",
17
- "PLAN_CONFLICT"
18
- ],
19
- "description": "Failure mechanism channel — which mechanism ended the round (TIMEOUT / CONTRACT_VIOLATION / ENGINE_SELF_WRITTEN / EXECUTION_FAILURE / UNVERIFIABLE / PLAN_CONFLICT). Orthogonal to status (the round conclusion) and to the content-level unverifiable[]/plan_conflicts[] notes. Engine-written on failure paths. A BLOCKED round may satisfy its grounding via this field (see allOf)."
20
- },
21
- "commits": {
22
- "type": "object",
23
- "required": [
24
- "base"
25
- ],
26
- "description": "commit identity of the dispatch's review/fix range; the template-contract review range check at 13.5 validates it.",
27
- "properties": {
28
- "base": {
29
- "type": "string",
30
- "pattern": "^[0-9a-f]{40}$",
31
- "description": "range base (TASK_BASE / FIXED_POINT): full 40-char SHA; never --short / %h / any truncated form."
32
- },
33
- "head": {
34
- "type": "string",
35
- "pattern": "^[0-9a-f]{40}$",
36
- "description": "full 40-char SHA; never --short / %h / any truncated form. Optional — omitted when the round has no head yet (e.g. some BLOCKED branch-review payloads)."
37
- }
38
- }
39
- },
40
- "doc_path": { "type": "string", "description": "the reviewed document's exact path — must match the doc argument, do not rewrite relative forms." },
41
- "doc_hash": { "type": "string", "description": "content state token (sha256 of the doc at review time); legacy handoffs may omit it." },
42
- "findings": { "type": "array", "description": "[{lens, severity, section|file, line?, summary, fix}] — every review finding; severity blocker → CHANGES_REQUESTED, warn/nit → REVIEW_FIX (review rolls up; fix keeps declared findings, #278)." },
43
- "changes": {
44
- "type": "array",
45
- "items": {
46
- "type": "object",
47
- "required": ["file"],
48
- "properties": {
49
- "file": { "type": "string", "description": "repo-relative path of a file this round changed." },
50
- "reason": { "type": "string", "description": "why the file changed (finding id / fix intent); omitted entries stay attributed by file." }
51
- }
52
- },
53
- "description": "Changed-file attribution ledger (fix rounds declare every file the round touched, each with its reason). The engine reconciles `git diff <base>..HEAD` against it — files off the ledger are surfaced (warn + notes), never blocked; the review scope axis judges them as findings. The docs commitment boundary is the same as the task family (commits{base,head}), not doc_path alone."
54
- },
55
- "recovery": {
56
- "type": "object",
57
- "required": ["cause"],
58
- "properties": {
59
- "cause": { "type": "string", "description": "round-end cause: the failure-category id (EXECUTION_FAILURE / TIMEOUT — the residue-preservation eligibility set) on engine-written death carriers, or the termination sub-cause on legacy salvage records." },
60
- "exit_code": { "type": "integer", "description": "the failed agent's process exit code (1 = run failure, 143 = SIGTERM) — the archived death diagnosis distinguishing exit 1 vs 143; absent on TIMEOUT rounds (the monitor killed the process)." },
61
- "residue_ref": { "type": "string", "description": "Salvaged-WIP stash commit SHA (index-independent: `stash@{N}` indices shift on every push/drop). Written by the residue settlement step on eligible EXECUTION_FAILURE/TIMEOUT rounds with a dirty tree; the re-dispatch resume pre-flight reads it and `git stash apply`s it. Settlement output ≡ resume input." },
62
- "wip_stat": { "type": "object", "required": ["files", "insertions", "deletions"], "properties": { "files": { "type": "integer" }, "insertions": { "type": "integer" }, "deletions": { "type": "integer" } }, "description": "structured WIP scale (files / +M / -M) at salvage time — the recovery carrier's archivable magnitude beside residue_ref; counts brand-new untracked files too." },
63
- "preserved": { "type": "boolean", "description": "true when the round's residue was stashed into the recovery carrier (residue_ref + wip_stat present); the settlement step's idempotence flag — an already-preserved carrier never double-stashes." },
64
- "stash_message": { "type": "string", "description": "The standardized stash name `cdd-<op>-<type>-<task>-r<round>-<cause>` (src/artifacts/residue.ts single source) — the legacy stash-list scan matches on it for pre-schema carriers." },
65
- "residue_scope": { "type": "string", "description": "WIP scope summary (`git diff HEAD --shortstat`) — data-driven input for the resume brief appendix." },
66
- "round": { "type": "integer", "minimum": 1, "description": "the salvaged round number (implement rounds are always round 1)." },
67
- "scope_base": { "type": "string", "pattern": "^[0-9a-f]{40}$", "description": "The round-level scope anchor at salvage time (ledger value priority / fallback dead-round brief TASK_BASE). Resume restores the same anchor — the round-BASE (resume-declared) adoption and the recovered scope stay consistent across round death." }
68
- },
69
- "additionalProperties": false,
70
- "description": "Residue recovery carrier — engine-written on EXECUTION_FAILURE/TIMEOUT failure rounds: cause + exit_code ride every death (the archived, replayable diagnosis); residue_ref / wip_stat / preserved appear once the settlement step stashed the dirty-tree WIP. Absent on all other rounds. Same law as every structured field: the facts live here, the blocker stays human-readable prose."
71
- },
72
- "artifacts": { "type": "object", "description": "point at files, do not embed report bodies — values are paths (e.g. {\"doc\": \"<path>\"}), never inline content." },
73
- "round": { "type": "integer", "description": "review/fix round number (engine-derived; canonical naming embeds it in the filename)." },
74
- "unverifiable": {
75
- "type": "array",
76
- "description": "Content-level notes — each entry states one claim the round could not verify (what + why: e.g. {claim, why}). A non-empty list makes the round BLOCKED with failure_category UNVERIFIABLE and a blocker summarizing the entries. Dev-measured acceptance items (plan-constraints §口径) are NOT unverifiable: an evidence-contract accepted-noted round records them in `notes`, never writes unverifiable and never blocks."
77
- },
78
- "plan_conflicts": {
79
- "type": "array",
80
- "description": "Content-level notes — each entry states one plan conflict discovered during the round. A non-empty list makes the round BLOCKED with failure_category PLAN_CONFLICT and a blocker summarizing the entries."
81
- },
82
- "blocker": { "type": "string", "description": "The round's single real blocker line — states what could not be verified and why, or the concrete reason the round cannot proceed. Real sources only (agent-declared / engine gate reason / failure mechanism / unverifiable summary); never fabricated. Omit when nothing blocks (NOT null) — null is invalid. BLOCKED requires a non-empty blocker or a failure_category (see allOf)." }
83
- },
84
- "allOf": [
85
- {
86
- "if": {
87
- "properties": {
88
- "phase": {
89
- "const": "review"
90
- }
91
- },
92
- "required": ["phase"]
93
- },
94
- "then": {
95
- "required": []
96
- },
97
- "else": {
98
- "required": ["status"]
99
- }
100
- },
101
- {
102
- "if": {
103
- "properties": {
104
- "status": {
105
- "const": "BLOCKED"
106
- }
107
- },
108
- "required": ["status"]
109
- },
110
- "then": {
111
- "anyOf": [
112
- {
113
- "required": ["blocker"],
114
- "properties": {
115
- "blocker": {
116
- "type": "string",
117
- "minLength": 1
118
- }
119
- }
120
- },
121
- {
122
- "required": ["failure_category"]
123
- }
124
- ]
125
- }
126
- }
127
- ],
128
- "additionalProperties": false
129
- }