@oscaner-skills/cdd-engine 2.0.0 → 3.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/README.zh-CN.md +2 -2
- package/{src-next/bin.ts → dist/bin.js} +18 -21
- package/dist/contract/declare.js +998 -0
- package/dist/contract/doc.js +565 -0
- package/dist/contract/frontmatter.js +209 -0
- package/dist/contract/home-extractors.js +379 -0
- package/dist/contract/invariants.js +1030 -0
- package/dist/contract/judge.js +109 -0
- package/dist/contract/lint.js +206 -0
- package/dist/contract/project.js +371 -0
- package/dist/contract/skill-anatomy.js +156 -0
- package/dist/contract/translate.js +85 -0
- package/dist/face/artifacts.js +189 -0
- package/dist/face/board-view.js +522 -0
- package/dist/face/capsule.js +141 -0
- package/dist/face/cli.js +891 -0
- package/dist/face/declare.js +241 -0
- package/dist/face/gate.js +158 -0
- package/dist/face/graph-view.js +66 -0
- package/dist/face/host.js +211 -0
- package/dist/face/lifecycle.js +603 -0
- package/dist/face/preview.js +136 -0
- package/dist/face/projection.js +259 -0
- package/dist/face/route-render.js +162 -0
- package/dist/face/termination.js +482 -0
- package/dist/face/words.js +220 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/dist/infra/doc-roots.js +19 -0
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/dist/infra/root.js +62 -0
- package/dist/infra/runtime.js +85 -0
- package/dist/infra/workspace.js +276 -0
- package/dist/render/brief.js +82 -0
- package/dist/render/issue-body.js +129 -0
- package/dist/render/skeleton.js +434 -0
- package/dist/render/templates.js +520 -0
- package/dist/session/faces.js +38 -0
- package/dist/session/graph.js +309 -0
- package/dist/session/handoff-schema.js +295 -0
- package/dist/session/ledger.js +762 -0
- package/dist/session/next.js +211 -0
- package/dist/session/preflight.js +194 -0
- package/dist/session/round-naming.js +73 -0
- package/dist/session/run.js +441 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +8 -7
- package/templates/report/issue-body.json +0 -46
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/smoke.integration.test.ts +0 -202
- package/src-next/__tests__/zero-dep.test.ts +0 -134
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
- package/src-next/contract/__tests__/declare.test.ts +0 -242
- package/src-next/contract/__tests__/doc.test.ts +0 -358
- package/src-next/contract/__tests__/judge.test.ts +0 -873
- package/src-next/contract/__tests__/lint.test.ts +0 -314
- package/src-next/contract/__tests__/project.test.ts +0 -419
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -983
- package/src-next/contract/doc.ts +0 -753
- package/src-next/contract/invariants.ts +0 -1268
- package/src-next/contract/judge.ts +0 -142
- package/src-next/contract/lint.ts +0 -275
- package/src-next/contract/project.ts +0 -596
- package/src-next/contract/skill-anatomy.ts +0 -273
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -948
- package/src-next/face/__tests__/capsule.test.ts +0 -276
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
- package/src-next/face/__tests__/cli.test.ts +0 -4643
- package/src-next/face/__tests__/face.test.ts +0 -289
- package/src-next/face/__tests__/graph-view.test.ts +0 -61
- package/src-next/face/__tests__/host.test.ts +0 -24
- package/src-next/face/__tests__/negation.ts +0 -6
- package/src-next/face/__tests__/projection.test.ts +0 -301
- package/src-next/face/__tests__/sync-runner.test.ts +0 -70
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -195
- package/src-next/face/board-view.ts +0 -662
- package/src-next/face/capsule.ts +0 -149
- package/src-next/face/cli.ts +0 -819
- package/src-next/face/declare.ts +0 -326
- package/src-next/face/gate.ts +0 -170
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -326
- package/src-next/face/lifecycle.ts +0 -700
- package/src-next/face/projection.ts +0 -282
- package/src-next/face/route-render.ts +0 -160
- package/src-next/face/words.ts +0 -296
- package/src-next/infra/__tests__/infra.test.ts +0 -287
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -185
- package/src-next/infra/workspace.ts +0 -232
- package/src-next/render/__tests__/render.test.ts +0 -499
- package/src-next/render/__tests__/skeleton.test.ts +0 -466
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -159
- package/src-next/render/skeleton.ts +0 -437
- package/src-next/render/templates.ts +0 -650
- package/src-next/session/__tests__/graph.test.ts +0 -270
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
- package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
- package/src-next/session/__tests__/ledger.test.ts +0 -744
- package/src-next/session/__tests__/next.test.ts +0 -368
- package/src-next/session/__tests__/preflight.test.ts +0 -491
- package/src-next/session/__tests__/run.test.ts +0 -1014
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -469
- package/src-next/session/faces.ts +0 -110
- package/src-next/session/graph.ts +0 -411
- package/src-next/session/handoff-schema.ts +0 -373
- package/src-next/session/ledger.ts +0 -1004
- package/src-next/session/next.ts +0 -192
- package/src-next/session/preflight.ts +0 -240
- package/src-next/session/run.ts +0 -606
- package/src-next/session/state.ts +0 -30
- package/src-next/session/wave.ts +0 -139
|
@@ -1,700 +0,0 @@
|
|
|
1
|
-
// packages/cdd-engine/src-next/face/lifecycle.ts
|
|
2
|
-
// T8 — the lifecycle face (the split contract §6.2: face/cli.ts slims to composition).
|
|
3
|
-
// The dispatch seam's production default lives here — CliLifecycle (the former
|
|
4
|
-
// HarnessDispatch composition member, renamed by the split; face/cli.ts re-exports it
|
|
5
|
-
// as HarnessDispatch so the public surface is unchanged) — the dispatch + readback +
|
|
6
|
-
// round-context plane (§6.2: implement/review/fix dispatch, the read-back reconstruct
|
|
7
|
-
// (#reconstruct/#reject/#materialize + carrier helpers), the round-context data
|
|
8
|
-
// (#valuesOf/#childPrompt/round-context fact assembly)). The shared seams the
|
|
9
|
-
// lifecycle rides (cli io / sync process / env / scene) are declared here too — the
|
|
10
|
-
// root composition imports them back (zero public-export drift, zero import cycle).
|
|
11
|
-
// The root Cli holds the lifecycle instances and composes through them via its .action
|
|
12
|
-
// thin shells — zero bare functions; every collaborator stays injectable (the tests
|
|
13
|
-
// substitute the hermetic ones).
|
|
14
|
-
|
|
15
|
-
// The module exports the shared seams + the lifecycle class — zero behavior-carrying
|
|
16
|
-
// bare functions.
|
|
17
|
-
|
|
18
|
-
import process from "node:process";
|
|
19
|
-
import { execaSync } from "execa";
|
|
20
|
-
import { printParseErrorCode } from "jsonc-parser";
|
|
21
|
-
import { ConfigLoader } from "../infra/config.ts";
|
|
22
|
-
import type { HandoffFamily } from "../infra/runtime.ts";
|
|
23
|
-
import type { Workspace } from "../infra/workspace.ts";
|
|
24
|
-
import type { TemplateValues, WorkMode } from "../render/templates.ts";
|
|
25
|
-
import { TemplateAssembler } from "../render/templates.ts";
|
|
26
|
-
import type { HandoffSchemaFace } from "../session/handoff-schema.ts";
|
|
27
|
-
import { HandoffSchema } from "../session/handoff-schema.ts";
|
|
28
|
-
import type { Ledger, OpType, RoundStatus } from "../session/ledger.ts";
|
|
29
|
-
import type { DispatchOutcome, DispatchStep, OpenFrame } from "../session/run.ts";
|
|
30
|
-
import { DISPATCH, HOSTS, HostDetect, type HostId, type HostReferenceTable, REFS } from "./host.ts";
|
|
31
|
-
|
|
32
|
-
// ---------------------------------------------------------------------------
|
|
33
|
-
// the stable seams — the shared faces the composition root + the lifecycle ride
|
|
34
|
-
// (declared here, re-exported by face/cli.ts so the public surface never drifts)
|
|
35
|
-
// ---------------------------------------------------------------------------
|
|
36
|
-
|
|
37
|
-
/** The CLI io seam — production wraps process stdio; tests capture. */
|
|
38
|
-
export interface CliIo {
|
|
39
|
-
stdout(text: string): void;
|
|
40
|
-
stderr(text: string): void;
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
// ---------------------------------------------------------------------------
|
|
44
|
-
// the sync process seam + the harness dispatch (the production dispatch default)
|
|
45
|
-
// ---------------------------------------------------------------------------
|
|
46
|
-
|
|
47
|
-
/** The sync child-process face — the fail-open subprocess seam the harness dispatch
|
|
48
|
-
* runs through (a non-zero/broken child rides the code, never a throw). */
|
|
49
|
-
export interface SyncProcess {
|
|
50
|
-
run(
|
|
51
|
-
command: string,
|
|
52
|
-
args: readonly string[],
|
|
53
|
-
cwd: string,
|
|
54
|
-
): { code: number; stdout: string; stderr: string };
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
/** SyncRunner — the unbounded sync child channel (spec §14 · D36): execa's
|
|
58
|
-
* synchronous face, which imposes no output-buffer ceiling — the whole-buffer
|
|
59
|
-
* cap class the retired built-in call hit (a fixed 1 MiB default, the W1
|
|
60
|
-
* `child claude returned no status line` truncation) does not exist here. The
|
|
61
|
-
* face stays synchronous (the T8 lifecycle's DispatchStep seam is one dispatch,
|
|
62
|
-
* one advance) and keeps the injected `SyncProcess` shape byte-for-byte: a
|
|
63
|
-
* non-zero/broken child rides the code, never a throw — `reject: false` surfaces
|
|
64
|
-
* the failure as a result, and `stripFinalNewline: false` keeps the child's
|
|
65
|
-
* stdout verbatim (the `RETURN_STDOUT_BLOCK` tail stays intact). The adapter is
|
|
66
|
-
* a pure `#collect` read: no buffering to bound, no worker, no concurrency. */
|
|
67
|
-
export class SyncRunner implements SyncProcess {
|
|
68
|
-
run(
|
|
69
|
-
command: string,
|
|
70
|
-
args: readonly string[],
|
|
71
|
-
cwd: string,
|
|
72
|
-
): { code: number; stdout: string; stderr: string } {
|
|
73
|
-
return this.#collect(command, args, cwd);
|
|
74
|
-
}
|
|
75
|
-
|
|
76
|
-
/** The synchronous collection — execa's sync face with the three options the
|
|
77
|
-
* fail-open `SyncProcess` contract needs: `reject: false` (a failed child is a
|
|
78
|
-
* result, never a throw), `stripFinalNewline: false` (byte-verbatim stdout), and
|
|
79
|
-
* the default unbounded output buffer (the cap class is retired). The result
|
|
80
|
-
* reads back into the same `{code, stdout, stderr}` face — `exitCode ?? 1` is the
|
|
81
|
-
* exit code; stderr is the child's own stream when it wrote one, else the execa
|
|
82
|
-
* diagnostic (a spawn failure like ENOENT writes nothing, so its reason rides the
|
|
83
|
-
* `shortMessage` — the fail-open face keeps a reason text, never an empty block). */
|
|
84
|
-
#collect(
|
|
85
|
-
command: string,
|
|
86
|
-
args: readonly string[],
|
|
87
|
-
cwd: string,
|
|
88
|
-
): { code: number; stdout: string; stderr: string } {
|
|
89
|
-
const result = execaSync(command, [...args], {
|
|
90
|
-
cwd,
|
|
91
|
-
reject: false,
|
|
92
|
-
stripFinalNewline: false,
|
|
93
|
-
});
|
|
94
|
-
return {
|
|
95
|
-
code: result.exitCode ?? 1,
|
|
96
|
-
stdout: result.stdout ?? "",
|
|
97
|
-
stderr: result.stderr || (result.failed ? (result.shortMessage ?? "") : ""),
|
|
98
|
-
};
|
|
99
|
-
}
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
/** The environment face the harness dispatch detects the host against. */
|
|
103
|
-
export type ProcessEnvLike = Record<string, string | undefined>;
|
|
104
|
-
|
|
105
|
-
/** One dispatch scene — the per-invocation composition the work commands assemble
|
|
106
|
-
* (the workspace + ledger the frame's round rides, the plan/brief paths the prompt
|
|
107
|
-
* references, the base artifact's branch name the branch review's scope anchor
|
|
108
|
-
* (BASE_BRANCH) derives). */
|
|
109
|
-
export interface DispatchScene {
|
|
110
|
-
workspace: Workspace;
|
|
111
|
-
ledger: Ledger;
|
|
112
|
-
planPath: string | null;
|
|
113
|
-
briefPath: string | null;
|
|
114
|
-
baseBranch?: string | null;
|
|
115
|
-
}
|
|
116
|
-
|
|
117
|
-
/**
|
|
118
|
-
* CliLifecycle — the lifecycle's dispatch-seam production default (the split contract's
|
|
119
|
-
* lifecycle face; face/cli.ts re-exports it as HarnessDispatch so the composition
|
|
120
|
-
* surface keeps its name). `step()` returns the DispatchStep the lifecycle runs, which
|
|
121
|
-
* assembles the dispatch prompt (the render template-contract data plane) from the
|
|
122
|
-
* frame, runs the host harness CLI (the harness-contract rows: cli + invoke flags +
|
|
123
|
-
* the phase's skill-ref slash form) and parses the child's return block back into the
|
|
124
|
-
* lifecycle's outcome. Detection reads the harness-contract detect markers from the
|
|
125
|
-
* injected env — empty host → a BLOCKED outcome over the CDD_BLOCKED channel (never a
|
|
126
|
-
* thrown dispatch).
|
|
127
|
-
*/
|
|
128
|
-
export class CliLifecycle {
|
|
129
|
-
readonly #env: ProcessEnvLike;
|
|
130
|
-
readonly #cwd: string;
|
|
131
|
-
readonly #sync: SyncProcess;
|
|
132
|
-
readonly #config: ConfigLoader;
|
|
133
|
-
readonly #template: TemplateAssembler;
|
|
134
|
-
readonly #io: CliIo;
|
|
135
|
-
readonly #scene: DispatchScene;
|
|
136
|
-
readonly #findings: string | null;
|
|
137
|
-
/** The handoff-schema face — stateless, one shared instance (the read-back
|
|
138
|
-
* validator + the injected prompt text). */
|
|
139
|
-
readonly #handoffSchema = new HandoffSchema();
|
|
140
|
-
|
|
141
|
-
constructor(opts: {
|
|
142
|
-
env?: ProcessEnvLike;
|
|
143
|
-
cwd?: string;
|
|
144
|
-
sync?: SyncProcess;
|
|
145
|
-
config?: ConfigLoader;
|
|
146
|
-
template?: TemplateAssembler;
|
|
147
|
-
io?: CliIo;
|
|
148
|
-
scene: DispatchScene;
|
|
149
|
-
findings?: string | null;
|
|
150
|
-
}) {
|
|
151
|
-
this.#env = opts.env ?? process.env;
|
|
152
|
-
this.#cwd = opts.cwd ?? process.cwd();
|
|
153
|
-
this.#sync = opts.sync ?? new SyncRunner();
|
|
154
|
-
this.#config = opts.config ?? new ConfigLoader();
|
|
155
|
-
this.#template = opts.template ?? new TemplateAssembler();
|
|
156
|
-
this.#io = opts.io ?? {
|
|
157
|
-
stdout: (t) => process.stdout.write(t),
|
|
158
|
-
stderr: (t) => process.stderr.write(t),
|
|
159
|
-
};
|
|
160
|
-
this.#scene = opts.scene;
|
|
161
|
-
this.#findings = opts.findings ?? null;
|
|
162
|
-
}
|
|
163
|
-
|
|
164
|
-
/** The host-harness id detected from the env — "claude" | "cursor" | "pi" | "" —
|
|
165
|
-
* a delegation to the module-level judgment (HostDetect.detect, face/host.ts —
|
|
166
|
-
* the detection's single home; this instance method is the injectable-env
|
|
167
|
-
* adapter the lifecycle face rides, behavior unchanged). */
|
|
168
|
-
detectHost(env: ProcessEnvLike = this.#env): string {
|
|
169
|
-
return HostDetect.detect(env);
|
|
170
|
-
}
|
|
171
|
-
|
|
172
|
-
/** The DispatchStep the lifecycle runs — one frame → the outcome. */
|
|
173
|
-
step(): DispatchStep {
|
|
174
|
-
return (frame) => this.#dispatch(frame);
|
|
175
|
-
}
|
|
176
|
-
|
|
177
|
-
/** One dispatch — prompt from the template plane + the frame, host child via
|
|
178
|
-
* the harness-contract rows, the child's write-back read in (v1.9: the draft at
|
|
179
|
-
* OUTPUT_HANDOFF is the round's content — the block is the pointer). */
|
|
180
|
-
#dispatch(frame: OpenFrame): DispatchOutcome {
|
|
181
|
-
const host = this.detectHost();
|
|
182
|
-
if (host === "") {
|
|
183
|
-
this.#io.stderr(
|
|
184
|
-
"CDD_BLOCKED: no host harness detected (run cdd from within a supported harness)\n",
|
|
185
|
-
);
|
|
186
|
-
return { status: "BLOCKED" };
|
|
187
|
-
}
|
|
188
|
-
const prompt = this.#template.render(this.#valuesOf(frame));
|
|
189
|
-
const row = HOSTS[host as HostId];
|
|
190
|
-
const cliName = row.cli;
|
|
191
|
-
const args = [...row.invoke.split(" ").filter((part) => part.length > 0)];
|
|
192
|
-
const ref = this.#skillRef(host, frame);
|
|
193
|
-
// The child receives ONE prompt argument — per the host's promptForm data column
|
|
194
|
-
// (§3.5): the ref-prefixed form embeds the slash ref at the start of the single
|
|
195
|
-
// prompt positional (claude -p consumes the whole first positional as the prompt;
|
|
196
|
-
// a standalone ref arg after the flags would be swallowed, losing everything after
|
|
197
|
-
// the ref) — the prompt assembly is data, never a code assumption.
|
|
198
|
-
const result = this.#sync.run(
|
|
199
|
-
cliName,
|
|
200
|
-
[...args, this.#childPrompt(row.promptForm, ref, prompt)],
|
|
201
|
-
this.#cwd,
|
|
202
|
-
);
|
|
203
|
-
if (result.code !== 0) {
|
|
204
|
-
this.#io.stderr(`CDD_BLOCKED: child ${cliName} exited ${result.code}\n`);
|
|
205
|
-
return { status: "BLOCKED" };
|
|
206
|
-
}
|
|
207
|
-
// The three-line block is the child's termination handshake — a child that exits 0
|
|
208
|
-
// without a status line misbehaved (the abnormal face owns it; no draft read).
|
|
209
|
-
if (!/^status:\s*\S+/m.test(result.stdout)) {
|
|
210
|
-
this.#io.stderr(`CDD_BLOCKED: child ${cliName} returned no status line\n`);
|
|
211
|
-
return { status: "BLOCKED" };
|
|
212
|
-
}
|
|
213
|
-
return this.#reconstruct(frame, this.#parseBlockReturn(result.stdout));
|
|
214
|
-
}
|
|
215
|
-
|
|
216
|
-
/** The work-mode of a frame phase — branch-review rides the review family. */
|
|
217
|
-
#opOf(frame: OpenFrame): OpType {
|
|
218
|
-
return frame.phase === "branch-review" ? "review" : frame.phase;
|
|
219
|
-
}
|
|
220
|
-
|
|
221
|
-
/** The dispatch-table work-mode (ROLE) of a frame — the spec/plan fix faces ride
|
|
222
|
-
* the docs-fix mode; everything else maps by its phase (§3.5's four-mode table). */
|
|
223
|
-
#roleOf(frame: OpenFrame): WorkMode {
|
|
224
|
-
if (frame.phase === "fix") {
|
|
225
|
-
return frame.type === "spec" || frame.type === "plan" ? "docs-fix" : "fix";
|
|
226
|
-
}
|
|
227
|
-
return frame.phase === "implement" ? "implement" : "review";
|
|
228
|
-
}
|
|
229
|
-
|
|
230
|
-
/** The phase's skill-ref slash form for the detected host ("/mattpocock-skills:implement"
|
|
231
|
-
* · "/mattpocock-skills:code-review" etc.); null when the phase carries no skill
|
|
232
|
-
* ref (the fix face and the spec/plan reviews — their criteria ride the
|
|
233
|
-
* prompt's fixed body, never a slash arg). */
|
|
234
|
-
#skillRef(host: string, frame: OpenFrame): string | null {
|
|
235
|
-
const dispatch = DISPATCH;
|
|
236
|
-
let ref: unknown = null;
|
|
237
|
-
if (frame.phase === "review" || frame.phase === "branch-review") {
|
|
238
|
-
// The task/branch rows are object-shaped {ref}; the spec/plan review types
|
|
239
|
-
// carry NO dispatch row (their criteria are the review prompt's fixed body).
|
|
240
|
-
const entry = dispatch.review[frame.type as "wave" | "branch"];
|
|
241
|
-
const declaredRef = (entry as { ref?: unknown } | undefined)?.ref;
|
|
242
|
-
ref =
|
|
243
|
-
typeof declaredRef === "string" && declaredRef.startsWith("mattpocock-skills:")
|
|
244
|
-
? declaredRef
|
|
245
|
-
: null;
|
|
246
|
-
} else {
|
|
247
|
-
// The implement row is the dispatch table's single string slot; the other
|
|
248
|
-
// phases (fix) carry no dispatch row — the lookup resolves null (the fix
|
|
249
|
-
// face's ref-less face, same-shape as the spec/plan reviews).
|
|
250
|
-
const value = dispatch[frame.phase as "implement"];
|
|
251
|
-
ref = typeof value === "string" ? value : null;
|
|
252
|
-
}
|
|
253
|
-
if (typeof ref !== "string") return null;
|
|
254
|
-
const hostForm = (REFS as HostReferenceTable)[ref]?.[host as HostId];
|
|
255
|
-
return hostForm ?? null;
|
|
256
|
-
}
|
|
257
|
-
|
|
258
|
-
/** The child's single prompt argument — per the host's promptForm data contract
|
|
259
|
-
* (§3.5): the ref-prefixed form embeds the skill-ref slash form at the start of
|
|
260
|
-
* the assembled dispatch prompt as one positional (`/kairos:cdd-* <prompt>`); the
|
|
261
|
-
* plain form passes the prompt verbatim. */
|
|
262
|
-
#childPrompt(form: "ref-prefixed" | "plain", ref: string | null, prompt: string): string {
|
|
263
|
-
return form === "ref-prefixed" && ref !== null ? `${ref} ${prompt}` : prompt;
|
|
264
|
-
}
|
|
265
|
-
|
|
266
|
-
/** The round-context zone values of the dispatch prompt (the naming contract:
|
|
267
|
-
* ROLE nominative · WAVE (unit) · INPUT_* read-side · OUTPUT_* write-side · WORKSPACE_*
|
|
268
|
-
* environment · BASE_BRANCH scope anchor). Every declared token supplied — a mode's
|
|
269
|
-
* non-consumed slots stay empty and are NOT emitted by the assembler
|
|
270
|
-
* (empty-valued keys are dropped), so each mode's round context carries only the
|
|
271
|
-
* facts the mode reads. The review criteria/lens are NOT values — they fold into
|
|
272
|
-
* the review type's fixed prefix (§3.7). */
|
|
273
|
-
#valuesOf(frame: OpenFrame): TemplateValues {
|
|
274
|
-
const scene = this.#scene;
|
|
275
|
-
const op = this.#opOf(frame);
|
|
276
|
-
const role = this.#roleOf(frame);
|
|
277
|
-
const params = frame.params;
|
|
278
|
-
const isReview = frame.phase === "review" || frame.phase === "branch-review";
|
|
279
|
-
const docPath = frame.target.kind === "doc" ? frame.target.doc : null;
|
|
280
|
-
const isWave = frame.type === "wave";
|
|
281
|
-
return {
|
|
282
|
-
ROLE: role,
|
|
283
|
-
// v1.22 (wave-unitary): the wave face's scope IS the wave (the whole task list)
|
|
284
|
-
// — the round context speaks the UNIT, `WAVE`; the line faces carry their own
|
|
285
|
-
// read-side identity (INPUT_DOC — the doc/branch line's own token under the
|
|
286
|
-
// wave-unitary model).
|
|
287
|
-
WAVE: isWave ? (params.tasks ?? "") : "",
|
|
288
|
-
// The wave-brief read input — the ONE engine-rendered brief of the current
|
|
289
|
-
// dispatch (the unconditional re-extract at every dispatch makes it the pure
|
|
290
|
-
// read face of the wave line — §4.2); the non-wave faces carry no brief path
|
|
291
|
-
// (the slot stays empty, never emitted).
|
|
292
|
-
INPUT_WAVE_BRIEF: isWave ? (scene.briefPath ?? "") : "",
|
|
293
|
-
// v1.9: INPUT_FINDINGS is fix/docs-fix only — the open findings of the source
|
|
294
|
-
// review; a review writes its own draft (INPUT_FINDINGS === OUTPUT_HANDOFF
|
|
295
|
-
// would be a short-circuit).
|
|
296
|
-
INPUT_FINDINGS:
|
|
297
|
-
op === "fix"
|
|
298
|
-
? (this.#findings ?? scene.ledger.handoffPath("review", frame.type, params))
|
|
299
|
-
: "",
|
|
300
|
-
// The doc anchor — the target doc for a doc line, the plan path for a branch
|
|
301
|
-
// line (the branch review/fix judge the plan document). Empty off those faces.
|
|
302
|
-
INPUT_DOC: docPath ?? (frame.target.kind === "branch" ? (scene.planPath ?? "") : ""),
|
|
303
|
-
// The branch/wave tree-review scope anchor (BASE_BRANCH) — engine-injected
|
|
304
|
-
// from the base artifact at dispatch; empty off those faces (spec/plan reviews
|
|
305
|
-
// carry none, and the empty slot is dropped by the assembler).
|
|
306
|
-
BASE_BRANCH:
|
|
307
|
-
isReview && (frame.type === "branch" || frame.type === "wave")
|
|
308
|
-
? (scene.baseBranch ?? "")
|
|
309
|
-
: "",
|
|
310
|
-
// find #5 (P4.1 T7) — the prescribed artifact write paths (the {family}-{key}-
|
|
311
|
-
// {artifact} single naming): the round context carries the canonical OUTPUT_*
|
|
312
|
-
// names the child MUST use (zero free naming · cross-round zero overwrite); a
|
|
313
|
-
// slot the frame's family does not consume stays empty and is dropped (only
|
|
314
|
-
// present facts land). The brief is a pure read input (INPUT_WAVE_BRIEF) with
|
|
315
|
-
// no write slot.
|
|
316
|
-
OUTPUT_REPORT: this.#outputOf(frame, "report"),
|
|
317
|
-
OUTPUT_EVIDENCE: this.#outputOf(frame, "evidence"),
|
|
318
|
-
OUTPUT_HANDOFF: scene.ledger.handoffPath(op, frame.type, params),
|
|
319
|
-
REVIEW_TYPE: isReview ? frame.type : "",
|
|
320
|
-
WORKSPACE_DIR: scene.workspace.path,
|
|
321
|
-
WORKSPACE_ID: scene.workspace.slug,
|
|
322
|
-
// v1.9 — the injected writable-subset schema (projection ①): the `## Handoff
|
|
323
|
-
// schema` section of the mode's fixed prefix (byte-stable per mode; the work
|
|
324
|
-
// faces — implement/fix — carry the evidence-file fence too).
|
|
325
|
-
HANDOFF_SCHEMA: this.#schemaText(frame),
|
|
326
|
-
};
|
|
327
|
-
}
|
|
328
|
-
|
|
329
|
-
/** The canonical prescribed OUTPUT_* write path of one artifact kind (find #5 —
|
|
330
|
-
* the {family}-{key}-{artifact} single naming scheme; find #9 — branch line
|
|
331
|
-
* drops the range token: `branch-{op}{-round}-report.md` · `branch-test-evidence.json`,
|
|
332
|
-
* the branch line carries no commit identity · doc = the {type}-{op}-{round} stem,
|
|
333
|
-
* spec-review-1). "" when the frame's family does not consume the slot — only
|
|
334
|
-
* present facts ride the prompt (the assembler drops the empty-valued keys). */
|
|
335
|
-
#outputOf(frame: OpenFrame, kind: "report" | "evidence"): string {
|
|
336
|
-
const workspace = this.#scene.workspace;
|
|
337
|
-
const op = this.#opOf(frame);
|
|
338
|
-
if (frame.type === "spec" || frame.type === "plan") {
|
|
339
|
-
// The doc family — the round-keyed {type}-{op}-{round} stem (spec-review-1):
|
|
340
|
-
// every review/docs-fix round books its own report (a re-review never
|
|
341
|
-
// overwrites its predecessor); evidence is a work-family face only.
|
|
342
|
-
if (kind !== "report") return "";
|
|
343
|
-
return workspace.resolve(`${frame.type}-${op}-${frame.round}-report.md`);
|
|
344
|
-
}
|
|
345
|
-
const family = frame.type === "wave" ? `tasks-${frame.params.tasks ?? ""}` : "branch";
|
|
346
|
-
if (kind === "report") {
|
|
347
|
-
const suffix = frame.phase === "implement" ? "" : `-${frame.round}`;
|
|
348
|
-
return workspace.resolve(`${family}-${op}${suffix}-report.md`);
|
|
349
|
-
}
|
|
350
|
-
// evidence — the work faces only (implement/fix write the canonical evidence file)
|
|
351
|
-
if (frame.phase !== "implement" && frame.phase !== "fix") return "";
|
|
352
|
-
return workspace.resolve(this.#evidenceName(frame));
|
|
353
|
-
}
|
|
354
|
-
|
|
355
|
-
/** The canonical evidence file name of a work frame (find #5/#9 — the
|
|
356
|
-
* {line}-test-evidence.json form: `tasks-{tasks}-test-evidence.json` /
|
|
357
|
-
* `branch-test-evidence.json` — the branch line's row-level current state,
|
|
358
|
-
* overwritten each round (the range token left the name);
|
|
359
|
-
* the same name the read-back gate reads). The line token joins when the frame
|
|
360
|
-
* keys it (the task face) — a key-less line (branch) names the family alone. */
|
|
361
|
-
#evidenceName(frame: OpenFrame): string {
|
|
362
|
-
const key = frame.type === "wave" ? (frame.params.tasks ?? "") : "";
|
|
363
|
-
const line = key === "" ? this.#evidencePrefix(frame) : `${this.#evidencePrefix(frame)}-${key}`;
|
|
364
|
-
return `${line}-test-evidence.json`;
|
|
365
|
-
}
|
|
366
|
-
|
|
367
|
-
/** The RETURN_STDOUT_BLOCK child stdout → the outcome: the two canonical lines
|
|
368
|
-
* (status / artifacts), each key=value tokens; a missing status line is a BLOCKED
|
|
369
|
-
* outcome (only present facts land). */
|
|
370
|
-
#parseBlockReturn(stdout: string): DispatchOutcome {
|
|
371
|
-
const status = stdout.match(/^status:\s*(\S+)/m)?.[1];
|
|
372
|
-
if (status === undefined) return { status: "BLOCKED" };
|
|
373
|
-
const outcome: DispatchOutcome = { status: status as RoundStatus };
|
|
374
|
-
const artifacts = stdout.match(/^artifacts:(.*)$/m);
|
|
375
|
-
if (artifacts !== null) {
|
|
376
|
-
outcome.artifacts = {};
|
|
377
|
-
for (const pair of artifacts[1].trim().split(/\s+/)) {
|
|
378
|
-
const eq = pair.indexOf("=");
|
|
379
|
-
if (eq !== -1) outcome.artifacts[pair.slice(0, eq)] = pair.slice(eq + 1);
|
|
380
|
-
}
|
|
381
|
-
}
|
|
382
|
-
return outcome;
|
|
383
|
-
}
|
|
384
|
-
|
|
385
|
-
// -------------------------------------------------------------------------
|
|
386
|
-
// the read-back reconstruct (§3.6) — the draft is the round's content
|
|
387
|
-
// -------------------------------------------------------------------------
|
|
388
|
-
|
|
389
|
-
/** The read-back reconstruct — the child's draft at OUTPUT_HANDOFF is the round's
|
|
390
|
-
* content source of truth: read it, validate it against the mode's writable
|
|
391
|
-
* subset (projection ② of session/handoff-schema.ts — the SAME declared objects
|
|
392
|
-
* the prompt injected), then build the final carrier the lifecycle persists in
|
|
393
|
-
* place (agent draft → finalized, full-replace at the same path — the engine
|
|
394
|
-
* remains the carrier's single author). A missing or schema-violating draft →
|
|
395
|
-
* BLOCK over the CDD_BLOCKED channel + a crash record + the draft untouched
|
|
396
|
-
* (on failure, no overwrite — the child's work is never clobbered; resume re-runs the same
|
|
397
|
-
* command, which re-offers the round). The test-evidence file (task-family work
|
|
398
|
-
* rounds only) is read back with the same stakes: a missing/violating file
|
|
399
|
-
* rewrites the carrier to BLOCKED (persisted — the child's work is kept, marked
|
|
400
|
-
* bad), the second fix for a prose-only claim. */
|
|
401
|
-
#reconstruct(frame: OpenFrame, block: DispatchOutcome): DispatchOutcome {
|
|
402
|
-
const scene = this.#scene;
|
|
403
|
-
const op = this.#opOf(frame);
|
|
404
|
-
const face = this.#familyOf(op, frame.type).schema ?? "work";
|
|
405
|
-
const schema = this.#handoffSchema;
|
|
406
|
-
const path = scene.ledger.handoffPath(op, frame.type, frame.params);
|
|
407
|
-
// The tri-state draft read — a MISSING draft ("never written") and a MALFORMED one
|
|
408
|
-
// (present but unparseable JSON) are different facts: the rejection reports each
|
|
409
|
-
// truly, so a corrupt draft is never misreported as "not written" (D27). The read
|
|
410
|
-
// is LENIENT (D39): the draft is a child-LLM-authored carrier, and a trailing comma
|
|
411
|
-
// (a routine model slip) must not void the whole round — jsonc-parser tolerates the
|
|
412
|
-
// lenient dialect while a real break (a missing brace, …) still reports malformed.
|
|
413
|
-
const draftRead = scene.workspace.readJsonLenient<Record<string, unknown>>(
|
|
414
|
-
scene.ledger.handoffName(op, frame.type, frame.params),
|
|
415
|
-
);
|
|
416
|
-
if (draftRead.kind === "missing") {
|
|
417
|
-
return this.#reject(frame, path, `the handoff draft was not written at ${path}`);
|
|
418
|
-
}
|
|
419
|
-
if (draftRead.kind === "malformed") {
|
|
420
|
-
// The lenient face carries the parser's precise error codes (D39) — surface
|
|
421
|
-
// them in the rejection so a genuinely corrupt draft is diagnosable, not just
|
|
422
|
-
// "malformed".
|
|
423
|
-
const codes = (draftRead.errors ?? [])
|
|
424
|
-
.map((error) => printParseErrorCode(error.error))
|
|
425
|
-
.join(", ");
|
|
426
|
-
const detail = codes === "" ? "" : ` (${codes})`;
|
|
427
|
-
return this.#reject(frame, path, `the handoff draft at ${path} is malformed JSON${detail}`);
|
|
428
|
-
}
|
|
429
|
-
const draft = draftRead.value;
|
|
430
|
-
const problems = schema.violations(face, draft);
|
|
431
|
-
if (problems.length > 0) {
|
|
432
|
-
return this.#reject(
|
|
433
|
-
frame,
|
|
434
|
-
path,
|
|
435
|
-
`the handoff draft at ${path} violates the ${face} schema: ${problems.join("; ")}`,
|
|
436
|
-
);
|
|
437
|
-
}
|
|
438
|
-
// T2 — the face-aware read: the findings face ALONE reads `draft.findings` (its
|
|
439
|
-
// own declared required field — rolled up to the conclusion); the work face
|
|
440
|
-
// derives its status from the draft's declared status, never the findings plane
|
|
441
|
-
// (the work writable subset declares no findings field — zero findings read).
|
|
442
|
-
// The conclusion rides the ONE source (`HandoffSchema.conclusionOf`) the ledger
|
|
443
|
-
// legs read too — the reconstruct never rules a work status by a second path.
|
|
444
|
-
const findings =
|
|
445
|
-
face === "findings" ? (Array.isArray(draft.findings) ? draft.findings : []) : [];
|
|
446
|
-
// A validated draft's conclusion is total: the findings face rolls up its own
|
|
447
|
-
// required findings, and the work face's `status` passed the `required` gate above
|
|
448
|
-
// — so the `?? "BLOCKED"` never fires here (a work draft without a status never
|
|
449
|
-
// reaches this line; the absent→undefined case exists only for on-disk legacy
|
|
450
|
-
// carriers the ledger reads back, never a schema-validated draft).
|
|
451
|
-
let status: RoundStatus = schema.conclusionOf(face, draft) ?? "BLOCKED";
|
|
452
|
-
let reason: string | null = null;
|
|
453
|
-
// The evidence gate (v1.9) — the work faces (implement/fix task+branch) write
|
|
454
|
-
// the canonical `{family-prefix}-{key}-test-evidence.json` under the workspace
|
|
455
|
-
// (§3.7 naming: tasks- for the task families, branch- for the branch fix); the
|
|
456
|
-
// docs faces (review/docs-fix) carry no evidence file. The read-back is REAL — a
|
|
457
|
-
// missing/malformed/schema-violating file rewrites the draft to BLOCKED (each
|
|
458
|
-
// cause reported truly — the tri-state read, D27).
|
|
459
|
-
if (face === "work") {
|
|
460
|
-
const evidenceName = this.#evidenceName(frame);
|
|
461
|
-
const evidencePath = scene.workspace.resolve(evidenceName);
|
|
462
|
-
const evidenceRead = scene.workspace.readJson<unknown>(evidenceName);
|
|
463
|
-
// The SAME tri-state discrimination as the draft leg (D27): a PRESENT-but-corrupt
|
|
464
|
-
// evidence file reports its true cause, never the misleading "missing" — only a
|
|
465
|
-
// genuinely absent file (or a schema-violating present one) rides the schema
|
|
466
|
-
// verdict below.
|
|
467
|
-
if (evidenceRead.kind === "malformed") {
|
|
468
|
-
status = "BLOCKED";
|
|
469
|
-
reason = `the test evidence at ${evidencePath} is malformed JSON`;
|
|
470
|
-
} else {
|
|
471
|
-
const evidence = evidenceRead.kind === "ok" ? evidenceRead.value : null;
|
|
472
|
-
const evidenceProblems = schema.evidenceViolations(evidence);
|
|
473
|
-
if (evidenceProblems.length > 0) {
|
|
474
|
-
status = "BLOCKED";
|
|
475
|
-
reason = `the test evidence at ${evidencePath} violates the contract: ${evidenceProblems.join("; ")}`;
|
|
476
|
-
}
|
|
477
|
-
}
|
|
478
|
-
}
|
|
479
|
-
return {
|
|
480
|
-
status,
|
|
481
|
-
findings: face === "findings" ? schema.findingsOf(findings) : undefined,
|
|
482
|
-
artifacts: block.artifacts,
|
|
483
|
-
carrier: this.#materialize(frame, face, draft, status, reason),
|
|
484
|
-
};
|
|
485
|
-
}
|
|
486
|
-
|
|
487
|
-
/** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
|
|
488
|
-
* same-command resume's decision source: the attempted handoff + the resume
|
|
489
|
-
* command) + NO carrier (the bookkeep leaves the draft untouched). */
|
|
490
|
-
#reject(frame: OpenFrame, path: string, reason: string): DispatchOutcome {
|
|
491
|
-
this.#io.stderr(`CDD_BLOCKED: ${reason}\n`);
|
|
492
|
-
const op = this.#opOf(frame);
|
|
493
|
-
this.#scene.ledger.writeCrash(`${op}.${frame.type}`, frame.round, {
|
|
494
|
-
exitCode: 0,
|
|
495
|
-
stderrTail: [reason],
|
|
496
|
-
stdoutTail: [],
|
|
497
|
-
attemptedHandoff: path,
|
|
498
|
-
next: this.#resumeOf(frame),
|
|
499
|
-
cause: "contract-violation",
|
|
500
|
-
});
|
|
501
|
-
return { status: "BLOCKED" };
|
|
502
|
-
}
|
|
503
|
-
|
|
504
|
-
/** Build the final carrier — the validated writable fields from the draft (the
|
|
505
|
-
* engine-seated identity rides the canonical file name, never inline: phase/tasks
|
|
506
|
-
* are not declared and never written — v1.30), persisted by the bookkeep
|
|
507
|
-
* full-replace at the SAME path (agent draft → finalized). The evidence override
|
|
508
|
-
* rewrites the status to BLOCKED + a failure_category + the reason note (the
|
|
509
|
-
* child's work preserved, marked bad). */
|
|
510
|
-
#materialize(
|
|
511
|
-
frame: OpenFrame,
|
|
512
|
-
face: HandoffSchemaFace,
|
|
513
|
-
draft: Record<string, unknown>,
|
|
514
|
-
status: RoundStatus,
|
|
515
|
-
reason: string | null,
|
|
516
|
-
): Record<string, unknown> {
|
|
517
|
-
const ledger = this.#scene.ledger;
|
|
518
|
-
const notes: string[] = [];
|
|
519
|
-
// The §8.7 classification ruling — the SAME judgment the read-back validator makes
|
|
520
|
-
// (non-declared keys are dropped, never a BLOCK): materialize drops them and books
|
|
521
|
-
// AT MOST ONE WARN on the carrier's notes (auditable, non-interrupting — replacing
|
|
522
|
-
// the retired "BLOCK + crash-resume + reopen" chain). The engine stays the carrier's
|
|
523
|
-
// single author; a child's stray key is surfaced, not obeyed.
|
|
524
|
-
const dropped = this.#handoffSchema.droppedKeys(face, draft);
|
|
525
|
-
if (dropped.length > 0) {
|
|
526
|
-
notes.push(
|
|
527
|
-
`dropped non-declared draft field(s): ${dropped.join(", ")} — engine-reserved, never written`,
|
|
528
|
-
);
|
|
529
|
-
}
|
|
530
|
-
// The per-face carrier — buildHandoff's typed overloads: the findings face REQUIRES
|
|
531
|
-
// its findings payload (the schema-required field — cli.test pins the review
|
|
532
|
-
// carrier's findings + status), the work face builds a findings-FREE typed carrier
|
|
533
|
-
// (the work writable subset declares no findings field — the materialized work
|
|
534
|
-
// carrier carries zero findings keys). `Record<string, unknown>` local: the round
|
|
535
|
-
// conclusion (status — a RoundStatus, wider than the carrier's declared union) and
|
|
536
|
-
// the engine's extended fields ride the caller's set below.
|
|
537
|
-
const carrier: Record<string, unknown> =
|
|
538
|
-
face === "findings"
|
|
539
|
-
? ledger.buildHandoff("findings", {
|
|
540
|
-
artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
|
|
541
|
-
findings: this.#findingsList(draft.findings),
|
|
542
|
-
})
|
|
543
|
-
: ledger.buildHandoff("work", {
|
|
544
|
-
artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
|
|
545
|
-
});
|
|
546
|
-
// The work face ALONE persists the round conclusion — it is the child's own
|
|
547
|
-
// declared status (the schema enum pinned it to APPROVED | BLOCKED). The findings
|
|
548
|
-
// face holds NO status field: its conclusion is DERIVED at judgment time
|
|
549
|
-
// (`HandoffSchema.conclusionOf("findings", carrier)` → rollup(findings)), so the
|
|
550
|
-
// persisted findings carrier stays the pure declaration plane
|
|
551
|
-
// (findings/artifacts/notes) and a fix child's INPUT_FINDINGS carrier is
|
|
552
|
-
// status-free (the judgment face is perpendicular to the input face · D27).
|
|
553
|
-
const draftNotes = Array.isArray(draft.notes) ? [...(draft.notes as unknown[])] : [];
|
|
554
|
-
if (face === "work") {
|
|
555
|
-
carrier.status = status;
|
|
556
|
-
if (typeof draft.failure_category === "string")
|
|
557
|
-
carrier.failure_category = draft.failure_category;
|
|
558
|
-
// The evidence-contract override (work faces only — the evidence gate reads a
|
|
559
|
-
// work round's evidence file) rewrites the persisted conclusion to BLOCKED.
|
|
560
|
-
if (reason !== null) {
|
|
561
|
-
carrier.status = "BLOCKED";
|
|
562
|
-
carrier.failure_category = "evidence-contract";
|
|
563
|
-
draftNotes.push(reason);
|
|
564
|
-
}
|
|
565
|
-
}
|
|
566
|
-
if (notes.length > 0 || draftNotes.length > 0) carrier.notes = [...notes, ...draftNotes];
|
|
567
|
-
return carrier;
|
|
568
|
-
}
|
|
569
|
-
|
|
570
|
-
/** The carrier's artifacts map (find #5 — the engine self-derives, never trusts a
|
|
571
|
-
* child-reported path for the canonical slots): a declared PRESCRIBED slot
|
|
572
|
-
* (report/test_evidence) books the frame's canonical OUTPUT_* path — a
|
|
573
|
-
* free-named deviation is replaced and surfaced on the notes (the review scope
|
|
574
|
-
* axis reads them); the non-prescribed slots (a docs-fix's `doc`, child extras)
|
|
575
|
-
* pass verbatim. undefined when the draft declared no artifacts. */
|
|
576
|
-
#canonicalArtifacts(
|
|
577
|
-
frame: OpenFrame,
|
|
578
|
-
artifacts: unknown,
|
|
579
|
-
notes: string[],
|
|
580
|
-
): Record<string, string> | undefined {
|
|
581
|
-
const declared = this.#stringMap(artifacts);
|
|
582
|
-
if (declared === undefined) return undefined;
|
|
583
|
-
const out: Record<string, string> = {};
|
|
584
|
-
for (const [key, value] of Object.entries(declared)) {
|
|
585
|
-
const canonical = this.#prescribedArtifact(frame, key);
|
|
586
|
-
if (canonical !== "" && value !== canonical) {
|
|
587
|
-
notes.push(
|
|
588
|
-
`artifact ${key}: declared path ${value} deviates from the prescribed ${canonical} — the canonical path is booked`,
|
|
589
|
-
);
|
|
590
|
-
out[key] = canonical;
|
|
591
|
-
} else {
|
|
592
|
-
out[key] = value;
|
|
593
|
-
}
|
|
594
|
-
}
|
|
595
|
-
return Object.keys(out).length > 0 ? out : undefined;
|
|
596
|
-
}
|
|
597
|
-
|
|
598
|
-
/** The prescribed path of one block-artifact slot — a slot the frame's family
|
|
599
|
-
* prescribes (report/test_evidence → the canonical OUTPUT_* name), "" for every
|
|
600
|
-
* other slot (the pure read input `brief` is never a write slot, and a docs-fix's
|
|
601
|
-
* `doc` is never prescribed — both pass verbatim). */
|
|
602
|
-
#prescribedArtifact(frame: OpenFrame, slot: string): string {
|
|
603
|
-
switch (slot) {
|
|
604
|
-
case "report":
|
|
605
|
-
return this.#outputOf(frame, "report");
|
|
606
|
-
case "test_evidence":
|
|
607
|
-
return this.#outputOf(frame, "evidence");
|
|
608
|
-
default:
|
|
609
|
-
return "";
|
|
610
|
-
}
|
|
611
|
-
}
|
|
612
|
-
|
|
613
|
-
/** The `## Handoff schema` section value — the mode's writable-subset fence
|
|
614
|
-
* (projection ①; byte-fixed per mode so the prompt's fixed prefix stays
|
|
615
|
-
* cache-friendly). The family's `schema` field selects the face (§3.6: work →
|
|
616
|
-
* carrier + evidence fence for the implement/fix modes; findings → the review /
|
|
617
|
-
* docs-fix fence only). */
|
|
618
|
-
#schemaText(frame: OpenFrame): string {
|
|
619
|
-
const op = this.#opOf(frame);
|
|
620
|
-
const face = this.#familyOf(op, frame.type).schema ?? "work";
|
|
621
|
-
const evidence = face === "work";
|
|
622
|
-
const prefix = evidence ? this.#evidencePrefix(frame) : "tasks";
|
|
623
|
-
return this.#handoffSchema.schemaText(face, evidence, prefix);
|
|
624
|
-
}
|
|
625
|
-
|
|
626
|
-
/** The evidence file's family prefix (§3.7 naming) — the task-family work rounds
|
|
627
|
-
* use the canonical `tasks-` prefix; the branch fix uses the `branch-` family
|
|
628
|
-
* prefix (never the misleading tasks- spine). */
|
|
629
|
-
#evidencePrefix(frame: OpenFrame): string {
|
|
630
|
-
return frame.type === "wave" ? "tasks" : "branch";
|
|
631
|
-
}
|
|
632
|
-
|
|
633
|
-
/** The op.type family record — the engine-config handoff namespace single truth
|
|
634
|
-
* (loud on an unknown family: never a second naming table). */
|
|
635
|
-
#familyOf(op: string, type: string): HandoffFamily {
|
|
636
|
-
const family = this.#config.engineConfig().handoffNamespace.families[`${op}.${type}`] as
|
|
637
|
-
| HandoffFamily
|
|
638
|
-
| undefined;
|
|
639
|
-
if (family === undefined) throw new Error(`unknown handoff family: ${op}.${type}`);
|
|
640
|
-
return family;
|
|
641
|
-
}
|
|
642
|
-
|
|
643
|
-
/** The artifacts field as a string-map (only string values land — non-string rows
|
|
644
|
-
* are dropped, never coerced). */
|
|
645
|
-
#stringMap(artifacts: unknown): Record<string, string> | undefined {
|
|
646
|
-
if (typeof artifacts !== "object" || artifacts === null || Array.isArray(artifacts))
|
|
647
|
-
return undefined;
|
|
648
|
-
const out: Record<string, string> = {};
|
|
649
|
-
for (const [key, value] of Object.entries(artifacts)) {
|
|
650
|
-
if (typeof value === "string") out[key] = value;
|
|
651
|
-
}
|
|
652
|
-
return Object.keys(out).length > 0 ? out : undefined;
|
|
653
|
-
}
|
|
654
|
-
|
|
655
|
-
/** The draft findings as a plain list (the materialized carrier keeps them
|
|
656
|
-
* verbatim; the schema validated their shape before this ran). */
|
|
657
|
-
#findingsList(findings: unknown): unknown[] {
|
|
658
|
-
return Array.isArray(findings) ? findings : [];
|
|
659
|
-
}
|
|
660
|
-
|
|
661
|
-
/** The same-command resume string — the crash record's `next`, mirroring the
|
|
662
|
-
* CLI's dispatchable form of this frame (re-run the same command per the BLOCKED
|
|
663
|
-
* `next:` to continue — the idempotent full mode re-run). */
|
|
664
|
-
#resumeOf(frame: OpenFrame): string {
|
|
665
|
-
const scene = this.#scene;
|
|
666
|
-
const plan = scene.planPath ?? "<plan>";
|
|
667
|
-
switch (frame.phase) {
|
|
668
|
-
case "implement":
|
|
669
|
-
return `cdd implement --tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
|
|
670
|
-
case "branch-review":
|
|
671
|
-
// The branch re-review literal carries only the workspace-identity `--plan`
|
|
672
|
-
// — the review judges the live tree (the scope anchor BASE_BRANCH is
|
|
673
|
-
// engine-injected at dispatch), so no range rides the command.
|
|
674
|
-
return `cdd review --type branch --plan ${plan}`;
|
|
675
|
-
case "review":
|
|
676
|
-
if (frame.type === "spec") return `cdd review --type spec --spec ${this.#docOf(frame)}`;
|
|
677
|
-
if (frame.type === "plan") return `cdd review --type plan --plan ${this.#docOf(frame)}`;
|
|
678
|
-
return `cdd review --type wave --tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
|
|
679
|
-
case "fix": {
|
|
680
|
-
const findings = scene.ledger.handoffPath("review", frame.type, frame.params);
|
|
681
|
-
const target =
|
|
682
|
-
frame.target.kind === "doc"
|
|
683
|
-
? `--${frame.type === "spec" ? "spec" : "plan"} ${frame.target.doc}`
|
|
684
|
-
: // The branch fix carries no refs — the source findings ride the
|
|
685
|
-
// --findings handoff; the workspace-identity `--plan` still rides
|
|
686
|
-
// (the plan is the branch line's identity, zero orchestrator fallback).
|
|
687
|
-
frame.target.kind === "branch"
|
|
688
|
-
? `--plan ${plan}`
|
|
689
|
-
: `--tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
|
|
690
|
-
return `cdd fix --type ${frame.type} ${target} --findings ${findings}`;
|
|
691
|
-
}
|
|
692
|
-
}
|
|
693
|
-
}
|
|
694
|
-
|
|
695
|
-
/** The doc path of a doc-target frame (the `""` never lands — the reject paths
|
|
696
|
-
* only frame docs). */
|
|
697
|
-
#docOf(frame: OpenFrame): string {
|
|
698
|
-
return frame.target.kind === "doc" ? frame.target.doc : "";
|
|
699
|
-
}
|
|
700
|
-
}
|