@oscaner-skills/cdd-engine 3.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/{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/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
- 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 +5 -5
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
- package/src-next/__tests__/floor.guard.test.ts +0 -69
- package/src-next/__tests__/issue-body.guard.test.ts +0 -66
- package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
- package/src-next/__tests__/smoke.integration.test.ts +0 -185
- package/src-next/__tests__/support/strip-comments.ts +0 -99
- package/src-next/__tests__/zero-dep.test.ts +0 -94
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
- package/src-next/contract/__tests__/declare.test.ts +0 -481
- package/src-next/contract/__tests__/doc.test.ts +0 -527
- package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
- package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
- package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
- package/src-next/contract/__tests__/judge.test.ts +0 -1111
- package/src-next/contract/__tests__/lint.test.ts +0 -324
- package/src-next/contract/__tests__/project.test.ts +0 -460
- package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -1071
- package/src-next/contract/doc.ts +0 -816
- package/src-next/contract/frontmatter.ts +0 -233
- package/src-next/contract/home-extractors.ts +0 -397
- package/src-next/contract/invariants.ts +0 -1413
- package/src-next/contract/judge.ts +0 -151
- package/src-next/contract/lint.ts +0 -239
- package/src-next/contract/project.ts +0 -656
- package/src-next/contract/skill-anatomy.ts +0 -301
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -1151
- package/src-next/face/__tests__/capsule.test.ts +0 -300
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
- package/src-next/face/__tests__/cli.test.ts +0 -4897
- 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__/install-rows.guard.test.ts +0 -58
- package/src-next/face/__tests__/negation.ts +0 -6
- package/src-next/face/__tests__/preview.test.ts +0 -374
- package/src-next/face/__tests__/projection.test.ts +0 -303
- package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
- package/src-next/face/__tests__/termination.test.ts +0 -650
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -248
- package/src-next/face/board-view.ts +0 -652
- package/src-next/face/capsule.ts +0 -163
- package/src-next/face/cli.ts +0 -1028
- package/src-next/face/declare.ts +0 -323
- package/src-next/face/gate.ts +0 -171
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -302
- package/src-next/face/lifecycle.ts +0 -725
- package/src-next/face/preview.ts +0 -151
- package/src-next/face/projection.ts +0 -285
- package/src-next/face/route-render.ts +0 -185
- package/src-next/face/termination.ts +0 -573
- package/src-next/face/words.ts +0 -314
- package/src-next/infra/__tests__/infra.test.ts +0 -333
- package/src-next/infra/__tests__/root.test.ts +0 -56
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -132
- package/src-next/infra/workspace.ts +0 -322
- package/src-next/render/__tests__/render.test.ts +0 -550
- package/src-next/render/__tests__/skeleton.test.ts +0 -684
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -162
- package/src-next/render/skeleton.ts +0 -502
- package/src-next/render/templates.ts +0 -645
- package/src-next/session/__tests__/graph.test.ts +0 -277
- 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 -745
- package/src-next/session/__tests__/next.test.ts +0 -460
- package/src-next/session/__tests__/preflight.test.ts +0 -545
- package/src-next/session/__tests__/round-naming.test.ts +0 -142
- package/src-next/session/__tests__/run.test.ts +0 -1026
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -476
- 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 -1076
- package/src-next/session/next.ts +0 -293
- package/src-next/session/preflight.ts +0 -271
- package/src-next/session/round-naming.ts +0 -84
- package/src-next/session/run.ts +0 -610
- package/src-next/session/state.ts +0 -30
- package/src-next/session/wave.ts +0 -139
|
@@ -1,373 +0,0 @@
|
|
|
1
|
-
// packages/cdd-engine/src-next/session/handoff-schema.ts
|
|
2
|
-
// T15 v1.9 — the handoff schema face (design spec §3.6): the child's writable handoff
|
|
3
|
-
// contract as ONE typed declaration with TWO projections. The cutover deleted the old
|
|
4
|
-
// JSON schema file together with its Ajv loader; the structural constraint now lives
|
|
5
|
-
// here as a typed declaration — zero JSON schema files, one source, two consumers:
|
|
6
|
-
//
|
|
7
|
-
// · projections: ① the prompt-injection text (schemaText — the ```json fences
|
|
8
|
-
// byte-fixed per face, so the fixed prefix tail of the dispatch prompt stays
|
|
9
|
-
// cache-friendly) and ② the engine read-back validator (violations /
|
|
10
|
-
// evidenceViolations — the child draft is validated against exactly the same
|
|
11
|
-
// declared objects the prompt showed it).
|
|
12
|
-
// · faces: the per-family `schema` field of the handoff families (infra/runtime.ts)
|
|
13
|
-
// selects the face — `work` (implement/fix: status+artifacts, plus the separate
|
|
14
|
-
// test-evidence file for task-family rounds) or `findings` (reviews: findings-only
|
|
15
|
-
// carrier — the engine rolls the status up from the findings, never a
|
|
16
|
-
// child-authored status).
|
|
17
|
-
//
|
|
18
|
-
// The validator is a purpose-built walker over the declared schema objects (the
|
|
19
|
-
// keywords this contract uses — type / properties / required / items / enum /
|
|
20
|
-
// minLength / maxLength) — the new tree reads zero config files and takes no Ajv
|
|
21
|
-
// dependency; a wrong-shape child draft is the engine's read-back BLOCK, and the
|
|
22
|
-
// same declared objects drive both projections so the prompt can never show a
|
|
23
|
-
// schema the engine does not enforce. Non-declared fields are DROPPED by
|
|
24
|
-
// materialize and never refuse the draft — the validator and materialize judge the
|
|
25
|
-
// same field the same way (zero second-arbiter friction).
|
|
26
|
-
//
|
|
27
|
-
// Module-level exports are types / the declared schema objects / the class — zero
|
|
28
|
-
// behavior-carrying bare functions (the plan's zero-bare-function discipline).
|
|
29
|
-
|
|
30
|
-
import type { FindingSeverity, RoundFinding, RoundStatus } from "./ledger.ts";
|
|
31
|
-
|
|
32
|
-
/** The handoff schema faces — the `HandoffFamily.schema` selector values. */
|
|
33
|
-
export type HandoffSchemaFace = "work" | "findings";
|
|
34
|
-
|
|
35
|
-
/** The declared schema node shape — the typed subset of JSON-schema this contract
|
|
36
|
-
* uses (the engine's validator walks exactly these objects). */
|
|
37
|
-
interface SchemaNode {
|
|
38
|
-
type?: "object" | "array" | "string" | "integer" | "boolean";
|
|
39
|
-
required?: readonly string[];
|
|
40
|
-
properties?: Readonly<Record<string, SchemaNode>>;
|
|
41
|
-
items?: SchemaNode;
|
|
42
|
-
enum?: readonly unknown[];
|
|
43
|
-
minLength?: number;
|
|
44
|
-
maxLength?: number;
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
/** One finding row — the shared base declaration of the findings face (severity +
|
|
48
|
-
* lens + summary required; the extra review columns — section / line / fix — are
|
|
49
|
-
* declared optional, and unknown extra fields ride along). */
|
|
50
|
-
const FINDING: SchemaNode = {
|
|
51
|
-
type: "object",
|
|
52
|
-
required: ["severity", "lens", "summary"],
|
|
53
|
-
properties: {
|
|
54
|
-
severity: { type: "string", enum: ["blocker", "warn", "nit"] },
|
|
55
|
-
lens: { type: "string" },
|
|
56
|
-
section: { type: "string" },
|
|
57
|
-
line: { type: "integer" },
|
|
58
|
-
summary: { type: "string" },
|
|
59
|
-
fix: { type: "string" },
|
|
60
|
-
},
|
|
61
|
-
};
|
|
62
|
-
|
|
63
|
-
/** The `work` writable subset — implement/fix carrier. `status` and `artifacts` are
|
|
64
|
-
* the round's required core; notes rides the declared optional field. Reserved
|
|
65
|
-
* fields (phase · tasks) are NOT declared and are DROPPED by materialize (never a
|
|
66
|
-
* BLOCK) — the engine stays the carrier's single author.
|
|
67
|
-
* `as const` preserves the literal property keys — the carrier type family
|
|
68
|
-
* (`CarrierOf<F>` below) derives its field set FROM these declared keys. */
|
|
69
|
-
const CARRIER_WORK = {
|
|
70
|
-
type: "object",
|
|
71
|
-
required: ["status", "artifacts"],
|
|
72
|
-
properties: {
|
|
73
|
-
status: { type: "string", enum: ["APPROVED", "BLOCKED"] },
|
|
74
|
-
failure_category: { type: "string" },
|
|
75
|
-
artifacts: { type: "object" },
|
|
76
|
-
notes: { type: "array", items: { type: "string" } },
|
|
77
|
-
},
|
|
78
|
-
} as const satisfies SchemaNode;
|
|
79
|
-
|
|
80
|
-
/** The `findings` writable subset — review + docs-fix carrier. NO status: the
|
|
81
|
-
* conclusion is derived from the findings at judgment time
|
|
82
|
-
* (`conclusionOf("findings", carrier)` → `rollup(findings)`), never a carrier field
|
|
83
|
-
* the child authors or the engine persists — the declaration plane IS the writable
|
|
84
|
-
* plane (one face, one field set). `as const` — see CARRIER_WORK. */
|
|
85
|
-
const CARRIER_FINDINGS = {
|
|
86
|
-
type: "object",
|
|
87
|
-
required: ["findings"],
|
|
88
|
-
properties: {
|
|
89
|
-
findings: { type: "array", items: FINDING },
|
|
90
|
-
artifacts: { type: "object" },
|
|
91
|
-
notes: { type: "array", items: { type: "string" } },
|
|
92
|
-
},
|
|
93
|
-
} as const satisfies SchemaNode;
|
|
94
|
-
|
|
95
|
-
/** The test-evidence file schema — the evidence gate's engine read-back contract
|
|
96
|
-
* (the second fix for a prose-only claim: the old prompt asserted an engine read-back
|
|
97
|
-
* that the engine never performed; now both projections are real). A task-family
|
|
98
|
-
* work round missing or violating this file rewrites the round to BLOCKED. */
|
|
99
|
-
const EVIDENCE: SchemaNode = {
|
|
100
|
-
type: "object",
|
|
101
|
-
required: ["command", "exit_code", "passed", "warnings_count", "typecheck"],
|
|
102
|
-
properties: {
|
|
103
|
-
command: { type: "string" },
|
|
104
|
-
exit_code: { type: "integer" },
|
|
105
|
-
passed: { type: "boolean" },
|
|
106
|
-
warnings_count: { type: "integer" },
|
|
107
|
-
typecheck: {
|
|
108
|
-
type: "object",
|
|
109
|
-
required: ["command", "exit_code", "passed"],
|
|
110
|
-
properties: {
|
|
111
|
-
command: { type: "string" },
|
|
112
|
-
exit_code: { type: "integer" },
|
|
113
|
-
passed: { type: "boolean" },
|
|
114
|
-
},
|
|
115
|
-
},
|
|
116
|
-
behavior_change: { type: "boolean" },
|
|
117
|
-
},
|
|
118
|
-
};
|
|
119
|
-
|
|
120
|
-
/** The face → declared writable-subset table (the single source both projections read).
|
|
121
|
-
* `as const` keeps the declarations' literal property keys visible — the carrier type
|
|
122
|
-
* family's `[K in keyof (typeof BY_FACE)[F]["properties"]]` derives its field set from
|
|
123
|
-
* exactly these tables, so a schema edit reshapes the carrier types by construction. */
|
|
124
|
-
const BY_FACE = {
|
|
125
|
-
work: CARRIER_WORK,
|
|
126
|
-
findings: CARRIER_FINDINGS,
|
|
127
|
-
} as const satisfies Readonly<Record<HandoffSchemaFace, SchemaNode>>;
|
|
128
|
-
|
|
129
|
-
/** The carrier value-type mapping — every declared carrier field's value type. This
|
|
130
|
-
* is the ONE hand-maintained byte table (the type-level twin of the schema property
|
|
131
|
-
* values); `CarrierOf<F>` maps each declared key through it. A wrong entry reads as a
|
|
132
|
-
* build error at the first carrier read/write — it cannot silently pass. */
|
|
133
|
-
export type CarrierValue = {
|
|
134
|
-
status: "APPROVED" | "BLOCKED";
|
|
135
|
-
failure_category: string;
|
|
136
|
-
artifacts: Record<string, string>;
|
|
137
|
-
notes: string[];
|
|
138
|
-
findings: {
|
|
139
|
-
severity: "blocker" | "warn" | "nit";
|
|
140
|
-
lens: string;
|
|
141
|
-
section?: string;
|
|
142
|
-
line?: number;
|
|
143
|
-
summary: string;
|
|
144
|
-
fix?: string;
|
|
145
|
-
}[];
|
|
146
|
-
};
|
|
147
|
-
|
|
148
|
-
/** The derived carrier-of: the mapped type whose field set comes FROM the face's
|
|
149
|
-
* declared `properties` keys (the face dispatcher resolves which declared table the
|
|
150
|
-
* mapped type reads — `WorkCarrier`/`FindingsCarrier` are the two faces'
|
|
151
|
-
* instantiations, so a schema declaration change reshapes the carrier types by
|
|
152
|
-
* construction, zero hand-maintained parallel field tables). `-readonly` keeps the
|
|
153
|
-
* carrier MUTABLE — the round conclusion (status) rides the caller's set below the
|
|
154
|
-
* skeleton, never a frozen build-time value. */
|
|
155
|
-
export type CarrierOf<F extends HandoffSchemaFace> = F extends "work"
|
|
156
|
-
? { -readonly [K in keyof (typeof BY_FACE)["work"]["properties"]]: CarrierValue[K] }
|
|
157
|
-
: { -readonly [K in keyof (typeof BY_FACE)["findings"]["properties"]]: CarrierValue[K] };
|
|
158
|
-
|
|
159
|
-
/** The work face's carrier — implement/fix write-back. Declared `findings`-free: the
|
|
160
|
-
* work writable subset declares no findings field, so the carrier type carries none —
|
|
161
|
-
* a `buildHandoff("work", { findings })` call is a compile-time refusal (Q1→c). */
|
|
162
|
-
export type WorkCarrier = CarrierOf<"work">;
|
|
163
|
-
|
|
164
|
-
/** The findings face's carrier — review write-back. `findings` is schema-required, so
|
|
165
|
-
* the carrier type always carries it (the compile-time twin of the required gate). */
|
|
166
|
-
export type FindingsCarrier = CarrierOf<"findings">;
|
|
167
|
-
|
|
168
|
-
/** One formed problem of a schema violation — the `path: reason` wording. */
|
|
169
|
-
export interface SchemaProblem {
|
|
170
|
-
path: string;
|
|
171
|
-
reason: string;
|
|
172
|
-
}
|
|
173
|
-
|
|
174
|
-
/**
|
|
175
|
-
* HandoffSchema — one declaration, two projections. `violations(face, value)` is
|
|
176
|
-
* the read-back validator (projection ② — the engine's seat, session plane);
|
|
177
|
-
* `schemaText(face, evidence)` is the injected prompt text (projection ① — fixed
|
|
178
|
-
* prefix tail, byte-stable per face so the dispatch prompt stays cache-friendly).
|
|
179
|
-
* `rollup(findings)` derives the review conclusion the old JSON face rolled up.
|
|
180
|
-
*/
|
|
181
|
-
export class HandoffSchema {
|
|
182
|
-
/** Projection ① — the `## Handoff schema` section text: the face's writable
|
|
183
|
-
* subset in a ```json fence + (work faces) the evidence file's schema in a second
|
|
184
|
-
* fence. The text is byte-stable per (face, evidence, prefix) — the fixed bytes
|
|
185
|
-
* of the dispatch prompt's contract surface. The evidence prefix is the family
|
|
186
|
-
* spine (§3.7 naming: `tasks-` for the task families, `branch-` for the branch
|
|
187
|
-
* fix — a branch evidence file never carries the misleading tasks- prefix). */
|
|
188
|
-
schemaText(face: HandoffSchemaFace, evidence: boolean, evidencePrefix = "tasks"): string {
|
|
189
|
-
const carrier = this.#json(BY_FACE[face]);
|
|
190
|
-
let text = `Write the handoff draft at \`OUTPUT_HANDOFF\` per this writable subset — the engine validates it, then materializes the final carrier in place; fields not listed here are engine-reserved, do not write them.\n\n\`\`\`json\n${carrier}\n\`\`\``;
|
|
191
|
-
if (evidence) {
|
|
192
|
-
text += `\n\nThe evidence file (\`${evidencePrefix}-{key}-test-evidence.json\` under \`WORKSPACE_DIR\`) must comply with this schema — the engine reads it back with the same stakes:\n\n\`\`\`json\n${this.#json(EVIDENCE)}\n\`\`\``;
|
|
193
|
-
}
|
|
194
|
-
return text;
|
|
195
|
-
}
|
|
196
|
-
|
|
197
|
-
/** The declared evidence schema, as text (the evidence-gate prompt's shared fence). */
|
|
198
|
-
evidenceSchemaText(): string {
|
|
199
|
-
return this.#json(EVIDENCE);
|
|
200
|
-
}
|
|
201
|
-
|
|
202
|
-
/** Projection ② — validate a child draft against a face's writable subset. Every
|
|
203
|
-
* problem is a read-back BLOCK; the draft is left untouched for the child's
|
|
204
|
-
* resume (never overwritten — the engine never clobbers a child's work). */
|
|
205
|
-
violations(face: HandoffSchemaFace, value: unknown): string[] {
|
|
206
|
-
const problems: SchemaProblem[] = [];
|
|
207
|
-
this.#check(BY_FACE[face], value, "", problems);
|
|
208
|
-
return problems.map((problem) =>
|
|
209
|
-
problem.path.length === 0 ? problem.reason : `${problem.path}: ${problem.reason}`,
|
|
210
|
-
);
|
|
211
|
-
}
|
|
212
|
-
|
|
213
|
-
/** Projection ② — validate the test-evidence file (task-family work rounds). */
|
|
214
|
-
evidenceViolations(value: unknown): string[] {
|
|
215
|
-
if (value === null || value === undefined) return ["the evidence file is missing"];
|
|
216
|
-
const problems: SchemaProblem[] = [];
|
|
217
|
-
this.#check(EVIDENCE, value, "", problems);
|
|
218
|
-
return problems.map((problem) =>
|
|
219
|
-
problem.path.length === 0 ? problem.reason : `${problem.path}: ${problem.reason}`,
|
|
220
|
-
);
|
|
221
|
-
}
|
|
222
|
-
|
|
223
|
-
/** The round conclusion, DERIVED at judgment time from the face's own plane — the
|
|
224
|
-
* single source the review/fix ledger legs read (D27 · judgment face ⊥ input face).
|
|
225
|
-
* The findings face rolls its conclusion UP from its findings (defined for every
|
|
226
|
-
* carrier — a review never carries a child-authored status, and the persisted
|
|
227
|
-
* findings carrier holds none). The work face reads its DECLARED status, and the
|
|
228
|
-
* absence of a declaration is itself a fact: an ABSENT status → `undefined` (no
|
|
229
|
-
* conclusion was declared — never an invented approval OR an invented failure ·
|
|
230
|
-
* D27 present-facts-only), while a PRESENT-but-invalid byte (outside the enum the
|
|
231
|
-
* schema pinned) degrades to BLOCKED — the conservative reading of a malformed
|
|
232
|
-
* declaration. `undefined` is DISTINCT from BLOCKED to the caller (the router
|
|
233
|
-
* treats undefined as "not a failure", a declared BLOCKED as the failure face), so
|
|
234
|
-
* a work carrier that predates the status field never reads as a fabricated
|
|
235
|
-
* failure. `carrier` is the on-disk carrier (or a freshly built one) — the
|
|
236
|
-
* conclusion is never a stored field, so any face's carrier derives it the same way. */
|
|
237
|
-
conclusionOf(face: HandoffSchemaFace, carrier: Record<string, unknown>): RoundStatus | undefined {
|
|
238
|
-
if (face === "findings") {
|
|
239
|
-
const findings = Array.isArray(carrier.findings) ? carrier.findings : [];
|
|
240
|
-
return this.rollup(findings);
|
|
241
|
-
}
|
|
242
|
-
// The work face reads its DECLARED status. Absent → undefined (no declaration);
|
|
243
|
-
// present-but-invalid → BLOCKED (a declared conclusion that is malformed is a
|
|
244
|
-
// failure signal, never silently approved). This is the ONE ruling for a work
|
|
245
|
-
// status: the reconstruct's work leg delegates here, so the read-back and the
|
|
246
|
-
// judgment-time derivation never disagree.
|
|
247
|
-
const status = carrier.status;
|
|
248
|
-
if (status === undefined) return undefined;
|
|
249
|
-
return status === "APPROVED" || status === "BLOCKED" ? status : "BLOCKED";
|
|
250
|
-
}
|
|
251
|
-
|
|
252
|
-
/** The review conclusion rollup — status derived from the findings severities
|
|
253
|
-
* (the rollup the retired JSON-return channel performed; a review never carries
|
|
254
|
-
* a child-authored status). */
|
|
255
|
-
rollup(findings: readonly unknown[]): RoundStatus {
|
|
256
|
-
const blockers = findings.filter(
|
|
257
|
-
(finding) => (finding as { severity?: unknown } | null)?.severity === "blocker",
|
|
258
|
-
).length;
|
|
259
|
-
return blockers > 0 ? "CHANGES_REQUESTED" : findings.length > 0 ? "REVIEW_FIX" : "APPROVED";
|
|
260
|
-
}
|
|
261
|
-
|
|
262
|
-
/** The draft findings presented as round findings — unknown severities dropped
|
|
263
|
-
* (the capsule's blocker count + the outcome's face, never the judgment domain). */
|
|
264
|
-
findingsOf(findings: unknown): readonly RoundFinding[] {
|
|
265
|
-
if (!Array.isArray(findings)) return [];
|
|
266
|
-
const rows: RoundFinding[] = [];
|
|
267
|
-
for (const entry of findings) {
|
|
268
|
-
const severity = (entry as { severity?: unknown } | null)?.severity;
|
|
269
|
-
if (severity !== "blocker" && severity !== "warn" && severity !== "nit") continue;
|
|
270
|
-
const summary = (entry as { summary?: unknown } | null)?.summary;
|
|
271
|
-
rows.push({
|
|
272
|
-
severity: severity as FindingSeverity,
|
|
273
|
-
summary: typeof summary === "string" ? summary : undefined,
|
|
274
|
-
});
|
|
275
|
-
}
|
|
276
|
-
return rows;
|
|
277
|
-
}
|
|
278
|
-
|
|
279
|
-
/** The declared schema object of a face — the single-source introspection of this
|
|
280
|
-
* module's reparametrized `HandoffFamily.schema` value. */
|
|
281
|
-
faceSchema(face: HandoffSchemaFace): SchemaNode {
|
|
282
|
-
return BY_FACE[face];
|
|
283
|
-
}
|
|
284
|
-
|
|
285
|
-
/** The draft keys materialize drops — every key the face does not declare as a
|
|
286
|
-
* child-writable `properties` slot (extra child fields such as a findings-draft
|
|
287
|
-
* `status`). The read-back validator judges these the same way (drop, never a
|
|
288
|
-
* BLOCK) — materialize surfaces them as the single §8.7 WARN on the carrier's
|
|
289
|
-
* notes. A non-object draft drops nothing here (its shape is the validator's
|
|
290
|
-
* semantic refusal). */
|
|
291
|
-
droppedKeys(face: HandoffSchemaFace, value: unknown): string[] {
|
|
292
|
-
if (typeof value !== "object" || value === null || Array.isArray(value)) return [];
|
|
293
|
-
const declared = new Set(Object.keys(BY_FACE[face].properties ?? {}));
|
|
294
|
-
return Object.keys(value as Record<string, unknown>).filter((key) => !declared.has(key));
|
|
295
|
-
}
|
|
296
|
-
|
|
297
|
-
/** Serialize a declared schema object into the prompt's fence — COMPACT (no pretty
|
|
298
|
-
* indent: the injected text is the per-mode fixed prefix's biggest token cost, and
|
|
299
|
-
* every dispatch pays it in the child context — minify keeps the round cheap). The
|
|
300
|
-
* declaration IS the writable plane (no engine-only metadata to strip) — the fence
|
|
301
|
-
* is the declared node verbatim. */
|
|
302
|
-
#json(node: SchemaNode): string {
|
|
303
|
-
return JSON.stringify(node);
|
|
304
|
-
}
|
|
305
|
-
|
|
306
|
-
/** Walk one schema node against a value; every mismatch is a `path: reason`. */
|
|
307
|
-
#check(node: SchemaNode, value: unknown, path: string, problems: SchemaProblem[]): void {
|
|
308
|
-
if (node.enum !== undefined && !node.enum.includes(value)) {
|
|
309
|
-
problems.push({ path, reason: `must be one of ${node.enum.join(" | ")}` });
|
|
310
|
-
return;
|
|
311
|
-
}
|
|
312
|
-
if (node.type !== undefined) {
|
|
313
|
-
if (node.type === "object") {
|
|
314
|
-
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
315
|
-
problems.push({ path, reason: "expected an object" });
|
|
316
|
-
return;
|
|
317
|
-
}
|
|
318
|
-
const obj = value as Record<string, unknown>;
|
|
319
|
-
for (const key of node.required ?? []) {
|
|
320
|
-
if (obj[key] === undefined)
|
|
321
|
-
problems.push({ path: this.#at(path, key), reason: "required" });
|
|
322
|
-
}
|
|
323
|
-
for (const [key, sub] of Object.entries(node.properties ?? {})) {
|
|
324
|
-
if (obj[key] !== undefined) this.#check(sub, obj[key], this.#at(path, key), problems);
|
|
325
|
-
}
|
|
326
|
-
// Non-declared keys (extra child fields such as a findings-draft
|
|
327
|
-
// `status`) are DROPPED by materialize, never a BLOCK — the validator
|
|
328
|
-
// and materialize judge the same field the same way (§8.7). Only
|
|
329
|
-
// semantic errors on declared fields (required / type / enum / length)
|
|
330
|
-
// refuse the draft.
|
|
331
|
-
return;
|
|
332
|
-
}
|
|
333
|
-
if (node.type === "array") {
|
|
334
|
-
if (!Array.isArray(value)) {
|
|
335
|
-
problems.push({ path, reason: "expected an array" });
|
|
336
|
-
return;
|
|
337
|
-
}
|
|
338
|
-
if (node.items !== undefined) {
|
|
339
|
-
for (let index = 0; index < value.length; index += 1) {
|
|
340
|
-
this.#check(node.items, value[index], `${path}[${index}]`, problems);
|
|
341
|
-
}
|
|
342
|
-
}
|
|
343
|
-
return;
|
|
344
|
-
}
|
|
345
|
-
if (node.type === "string") {
|
|
346
|
-
if (typeof value !== "string") {
|
|
347
|
-
problems.push({ path, reason: "expected a string" });
|
|
348
|
-
return;
|
|
349
|
-
}
|
|
350
|
-
if (node.minLength !== undefined && value.length < node.minLength)
|
|
351
|
-
problems.push({ path, reason: `must be at least ${node.minLength} characters` });
|
|
352
|
-
if (node.maxLength !== undefined && value.length > node.maxLength)
|
|
353
|
-
problems.push({ path, reason: `must be at most ${node.maxLength} characters` });
|
|
354
|
-
return;
|
|
355
|
-
}
|
|
356
|
-
if (node.type === "integer") {
|
|
357
|
-
if (typeof value !== "number" || !Number.isInteger(value)) {
|
|
358
|
-
problems.push({ path, reason: "expected an integer" });
|
|
359
|
-
}
|
|
360
|
-
return;
|
|
361
|
-
}
|
|
362
|
-
if (node.type === "boolean") {
|
|
363
|
-
if (typeof value !== "boolean") problems.push({ path, reason: "expected a boolean" });
|
|
364
|
-
return;
|
|
365
|
-
}
|
|
366
|
-
}
|
|
367
|
-
}
|
|
368
|
-
|
|
369
|
-
/** The JSON-path join — `.field` (or bare, at the root). */
|
|
370
|
-
#at(path: string, key: string): string {
|
|
371
|
-
return path.length === 0 ? key : `${path}.${key}`;
|
|
372
|
-
}
|
|
373
|
-
}
|