@oscaner-skills/cdd-engine 3.1.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/face/cli.js CHANGED
@@ -48,13 +48,13 @@ import { CommanderError } from "commander";
48
48
  import { declaredRegistries } from "../contract/declare.js";
49
49
  import { PlanDocType } from "../contract/doc.js";
50
50
  import { FrontMatterExtractor } from "../contract/frontmatter.js";
51
- import { FileExistenceInvariant } from "../contract/invariants.js";
52
51
  import { Contract } from "../contract/judge.js";
53
52
  import { Projector } from "../contract/project.js";
54
53
  import { Translator } from "../contract/translate.js";
55
54
  import { ConfigLoader } from "../infra/config.js";
56
55
  import { GitClient } from "../infra/git.js";
57
56
  import { RepoRoot } from "../infra/root.js";
57
+ import { SlugIndex } from "../infra/slug-index.js";
58
58
  import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
59
59
  import { BriefRenderer } from "../render/brief.js";
60
60
  import { IssueBodyRenderer } from "../render/issue-body.js";
@@ -254,37 +254,79 @@ export class Cli {
254
254
  this.#exitCode = this.#artifacts.runIssue();
255
255
  });
256
256
  // the board observability command — a pure read (no preflight gate)
257
- commandNode("board").action(async (_slug, _opts, command) => {
257
+ commandNode("board").action(async (_opts, command) => {
258
258
  this.#exitCode = await this.#runBoard(command, this.#runInput(null, command));
259
259
  });
260
260
  }
261
- /** `cdd board <slug>` — the slug progress board (spec §5 · §2.2): a PURE READ —
262
- * zero preflight gate, zero tree writes, zero ledger writes, zero child dispatch.
263
- * The slug (the one positional) resolves the repo root, assembles the node tree
264
- * and renders the phase/program board + the `next:` derivation to stdout. A
265
- * missing slug is a usage error (exit 2, commander's own byte); a slug matching
266
- * nothing on disk renders the not-found face and exits 2; a present doc line
267
- * carrying no `doc-type:` key renders its BLOCKED marker and exits 2
268
- * (spec §12 · D34). The host is detected once for the pipeline-entry ref render
269
- * (REFS[ref][host], the same judgment the capsule injects — never hard-coded). */
261
+ /** `cdd board --plan <path> / --spec <path>` — the entry document's progress board
262
+ * (spec §3.1): a PURE READ — zero preflight gate, zero tree writes, zero ledger
263
+ * writes, zero child dispatch. At least one path flag is required (missing →
264
+ * usage exit 2); each path resolves through the ONE identity index (`SlugIndex`
265
+ * scans every docRoot), so a path outside the docRoots or absent on disk is
266
+ * the not-found face (exit 2, zero doc reads, zero BLOCKED markers). Two flags
267
+ * naming different slugs are an argument conflict (exit 2, both values on
268
+ * stderr); two flags on one slug render ONE board shaped by the `--spec`
269
+ * document's `doc-type:`. The host is detected once for the pipeline-entry ref
270
+ * render (REFS[ref][host], the same judgment the capsule injects). */
270
271
  async #runBoard(node, parsed) {
271
272
  this.#assertDryRunScope(node, parsed.dryRun);
272
- const slug = parsed.positionals[0];
273
- if (slug === undefined)
274
- this.#usage(node, "cdd board: missing <slug>");
273
+ const planArg = parsed.args.plan;
274
+ const specArg = parsed.args.spec;
275
+ if (planArg === undefined && specArg === undefined)
276
+ this.#usage(node, "cdd board: pass --plan and/or --spec");
275
277
  const repoRoot = await this.#rootOf();
276
278
  if (repoRoot === null)
277
279
  return 1;
278
- if (!BoardView.hasNode(slug, repoRoot)) {
279
- this.#io.stderr(`cdd board: no docs match slug ${slug}\n`);
280
+ const root = new RepoRoot(repoRoot);
281
+ const planRel = planArg === undefined ? null : this.#relativizePath(root, planArg);
282
+ const specRel = specArg === undefined ? null : this.#relativizePath(root, specArg);
283
+ // The not-found face reads ZERO documents (spec §3.1): a path outside the two
284
+ // doc roots or absent on disk refuses BEFORE the identity scan — the scan is
285
+ // this face's only document-reading step, and it never runs for this verdict.
286
+ const planMissing = planRel !== null &&
287
+ (!SlugIndex.insideDocRoots(planRel) || !existsSync(root.resolve(planRel)));
288
+ const specMissing = specRel !== null &&
289
+ (!SlugIndex.insideDocRoots(specRel) || !existsSync(root.resolve(specRel)));
290
+ if (planMissing || specMissing)
291
+ return this.#boardNotFound([
292
+ planMissing ? `--plan ${planArg}` : null,
293
+ specMissing ? `--spec ${specArg}` : null,
294
+ ]);
295
+ const index = SlugIndex.build(repoRoot);
296
+ const planEntry = planRel === null ? null : index.entryAt(planRel);
297
+ const specEntry = specRel === null ? null : index.entryAt(specRel);
298
+ const unmatched = [
299
+ planRel !== null && planEntry === null ? `--plan ${planArg}` : null,
300
+ specRel !== null && specEntry === null ? `--spec ${specArg}` : null,
301
+ ].filter((part) => part !== null);
302
+ if (unmatched.length > 0)
303
+ return this.#boardNotFound(unmatched);
304
+ const planSlug = planEntry?.slug ?? null;
305
+ const specSlug = specEntry?.slug ?? null;
306
+ if (planEntry !== null &&
307
+ specEntry !== null &&
308
+ SlugIndex.isLegalSlug(planSlug) &&
309
+ SlugIndex.isLegalSlug(specSlug) &&
310
+ planSlug !== specSlug) {
311
+ this.#io.stderr(`cdd board: --plan slug "${planSlug}" conflicts with --spec slug "${specSlug}"\n`);
280
312
  return 2;
281
313
  }
314
+ const entry = specEntry ?? planEntry;
315
+ if (entry === null)
316
+ return 2;
282
317
  const host = HostDetect.detect(process.env);
283
- const board = BoardView.render(slug, repoRoot, this.#words, host, ARGV_CHANNEL);
318
+ const board = BoardView.render(index, entry, repoRoot, this.#words, host, ARGV_CHANNEL);
284
319
  for (const line of board.lines)
285
320
  this.#io.stdout(`${line}\n`);
286
321
  return board.exitCode;
287
322
  }
323
+ /** The board's not-found face (spec §3.1) — the ONE stderr line + exit 2 the
324
+ * pre-scan membership/existence probe and the post-scan entry lookup share. */
325
+ #boardNotFound(parts) {
326
+ const named = parts.filter((part) => part !== null);
327
+ this.#io.stderr(`cdd board: no docs match ${named.join(" and ")}\n`);
328
+ return 2;
329
+ }
288
330
  /** The thin shell's run input — commander's parsed opts mapped to the domain
289
331
  * run's consumption face (the parseArg-normalized values ride through verbatim:
290
332
  * int-list → the comma string · enum → the value · sha → the short form · the
@@ -577,7 +619,6 @@ export class Cli {
577
619
  const harness = new CliLifecycle({
578
620
  env: process.env,
579
621
  sync: this.#sync,
580
- config: this.#config,
581
622
  template: this.#template,
582
623
  io: this.#io,
583
624
  words: this.#words,
@@ -588,6 +629,7 @@ export class Cli {
588
629
  briefPath: scene.briefPath,
589
630
  baseBranch: this.#baseBranchOf(scene),
590
631
  specLink: scene.specLink,
632
+ overallLink: scene.overallLink,
591
633
  },
592
634
  reviews: parsed.paths.reviews,
593
635
  });
@@ -668,23 +710,45 @@ export class Cli {
668
710
  const planPath = planRel === null ? null : root.resolve(planRel);
669
711
  const specRel = parsed.paths.spec;
670
712
  const specPath = specRel === null ? null : root.resolve(specRel);
713
+ // The identity index — the ONE slug judgment (spec §2.1/§2.2). The workspace
714
+ // key is the target document's declared `slug:`; the same index supplies the
715
+ // same-slug spec link and the duplicate gates.
716
+ const index = SlugIndex.build(repoRoot);
671
717
  let slug;
672
718
  let planText = null;
673
719
  let specLink = null;
720
+ let overallLink = null;
674
721
  let target = null;
675
722
  switch (type) {
676
723
  case "wave": {
677
724
  if (planPath === null || planRel === null)
678
725
  this.#usage(node, `cdd ${verb} --type wave: missing required --plan <path>`);
679
- slug = Workspace.slugFromDoc(planPath);
680
726
  planText = this.#artifacts.readText(node, root, planRel);
727
+ const resolved = this.#targetSlug(index, planRel, planText);
728
+ if (resolved === null)
729
+ return null;
730
+ slug = resolved;
681
731
  break;
682
732
  }
683
733
  case "spec": {
684
- if (specPath === null)
734
+ if (specPath === null || specRel === null)
685
735
  this.#usage(node, `cdd ${verb} --type spec: missing required --spec <path>`);
686
- slug = Workspace.slugFromDoc(specPath);
736
+ // An unreadable target declares no identity: the SAME slug carrier hard-refuses
737
+ // it (CDD_BLOCKED + exit 1, never a filename-derived key). The T7 null-verdict
738
+ // face covers the other shape — a document ON DISK that declares no
739
+ // `doc-type:` / `slug:`.
740
+ const resolved = this.#targetSlug(index, specRel, this.#readTarget(root, specRel));
741
+ if (resolved === null)
742
+ return null;
743
+ slug = resolved;
687
744
  target = { kind: "spec", doc: specPath };
745
+ // The judged spec's own `program:` — the parent charter (INPUT_OVERALL) the
746
+ // spec-scope reviewer judges the phase against. A spec without `program:`
747
+ // (a single-spec) leaves the slot null; an off-disk target reads null here
748
+ // and the existing slug-ref invariant reports it (never a second reporter).
749
+ const specEntry = index.entryAt(specRel);
750
+ const overallEntry = specEntry?.program == null ? null : index.overallOf(specEntry.program);
751
+ overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
688
752
  break;
689
753
  }
690
754
  case "plan":
@@ -692,29 +756,28 @@ export class Cli {
692
756
  case "branch": {
693
757
  // The plan-doc seam (shared by the plan + branch lines): the target plan
694
758
  // must exist (a required fact for both — the branch review/fix faces carry
695
- // `--plan`), its text is read ONCE, and the plan's design-spec reference
696
- // (the `spec:` front-matter key — the §2.2 delivery seam: the ONE head-
697
- // REQUIRED parse call site) is derived from that text as the round context's
698
- // extra read input (no second file read). Rebased to repoRoot-relative
699
- // (D46 · T3): the raw header form is markdown link-space (relative to the
700
- // plan's own dir), so it is first resolved to an absolute path, then routed
701
- // through the ONE value object (`RepoRoot.relativize`) — every round-context
702
- // path token speaks ONE basis (the child is spawned at cwd = repoRoot). The
703
- // plan review judges the plan doc; the branch line carries no commit identity
704
- // (the audit target is the branch itself, its workspace identity is the plan
705
- // path, and the review's scope anchor BASE_BRANCH is engine-injected from the
706
- // base artifact) — both faces carry the plan + its spec anchor.
759
+ // `--plan`), its text is read ONCE, and the same-slug identity document
760
+ // (the index's `identityDoc` — never a path scalar) supplies the round
761
+ // context's extra read input. The link is rebased to repoRoot-relative
762
+ // (D46 · T3) so every round-context path token speaks ONE basis (the child
763
+ // is spawned at cwd = repoRoot). The plan review judges the plan doc; the
764
+ // branch line carries no commit identity (the audit target is the branch
765
+ // itself, its workspace identity is the plan path, and the review's scope
766
+ // anchor BASE_BRANCH is engine-injected from the base artifact) — both
767
+ // faces carry the plan + its same-slug spec anchor.
707
768
  if (planPath === null || planRel === null)
708
769
  this.#usage(node, `cdd ${verb} --type ${type}: missing required --plan <path>`);
709
- slug = Workspace.slugFromDoc(planPath);
710
770
  planText = this.#artifacts.readText(node, root, planRel);
711
- const split = FrontMatterExtractor.split(planText);
712
- const rawSpecLink = new PlanDocType("plan").parse(split.body.split("\n"), split.head).chain.specLink
713
- ?.target ?? null;
714
- specLink =
715
- rawSpecLink === null
716
- ? null
717
- : root.relativize(this.#resolveSpecLink(repoRoot, planPath, rawSpecLink));
771
+ const resolved = this.#targetSlug(index, planRel, planText);
772
+ if (resolved === null)
773
+ return null;
774
+ slug = resolved;
775
+ const specEntry = index.identityDoc(slug);
776
+ specLink = specEntry === null ? null : root.relativize(specEntry.path);
777
+ // The plan/branch line reads the same-slug identity document's `program:` —
778
+ // the parent charter (INPUT_OVERALL) the reviewer judges the plan against.
779
+ const overallEntry = specEntry?.program == null ? null : index.overallOf(specEntry.program);
780
+ overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
718
781
  target = type === "plan" ? { kind: "plan", doc: planPath } : { kind: "branch" };
719
782
  break;
720
783
  }
@@ -742,8 +805,60 @@ export class Cli {
742
805
  router: new NextStepRouter(),
743
806
  briefPath: null,
744
807
  specLink,
808
+ overallLink,
745
809
  };
746
810
  }
811
+ /** The dispatch target's workspace key — the document's declared `slug:`
812
+ * (spec §2.1 · §2.4). ONE read face shared by the three work verbs and `base`:
813
+ * an unreadable target, a missing `slug:`, an illegal value, or a slug the index
814
+ * judges duplicated (identity or plan) each render the CDD_BLOCKED station and
815
+ * return null (exit 1 at the caller — never the board's exit 2). The duplicate
816
+ * judgment reads the SAME `SlugIndex` the board renders, so the two faces never
817
+ * diverge (one fact, two carriers). The caller passes the document text it
818
+ * already holds — the identity read never opens the file a second time. */
819
+ #targetSlug(index, rel, content) {
820
+ // An unreadable target document declares no identity — the workspace key has
821
+ // no source, so the dispatch face refuses on the SAME carrier as a missing
822
+ // `slug:` (never a filename-derived directory).
823
+ if (content === null)
824
+ return this.#slugBlocked(`the target document ${rel} is unreadable — its declared \`slug:\` is the workspace key`);
825
+ const head = FrontMatterExtractor.split(content).head;
826
+ const parseError = head.parseError;
827
+ if (parseError !== null)
828
+ return this.#slugBlocked(this.#words
829
+ .routeWord("frontmatterParse")
830
+ .replace("{reason}", parseError.reason)
831
+ .replace("{line}", String(parseError.line))
832
+ .replace("{column}", String(parseError.column))
833
+ .replace("{source}", parseError.source));
834
+ // The four-way identity gate (present · legal · indexed · unique) is the ONE
835
+ // `SlugIndex` judgment the pre-flight gate also reads — this carrier supplies
836
+ // only the CDD_BLOCKED channel, never a second spelling of the rule.
837
+ const verdict = index.slugVerdict(rel, head.slug);
838
+ return verdict.kind === "accepted"
839
+ ? verdict.slug
840
+ : this.#slugBlocked(this.#words.slugRefusal(verdict));
841
+ }
842
+ /** Read a dispatch target's text — null when the file is absent or unreadable.
843
+ * The null is NOT a degradation: every caller hands it to `#targetSlug`, which
844
+ * refuses the target on the slug carrier (CDD_BLOCKED + exit 1). A document
845
+ * that IS readable and declares no `doc-type:` / `slug:` is the separate
846
+ * T7 null-verdict shape. */
847
+ #readTarget(root, rel) {
848
+ try {
849
+ return readFileSync(root.resolve(rel), "utf8");
850
+ }
851
+ catch {
852
+ return null;
853
+ }
854
+ }
855
+ /** The dispatch-face critical stop carrier — the CDD_BLOCKED station + the
856
+ * reason row; the caller returns exit 1 (the CDD_BLOCKED channel carries
857
+ * dispatch hard gates only, never a board reject face). */
858
+ #slugBlocked(message) {
859
+ this.#io.stderr(`${this.#words.station("blocked")} ${message}\n`);
860
+ return null;
861
+ }
747
862
  /** The input funnel — the ONE path normalization landing (T3 · §2.3): every
748
863
  * path-typed argv value is relativized to the repo root EXACTLY once, here,
749
864
  * before the scene or any downstream face reads it, so no face ever sees a raw
@@ -800,20 +915,6 @@ export class Cli {
800
915
  }
801
916
  return root;
802
917
  }
803
- /** The plan's `spec:` link target resolved to an ABSOLUTE path (D46) — the
804
- * plan-review round context's `INPUT_SPEC` (the round-context exit relativizes it
805
- * to repoRoot along with every other path token). The raw header form is markdown
806
- * link-space (relative to the plan's own dir — the skeleton's form) or a repoRoot
807
- * form; the resolution IS the doc-contract's own chain-link judgment, delegated
808
- * to its ONE home (`FileExistenceInvariant.targetPath`) so a future contract
809
- * change cannot silently diverge from this mirror (P9 branch-review-1 F8 — never
810
- * a re-implemented chain). The fallback (neither reading exists) resolves against
811
- * the plan's own dir — the link-space semantic — so the exit still receives an
812
- * absolute path (the doc-contract's file-existence finding owns the truly-missing
813
- * case). */
814
- #resolveSpecLink(repoRoot, planPath, target) {
815
- return FileExistenceInvariant.targetPath(repoRoot, planPath, target, (p) => existsSync(p));
816
- }
817
918
  // ---------------------------------------------------------------------------
818
919
  // the pure commands — schema / issue / base
819
920
  // ---------------------------------------------------------------------------
@@ -868,11 +969,18 @@ export class Cli {
868
969
  // the work-command path argv: the stored artifact's path field speaks the ONE
869
970
  // canonical shape (repoRoot-relative).
870
971
  const planPath = this.#relativizePath(root, planArg);
972
+ // The workspace key is the plan document's `slug:` — the SAME resolution point
973
+ // (and rejection carrier) the work verbs use. `base` carries no pre-flight gate,
974
+ // so a missing / illegal / duplicated slug or an unreadable target stops HERE:
975
+ // CDD_BLOCKED + exit 1 (never a filename-derived key).
976
+ const slug = this.#targetSlug(SlugIndex.build(repoRoot), planPath, this.#readTarget(root, planPath));
977
+ if (slug === null)
978
+ return 1;
871
979
  // The workspace is not built here (P11 · §4.2): `base set` builds it through
872
980
  // `Workspace.writeJson`'s internal ensure, while the read-only `base get`
873
981
  // creates nothing. The read rides `Workspace.readJson`, so the P9 read-time
874
982
  // normalization covers `base.json` (the retired migration's job).
875
- const workspace = new Workspace(new WorkspaceRoot(repoRoot, this.#config.handoffNamespace().workspaceRoot), Workspace.slugFromDoc(planPath));
983
+ const workspace = new Workspace(new WorkspaceRoot(repoRoot, this.#config.handoffNamespace().workspaceRoot), slug);
876
984
  if (parsed.leaf === "set")
877
985
  return this.#artifacts.baseSet(node, parsed, planPath, workspace, root);
878
986
  if (parsed.leaf === "get")
@@ -200,19 +200,18 @@ export const CLI_COMMANDS = [
200
200
  },
201
201
  {
202
202
  name: "board",
203
- description: "render the slug progress board (overall/spec/plan/wave/branch)",
204
- example: "cdd board 2026-10-10-engine-doc-tooling-p7",
205
- keys: [],
206
- positionals: [{ key: "slug", required: true }],
203
+ description: "render the progress board from a --plan or --spec entry (overall/spec/plan/wave/branch)",
204
+ example: `cdd board --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
205
+ keys: [{ key: "plan" }, { key: "spec" }],
207
206
  },
208
207
  ];
209
208
  /** The schema `<type>` vocabulary — the get leaf's ONE table (spec §5.3): the
210
- * primary DocKey spellings (overall-spec | plan | phase-spec | single-spec) plus
209
+ * primary DocKey spellings (overall | plan | phase-spec | single-spec) plus
211
210
  * the legacy `phaseSpec` alias row normalized to the kebab key. One normalizing
212
211
  * vocabulary, never a second hand-written list — the builder's #parseTypeKey
213
212
  * validates through it. */
214
213
  export const SCHEMA_TYPE_KEYS = {
215
- "overall-spec": "overall-spec",
214
+ overall: "overall",
216
215
  plan: "plan",
217
216
  "phase-spec": "phase-spec",
218
217
  "single-spec": "single-spec",