@oscaner-skills/cdd-engine 4.12.0 → 4.14.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/README.md +22 -0
- package/README.zh-CN.md +22 -0
- package/dist/contract/census.js +134 -0
- package/dist/contract/invariants.js +11 -6
- package/dist/contract/pins.js +893 -0
- package/dist/contract/review-criteria.js +332 -0
- package/dist/face/artifacts.js +13 -4
- package/dist/face/board-view.js +414 -71
- package/dist/face/capsule.js +7 -5
- package/dist/face/cli.js +192 -63
- package/dist/face/declare.js +10 -6
- package/dist/face/lifecycle.js +303 -114
- package/dist/face/preview.js +9 -0
- package/dist/face/route-render.js +23 -7
- package/dist/face/words.js +53 -7
- package/dist/infra/carrier-seal.js +47 -24
- package/dist/infra/plan-source.js +180 -78
- package/dist/infra/slug-index.js +58 -27
- package/dist/infra/workspace.js +19 -1
- package/dist/render/templates.js +84 -16
- package/dist/session/artifact-reads.js +108 -0
- package/dist/session/carrier-rulings.js +98 -45
- package/dist/session/dispatch-authority.js +2 -3
- package/dist/session/handoff-schema.js +137 -5
- package/dist/session/inflight.js +5 -2
- package/dist/session/ledger.js +178 -248
- package/dist/session/next.js +62 -15
- package/dist/session/round-artifacts.js +645 -0
- package/dist/session/round-naming.js +16 -81
- package/dist/session/run.js +19 -16
- package/package.json +1 -1
package/dist/face/capsule.js
CHANGED
|
@@ -17,9 +17,9 @@
|
|
|
17
17
|
// count is exactly the number the review criterion rules undisplayed. The key set is
|
|
18
18
|
// still the word table's single source (`Words.capsuleKeys(status, withHandoff)`) —
|
|
19
19
|
// a failure status keeps the handoff cell only when the round wrote a crash record.
|
|
20
|
-
// The fix round's disposition summary
|
|
21
|
-
//
|
|
22
|
-
// `reason:`.
|
|
20
|
+
// The `summary` slot — the fix round's disposition summary, or the review round's
|
|
21
|
+
// downgrade note — rides the SAME render, placed so the dispatchable `next:` literal
|
|
22
|
+
// keeps its line: `status` → summary → `next:` → `reason:`.
|
|
23
23
|
//
|
|
24
24
|
// The byte face is v1-pinned: the key words (status · handoff) are pin-enforced by
|
|
25
25
|
// the CapsuleKey type and the emit signature — a data-only change cannot reshape
|
|
@@ -85,8 +85,10 @@ export class Capsule {
|
|
|
85
85
|
/** emit(status, handoff, hop, withHandoff, summary) → the capsule stdout lines:
|
|
86
86
|
* the status-class key set from the word table (a success status renders
|
|
87
87
|
* `status · handoff`; a failure status renders `status`, plus `handoff` only when
|
|
88
|
-
* the round wrote a crash record), then the
|
|
89
|
-
*
|
|
88
|
+
* the round wrote a crash record), then the optional `summary` line — the fix
|
|
89
|
+
* round's disposition summary, or the review round's downgrade note (both fill the
|
|
90
|
+
* ONE slot; there is no second render path for either), then the optional `next:`
|
|
91
|
+
* row followed by its `reason:` row — the dispatchable
|
|
90
92
|
* literal keeps its exact bytes and the diagnostic fact lands on the line after
|
|
91
93
|
* it. `hop` is the ONE injected `NextHop` object — its ABSENCE (null: the
|
|
92
94
|
* BLOCKED / TIMEOUT failure face) prints neither row, while a present object
|
package/dist/face/cli.js
CHANGED
|
@@ -68,6 +68,7 @@ import { HoldingError, InFlight } from "../session/inflight.js";
|
|
|
68
68
|
import { Ledger } from "../session/ledger.js";
|
|
69
69
|
import { NextStepRouter } from "../session/next.js";
|
|
70
70
|
import { PreFlight } from "../session/preflight.js";
|
|
71
|
+
import { ArtifactRegistry } from "../session/round-artifacts.js";
|
|
71
72
|
import { EMPTY_RUN_STATE, Lifecycle } from "../session/run.js";
|
|
72
73
|
import { CliArtifacts } from "./artifacts.js";
|
|
73
74
|
import { BoardNext, BoardView } from "./board-view.js";
|
|
@@ -137,6 +138,19 @@ export class Cli {
|
|
|
137
138
|
/** The pure-command domain (T8 — the split contract's artifacts face,
|
|
138
139
|
* face/artifacts.ts): the schema/issue/base run bodies. */
|
|
139
140
|
#artifacts;
|
|
141
|
+
/** The artifact matrix of this invocation — constructed ONCE per command and handed
|
|
142
|
+
* down to the scene's ledger / router / lifecycle, the board's node ledgers and the
|
|
143
|
+
* seal sweep. It binds no workspace (the matrix is naming knowledge; the workspace is
|
|
144
|
+
* the read-time coordinate), so ONE instance serves every node a command observes.
|
|
145
|
+
* The doc domain answers through the command's identity index, which is bound ONTO
|
|
146
|
+
* this instance at `#indexOf` — the same object, never a second registry. */
|
|
147
|
+
#matrix;
|
|
148
|
+
/** The command's ONE identity index — built once per repo root at `#indexOf`, so no
|
|
149
|
+
* two read faces of a command scan the doc roots twice. */
|
|
150
|
+
#index = null;
|
|
151
|
+
/** The repo root `#index` was built over — the memo's key (a Cli may serve several
|
|
152
|
+
* commands, and a fixture several repos). */
|
|
153
|
+
#indexRoot = null;
|
|
140
154
|
/** The harness plugin bootstrap (P20 — face/init.ts): the repo-independent
|
|
141
155
|
* install/update sequence face. */
|
|
142
156
|
#init;
|
|
@@ -175,11 +189,16 @@ export class Cli {
|
|
|
175
189
|
});
|
|
176
190
|
this.#authority = opts.authority ?? new DispatchAuthority();
|
|
177
191
|
this.#gate = new CliGate({ brief: this.#brief, authority: this.#authority });
|
|
192
|
+
// The invocation's ONE matrix — the command preamble's construction point. The
|
|
193
|
+
// declared domain is bound onto this same instance at `#indexOf` (an injected one
|
|
194
|
+
// included), so no face ever holds a registry the doc reads do not answer through.
|
|
195
|
+
this.#matrix = opts.artifacts ?? new ArtifactRegistry();
|
|
178
196
|
this.#artifacts = new CliArtifacts({
|
|
179
197
|
io: this.#io,
|
|
180
198
|
projector: this.#projector,
|
|
181
199
|
issue: this.#issue,
|
|
182
200
|
stdinRead: this.#stdinRead,
|
|
201
|
+
matrix: this.#matrix,
|
|
183
202
|
usage: (node, message) => this.#usage(node, message),
|
|
184
203
|
});
|
|
185
204
|
// The synchronous writer — the step header must land before the spawned
|
|
@@ -210,6 +229,12 @@ export class Cli {
|
|
|
210
229
|
async runArgv(raw) {
|
|
211
230
|
try {
|
|
212
231
|
this.#exitCode = 0;
|
|
232
|
+
// One COMMAND, one index: the memo below serves a single invocation (its two
|
|
233
|
+
// call points — the command preamble and the scene — must read one snapshot),
|
|
234
|
+
// and the next invocation re-scans. A memo carried across commands would answer
|
|
235
|
+
// from a snapshot taken before the documents this command writes or observes.
|
|
236
|
+
this.#index = null;
|
|
237
|
+
this.#indexRoot = null;
|
|
213
238
|
await this.#program.parseAsync([...raw], { from: "user" });
|
|
214
239
|
return this.#exitCode;
|
|
215
240
|
}
|
|
@@ -327,6 +352,21 @@ export class Cli {
|
|
|
327
352
|
this.#exitCode = await this.#init.run(request);
|
|
328
353
|
});
|
|
329
354
|
}
|
|
355
|
+
/** The command's ONE identity index — the doc-domain binding point. `board` · the
|
|
356
|
+
* scene assembly · `base` each call this once, and a second call inside one command
|
|
357
|
+
* reuses the memo (a command never scans the doc roots twice). The matrix's declared
|
|
358
|
+
* domain is bound onto the SAME registry instance here — the base face, the ledgers,
|
|
359
|
+
* the lifecycle and the board all keep holding it, so a doc read can not fall on a
|
|
360
|
+
* table that never learned the index. */
|
|
361
|
+
#indexOf(repoRoot) {
|
|
362
|
+
if (this.#index !== null && this.#indexRoot === repoRoot)
|
|
363
|
+
return this.#index;
|
|
364
|
+
const index = SlugIndex.build(repoRoot);
|
|
365
|
+
this.#index = index;
|
|
366
|
+
this.#indexRoot = repoRoot;
|
|
367
|
+
this.#matrix.bindDocIndex(index);
|
|
368
|
+
return index;
|
|
369
|
+
}
|
|
330
370
|
/** `cdd board --plan <path> / --spec <path>` — the entry document's progress board
|
|
331
371
|
* (spec §3.1): a PURE READ — zero preflight gate, zero tree writes, zero ledger
|
|
332
372
|
* writes, zero child dispatch. At least one path flag is required (missing →
|
|
@@ -347,10 +387,6 @@ export class Cli {
|
|
|
347
387
|
if (repoRoot === null)
|
|
348
388
|
return 1;
|
|
349
389
|
const root = new RepoRoot(repoRoot);
|
|
350
|
-
// The board's plan read seam — ONE instance per command, threaded down the
|
|
351
|
-
// static render chain (the board's ledgers read their brief revisions through
|
|
352
|
-
// it; a node workspace never mints its own).
|
|
353
|
-
const planSource = new PlanSource(root);
|
|
354
390
|
const planRel = planArg === undefined ? null : this.#relativizePath(root, planArg);
|
|
355
391
|
const specRel = specArg === undefined ? null : this.#relativizePath(root, specArg);
|
|
356
392
|
// The not-found face reads ZERO documents (spec §3.1): a path outside the two
|
|
@@ -365,6 +401,15 @@ export class Cli {
|
|
|
365
401
|
planMissing ? `--plan ${planArg}` : null,
|
|
366
402
|
specMissing ? `--spec ${specArg}` : null,
|
|
367
403
|
]);
|
|
404
|
+
// The command's ONE identity index — built BEFORE the read seam, which is handed
|
|
405
|
+
// it: the plan read asks the same scan the board renders from (a second index
|
|
406
|
+
// would be a second snapshot of the disk, and §2.7's "clean surface" answer must
|
|
407
|
+
// describe the one the board names).
|
|
408
|
+
const index = this.#indexOf(repoRoot);
|
|
409
|
+
// The board's plan read seam — ONE instance per command, threaded down the
|
|
410
|
+
// static render chain (the board's ledgers read their brief revisions through
|
|
411
|
+
// it; a node workspace never mints its own).
|
|
412
|
+
const planSource = new PlanSource(root, index);
|
|
368
413
|
// ② the read (spec §2.4): ONLY a solo `--plan` reads X's bytes. When `--spec` is
|
|
369
414
|
// present the board's value comes from `readFor(specEntry)` (§2.1: `--spec` wins),
|
|
370
415
|
// so X's bytes are never opened — its `--plan` duties stay the ① existence probe
|
|
@@ -374,7 +419,6 @@ export class Cli {
|
|
|
374
419
|
const soloPlanRead = specRel === null && planRel !== null ? planSource.readPath(planRel) : null;
|
|
375
420
|
if (soloPlanRead !== null && soloPlanRead.failure()?.cause === "io")
|
|
376
421
|
return this.#boardCannotRead(`--plan ${planArg}`);
|
|
377
|
-
const index = SlugIndex.build(repoRoot);
|
|
378
422
|
const planEntry = planRel === null ? null : index.entryAt(planRel);
|
|
379
423
|
const specEntry = specRel === null ? null : index.entryAt(specRel);
|
|
380
424
|
const unmatched = [
|
|
@@ -399,7 +443,13 @@ export class Cli {
|
|
|
399
443
|
const host = HostDetect.detect(process.env);
|
|
400
444
|
// The in-flight fact is TREE-level: the board inspects it (read-only — the gate
|
|
401
445
|
// and the board share `InFlight.inspect()`, never a second liveness judgment).
|
|
402
|
-
const
|
|
446
|
+
const workspaceRoot = new WorkspaceRoot(repoRoot, this.#config.handoffNamespace().workspaceRoot);
|
|
447
|
+
// The board's ONE matrix instance — the invocation's registry, the same table the
|
|
448
|
+
// node ledgers and the seal sweep read, so the board renders facts and holds no
|
|
449
|
+
// name rule of its own. Each node ledger resolves against ITS OWN workspace (the
|
|
450
|
+
// registry carries no directory), so a parent row never reads a child's names.
|
|
451
|
+
const artifacts = this.#matrix;
|
|
452
|
+
const inflight = new InFlight(workspaceRoot, entry.slug ?? "");
|
|
403
453
|
// The board's `next:` line renders ONE injected `NextHop` (P22 §5.2 · P24 §11):
|
|
404
454
|
// the pipeline FACTS come from the board face, and the ONE hop assembly (the four
|
|
405
455
|
// face-order rules + the six hop cells) lives in the session plane's
|
|
@@ -412,7 +462,15 @@ export class Cli {
|
|
|
412
462
|
// otherwise).
|
|
413
463
|
const readTable = this.#boardReadTable(planSource, index, entry, soloPlanRead);
|
|
414
464
|
const read = readTable[0] ?? planSource.readFor(entry);
|
|
415
|
-
|
|
465
|
+
// The board's artifact observation is ONE value: the matrix seam plus the
|
|
466
|
+
// `--artifacts` switch. Both the hop assembly and the render read it, so the
|
|
467
|
+
// board can never print a `next:` computed against one registry and an `art:`
|
|
468
|
+
// block read through another.
|
|
469
|
+
const projection = {
|
|
470
|
+
registry: artifacts,
|
|
471
|
+
showAll: parsed.args.artifacts === "true",
|
|
472
|
+
};
|
|
473
|
+
const next = BoardNext.of(read, planSource, index, entry, root, projection);
|
|
416
474
|
// The read's own diagnostics (spec §2.4): stderr, one line per bad read, printed
|
|
417
475
|
// BEFORE the board. `warnLine` answers null for a healthy plan and for the normal
|
|
418
476
|
// `undeclared` gap, so the line count is exactly (bad plans + `spec-absent`
|
|
@@ -422,7 +480,7 @@ export class Cli {
|
|
|
422
480
|
if (warn !== null)
|
|
423
481
|
this.#io.stderr(`${warn}\n`);
|
|
424
482
|
}
|
|
425
|
-
const board = BoardView.render(readTable, planSource, index, entry, repoRoot, this.#words, host, ARGV_CHANNEL, await inflight.inspect(), next);
|
|
483
|
+
const board = BoardView.render(readTable, planSource, index, entry, repoRoot, this.#words, host, ARGV_CHANNEL, await inflight.inspect(), next, projection);
|
|
426
484
|
for (const line of board.lines)
|
|
427
485
|
this.#io.stdout(`${line}\n`);
|
|
428
486
|
return board.exitCode;
|
|
@@ -537,15 +595,20 @@ export class Cli {
|
|
|
537
595
|
if (repoRoot === null)
|
|
538
596
|
return 1;
|
|
539
597
|
const root = new RepoRoot(repoRoot);
|
|
598
|
+
// The identity index FIRST: the plan read seam below is handed THIS scan, so the
|
|
599
|
+
// phase's plan row, the same-slug spec link and the phase list all speak one
|
|
600
|
+
// snapshot of the doc roots.
|
|
601
|
+
const index = this.#indexOf(repoRoot);
|
|
540
602
|
// The plan read seam — ONE instance per command, built here in the command
|
|
541
|
-
// preamble (the repo root
|
|
542
|
-
// passed down as a parameter: the scene, the pre-flight context and the
|
|
543
|
-
// all read their plan through this ONE seam.
|
|
544
|
-
const planSource = new PlanSource(root);
|
|
603
|
+
// preamble (the repo root and the index exist now; `Cli.create` runs before they
|
|
604
|
+
// do) and passed down as a parameter: the scene, the pre-flight context and the
|
|
605
|
+
// ledger all read their plan through this ONE seam.
|
|
606
|
+
const planSource = new PlanSource(root, index);
|
|
545
607
|
const parsed = this.#funnel(root, raw);
|
|
546
|
-
const
|
|
547
|
-
if (
|
|
608
|
+
const assembled = await this.#sceneOf(verb, type, node, root, planSource, parsed);
|
|
609
|
+
if (assembled === null)
|
|
548
610
|
return 1;
|
|
611
|
+
const { scene, artifacts } = assembled;
|
|
549
612
|
// THE pre-flight seam (P4.1 T1 · design §1): the STRUCTURE gates —
|
|
550
613
|
// tree-clean → in-flight → graph → plan-ledger → doc-contract — ONE call, the
|
|
551
614
|
// whole sequence lives in the seam (session/preflight.ts), the CLI orchestrates
|
|
@@ -627,7 +690,7 @@ export class Cli {
|
|
|
627
690
|
const recovery = !parsed.dryRun &&
|
|
628
691
|
parsed.args.recover === "true" &&
|
|
629
692
|
this.#authority.structureRefusal(preflight) === null
|
|
630
|
-
? await this.#recoverRun(verb, type, scene, parsed, inflight)
|
|
693
|
+
? await this.#recoverRun(verb, type, scene, parsed, inflight, artifacts)
|
|
631
694
|
: null;
|
|
632
695
|
if (recovery !== null && recovery.kind === "blocked") {
|
|
633
696
|
this.#io.stderr(`${this.#words.station("blocked")} ${recovery.message}\n`);
|
|
@@ -705,7 +768,7 @@ export class Cli {
|
|
|
705
768
|
scene.briefPath = this.#gate.renderBrief(scene, parsed, text, doc);
|
|
706
769
|
}
|
|
707
770
|
const statuses = [];
|
|
708
|
-
const dispatch = await this.#dispatchOf(scene, parsed, recovery?.harness ?? null);
|
|
771
|
+
const { step: dispatch, harness } = await this.#dispatchOf(scene, parsed, recovery?.harness ?? null, artifacts);
|
|
709
772
|
const run = new Lifecycle({
|
|
710
773
|
face: scene.face,
|
|
711
774
|
state: scene.state,
|
|
@@ -769,7 +832,18 @@ export class Cli {
|
|
|
769
832
|
// derivation), and the early return means no write point below ever runs
|
|
770
833
|
// (`renderBrief` skipped above, `#bookkeep`/`#reject` never reached).
|
|
771
834
|
if (parsed.dryRun) {
|
|
772
|
-
|
|
835
|
+
// The artifact-identity gate is a PURE read (the matrix's names + the strict
|
|
836
|
+
// sidecar schema), so the preview asks the SAME judgment the real dispatch
|
|
837
|
+
// applies and prints its reason verbatim — a dry run that stayed silent here
|
|
838
|
+
// would forecast a dispatch the real run refuses.
|
|
839
|
+
const refused = harness === null ? null : harness.artifactRefusal(frame);
|
|
840
|
+
const preview = new Preview({ scene, words: this.#words });
|
|
841
|
+
if (refused !== null) {
|
|
842
|
+
for (const line of preview.artifactBlock(verb, refused))
|
|
843
|
+
this.#io.stdout(`${line}\n`);
|
|
844
|
+
return 1;
|
|
845
|
+
}
|
|
846
|
+
for (const line of preview.render(verb, frame))
|
|
773
847
|
this.#io.stdout(`${line}\n`);
|
|
774
848
|
return 0;
|
|
775
849
|
}
|
|
@@ -844,17 +918,22 @@ export class Cli {
|
|
|
844
918
|
* retired synthetic approval (`() => ({ status: "APPROVED", findings: [] })`)
|
|
845
919
|
* has no remaining caller: a preview books no round and fabricates no
|
|
846
920
|
* conclusion. */
|
|
847
|
-
async #dispatchOf(scene, parsed, recovered
|
|
921
|
+
async #dispatchOf(scene, parsed, recovered, artifacts) {
|
|
848
922
|
if (this.#dispatch !== null)
|
|
849
|
-
return this.#dispatch;
|
|
850
|
-
const harness = recovered ?? this.#lifecycleOf(scene, parsed);
|
|
923
|
+
return { step: this.#dispatch, harness: null };
|
|
924
|
+
const harness = recovered ?? this.#lifecycleOf(scene, parsed, artifacts);
|
|
851
925
|
// The abort fold already ran at the composition root's `--recover` judgment
|
|
852
926
|
// (`#recoverRun`) when a harness was handed in; the injected/default face keeps
|
|
853
927
|
// its own fold here, so the takeover always precedes this dispatch's own record.
|
|
854
928
|
if (recovered === null && !parsed.dryRun && parsed.args.recover === "true") {
|
|
855
929
|
await harness.foldAbort();
|
|
856
930
|
}
|
|
857
|
-
|
|
931
|
+
// The harness itself rides back so the `--dry-run` branch can ask it the
|
|
932
|
+
// artifact-identity gate's PURE read (the same judgment `step()` applies), and
|
|
933
|
+
// the preview can print the real run's refusal instead of forecasting a dispatch
|
|
934
|
+
// it would refuse. The injected `#dispatch` seam has no harness — a hermetic
|
|
935
|
+
// caller already replaced the whole dispatch, so there is no gate to ask.
|
|
936
|
+
return { step: harness.step(), harness };
|
|
858
937
|
}
|
|
859
938
|
/** The `--recover` judgment (spec §2.1①–③) — the two legs, judged in order and
|
|
860
939
|
* allowed to stack:
|
|
@@ -869,8 +948,8 @@ export class Cli {
|
|
|
869
948
|
* `N+1` dispatch third — it lives here, not in `step()`'s internals. `fix --recover`
|
|
870
949
|
* and `implement --recover` take leg ① only (never a reopen), wave lines likewise
|
|
871
950
|
* (their reopen face stays P29's brief-drift). */
|
|
872
|
-
async #recoverRun(verb, type, scene, parsed, inflight) {
|
|
873
|
-
const harness = this.#lifecycleOf(scene, parsed);
|
|
951
|
+
async #recoverRun(verb, type, scene, parsed, inflight, artifacts) {
|
|
952
|
+
const harness = this.#lifecycleOf(scene, parsed, artifacts);
|
|
874
953
|
const stale = (await inflight.staleState()) !== null;
|
|
875
954
|
if (stale)
|
|
876
955
|
await harness.foldAbort();
|
|
@@ -901,19 +980,19 @@ export class Cli {
|
|
|
901
980
|
return false;
|
|
902
981
|
if (!ledger.pendingFix(identity.key, type))
|
|
903
982
|
return false;
|
|
904
|
-
const completed = ledger.completedCycles(identity.key, "review"
|
|
983
|
+
const completed = ledger.completedCycles(identity.key, "review");
|
|
905
984
|
if (completed.length === 0)
|
|
906
985
|
return false;
|
|
907
986
|
// The next review cycle is the latest completed review's + 1 — allocated BEFORE
|
|
908
987
|
// the stamp lands (the spec's fixed action order), and it is exactly the cycle the
|
|
909
988
|
// following dispatch allocates (the register's cycle count is unchanged by a stamp).
|
|
910
989
|
const latest = Math.max(...completed);
|
|
911
|
-
return ledger.supersedeReview(identity.key,
|
|
990
|
+
return ledger.supersedeReview(identity.key, latest, latest + 1);
|
|
912
991
|
}
|
|
913
992
|
/** The invocation's lifecycle harness — the production dispatch face, held by the
|
|
914
993
|
* composition root so the abort fold can ride the SAME instance that dispatches
|
|
915
994
|
* (the takeover precedes the stamp, spec §2.1④). */
|
|
916
|
-
#lifecycleOf(scene, parsed) {
|
|
995
|
+
#lifecycleOf(scene, parsed, artifacts) {
|
|
917
996
|
return new CliLifecycle({
|
|
918
997
|
env: process.env,
|
|
919
998
|
sync: this.#sync,
|
|
@@ -934,6 +1013,8 @@ export class Cli {
|
|
|
934
1013
|
// The explicit takeover flag (`--recover`): the ONLY path that displaces a
|
|
935
1014
|
// standing in-flight record — and only when its holder is dead.
|
|
936
1015
|
recover: parsed.args.recover === "true",
|
|
1016
|
+
// The same matrix instance the scene's ledger and router hold.
|
|
1017
|
+
artifacts,
|
|
937
1018
|
});
|
|
938
1019
|
}
|
|
939
1020
|
/** The branch scope anchor (BASE_BRANCH) — the base artifact's branch name read
|
|
@@ -941,7 +1022,8 @@ export class Cli {
|
|
|
941
1022
|
* writes). "" when the artifact is absent or malformed (the slot stays empty and
|
|
942
1023
|
* the assembler drops it — the wave/branch review then judges the live tree). */
|
|
943
1024
|
#baseBranchOf(scene) {
|
|
944
|
-
const
|
|
1025
|
+
const name = this.#matrix.render({ domain: "workspace", tasks: null }, "base");
|
|
1026
|
+
const read = scene.workspace.readJson(name);
|
|
945
1027
|
const artifact = read.kind === "ok" ? read.value : null;
|
|
946
1028
|
return typeof artifact?.base === "string" ? artifact.base : "";
|
|
947
1029
|
}
|
|
@@ -1046,12 +1128,15 @@ export class Cli {
|
|
|
1046
1128
|
// The identity index — the ONE slug judgment (spec §2.1/§2.2). The workspace
|
|
1047
1129
|
// key is the target document's declared `slug:`; the same index supplies the
|
|
1048
1130
|
// same-slug spec link and the duplicate gates.
|
|
1049
|
-
const index =
|
|
1131
|
+
const index = this.#indexOf(repoRoot);
|
|
1050
1132
|
let slug;
|
|
1051
1133
|
let plan;
|
|
1052
1134
|
let specLink = null;
|
|
1053
1135
|
let overallLink = null;
|
|
1054
1136
|
let target = null;
|
|
1137
|
+
/** The slug's declared identity document, when the face looks one up — the plan
|
|
1138
|
+
* and branch lines carry it as the round context's spec anchor. */
|
|
1139
|
+
let specDoc = null;
|
|
1055
1140
|
switch (type) {
|
|
1056
1141
|
case "wave": {
|
|
1057
1142
|
if (planPath === null || planRel === null)
|
|
@@ -1098,15 +1183,15 @@ export class Cli {
|
|
|
1098
1183
|
case "branch": {
|
|
1099
1184
|
// The plan-doc seam (shared by the plan + branch lines): the target plan
|
|
1100
1185
|
// must exist (a required fact for both — the branch review/fix faces carry
|
|
1101
|
-
// `--plan`), its text is read ONCE, and the same-slug identity document
|
|
1102
|
-
//
|
|
1103
|
-
//
|
|
1104
|
-
//
|
|
1105
|
-
//
|
|
1106
|
-
//
|
|
1107
|
-
//
|
|
1108
|
-
//
|
|
1109
|
-
//
|
|
1186
|
+
// `--plan`), its text is read ONCE, and the same-slug identity document (the
|
|
1187
|
+
// index's SET answer — never a path scalar) supplies the round context's
|
|
1188
|
+
// extra read input. Its PATH is read through the doc domain after the
|
|
1189
|
+
// workspace exists (below), so the path and the identity come from one read.
|
|
1190
|
+
// The plan review judges the plan doc; the branch line carries no commit
|
|
1191
|
+
// identity (the audit target is the branch itself, its workspace identity is
|
|
1192
|
+
// the plan path, and the review's scope anchor BASE_BRANCH is engine-injected
|
|
1193
|
+
// from the base artifact) — both faces carry the plan + its same-slug spec
|
|
1194
|
+
// anchor.
|
|
1110
1195
|
if (planPath === null || planRel === null)
|
|
1111
1196
|
this.#usage(node, `cdd ${verb} --type ${type}: missing required --plan <path>`);
|
|
1112
1197
|
plan = this.#argvPlanOf(node, planSource, planRel);
|
|
@@ -1114,11 +1199,10 @@ export class Cli {
|
|
|
1114
1199
|
if (resolved === null)
|
|
1115
1200
|
return null;
|
|
1116
1201
|
slug = resolved;
|
|
1117
|
-
|
|
1118
|
-
specLink = specEntry === null ? null : root.relativize(specEntry.path);
|
|
1202
|
+
specDoc = this.#specDocOf(index, slug);
|
|
1119
1203
|
// The plan/branch line reads the same-slug identity document's `program:` —
|
|
1120
1204
|
// the parent charter (INPUT_OVERALL) the reviewer judges the plan against.
|
|
1121
|
-
const overallEntry =
|
|
1205
|
+
const overallEntry = specDoc?.program == null ? null : index.overallOf(specDoc.program);
|
|
1122
1206
|
overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
|
|
1123
1207
|
target = type === "plan" ? { kind: "plan", doc: planPath } : { kind: "branch" };
|
|
1124
1208
|
break;
|
|
@@ -1131,41 +1215,75 @@ export class Cli {
|
|
|
1131
1215
|
// normalization is the ONE heal path, covering `base.json` alongside
|
|
1132
1216
|
// `progress.json` (a second healing point is gone).
|
|
1133
1217
|
const workspace = new Workspace(rootPath, slug);
|
|
1134
|
-
|
|
1218
|
+
// The artifact matrix — the invocation's ONE instance (the command preamble's),
|
|
1219
|
+
// handed down: the ledger, the router, the lifecycle's seal sweep and the board all
|
|
1220
|
+
// read the same table, so no face can spell an artifact name of its own.
|
|
1221
|
+
const artifacts = this.#matrix;
|
|
1222
|
+
const ledger = new Ledger(workspace, config, planSource, artifacts);
|
|
1135
1223
|
// The run state degrades to the empty state on a non-ready plan: the scene is
|
|
1136
1224
|
// assembled BEFORE the pre-flight verdict, and the refusal leg (Task 4's
|
|
1137
1225
|
// doc-contract leg) stops the dispatch before any `state` consumer runs. No
|
|
1138
1226
|
// try/catch: the read has already happened, so assembly has no throw point.
|
|
1139
1227
|
const graph = plan.graph();
|
|
1140
1228
|
const state = type === "wave" && graph !== null ? graph : EMPTY_RUN_STATE;
|
|
1229
|
+
// The identity document the pipeline frontier names — the plan/branch faces already
|
|
1230
|
+
// looked it up; the wave and doc-target faces look it up from their own slug.
|
|
1231
|
+
specDoc ??= this.#specDocOf(index, slug);
|
|
1232
|
+
// ONE read of that document, through the doc domain: a duplicated identity
|
|
1233
|
+
// (`invalid(found)`) supplies NO path — the slug carrier has already refused that
|
|
1234
|
+
// shape, so this face never picks a first document to hand downstream.
|
|
1235
|
+
const identityRead = specDoc === null || specDoc.docType === null
|
|
1236
|
+
? null
|
|
1237
|
+
: artifacts.read({ domain: "doc", slug, docType: specDoc.docType }, specDoc.docType, workspace);
|
|
1238
|
+
const identityPath = identityRead?.kind === "ok" ? identityRead.path : null;
|
|
1239
|
+
// The spec link is the SAME read's path rebased to repoRoot-relative (D46 · T3), so
|
|
1240
|
+
// every round-context path token speaks ONE basis (the child spawns at cwd = the
|
|
1241
|
+
// repo root) and the anchor and the frontier can never name two documents. The wave
|
|
1242
|
+
// line reads it on the same rule as the plan / branch lines (P37 §4.1): a code
|
|
1243
|
+
// review that cannot open the phase contract is the constructive blind spot the
|
|
1244
|
+
// phase closes.
|
|
1245
|
+
if (type === "plan" || type === "branch" || type === "wave") {
|
|
1246
|
+
specLink = identityPath === null ? null : root.relativize(identityPath);
|
|
1247
|
+
}
|
|
1248
|
+
// P37 §4.1 — the wave line's charter anchor. The two anchors are judged
|
|
1249
|
+
// INDEPENDENTLY: the spec anchor follows the identity document's own resolution
|
|
1250
|
+
// (a single-spec resolves fine and owns no `program:` by design), the charter
|
|
1251
|
+
// anchor follows that document's `program:` alone. Coupling them would strip a
|
|
1252
|
+
// single-spec phase's spec anchor — the blind spot this phase closes.
|
|
1253
|
+
if (type === "wave" && identityPath !== null && specDoc?.program != null) {
|
|
1254
|
+
const overallEntry = index.overallOf(specDoc.program);
|
|
1255
|
+
overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
|
|
1256
|
+
}
|
|
1141
1257
|
// The pipeline frontier's four declared cells (§11) — the composition root's ONE
|
|
1142
|
-
// collection point. The identity word + path come from the document index
|
|
1143
|
-
// the argv `--type` spelling): every non-plan declared document owns the
|
|
1144
|
-
// slot, so `phase-spec` / `single-spec` / `overall` all reach the same
|
|
1145
|
-
// The plan path is the read value's OWN frontier path (`stationPath()`):
|
|
1146
|
-
// command has ONE plan path carrier, so the authority's verdict and this line's
|
|
1258
|
+
// collection point. The identity word + path come from the document index's read
|
|
1259
|
+
// (never the argv `--type` spelling): every non-plan declared document owns the
|
|
1260
|
+
// identity slot, so `phase-spec` / `single-spec` / `overall` all reach the same
|
|
1261
|
+
// assembly. The plan path is the read value's OWN frontier path (`stationPath()`):
|
|
1262
|
+
// a command has ONE plan path carrier, so the authority's verdict and this line's
|
|
1147
1263
|
// hop can never name two different documents.
|
|
1148
|
-
const identity = index.identityDoc(slug);
|
|
1149
1264
|
const pipeline = {
|
|
1150
|
-
specType:
|
|
1151
|
-
specPath:
|
|
1265
|
+
specType: specDoc?.docType ?? null,
|
|
1266
|
+
specPath: identityPath,
|
|
1152
1267
|
planPath: plan.stationPath(),
|
|
1153
1268
|
plan,
|
|
1154
1269
|
};
|
|
1155
1270
|
return {
|
|
1156
|
-
|
|
1157
|
-
|
|
1158
|
-
|
|
1159
|
-
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1271
|
+
scene: {
|
|
1272
|
+
workspace,
|
|
1273
|
+
ledger,
|
|
1274
|
+
planPath,
|
|
1275
|
+
plan,
|
|
1276
|
+
type,
|
|
1277
|
+
face,
|
|
1278
|
+
target,
|
|
1279
|
+
state,
|
|
1280
|
+
router: new NextStepRouter(artifacts),
|
|
1281
|
+
pipeline,
|
|
1282
|
+
briefPath: null,
|
|
1283
|
+
specLink,
|
|
1284
|
+
overallLink,
|
|
1285
|
+
},
|
|
1286
|
+
artifacts,
|
|
1169
1287
|
};
|
|
1170
1288
|
}
|
|
1171
1289
|
/** The argv-face plan read (the wave / plan / branch lines) — ONE read through the
|
|
@@ -1179,6 +1297,17 @@ export class Cli {
|
|
|
1179
1297
|
this.#usage(node, `cannot read file: ${rel}`);
|
|
1180
1298
|
return plan;
|
|
1181
1299
|
}
|
|
1300
|
+
/** The slug's declared identity document — the sole index entry of an identity class
|
|
1301
|
+
* (`null` when the slug names none, or when it carries two: an ambiguous set is the
|
|
1302
|
+
* doc domain `read`'s refusal, and this face never picks a first). The returned
|
|
1303
|
+
* entry supplies the declared `docType:` and `program:`; its PATH comes from the doc
|
|
1304
|
+
* domain's read, so a filename is never an identity. */
|
|
1305
|
+
#specDocOf(index, slug) {
|
|
1306
|
+
const docs = index
|
|
1307
|
+
.docsOf(slug)
|
|
1308
|
+
.filter((entry) => entry.docType !== null && entry.docType !== "plan");
|
|
1309
|
+
return docs.length === 1 ? docs[0] : null;
|
|
1310
|
+
}
|
|
1182
1311
|
/** The plan-carrier target's workspace key (the wave / plan / branch lines) — the
|
|
1183
1312
|
* document's declared `slug:` (spec §2.1 · §2.4), taken from the plan READ rather
|
|
1184
1313
|
* than a second text hand-off: a `ready` read supplies its parsed front-matter
|
|
@@ -1373,7 +1502,7 @@ export class Cli {
|
|
|
1373
1502
|
// (and rejection carrier) the work verbs use. `base` carries no pre-flight gate,
|
|
1374
1503
|
// so a missing / illegal / duplicated slug or an unreadable target stops HERE:
|
|
1375
1504
|
// CDD_BLOCKED + exit 1 (never a filename-derived key).
|
|
1376
|
-
const slug = this.#targetSlugText(
|
|
1505
|
+
const slug = this.#targetSlugText(this.#indexOf(repoRoot), planPath, this.#readTarget(root, planPath));
|
|
1377
1506
|
if (slug === null)
|
|
1378
1507
|
return 1;
|
|
1379
1508
|
// The workspace is not built here (P11 · §4.2): `base set` builds it through
|
package/dist/face/declare.js
CHANGED
|
@@ -21,7 +21,6 @@
|
|
|
21
21
|
// algorithm lives in the single CommandTreeBuilder class (face/projection.ts).
|
|
22
22
|
import { InvalidArgumentError } from "commander";
|
|
23
23
|
import { MAX_TASKS_PER_WAVE } from "../contract/wave-width.js";
|
|
24
|
-
import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
|
|
25
24
|
import { HOST_IDS } from "./host.js";
|
|
26
25
|
/** The argv channel table — the CLI flag/type/enum single source (the engine-config
|
|
27
26
|
* argv channel verbatim: flag spellings, value types and enum domains ride these
|
|
@@ -94,6 +93,11 @@ export const ARGV_CHANNEL = {
|
|
|
94
93
|
scope: "program",
|
|
95
94
|
help: "show this help",
|
|
96
95
|
},
|
|
96
|
+
artifacts: {
|
|
97
|
+
flag: "--artifacts",
|
|
98
|
+
type: "bool",
|
|
99
|
+
help: "expand the board's artifact inventory — one row per observed review round (a troubleshooting view, off by default)",
|
|
100
|
+
},
|
|
97
101
|
output: {
|
|
98
102
|
flag: "--output",
|
|
99
103
|
type: "enum",
|
|
@@ -145,13 +149,13 @@ export const CLI_COMMANDS = [
|
|
|
145
149
|
{
|
|
146
150
|
name: "implement",
|
|
147
151
|
description: `run the task implement phase — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
|
|
148
|
-
example:
|
|
152
|
+
example: "cdd implement --tasks 1,2 --plan <path>",
|
|
149
153
|
keys: [{ key: "tasks", required: true }, { key: "plan", required: true }, { key: "recover" }],
|
|
150
154
|
},
|
|
151
155
|
{
|
|
152
156
|
name: "review",
|
|
153
157
|
description: "run a review — wave | branch | phase-spec | overall | plan | single-spec",
|
|
154
|
-
example:
|
|
158
|
+
example: "cdd review --type phase-spec --spec <path>",
|
|
155
159
|
keys: [
|
|
156
160
|
{ key: "type", required: true },
|
|
157
161
|
{ key: "tasks" },
|
|
@@ -177,7 +181,7 @@ export const CLI_COMMANDS = [
|
|
|
177
181
|
{
|
|
178
182
|
name: "base",
|
|
179
183
|
description: "read/write base.json (single CDD --plan target)",
|
|
180
|
-
example:
|
|
184
|
+
example: "cdd base set --plan <path> --base develop --source plan-field",
|
|
181
185
|
keys: [],
|
|
182
186
|
leaves: [
|
|
183
187
|
{
|
|
@@ -227,8 +231,8 @@ export const CLI_COMMANDS = [
|
|
|
227
231
|
{
|
|
228
232
|
name: "board",
|
|
229
233
|
description: "render the progress board from a --plan or --spec entry (overall/phase-spec/single-spec/plan/wave/branch)",
|
|
230
|
-
example:
|
|
231
|
-
keys: [{ key: "plan" }, { key: "spec" }],
|
|
234
|
+
example: "cdd board --plan <path>",
|
|
235
|
+
keys: [{ key: "plan" }, { key: "spec" }, { key: "artifacts" }],
|
|
232
236
|
},
|
|
233
237
|
{
|
|
234
238
|
name: "init",
|