@oscaner-skills/cdd-engine 4.10.0 → 4.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/contract/completion-criterion.js +19 -28
- package/dist/contract/doc.js +24 -0
- package/dist/contract/invariants.js +11 -8
- package/dist/contract/judge.js +45 -4
- package/dist/contract/project.js +12 -1
- package/dist/contract/task-block-grammar.js +3 -1
- package/dist/face/board-view.js +327 -138
- package/dist/face/cli.js +172 -63
- package/dist/face/gate.js +6 -3
- package/dist/face/lifecycle.js +191 -128
- package/dist/face/words.js +51 -0
- package/dist/infra/plan-source.js +359 -0
- package/dist/infra/runtime.js +20 -52
- package/dist/render/brief.js +34 -32
- package/dist/render/templates.js +63 -29
- package/dist/session/carrier-integrity.js +0 -8
- package/dist/session/dispatch-authority.js +1 -1
- package/dist/session/handoff-schema.js +135 -73
- package/dist/session/ledger.js +269 -104
- package/dist/session/pipeline.js +2 -2
- package/dist/session/preflight.js +65 -34
- package/dist/session/round-naming.js +138 -89
- package/dist/session/run.js +73 -74
- package/package.json +1 -1
package/dist/render/templates.js
CHANGED
|
@@ -62,17 +62,21 @@ const FRAME_ITEMS = [
|
|
|
62
62
|
* prefix), never this fixed text. */
|
|
63
63
|
const EVIDENCE_ITEM = "**Evidence gate:** write the test-evidence file at the prescribed `OUTPUT_EVIDENCE` path per the `test-evidence` schema in `## Handoff schema` — `command`/`exit_code`/`passed`/`warnings_count` + `typecheck` (`command`/`exit_code`/`passed`); `behavior_change` when applicable. Update the round's report after verification. Missing or schema-violating evidence → the engine rewrites the draft to `status: BLOCKED`. Reports, test output, diffs: files only, never the return.";
|
|
64
64
|
/** The work plane's ONE capability declaration (design spec §7.3) — a dispatched
|
|
65
|
-
* implement / fix / docs-fix round may amend the
|
|
65
|
+
* implement / fix / docs-fix round may amend the CONTENT face of the judged
|
|
66
|
+
* document — the phase-spec / single-spec / overall charter / plan families —
|
|
66
67
|
* because the document authoring right is a prompt slot, never a carrier slot (it
|
|
67
68
|
* is not in `CARRIER`, not in `PLANE_REQUIRED`, not in the frame and not in
|
|
68
69
|
* `progress.json` — the gate judges the result, never the declaration). The
|
|
69
|
-
*
|
|
70
|
+
* declaration names the families in their own words: the freeze clause limits
|
|
71
|
+
* itself to this declared scope, so a docs-fix round on the charter can never read
|
|
72
|
+
* "amend the charter" beside "freeze the spec". The structure face (the plan's Task
|
|
73
|
+
* id set and any task's `DependsOn` set) belongs to
|
|
70
74
|
* the orchestrator: the engine snapshots both faces at dispatch and compares them at
|
|
71
75
|
* the close, so a round-internal structure edit judges the round hard. The docs-fix
|
|
72
76
|
* row carries it too — a fix round on a spec / plan line IS docs-fix, so this is the
|
|
73
77
|
* row the authorization has to reach. The review variants declare nothing — a review
|
|
74
78
|
* is read-only. */
|
|
75
|
-
const WORK_CAPABILITY = "**Capability — `capability: may.amend = content`:** this round may amend the
|
|
79
|
+
const WORK_CAPABILITY = "**Capability — `capability: may.amend = content`:** this round may amend the judged document's content face — the phase-spec, single-spec, overall charter and plan families (facts, file lists, steps, acceptance detail, cited line numbers). The structure face — the plan's Task id set and any task's `DependsOn` set — belongs to the orchestrator: the engine snapshots it at dispatch and compares it at the close, so changing it inside this round judges the round hard.";
|
|
76
80
|
/** The discipline-clause cells shared by every shell (the `{{> cl:…}}` partials
|
|
77
81
|
* resolve from the single clause container — the same bytes, one per shell). */
|
|
78
82
|
const LICENSE_ITEMS = [
|
|
@@ -120,7 +124,7 @@ const FIX_SHELL = [
|
|
|
120
124
|
...FRAME_ITEMS,
|
|
121
125
|
WORK_CAPABILITY,
|
|
122
126
|
...FIX_TYPED_INSTRUCTIONS,
|
|
123
|
-
"**fix:** read `INPUT_REVIEWS` (open findings) + the plan context (`INPUT_WAVE_BRIEF` on a wave line — the complete plan mirror; `INPUT_PLAN` on the
|
|
127
|
+
"**fix:** read `INPUT_REVIEWS` (open findings) + the plan context (`INPUT_WAVE_BRIEF` on a wave line — the complete plan mirror; `INPUT_PLAN` on the branch line — the plan document; `INPUT_SPEC` on the branch line — the design spec, a conformance reference, never the judged document). Fix ALL findings (blocker/warn/nit), verifying against `INPUT_REVIEWS` none remain open. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
|
|
124
128
|
'**Dispositions:** every requested finding needs a disposition keyed by its `id` exactly as the requesting carrier prints it (`F1`, `F2`, … — the summary is description only), valued `{ "status": "fixed" | "rejected", "reason"?: "…" }` — a missing or mis-keyed disposition fails the round.',
|
|
125
129
|
EVIDENCE_ITEM,
|
|
126
130
|
...LICENSE_ITEMS,
|
|
@@ -143,7 +147,7 @@ const DOCS_FIX_SHELL = [
|
|
|
143
147
|
"",
|
|
144
148
|
...FRAME_ITEMS,
|
|
145
149
|
WORK_CAPABILITY,
|
|
146
|
-
"**docs-fix:** apply `INPUT_REVIEWS` (all severities) directly to the judged doc — `INPUT_PLAN` on a plan-doc line, `INPUT_SPEC` on a spec-doc line — removing fixed findings; record the path in `artifacts.doc` and report the round in `status` (APPROVED once every finding is applied, else BLOCKED + the reason in `notes`). Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; retry = full re-run (idempotent).",
|
|
150
|
+
"**docs-fix:** apply `INPUT_REVIEWS` (all severities) directly to the judged doc — `INPUT_PLAN` on a plan-doc line (where `INPUT_SPEC` is the design reference, never edited here), `INPUT_SPEC` on a spec-doc line, `INPUT_OVERALL` on the overall line — removing fixed findings; record the path in `artifacts.doc` and report the round in `status` (APPROVED once every finding is applied, else BLOCKED + the reason in `notes`). Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; retry = full re-run (idempotent).",
|
|
147
151
|
"**Change-history rows:** a new `## Change history` row bumps the front-matter `version:` in the same edit — the header version is the lineage's newest numeric version, and the two can never disagree.",
|
|
148
152
|
"**Table cells:** never hard-wrap a table cell — a wrapped continuation parses as a row whose cell count disagrees with the header, and the lineage row it was meant to be stops registering.",
|
|
149
153
|
"**Escaped pipes:** a `## Change history` summary cell that needs a literal vertical bar carries `\\|` — a bare `|` splits the cell in two and the row stops matching the declared header.",
|
|
@@ -157,16 +161,20 @@ const DOCS_FIX_SHELL = [
|
|
|
157
161
|
];
|
|
158
162
|
/** The review variants' shared instruction text — the review's mode rule (the
|
|
159
163
|
* criteria body + the lens vocabulary ride per-type fixed items below). */
|
|
160
|
-
const REVIEW_ITEM = "**review:** review the criteria below against the reference face named in the round context.
|
|
164
|
+
const REVIEW_ITEM = "**review:** review the criteria below against the reference face named in the round context. A wave review judges `INPUT_WAVE_BRIEF` (the complete plan mirror); the plan review judges the plan at `INPUT_PLAN`; the branch review judges the live tree against its base branch (`INPUT_PLAN` is its plan-conformance reference); the spec review judges the spec at `INPUT_SPEC`; the overall review judges the charter at `INPUT_OVERALL`; and a face whose spec carries a `program:` also carries the parent charter at `INPUT_OVERALL`. Write findings into the draft at `OUTPUT_HANDOFF` per `## Handoff schema` (never print them); empty `findings` = approved. The engine derives the conclusion from the draft's findings (blocker → CHANGES_REQUESTED · warn/nit → REVIEW_FIX · none → APPROVED) — a review never declares its own status. **Read-only:** never mutate tracked content, the index, HEAD, or branch state — the prescribed `OUTPUT_*` artifacts are a review's only writes, and committing belongs to the orchestrator — read history through `git show` / `git diff` / `git log`, and inspect another revision in a separate directory rather than moving HEAD here; repairs belong to the fix round, never to a review. **Single agent:** do the whole review yourself — never spawn a subagent for part of the diff or for a second opinion; this overrides any dispatched skill's parallel-sub-agent default.";
|
|
161
165
|
/** The review mode's shared reduced tail — the only dynamic region of every review
|
|
162
166
|
* variant (the criteria/lens are fixed-prefix per type, never here). Each review
|
|
163
|
-
* type carries its own judged-doc referent (wave → `INPUT_WAVE_BRIEF`; plan
|
|
164
|
-
*
|
|
165
|
-
*
|
|
167
|
+
* type carries its own judged-doc referent (wave → `INPUT_WAVE_BRIEF`; plan →
|
|
168
|
+
* `INPUT_PLAN` as the judged doc, with `INPUT_SPEC` as its plan→spec conformance
|
|
169
|
+
* reference; branch → the live tree against `BASE_BRANCH`, with `INPUT_PLAN` as its
|
|
170
|
+
* plan-conformance reference and the same `INPUT_SPEC` design-spec reference; spec →
|
|
171
|
+
* `INPUT_SPEC`; overall → `INPUT_OVERALL`); empty slots are dropped by the
|
|
172
|
+
* assembler, so a face renders only the anchors it reads. */
|
|
166
173
|
const REVIEW_CONTEXT = [
|
|
167
174
|
"## Round context",
|
|
168
175
|
"",
|
|
169
176
|
"- `ROLE`: {{ROLE}}",
|
|
177
|
+
"- `TARGET_TYPE`: {{TARGET_TYPE}}",
|
|
170
178
|
"- `WAVE`: {{WAVE}}",
|
|
171
179
|
"- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
|
|
172
180
|
"- `INPUT_PLAN`: {{INPUT_PLAN}}",
|
|
@@ -206,6 +214,7 @@ const MODE_PROMPTS = {
|
|
|
206
214
|
"## Round context",
|
|
207
215
|
"",
|
|
208
216
|
"- `ROLE`: {{ROLE}}",
|
|
217
|
+
"- `TARGET_TYPE`: {{TARGET_TYPE}}",
|
|
209
218
|
"- `WAVE`: {{WAVE}}",
|
|
210
219
|
"- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
|
|
211
220
|
"- `INPUT_PLAN`: {{INPUT_PLAN}}",
|
|
@@ -227,6 +236,7 @@ const MODE_PROMPTS = {
|
|
|
227
236
|
"## Round context",
|
|
228
237
|
"",
|
|
229
238
|
"- `ROLE`: {{ROLE}}",
|
|
239
|
+
"- `TARGET_TYPE`: {{TARGET_TYPE}}",
|
|
230
240
|
"- `WAVE`: {{WAVE}}",
|
|
231
241
|
"- `INPUT_PLAN`: {{INPUT_PLAN}}",
|
|
232
242
|
"- `INPUT_SPEC`: {{INPUT_SPEC}}",
|
|
@@ -256,14 +266,14 @@ export const SEVERITY_RUBRIC = "Calibrate findings by real severity — not ever
|
|
|
256
266
|
* `{artifact}` = the reviewed product's name; `{audience}` = the subject whose
|
|
257
267
|
* expectation judges the artifact's silence. The two spec-shaped targets share the
|
|
258
268
|
* ONE `spec` row, so their shared narrative body can never fork its vocabulary;
|
|
259
|
-
* the charter's own
|
|
260
|
-
* never a
|
|
269
|
+
* the charter's own row reads charter / phase author — the completion of the P17
|
|
270
|
+
* `overall-spec` → `overall` rename, never a copy of the spec's vocabulary. */
|
|
261
271
|
export const REVIEW_BODY_TEXT = {
|
|
262
272
|
wave: { artifact: "artifact", audience: "user" },
|
|
263
273
|
branch: { artifact: "artifact", audience: "user" },
|
|
264
274
|
spec: { artifact: "spec", audience: "downstream author" },
|
|
265
275
|
plan: { artifact: "plan", audience: "implementer" },
|
|
266
|
-
overall: { artifact: "
|
|
276
|
+
overall: { artifact: "charter", audience: "phase author" },
|
|
267
277
|
};
|
|
268
278
|
/** The filled severity rubric of one criteria body — the shared fragment with that
|
|
269
279
|
* body's two slot values substituted. The parameter domain IS the `REVIEWS` key
|
|
@@ -288,7 +298,7 @@ export const CLOSED_WAVE_DISCIPLINE = "Closed waves are history: a finding on th
|
|
|
288
298
|
* today's tree happens to have: a line number is not a pin, a prose count is the
|
|
289
299
|
* guard's business, and a present-tense description of today's shape belongs to the
|
|
290
300
|
* plan. Nothing gates the writing moment — the review is where a violation surfaces. */
|
|
291
|
-
const docNarrativeAxes = (guide) => `Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin by module path + symbol name — a line number is not a pin; a count ("N places" · "N rows" · "N modules") must be stated as pinned by the named guard or test; a present-tense description of today's shape belongs to the plan — in a design spec a measurement input is a lens-tagged finding unless restated as a condition that must hold — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + program conformance — judge the phase against its parent overall at \`INPUT_OVERALL\` (the charter its \`program:\` names): the phase must sit inside the scope the overall's Phase inventory registered for it, and a phase that reaches beyond it is a completeness finding. ${CLOSED_WAVE_DISCIPLINE} ${guide}`;
|
|
301
|
+
const docNarrativeAxes = (guide) => `Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin by module path + symbol name — a line number is not a pin; a count ("N places" · "N rows" · "N modules") must be stated as pinned by the named guard or test; a present-tense description of today's shape belongs to the plan — in a design spec a measurement input is a lens-tagged finding unless restated as a condition that must hold — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + program conformance (phase-spec only — a single-spec carries no \`program:\` and no \`INPUT_OVERALL\`, and is not a phase) — judge the phase against its parent overall at \`INPUT_OVERALL\` (the charter its \`program:\` names): the phase must sit inside the scope the overall's Phase inventory registered for it, and a phase that reaches beyond it is a completeness finding. ${CLOSED_WAVE_DISCIPLINE} ${guide}`;
|
|
292
302
|
/** The charter's criteria body — the six things a program charter owns, and only
|
|
293
303
|
* those. It carries none of the implementation-face evidence duty the narrative
|
|
294
304
|
* body carries (running the repository's commands, pinning every claim): a charter
|
|
@@ -306,7 +316,7 @@ export const REVIEWS = {
|
|
|
306
316
|
},
|
|
307
317
|
branch: {
|
|
308
318
|
lensEnum: ["standards", "spec", "buildability"],
|
|
309
|
-
axesGuide: `Same four axes as
|
|
319
|
+
axesGuide: `Same four axes as the wave review (branch-wide health: run \`git diff origin/<BASE_BRANCH>..HEAD\` + plan conformance) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — \`tsc --noEmit\`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): branch review IS the full diff — every changed file must be attributable to a finding, a plan requirement, or the reviewed intent; unrelated surface = candidate finding (severity by your judgment), normal finding → fix loop. ${reviewGuideOf("branch")} Three things a green run cannot show you: design — does the changed structure fit this codebase and is it the simplest structure that solves the plan's problem (over-engineering is a finding, not a preference); test adequacy — would these tests fail if the code broke (a run that cannot go red is not evidence); migration — does every breaking change name the path a not-yet-migrated consumer takes.`,
|
|
310
320
|
},
|
|
311
321
|
spec: {
|
|
312
322
|
lensEnum: ["completeness", "consistency", "clarity"],
|
|
@@ -377,8 +387,8 @@ const RETURN_ZONE = {
|
|
|
377
387
|
/** The token registry — the union across every mode's round context + the shell's
|
|
378
388
|
* schema slot (the v1.8 normalized vocabulary; the assembly face supplies every
|
|
379
389
|
* declared slot, empty where the mode does not consume it — the round-context
|
|
380
|
-
* renderer drops the empty-valued lines).
|
|
381
|
-
*
|
|
390
|
+
* renderer drops the empty-valued lines). TARGET_TYPE is the target discriminant:
|
|
391
|
+
* it selects the review row AND renders on every targeted face. */
|
|
382
392
|
const TOKENS = [
|
|
383
393
|
{ name: "BASE_BRANCH", zone: "round-context" },
|
|
384
394
|
{ name: "HANDOFF_SCHEMA", zone: "shell" },
|
|
@@ -395,8 +405,11 @@ const TOKENS = [
|
|
|
395
405
|
{ name: "OUTPUT_REPORT", zone: "round-context" },
|
|
396
406
|
{ name: "OUTPUT_EVIDENCE", zone: "round-context" },
|
|
397
407
|
{ name: "OUTPUT_HANDOFF", zone: "round-context" },
|
|
398
|
-
{ name: "REVIEW_TYPE", zone: "round-context" },
|
|
399
408
|
{ name: "ROLE", zone: "round-context" },
|
|
409
|
+
// P33 T1 — the target discriminant RENDERS, immediately below ROLE: the child
|
|
410
|
+
// reads the target word the CLI `--type` declared. Implement is the one role
|
|
411
|
+
// without a target, so its layout carries no such line and its value is empty.
|
|
412
|
+
{ name: "TARGET_TYPE", zone: "round-context" },
|
|
400
413
|
{ name: "WAVE", zone: "round-context" },
|
|
401
414
|
{ name: "WORKSPACE_DIR", zone: "round-context" },
|
|
402
415
|
{ name: "WORKSPACE_ID", zone: "round-context" },
|
|
@@ -408,13 +421,34 @@ export const CLAUSES = {
|
|
|
408
421
|
"cl:no-full-tree-find": "Never run an unbounded full-tree `find` over a large directory and never bare-read a large file — constrain to explicit paths with `maxdepth`/`-path`, or read only the needed range.",
|
|
409
422
|
"cl:bash-stall-limit": `Put a \`timeout\` on every Bash command — no single invocation may run longer than ${TerminationPolicy.CHILD_BASH_TIMEOUT_MS / 60_000} minutes; a command that stalls without progress is terminated and replaced with an equivalent, lighter command.`,
|
|
410
423
|
"cl:no-infinite-loop": "Never run an unbounded loop — no `while True: pass`, no `while true; do …; done`, no spin-wait or tail-follow that only a human can stop. A wait must carry a bounded exit condition (a timeout, a max-attempt counter, or a terminating predicate) that ends the loop on its own.",
|
|
411
|
-
"cl:plan-freeze": "Approved plan/spec files are frozen
|
|
412
|
-
"cl:atomic-commit": "Commit each round's change as one atomic conventional commit scoped to the round — no mixed or out-of-scope content, no AI-generation trailers.",
|
|
424
|
+
"cl:plan-freeze": "Approved plan/spec files are frozen beyond the round's declared `capability: may.amend` scope — without that declaration a needed change goes out through findings, never an in-place edit; the structure face is outside amending authority in every round.",
|
|
425
|
+
"cl:atomic-commit": "Commit each round's change as one atomic conventional commit scoped to the round — no mixed or out-of-scope content, no AI-generation trailers. A read-only round has nothing to commit: its only writes are the prescribed `OUTPUT_*` artifacts, and committing belongs to the orchestrator.",
|
|
413
426
|
"cl:self-validate": "Self-validate before returning: run the validation/checks your change requires and record the evidence (command + exit code + result) in the report.",
|
|
414
427
|
"cl:no-secret-access": "Never read, print, or derive a user secret — no keychain access (`security find-generic-password` / `security dump-keychain` / `login.keychain-db`), no `~/.ssh/*`, `~/.aws/credentials`, `~/.netrc`, no host CLI credential store, and no token-bearing environment variable (`*_TOKEN` / `*_API_KEY` / `*_SECRET`). A missing or failing credential is never yours to obtain: report it as `status: BLOCKED` on a work round or as a finding on a review round, then continue with the rest. A secret that reaches a report, evidence file, handoff draft, commit, or issue body has leaked — if one is already visible in your inputs, redact it as `[REDACTED]` and never echo its value.",
|
|
415
428
|
"cl:sync-completion": "This dispatch is one-shot and non-interactive: end your turn with anything still running and the process exits — the work and the handoff die with it. So do not end your turn — a background command, a background subagent, or any yield-and-wait path such as `bg_run` / `bg_delegate` — before the handoff draft is written. Finish nested work in this same turn: complete it synchronously in this process turn, then write the handoff and finish.",
|
|
416
429
|
};
|
|
417
|
-
/** The dispatch-prompt data plane — the typed template-contract surface. $version
|
|
430
|
+
/** The dispatch-prompt data plane — the typed template-contract surface. $version 23
|
|
431
|
+
* calibrates the shared body's five faces (§2.6 G · H · I · J · K): the freeze
|
|
432
|
+
* clause limits itself to the round's declared `capability: may.amend` scope and
|
|
433
|
+
* the commit clause names the read-only round's absent commit; the capability
|
|
434
|
+
* declaration names the judged document families (phase-spec / single-spec /
|
|
435
|
+
* overall charter / plan); the program-conformance clause is scoped to phase-spec;
|
|
436
|
+
* the branch criteria speak `wave`, not the retired `task`; the charter's rubric
|
|
437
|
+
* slots read charter / phase author. $version 22
|
|
438
|
+
* calibrates the referent face of the three instruction shells (§2.5 A · B · D):
|
|
439
|
+
* the review item splits the branch review out of the plan review (the live tree
|
|
440
|
+
* against `BASE_BRANCH`, with `INPUT_PLAN` as its plan-conformance reference) and
|
|
441
|
+
* names the charter anchor; the fix shell drops the unreachable spec line and
|
|
442
|
+
* marks the branch line's `INPUT_SPEC` as a conformance reference; the docs-fix
|
|
443
|
+
* shell marks the plan-doc line's `INPUT_SPEC` un-editable and names the overall
|
|
444
|
+
* line's `INPUT_OVERALL` anchor. The overall face's `INPUT_SPEC` value went empty
|
|
445
|
+
* in the same batch (C2 — one charter anchor). $version 21
|
|
446
|
+
* renames the target discriminant token to TARGET_TYPE and RENDERS it as a
|
|
447
|
+
* round-context line (`- \`TARGET_TYPE\`: <target word>`) immediately below ROLE on
|
|
448
|
+
* every face that has a target — the review variants, the two fix rows (wave ·
|
|
449
|
+
* branch) and the two document-fix rows' plan/spec types (plan · phase-spec ·
|
|
450
|
+
* overall · single-spec). Implement is the one role without a target, so its layout
|
|
451
|
+
* carries no such line and the empty value is dropped. $version 20
|
|
418
452
|
* gives the charter its own review criteria body (the six charter criteria, with
|
|
419
453
|
* none of the implementation-face evidence duty) and makes the criteria-body
|
|
420
454
|
* selection explicit — the two spec-shaped document targets share the ONE narrative
|
|
@@ -456,7 +490,7 @@ export const CLAUSES = {
|
|
|
456
490
|
* prose return contract (`RETURN_PROSE` — nothing downstream parses the child's
|
|
457
491
|
* stdout), and the per-type review criterion shells. */
|
|
458
492
|
export const TEMPLATE_PROMPT = {
|
|
459
|
-
$version:
|
|
493
|
+
$version: 23,
|
|
460
494
|
modes: MODE_PROMPTS,
|
|
461
495
|
reviews: REVIEW_VARIANTS,
|
|
462
496
|
return: RETURN_ZONE,
|
|
@@ -469,7 +503,7 @@ export const WORK_MODES = ["implement", "fix", "review", "docs-fix"];
|
|
|
469
503
|
* The template assembler — the ONE renderer over the typed template-prompt data
|
|
470
504
|
* plane. Construction reads the typed contract (the module's declared data —
|
|
471
505
|
* no file reads, no second copy). render(values) selects the row by the ROLE value
|
|
472
|
-
* (the review mode by ROLE +
|
|
506
|
+
* (the review mode by ROLE + TARGET_TYPE) — the row's fixed prefix + the single
|
|
473
507
|
* return contract + its reduced round context (empty-value keys not emitted).
|
|
474
508
|
*/
|
|
475
509
|
export class TemplateAssembler {
|
|
@@ -502,12 +536,12 @@ export class TemplateAssembler {
|
|
|
502
536
|
return lines.join("\n");
|
|
503
537
|
}
|
|
504
538
|
/** The row of a ROLE — the review mode's per-type variant (selected by the
|
|
505
|
-
*
|
|
539
|
+
* TARGET_TYPE discriminant), the work modes from the modes table. */
|
|
506
540
|
#rowOf(values) {
|
|
507
541
|
if (values.ROLE === "review") {
|
|
508
|
-
const row = this.#contract.reviews[values.
|
|
542
|
+
const row = this.#contract.reviews[values.TARGET_TYPE];
|
|
509
543
|
if (row === undefined) {
|
|
510
|
-
throw new Error(`template review type not declared: ${values.
|
|
544
|
+
throw new Error(`template review type not declared: ${values.TARGET_TYPE === undefined || values.TARGET_TYPE === "" ? "(missing TARGET_TYPE)" : values.TARGET_TYPE}`);
|
|
511
545
|
}
|
|
512
546
|
return row;
|
|
513
547
|
}
|
|
@@ -529,7 +563,7 @@ export class TemplateAssembler {
|
|
|
529
563
|
}
|
|
530
564
|
return lines.join("\n");
|
|
531
565
|
}
|
|
532
|
-
/** The hard gates — a known ROLE (+ its
|
|
566
|
+
/** The hard gates — a known ROLE (+ its TARGET_TYPE for reviews), every declared
|
|
533
567
|
* token supplied (empty allowed — a mode's non-consumed slots are legitimately
|
|
534
568
|
* empty and merely not emitted), no undeclared values, the single return
|
|
535
569
|
* contract declared, and every round-context name the mode's shell prose
|
|
@@ -543,7 +577,7 @@ export class TemplateAssembler {
|
|
|
543
577
|
: this.#workRow(role);
|
|
544
578
|
if (row === undefined) {
|
|
545
579
|
const message = role === "review"
|
|
546
|
-
? `template review type not declared: ${values.
|
|
580
|
+
? `template review type not declared: ${values.TARGET_TYPE === undefined || values.TARGET_TYPE === "" ? "(missing TARGET_TYPE)" : values.TARGET_TYPE}`
|
|
547
581
|
: `template work-mode not declared: ${role === undefined ? "(missing ROLE)" : role}`;
|
|
548
582
|
throw new Error(message);
|
|
549
583
|
}
|
|
@@ -578,9 +612,9 @@ export class TemplateAssembler {
|
|
|
578
612
|
}
|
|
579
613
|
}
|
|
580
614
|
}
|
|
581
|
-
/** The review variant of a
|
|
615
|
+
/** The review variant of a TARGET_TYPE (verified in the gate). */
|
|
582
616
|
#reviewRow(values) {
|
|
583
|
-
return this.#contract.reviews[values.
|
|
617
|
+
return this.#contract.reviews[values.TARGET_TYPE];
|
|
584
618
|
}
|
|
585
619
|
/** The work-mode row of a ROLE (verified in the gate). */
|
|
586
620
|
#workRow(role) {
|
|
@@ -85,14 +85,6 @@ export class CarrierIntegrity {
|
|
|
85
85
|
return bytes;
|
|
86
86
|
throw new CarrierMismatchError(path, gap.recorded, gap.current);
|
|
87
87
|
}
|
|
88
|
-
/** The record-shaped thin shell — the `RoundRecord`'s own two cells, so a caller
|
|
89
|
-
* holding a record never re-derives "which digest belongs to this path". A record
|
|
90
|
-
* with no carrier path reads `null` without touching the disk. */
|
|
91
|
-
static readFor(record) {
|
|
92
|
-
if (record.carrierPath === null)
|
|
93
|
-
return null;
|
|
94
|
-
return CarrierIntegrity.read(record.carrierPath, record.carrierDigest ?? null);
|
|
95
|
-
}
|
|
96
88
|
/** The payload view `digestOf` hashes — a shallow copy with the top-level
|
|
97
89
|
* `contentSha256` key dropped (a non-object payload is returned as it stands). */
|
|
98
90
|
static #payloadOf(value) {
|
|
@@ -181,7 +181,7 @@ export class DispatchAuthority {
|
|
|
181
181
|
* finished run's plan edit blocked the branch review). Only an OPEN batch's brief
|
|
182
182
|
* movement refuses the faces below the wave face. */
|
|
183
183
|
#waveStation(facts) {
|
|
184
|
-
const graph = facts.pipeline.
|
|
184
|
+
const graph = facts.pipeline.plan.graph();
|
|
185
185
|
if (graph === null)
|
|
186
186
|
return null;
|
|
187
187
|
const frontier = this.#frontierOf(facts);
|
|
@@ -6,9 +6,10 @@
|
|
|
6
6
|
//
|
|
7
7
|
// · projections: ① the prompt-injection text (schemaText — the ```json fences
|
|
8
8
|
// byte-fixed per plane, so the fixed prefix tail of the dispatch prompt stays
|
|
9
|
-
// cache-friendly) and ② the engine read-back validator (
|
|
10
|
-
// evidenceViolations — the child draft is
|
|
11
|
-
// projected objects the prompt showed it
|
|
9
|
+
// cache-friendly) and ② the engine read-back validator (readBack /
|
|
10
|
+
// evidenceViolations — the child draft is judged against exactly the same
|
|
11
|
+
// projected objects the prompt showed it, the required slots refusing the round
|
|
12
|
+
// and the decorative ones dropped in place).
|
|
12
13
|
// · planes: the carrier plane is DERIVED from the op (planeOf), never declared per
|
|
13
14
|
// family — `work` (implement/fix: status + artifacts, plus the separate
|
|
14
15
|
// test-evidence file for task-family rounds) or `judge` (reviews: findings-only
|
|
@@ -26,6 +27,7 @@
|
|
|
26
27
|
//
|
|
27
28
|
// Module-level exports are types / the declared schema objects / the class — zero
|
|
28
29
|
// behavior-carrying bare functions (the plan's zero-bare-function discipline).
|
|
30
|
+
var _a;
|
|
29
31
|
/** One finding row — the shared base declaration of the judge plane (severity +
|
|
30
32
|
* lens + summary required; the extra review columns — section / line / fix — are
|
|
31
33
|
* declared optional, and unknown extra fields ride along).
|
|
@@ -113,8 +115,12 @@ const EVIDENCE = {
|
|
|
113
115
|
},
|
|
114
116
|
};
|
|
115
117
|
/**
|
|
116
|
-
* HandoffSchema — one declaration, two projections. `
|
|
117
|
-
*
|
|
118
|
+
* HandoffSchema — one declaration, two projections. `readBack(plane, draft)` is the
|
|
119
|
+
* carrier read-back validator (projection ② — the engine's seat, session plane: the
|
|
120
|
+
* dispatch gate's tiered ruling), and `evidenceViolations(value)` is the strict walk
|
|
121
|
+
* of the evidence file's own declaration (the evidence gate's input). The carrier
|
|
122
|
+
* plane has no strict reader: a decorative slot's mistake there costs a field, never
|
|
123
|
+
* a round, so a second strict walk of the carrier would judge nothing.
|
|
118
124
|
* `schemaText(plane, evidence)` is the injected prompt text (projection ① — fixed
|
|
119
125
|
* prefix tail, byte-stable per plane so the dispatch prompt stays cache-friendly).
|
|
120
126
|
* `rollup(findings)` derives the review conclusion the old JSON face rolled up.
|
|
@@ -128,15 +134,15 @@ export class HandoffSchema {
|
|
|
128
134
|
}
|
|
129
135
|
/** Projection ① — the `## Handoff schema` section text: the plane's writable
|
|
130
136
|
* subset in a ```json fence + (work plane) the evidence file's schema in a second
|
|
131
|
-
* fence. The
|
|
132
|
-
* of the dispatch prompt's contract surface. The evidence
|
|
133
|
-
*
|
|
134
|
-
*
|
|
135
|
-
schemaText(plane, evidence
|
|
137
|
+
* fence. The carrier fence is byte-stable per (plane, evidence) — the fixed bytes
|
|
138
|
+
* of the dispatch prompt's contract surface. The evidence sentence names the
|
|
139
|
+
* `OUTPUT_EVIDENCE` slot alone — the file's own name is the naming face's single
|
|
140
|
+
* source (`tasks-*` / `branch-*` per family), never a second spelling here. */
|
|
141
|
+
schemaText(plane, evidence) {
|
|
136
142
|
const carrier = this.#json(this.#writable(plane));
|
|
137
143
|
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\`\`\``;
|
|
138
144
|
if (evidence) {
|
|
139
|
-
text += `\n\nThe evidence file (
|
|
145
|
+
text += `\n\nThe evidence file (the file named by \`OUTPUT_EVIDENCE\`) must comply with this schema — the engine reads it back with the same stakes:\n\n\`\`\`json\n${this.#json(EVIDENCE)}\n\`\`\``;
|
|
140
146
|
}
|
|
141
147
|
return text;
|
|
142
148
|
}
|
|
@@ -144,21 +150,28 @@ export class HandoffSchema {
|
|
|
144
150
|
evidenceSchemaText() {
|
|
145
151
|
return this.#json(EVIDENCE);
|
|
146
152
|
}
|
|
147
|
-
/**
|
|
148
|
-
*
|
|
149
|
-
*
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
153
|
+
/** The TIERED read-back — the dispatch gate's ONE ruling (spec §2.1): a REQUIRED
|
|
154
|
+
* slot that violates its declaration REFUSES the draft (the round blocks), while a
|
|
155
|
+
* DECORATIVE slot (declared, not required — BOTH planes' `notes`, the work plane's
|
|
156
|
+
* `dispositions`, the judge plane's `artifacts` and the finding row's `id` /
|
|
157
|
+
* `section` / `line` / `fix`) is DROPPED: its path is reported once and the slot is
|
|
158
|
+
* never carried. The walk WRITES nothing — materialize's copy points (`draftNotes`
|
|
159
|
+
* / `dispositions` / the judge carrier's `artifacts` read at lifecycle.ts's
|
|
160
|
+
* `#materialize` / `#findingsList`) consume `dropped`, so the ruling and the carrier
|
|
161
|
+
* cannot disagree. A wrong decorative value costs a field, never a round — the
|
|
162
|
+
* refusal face stays exactly as wide as the fields the child owes. */
|
|
163
|
+
readBack(plane, draft) {
|
|
164
|
+
const out = { tier: "tiered", problems: [], dropped: [] };
|
|
165
|
+
this.#check(this.#writable(plane), draft, "", out);
|
|
166
|
+
return { problems: _a.#problemsOf(out.problems), dropped: out.dropped };
|
|
154
167
|
}
|
|
155
168
|
/** Projection ② — validate the test-evidence file (work-plane wave / branch rounds). */
|
|
156
169
|
evidenceViolations(value) {
|
|
157
170
|
if (value === null || value === undefined)
|
|
158
171
|
return ["the evidence file is missing"];
|
|
159
|
-
const
|
|
160
|
-
this.#check(EVIDENCE, value, "",
|
|
161
|
-
return
|
|
172
|
+
const out = { tier: "strict", problems: [], dropped: [] };
|
|
173
|
+
this.#check(EVIDENCE, value, "", out);
|
|
174
|
+
return _a.#problemsOf(out.problems);
|
|
162
175
|
}
|
|
163
176
|
/** The round conclusion, DERIVED at judgment time from the plane — the single
|
|
164
177
|
* source the review/fix ledger legs read (D27 · judgment face ⊥ input face).
|
|
@@ -233,6 +246,15 @@ export class HandoffSchema {
|
|
|
233
246
|
const declared = new Set(Object.keys(this.#writable(plane).properties ?? {}));
|
|
234
247
|
return Object.keys(value).filter((key) => !declared.has(key));
|
|
235
248
|
}
|
|
249
|
+
/** The column one dropped path names inside a finding row — `findings[2].line` at
|
|
250
|
+
* index 2 reads `line`; every other dropped path (a plane-level slot, another row's
|
|
251
|
+
* column) reads null. The dropped-path grammar is the walker's own
|
|
252
|
+
* (`findings[{index}].{column}`), so its parse lives beside the walk that spells it —
|
|
253
|
+
* materialize's finding copy point calls this instead of re-spelling the shape. */
|
|
254
|
+
static findingColumnOf(path, index) {
|
|
255
|
+
const match = /^findings\[(\d+)\]\.(.+)$/.exec(path);
|
|
256
|
+
return match !== null && Number(match[1]) === index ? match[2] : null;
|
|
257
|
+
}
|
|
236
258
|
/** The plane's writable subset — CARRIER's declared slots filtered to the plane's
|
|
237
259
|
* writable set (declaration order preserved) + the plane's required slots. */
|
|
238
260
|
#writable(plane) {
|
|
@@ -252,71 +274,111 @@ export class HandoffSchema {
|
|
|
252
274
|
#json(node) {
|
|
253
275
|
return JSON.stringify(node);
|
|
254
276
|
}
|
|
255
|
-
/**
|
|
256
|
-
|
|
277
|
+
/** The `path: reason` forms of one walk's problems — the ONE wording the read-back
|
|
278
|
+
* and the evidence gate report. */
|
|
279
|
+
static #problemsOf(problems) {
|
|
280
|
+
return problems.map((problem) => problem.path.length === 0 ? problem.reason : `${problem.path}: ${problem.reason}`);
|
|
281
|
+
}
|
|
282
|
+
/** Walk one schema node against a value — the ONE walker behind both tiers. `owed`
|
|
283
|
+
* says whether the slot being judged is one the child OWES: its mismatch is a
|
|
284
|
+
* problem on either tier. A DECORATIVE slot's mismatch (a declared slot outside the
|
|
285
|
+
* plane's required set, a finding row's decorative column) is a problem on the strict
|
|
286
|
+
* walk and a DROP on the tiered one; the parent prunes whatever the slot booked
|
|
287
|
+
* inside itself and reports the slot's own path.
|
|
288
|
+
* Five parameters, one reason: `owed` is the recursion's own fact — a per-node
|
|
289
|
+
* wrapper object would allocate a frame for one boolean and hide the frame's tier. */
|
|
290
|
+
#check(node, value, path, out, owed = true) {
|
|
257
291
|
if (node.enum !== undefined && !node.enum.includes(value)) {
|
|
258
|
-
|
|
292
|
+
this.#refuse(out, path, `must be one of ${node.enum.join(" | ")}`, owed);
|
|
259
293
|
return;
|
|
260
294
|
}
|
|
261
|
-
if (node.type
|
|
262
|
-
if (
|
|
263
|
-
|
|
264
|
-
problems.push({ path, reason: "expected an object" });
|
|
265
|
-
return;
|
|
266
|
-
}
|
|
267
|
-
const obj = value;
|
|
268
|
-
for (const key of node.required ?? []) {
|
|
269
|
-
if (obj[key] === undefined)
|
|
270
|
-
problems.push({ path: this.#at(path, key), reason: "required" });
|
|
271
|
-
}
|
|
272
|
-
for (const [key, sub] of Object.entries(node.properties ?? {})) {
|
|
273
|
-
if (obj[key] !== undefined)
|
|
274
|
-
this.#check(sub, obj[key], this.#at(path, key), problems);
|
|
275
|
-
}
|
|
276
|
-
// Non-declared keys (extra child fields such as a work-draft `findings`) are
|
|
277
|
-
// DROPPED by materialize, never a BLOCK — the validator and materialize judge
|
|
278
|
-
// the same field the same way (§8.7). Only semantic errors on declared fields
|
|
279
|
-
// (required / type / enum / length) refuse the draft.
|
|
295
|
+
if (node.type === "object") {
|
|
296
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
297
|
+
this.#refuse(out, path, "expected an object", owed);
|
|
280
298
|
return;
|
|
281
299
|
}
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
return;
|
|
293
|
-
}
|
|
294
|
-
if (node.type === "string") {
|
|
295
|
-
if (typeof value !== "string") {
|
|
296
|
-
problems.push({ path, reason: "expected a string" });
|
|
297
|
-
return;
|
|
298
|
-
}
|
|
299
|
-
if (node.minLength !== undefined && value.length < node.minLength)
|
|
300
|
-
problems.push({ path, reason: `must be at least ${node.minLength} characters` });
|
|
301
|
-
if (node.maxLength !== undefined && value.length > node.maxLength)
|
|
302
|
-
problems.push({ path, reason: `must be at most ${node.maxLength} characters` });
|
|
303
|
-
return;
|
|
304
|
-
}
|
|
305
|
-
if (node.type === "integer") {
|
|
306
|
-
if (typeof value !== "number" || !Number.isInteger(value)) {
|
|
307
|
-
problems.push({ path, reason: "expected an integer" });
|
|
308
|
-
}
|
|
300
|
+
// Non-declared keys (extra child fields such as a work-draft `findings`) are
|
|
301
|
+
// DROPPED by materialize, never a BLOCK — the validator and materialize judge
|
|
302
|
+
// the same field the same way (§8.7). Only semantic errors on declared fields
|
|
303
|
+
// (required / type / enum / length) refuse the draft.
|
|
304
|
+
this.#checkObject(node, value, path, out);
|
|
305
|
+
return;
|
|
306
|
+
}
|
|
307
|
+
if (node.type === "array") {
|
|
308
|
+
if (!Array.isArray(value)) {
|
|
309
|
+
this.#refuse(out, path, "expected an array", owed);
|
|
309
310
|
return;
|
|
310
311
|
}
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
problems.push({ path, reason: "expected a boolean" });
|
|
312
|
+
const items = node.items;
|
|
313
|
+
if (items === undefined)
|
|
314
314
|
return;
|
|
315
|
+
// An element is owed once its slot is present: a bad element is judged INSIDE the
|
|
316
|
+
// slot, and a decorative slot's parent prunes it with the rest of the slot.
|
|
317
|
+
for (const [index, entry] of value.entries()) {
|
|
318
|
+
this.#check(items, entry, `${path}[${index}]`, out);
|
|
315
319
|
}
|
|
320
|
+
return;
|
|
321
|
+
}
|
|
322
|
+
const reason = _a.#scalarReason(node, value);
|
|
323
|
+
if (reason !== null)
|
|
324
|
+
this.#refuse(out, path, reason, owed);
|
|
325
|
+
}
|
|
326
|
+
/** The object half — the required sweep (a missing owed key refuses on either tier),
|
|
327
|
+
* then every present declared slot judged at its own owed-ness. */
|
|
328
|
+
#checkObject(node, obj, path, out) {
|
|
329
|
+
const required = node.required ?? [];
|
|
330
|
+
for (const key of required) {
|
|
331
|
+
if (obj[key] !== undefined)
|
|
332
|
+
continue;
|
|
333
|
+
out.problems.push({ path: this.#at(path, key), reason: "required" });
|
|
334
|
+
}
|
|
335
|
+
for (const [key, sub] of Object.entries(node.properties ?? {})) {
|
|
336
|
+
if (obj[key] === undefined)
|
|
337
|
+
continue;
|
|
338
|
+
const at = this.#at(path, key);
|
|
339
|
+
const owed = required.includes(key);
|
|
340
|
+
const markProblems = out.problems.length;
|
|
341
|
+
const markDropped = out.dropped.length;
|
|
342
|
+
this.#check(sub, obj[key], at, out, owed);
|
|
343
|
+
if (owed || out.tier === "strict" || out.problems.length === markProblems)
|
|
344
|
+
continue;
|
|
345
|
+
// The decorative slot breaks its own declaration — prune everything it booked
|
|
346
|
+
// inside, then report the slot once (materialize's copy point reads this path).
|
|
347
|
+
out.problems.length = markProblems;
|
|
348
|
+
out.dropped.length = markDropped;
|
|
349
|
+
out.dropped.push(at);
|
|
316
350
|
}
|
|
317
351
|
}
|
|
352
|
+
/** The scalar keywords' judgment — the reason a value breaks its declared type or
|
|
353
|
+
* length, null when it passes. The enum is judged by the caller first (an enum value
|
|
354
|
+
* is matched by value, never by the declared type alone). */
|
|
355
|
+
static #scalarReason(node, value) {
|
|
356
|
+
if (node.type === "string") {
|
|
357
|
+
if (typeof value !== "string")
|
|
358
|
+
return "expected a string";
|
|
359
|
+
if (node.minLength !== undefined && value.length < node.minLength)
|
|
360
|
+
return `must be at least ${node.minLength} characters`;
|
|
361
|
+
if (node.maxLength !== undefined && value.length > node.maxLength)
|
|
362
|
+
return `must be at most ${node.maxLength} characters`;
|
|
363
|
+
return null;
|
|
364
|
+
}
|
|
365
|
+
if (node.type === "integer")
|
|
366
|
+
return typeof value === "number" && Number.isInteger(value) ? null : "expected an integer";
|
|
367
|
+
if (node.type === "boolean")
|
|
368
|
+
return typeof value === "boolean" ? null : "expected a boolean";
|
|
369
|
+
return null;
|
|
370
|
+
}
|
|
371
|
+
/** Book one mismatch at its tier — a problem for an owed slot (or a strict walk), a
|
|
372
|
+
* dropped path for a decorative one. */
|
|
373
|
+
#refuse(out, path, reason, owed) {
|
|
374
|
+
if (owed || out.tier === "strict")
|
|
375
|
+
out.problems.push({ path, reason });
|
|
376
|
+
else
|
|
377
|
+
out.dropped.push(path);
|
|
378
|
+
}
|
|
318
379
|
/** The JSON-path join — `.field` (or bare, at the root). */
|
|
319
380
|
#at(path, key) {
|
|
320
381
|
return path.length === 0 ? key : `${path}.${key}`;
|
|
321
382
|
}
|
|
322
383
|
}
|
|
384
|
+
_a = HandoffSchema;
|