@oscaner-skills/cdd-engine 3.0.0 → 3.1.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.
Files changed (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +149 -0
  15. package/dist/face/cli.js +893 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +702 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +504 -0
  25. package/dist/face/words.js +258 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +453 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -1,93 +0,0 @@
1
- // packages/cdd-engine/src-next/face/__tests__/words.guard.test.ts
2
- // P5 — the engine-literal half of the word-face audit, colocated after the
3
- // D17 six-premise ownership-migration (the root guard's checkWords split: the skill-text half
4
- // re-homes to the kairos test plane, the engine-literal half lands HERE — the
5
- // surfaces this tree owns must carry zero of its own retired vocabulary). The
6
- // token set is the exported ban-table data (`guard.ts` GUARD_BAN_WORDS), never a
7
- // hand-written list; the scan release-masks the ban-round's own data homes
8
- // (`face/words.ts` · `face/host.ts` — their quoted rows ARE the release form,
9
- // where the guard-ban vocabulary legitimately lives as declared data).
10
- //
11
- // The stale + gate families are the retired-mechanism tokens the engine's live
12
- // faces must stay clean of; the shape family is the consumer-skill surface's
13
- // concern (the kairos plane) and rides no source-face scan here.
14
- //
15
- // Zero module-level bare functions — the walk/scan helpers are `const` (the P5
16
- // zero-`function`-declaration discipline).
17
-
18
- import { readdirSync, readFileSync } from "node:fs";
19
- import path from "node:path";
20
- import { fileURLToPath } from "node:url";
21
- import { describe, expect, it } from "vitest";
22
-
23
- import { GUARD_BAN_WORDS } from "../words.ts";
24
-
25
- /** The src-next plane root — the engine's own source face (the scan set). */
26
- const FACE_ROOT = fileURLToPath(new URL("../../", import.meta.url));
27
-
28
- /** The ban vocabulary's data homes — the files whose quoted rows are the release
29
- * form (a live face never carries the lexeme outside these homes). */
30
- const RELEASE_FILES = new Set(["face/words.ts", "face/host.ts"]);
31
-
32
- /** Walk the src-next tree collecting `.ts` files (bounded — the explicit plane root). */
33
- const collectTsFiles = (dir: string, out: string[]): void => {
34
- for (const entry of readdirSync(dir, { withFileTypes: true })) {
35
- const full = path.join(dir, entry.name);
36
- if (entry.isDirectory()) collectTsFiles(full, out);
37
- else if (entry.name.endsWith(".ts")) out.push(full);
38
- }
39
- };
40
-
41
- /** Whether a line carries the token only inside quoted strings (the release-row
42
- * form — a data-home line that lists the value, never restates it bare). */
43
- const isQuotedDataRow = (line: string, token: string): boolean =>
44
- !line.replace(/"[^"]*"/g, "").includes(token);
45
-
46
- /** One token's scanned hits over the src-next tree (the relative file + line). */
47
- const scanHits = (token: string): string[] => {
48
- const files: string[] = [];
49
- collectTsFiles(FACE_ROOT, files);
50
- const hits: string[] = [];
51
- for (const file of files) {
52
- const relative = path.relative(FACE_ROOT, file);
53
- const release = RELEASE_FILES.has(relative);
54
- const lines = readFileSync(file, "utf8").split("\n");
55
- for (let index = 0; index < lines.length; index += 1) {
56
- const text = lines[index]!;
57
- if (!text.includes(token)) continue;
58
- if (release && isQuotedDataRow(text, token)) continue;
59
- hits.push(`${relative}:${index + 1}`);
60
- }
61
- }
62
- return hits;
63
- };
64
-
65
- describe("the engine-literal word-face audit — the guard-ban vocabulary on the engine source face", () => {
66
- it("the src-next face carries zero stale-family ban tokens (release-masked at the data homes)", () => {
67
- const tokens = GUARD_BAN_WORDS.stale.map((row) => row.token);
68
- for (const token of tokens) {
69
- const hits = scanHits(token);
70
- expect(hits, `the engine source face carries the ban token "${token}"`).toEqual([]);
71
- }
72
- });
73
-
74
- it("the src-next face carries zero gate-family ban tokens (release-masked at the data homes)", () => {
75
- const tokens = GUARD_BAN_WORDS.gate.map((row) => row.token);
76
- for (const token of tokens) {
77
- const hits = scanHits(token);
78
- expect(hits, `the engine source face carries the ban token "${token}"`).toEqual([]);
79
- }
80
- });
81
-
82
- it("the release homes do carry their declared rows — the mask is the release form, never a blind skip", () => {
83
- // The mask must NOT be vacuous: the two data homes hold every stale + gate
84
- // row as a quoted data value — the release-masked scan stands down only for
85
- // those exact rows (a non-quoted restatement would build a hit).
86
- const tokens = [...GUARD_BAN_WORDS.stale, ...GUARD_BAN_WORDS.gate].map((row) => row.token);
87
- const homes = [...RELEASE_FILES].map((relative) => path.join(FACE_ROOT, relative));
88
- const all = readFileSync(homes[0]!, "utf8") + readFileSync(homes[1]!, "utf8");
89
- for (const token of tokens) {
90
- expect(all.includes(token), `the data home carries its declared row "${token}"`).toBe(true);
91
- }
92
- });
93
- });
@@ -1,248 +0,0 @@
1
- // packages/cdd-engine/src-next/face/artifacts.ts
2
- // T8 — the split contract's artifacts face (§6.2: face/artifacts.ts — the pure-command
3
- // domain). The pure artifact surfaces run through this class: the schema skeleton
4
- // (#runSchemaSkeleton/#today), the issue render (#runIssue) and the base artifact
5
- // read/write (#baseSet/#baseGet/#readBase) plus the doc read/usage face (#readText).
6
- // The method bodies are the pre-split Cli members moved verbatim — behavior bytes
7
- // identical; the root Cli holds the artifacts instance and composes through it via its
8
- // .action thin shells. The root's commander usage throw (#usage — the composition-
9
- // root exit face, never re-implemented here) is injected as the usage seam; the BaseArtifact
10
- // row (the CDD --plan target's read/write face) is declared here and re-exported by
11
- // face/cli.ts so the public surface never drifts.
12
-
13
- import { readFileSync, writeFileSync } from "node:fs";
14
- import process from "node:process";
15
- import type { Command } from "commander";
16
- import { declaredRegistries } from "../contract/declare.ts";
17
- import type { DocKey } from "../contract/project.ts";
18
- import { Projector } from "../contract/project.ts";
19
- import type { RepoPath, RepoRoot } from "../infra/root.ts";
20
- import type { Workspace } from "../infra/workspace.ts";
21
- import type { IssueBodyRenderer, IssueReportInput } from "../render/issue-body.ts";
22
- import { SkeletonAssembler } from "../render/skeleton.ts";
23
- import type { RunInput } from "./cli.ts";
24
- import { ARGV_CHANNEL } from "./declare.ts";
25
- import type { CliIo } from "./lifecycle.ts";
26
-
27
- // ---------------------------------------------------------------------------
28
- // the pure artifact surfaces — the base artifact + the issue body
29
- // ---------------------------------------------------------------------------
30
-
31
- /** The base's source value domain — the four-value enum (design spec §3.2 ⑪).
32
- * Derived from the ONE declaration (the argv channel's `--source` domain,
33
- * face/declare.ts:76), so the artifact's `source` field and the CLI's accepted
34
- * values can never drift. */
35
- export type BaseSource = (typeof ARGV_CHANNEL.source.values)[number];
36
-
37
- /** The base artifact's declared field set, in canonical order — the runtime
38
- * companion of `BaseArtifact` (the `base.md` documented schema's four fields,
39
- * spec §3.2 ⑪). The cross-face gate (kairos suite) pins the `base.md` schema
40
- * table's field set to THIS tuple, so the doc and the artifact can never drift. */
41
- export const BASE_ARTIFACT_FIELDS = ["base", "source", "plan", "recordedAt"] as const;
42
-
43
- /** The base artifact schema — the sole CDD --plan target's read/write row (the
44
- * artifact file carries the `base` face: the base branch the plan's line rides).
45
- * The field set (`base`/`source`/`plan`/`recordedAt`) mirrors the `base.md`
46
- * documented schema (spec §3.2 ⑪); `source` is narrowed to the declared enum
47
- * `BaseSource` — never a bare `string` (the drifted face this gate closes). */
48
- export interface BaseArtifact {
49
- /** The base branch name. */
50
- base: string;
51
- /** The base's source channel (the declared `--source` enum). */
52
- source: BaseSource;
53
- /** The plan path the artifact serves. */
54
- plan: string;
55
- /** The ISO write timestamp. */
56
- recordedAt: string;
57
- }
58
-
59
- /**
60
- * CliArtifacts — the pure-command domain (the split contract's artifacts face): the
61
- * schema/issue/base run bodies. The instance holds the pure-domain renderers + the
62
- * root-injected seam faces (io / the usage throw); the root composes the command
63
- * scenes and delegates the pure runs here.
64
- */
65
- export class CliArtifacts {
66
- readonly #io: CliIo;
67
- readonly #projector: Projector;
68
- readonly #issue: IssueBodyRenderer;
69
- readonly #stdinRead: () => string;
70
- /** The composition-root usage throw — commander's OWN CommanderError (the root's
71
- * exit-normalization face; the split never re-implements the usage byte). */
72
- readonly #usage: (node: Command, message: string) => never;
73
-
74
- constructor(opts: {
75
- io?: CliIo;
76
- projector?: Projector;
77
- issue: IssueBodyRenderer;
78
- stdinRead: () => string;
79
- usage: (node: Command, message: string) => never;
80
- }) {
81
- this.#io = opts.io ?? {
82
- stdout: (t) => process.stdout.write(t),
83
- stderr: (t) => process.stderr.write(t),
84
- };
85
- this.#projector = opts.projector ?? new Projector(declaredRegistries);
86
- this.#issue = opts.issue;
87
- this.#stdinRead = opts.stdinRead;
88
- this.#usage = opts.usage;
89
- }
90
-
91
- /** `cdd schema get <type> --output skeleton <target>` — the derived doc skeleton
92
- * rendered DIRECTLY into the target document (the D19 merged leaf's skeleton
93
- * face): the normalized DocType key → the projector's skeleton projection → the
94
- * SkeletonAssembler bytes → the single appended newline written to <target>
95
- * (the assembler never appends one — the written doc ends with exactly one
96
- * `\n`). The target is the engine-declared parameter of the skeleton render
97
- * face — the authoring scaffold lands in place, zero shell-redirection
98
- * indirection (the D19 `<path>` zero-constraint fix). The echoed path is the
99
- * repoRoot-relative shape (D47 · §2.13: the branded `RepoPath` param on both the
100
- * stdout line and the failure byte; `RepoRoot.resolve` feeds only the writeFileSync
101
- * syscall). */
102
- runSchemaSkeleton(node: Command, root: RepoRoot, type: string, target: RepoPath): number {
103
- const projection = this.#projector.skeleton()[type as DocKey];
104
- const date = this.#today();
105
- const file = `${new SkeletonAssembler(projection, date).render()}\n`;
106
- const absolute = root.resolve(target);
107
- try {
108
- writeFileSync(absolute, file, "utf8");
109
- } catch {
110
- this.#usage(node, `cannot write file: ${target}`);
111
- }
112
- this.#io.stdout(`${target}\n`);
113
- return 0;
114
- }
115
-
116
- /** `cdd issue render` — stdin findings JSON → the aggregate body → stdout (the
117
- * renderer's only CLI entry; a bare call, no flags). */
118
- runIssue(): number {
119
- let input: unknown;
120
- try {
121
- input = JSON.parse(this.#stdinRead());
122
- } catch (err) {
123
- this.#io.stderr(
124
- `cdd issue render: invalid input JSON — ${err instanceof Error ? err.message : String(err)}\n`,
125
- );
126
- return 1;
127
- }
128
- const violations = this.#issue.validateInput(input);
129
- if (violations.length > 0) {
130
- this.#io.stderr(
131
- `cdd issue render: invalid input:\n${violations.map((v) => ` ${v}`).join("\n")}\n`,
132
- );
133
- return 1;
134
- }
135
- this.#io.stdout(`${this.#issue.renderBody(input as IssueReportInput)}\n`);
136
- return 0;
137
- }
138
-
139
- /** The `set` body — base/source required, a different existing base refuses without
140
- * `--force` (the write-through artifact single-author). The write rides
141
- * `Workspace.writeJson` (P11 · §4.2: the JSON write self-ensures, so `base set` on
142
- * a fresh repo builds the workspace with no scene-side ensure); the read rides the
143
- * same `Workspace.readJson` normalization path. The echoed path is the
144
- * repoRoot-relative shape (D47 · the ONE basis), normalized through the threaded
145
- * basis (F2). */
146
- baseSet(
147
- node: Command,
148
- parsed: RunInput,
149
- planPath: RepoPath,
150
- workspace: Workspace,
151
- root: RepoRoot,
152
- ): number {
153
- const base = parsed.args.base;
154
- const source = parsed.args.source;
155
- if (base === undefined || source === undefined) {
156
- this.#usage(node, "cdd base set: required --base <branch> and --source <source>");
157
- }
158
- const existing = this.#readBase(workspace);
159
- if (existing !== null && existing.base !== base && parsed.args.force !== "true") {
160
- this.#usage(
161
- node,
162
- `cdd base set: base already set to ${existing.base} — pass --force to override`,
163
- );
164
- }
165
- // The `--source` enum channel already validated the raw against the declared
166
- // domain, so the value is narrowed to BaseSource here (single source: the
167
- // channel's `values` array).
168
- const artifact: BaseArtifact = {
169
- base,
170
- source: source as BaseSource,
171
- plan: planPath,
172
- recordedAt: new Date().toISOString(),
173
- };
174
- workspace.writeJson("base.json", artifact);
175
- this.#io.stdout(`${root.relativize(workspace.resolve("base.json"))}\n`);
176
- return 0;
177
- }
178
-
179
- /** The `get` body — read + validate + print the artifact JSON (exit 2 when the
180
- * artifact is missing or corrupt — the orchestrator's inference-chain input). A
181
- * pure READ (P11 · §4.2): the workspace is never built here, so `cdd base get`
182
- * leaves `.kairos/` absent on a fresh repo. The echoed path is the repoRoot-relative
183
- * shape (D47), normalized through the threaded basis (F2). */
184
- baseGet(workspace: Workspace, root: RepoRoot): number {
185
- const artifact = this.#readBase(workspace);
186
- if (artifact === null) {
187
- const path = root.relativize(workspace.resolve("base.json"));
188
- this.#io.stderr(`cdd base get: missing or corrupt base artifact at ${path}\n`);
189
- return 2;
190
- }
191
- this.#io.stdout(`${JSON.stringify(artifact, null, 2)}\n`);
192
- return 0;
193
- }
194
-
195
- /** Read a text file through the caller's command face; a missing/unreadable file is
196
- * the usage error of that face (the owning node's commander-native usage line). The
197
- * path is a branded `RepoPath` (repoRoot-relative — T3 §2.3: a bare `string` never
198
- * reaches this read) erased to the absolute syscall form through the ONE value
199
- * object (`RepoRoot.resolve`), so the read reads the file the funnel named. The
200
- * echoed path in the refusal byte is the repoRoot-relative shape (D47 · §2.13: the
201
- * branded `RepoPath`; `RepoRoot.resolve` feeds only the readFileSync syscall). */
202
- readText(node: Command, root: RepoRoot, file: RepoPath): string {
203
- const absolute = root.resolve(file);
204
- try {
205
- return readFileSync(absolute, "utf8");
206
- } catch {
207
- this.#usage(node, `cannot read file: ${file}`);
208
- }
209
- }
210
-
211
- /** The run date in `YYYY-MM-DD` — the skeleton's version-row date truth (the
212
- * local day; the skeleton carries no date parameter face). */
213
- #today(): string {
214
- const now = new Date();
215
- const month = String(now.getMonth() + 1).padStart(2, "0");
216
- const day = String(now.getDate()).padStart(2, "0");
217
- return `${now.getFullYear()}-${month}-${day}`;
218
- }
219
-
220
- /** Read + validate the base artifact; null when missing or malformed — a total
221
- * read (never a throw). The read rides `Workspace.readJson` (P11 · §4.2) — the
222
- * read/write single normalization path, so a legacy absolute `plan` field reads
223
- * back in the canonical repoRoot-relative shape (the retired migration's job is the
224
- * read-time backstop). A non-object JSON payload (the literal `null`, a bare
225
- * scalar/array) is malformed input, not a base artifact. The `source` field is
226
- * narrowed to the declared enum domain (a value outside the four-value set is a
227
- * schema-invalid artifact → null, never a fabricated source). */
228
- #readBase(workspace: Workspace): BaseArtifact | null {
229
- const read = workspace.readJson<unknown>("base.json");
230
- if (read.kind !== "ok") return null;
231
- const parsed = read.value;
232
- if (parsed === null || typeof parsed !== "object") return null;
233
- const record = parsed as Record<string, unknown>;
234
- if (
235
- typeof record.base !== "string" ||
236
- typeof record.source !== "string" ||
237
- typeof record.plan !== "string"
238
- )
239
- return null;
240
- if (!(ARGV_CHANNEL.source.values as readonly string[]).includes(record.source)) return null;
241
- return {
242
- base: record.base,
243
- source: record.source as BaseSource,
244
- plan: record.plan,
245
- recordedAt: typeof record.recordedAt === "string" ? record.recordedAt : "",
246
- };
247
- }
248
- }