@gtrabanco/agentic-workflow 0.1.1 → 0.4.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.
@@ -0,0 +1,95 @@
1
+ /**
2
+ * Retrieval operations for `agentic-workflow doc` (unit 65).
3
+ *
4
+ * Each operation keeps the envelope contract fixed while its engine grows:
5
+ * sync — incremental sync engine: runs syncIndex and reports
6
+ * files_scanned / files_changed / files_deleted in the store value
7
+ * query — FTS5 keyword core behind ensureFresh (AC9), offline (AC13),
8
+ * with the AC14 structured session-log filters
9
+ * status — informational store report; never syncs
10
+ * rebuild — discard the disposable cache and resync from scratch
11
+ * Degradations come only from D3's closed vocabulary, as engines grow into
12
+ * the hybrid mode (P6/P7).
13
+ */
14
+
15
+ import { buildEnvelope } from "./envelope.mjs";
16
+ import { storePath } from "./store.mjs";
17
+ import { syncIndex, rebuildIndex } from "./sync.mjs";
18
+ import { queryIndex, statusIndex } from "./query.mjs";
19
+ import { loadConfig } from "./config.mjs";
20
+ import { resolveEmbedConfig, makeOpenAIProvider, embedPendingChunks } from "./embeddings.mjs";
21
+
22
+ /**
23
+ * Run one retrieval operation. `grammar` is parseDocArgs' output;
24
+ * `ctx.rootDir` is the project root the store and config resolve against.
25
+ * Returns the canonical envelope (async: the engines are async).
26
+ */
27
+ export async function runDocOp(grammar, ctx = {}) {
28
+ const root = ctx.rootDir ?? process.cwd();
29
+
30
+ if (grammar.op === "sync") {
31
+ const r = await syncIndex(root);
32
+ // P6: when a provider is configured (D10), embed pending chunks in the
33
+ // same pass; otherwise the store answers keyword-only (AC17's root).
34
+ const cfg = resolveEmbedConfig({ config: loadConfig(root), env: process.env });
35
+ let embedded = null;
36
+ let degradations = [];
37
+ if (cfg.configured) {
38
+ try {
39
+ embedded = await embedPendingChunks(root, makeOpenAIProvider(cfg));
40
+ if (embedded.skipped === true) {
41
+ // Model mismatch: keep the frozen key and declare the cause.
42
+ // (AC18: embeddings-model-mismatch; D3 frozen key set.)
43
+ degradations = [embedded.reason || "embeddings-model-mismatch"];
44
+ embedded = { embedded: 0 };
45
+ }
46
+ } catch (e) {
47
+ // AC17: provider-down ⇒ declared cause, ok:true, keyword results survive.
48
+ degradations = ["unavailable-embeddings-provider-down"];
49
+ embedded = { embedded: 0 };
50
+ }
51
+ }
52
+ return buildEnvelope({
53
+ command: "sync",
54
+ results: [],
55
+ degradations,
56
+ store: {
57
+ path: storePath(root),
58
+ present: true,
59
+ files: r.filesScanned,
60
+ chunks: r.chunks,
61
+ lastSync: {
62
+ files_scanned: r.filesScanned,
63
+ files_changed: r.filesChanged,
64
+ files_deleted: r.filesDeleted,
65
+ embedded: embedded === null ? 0 : embedded.embedded,
66
+ },
67
+ },
68
+ });
69
+ }
70
+
71
+ if (grammar.op === "query") {
72
+ return queryIndex(
73
+ root,
74
+ grammar.query,
75
+ { since: grammar.since, until: grammar.until, file: grammar.file },
76
+ { mode: grammar.mode ?? "keyword" },
77
+ );
78
+ }
79
+
80
+ if (grammar.op === "status") {
81
+ return statusIndex(root);
82
+ }
83
+
84
+ if (grammar.op === "rebuild") {
85
+ const r = await rebuildIndex(root);
86
+ return buildEnvelope({
87
+ command: "rebuild",
88
+ results: [],
89
+ degradations: [],
90
+ store: { path: storePath(root), present: true, files: r.filesScanned, chunks: r.chunks },
91
+ });
92
+ }
93
+
94
+ throw new Error(`usage: unknown doc op "${grammar.op}"`);
95
+ }
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Runtime SQLite adapter for the `doc` retrieval index (unit 65, D7).
3
+ *
4
+ * bun is the primary runtime (`bun:sqlite`); node ≥ 24 is the supported floor
5
+ * (`node:sqlite`). Both ship FTS5 here (P1 verified). The adapter returns the
6
+ * raw database plus the runtime name so callers can paper over the few API
7
+ * differences; a runtime without a usable SQLite module surfaces the closed
8
+ * `unavailable-sqlite-<runtime>` degradation (D3) — it never crashes.
9
+ */
10
+
11
+ import { mkdirSync } from "node:fs";
12
+ import { dirname } from "node:path";
13
+
14
+ export function runtimeName() {
15
+ return typeof Bun !== "undefined" ? "bun" : "node";
16
+ }
17
+
18
+ /**
19
+ * Open (creating if needed) the SQLite database at `path`. For `:memory:`
20
+ * no directory creation happens. Returns `{ db, kind }` where `kind` is
21
+ * `"bun" | "node"` and `db` is the raw runtime database handle.
22
+ */
23
+ export async function openDatabase(path) {
24
+ const kind = runtimeName();
25
+ if (path !== ":memory:") {
26
+ mkdirSync(dirname(path), { recursive: true });
27
+ }
28
+ if (kind === "bun") {
29
+ const { Database } = await import("bun:sqlite");
30
+ return { db: new Database(path), kind };
31
+ }
32
+ const { DatabaseSync } = await import("node:sqlite");
33
+ return { db: new DatabaseSync(path), kind };
34
+ }
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Store location for the `doc` retrieval index (unit 65, D4).
3
+ *
4
+ * The store is `.agentic-workflow/index/index.db` under the project root —
5
+ * a gitignored, disposable cache over git (AC7: `git status` stays clean
6
+ * after first creation). The canonical manifest export is the sidecar
7
+ * `manifest.json` in the same gitignored directory; AC12's byte-for-byte
8
+ * assertion runs over that export, never over SQLite page bytes.
9
+ */
10
+
11
+ import { existsSync } from "node:fs";
12
+ import { dirname, join } from "node:path";
13
+ import { openDatabase } from "./sqlite.mjs";
14
+ import { loadConfig } from "./config.mjs";
15
+
16
+ export const MANIFEST_EXPORT_NAME = "manifest.json";
17
+
18
+ /** Default store location: `.agentic-workflow/index/index.db`. */
19
+ const DEFAULT_STORE_DIR = join(".agentic-workflow", "index");
20
+
21
+ /**
22
+ * Resolve the store file path. Honours `config.store.path` when present;
23
+ * falls back to the default (`.agentic-workflow/index/index.db`).
24
+ */
25
+ export function storePath(root) {
26
+ const cfg = loadConfig(root);
27
+ if (cfg.store?.path) return join(root, cfg.store.path);
28
+ return join(root, DEFAULT_STORE_DIR, "index.db");
29
+ }
30
+
31
+ /**
32
+ * Canonical manifest export: the sidecar `manifest.json` beside the resolved
33
+ * store — the configured `store.path`'s directory when set (F18: the sidecar
34
+ * must travel with the store, or a custom store path ENOENTs on sync), else
35
+ * the default gitignored index dir. AC12's byte-for-byte assertion runs over
36
+ * that export, never over SQLite page bytes.
37
+ */
38
+ export function manifestExportPath(root) {
39
+ return join(dirname(storePath(root)), MANIFEST_EXPORT_NAME);
40
+ }
41
+
42
+ export function storePresent(root) {
43
+ return existsSync(storePath(root));
44
+ }
45
+
46
+ /**
47
+ * Create the store if absent. Idempotent: an existing store is left exactly
48
+ * as it is (P4's sync engine owns its schema migration).
49
+ */
50
+ export async function ensureStore(root) {
51
+ if (storePresent(root)) return storePath(root);
52
+ const { db } = await openDatabase(storePath(root));
53
+ db.close();
54
+ return storePath(root);
55
+ }
@@ -0,0 +1,176 @@
1
+ /**
2
+ * Incremental sync engine for the `doc` retrieval index (unit 65, P4).
3
+ *
4
+ * Change detection is hash-based (per-file sha256 from the canonical
5
+ * manifest, AC10): only files whose hash changed — or that disappeared —
6
+ * are reprocessed. Deletions reap every chunk of the removed file, and the
7
+ * external-content FTS5 table is kept in step by triggers, so no orphan
8
+ * chunk or ghost row survives (AC11). Determinism (AC12): the canonical
9
+ * manifest export written per sync is byte-identical for an unchanged
10
+ * corpus — sorted keys, git HEAD, no timestamps.
11
+ *
12
+ * Freshness invariant (AC9): `ensureFresh` compares the stored manifest
13
+ * (hashes + git HEAD) against the live corpus on every call; a stale store
14
+ * gets an inline incremental sync before the caller answers.
15
+ */
16
+
17
+ import { readFileSync, writeFileSync, rmSync } from "node:fs";
18
+ import { join } from "node:path";
19
+ import { openDatabase } from "./sqlite.mjs";
20
+ import { storePath, storePresent, manifestExportPath } from "./store.mjs";
21
+ import { loadConfig } from "./config.mjs";
22
+ import { collectManifest, canonicalJson } from "./manifest.mjs";
23
+ import { scanChunks } from "./chunks.mjs";
24
+
25
+ const SCHEMA = `
26
+ CREATE TABLE IF NOT EXISTS chunks (
27
+ chunk_id TEXT UNIQUE NOT NULL,
28
+ path TEXT NOT NULL,
29
+ section TEXT,
30
+ line_start INTEGER NOT NULL,
31
+ line_end INTEGER NOT NULL,
32
+ meta TEXT NOT NULL,
33
+ body TEXT NOT NULL,
34
+ embedding BLOB,
35
+ emb_model TEXT
36
+ );
37
+ CREATE INDEX IF NOT EXISTS chunks_path ON chunks(path);
38
+ CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(body, content='chunks', content_rowid='rowid');
39
+ CREATE TRIGGER IF NOT EXISTS chunks_ai AFTER INSERT ON chunks BEGIN
40
+ INSERT INTO chunks_fts(rowid, body) VALUES (new.rowid, new.body);
41
+ END;
42
+ CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
43
+ INSERT INTO chunks_fts(chunks_fts, rowid, body) VALUES ('delete', old.rowid, old.body);
44
+ END;
45
+ CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
46
+ `;
47
+
48
+ /** Read the manifest persisted in the store's meta table (null if absent). */
49
+ export function storedManifest(db) {
50
+ try {
51
+ const row = db.prepare("select value from meta where key = 'manifest'").get();
52
+ return row ? JSON.parse(row.value) : null;
53
+ } catch {
54
+ return null;
55
+ }
56
+ }
57
+
58
+ /** Counts for `--status`: `{files, chunks}` over the store at `root`. */
59
+ export async function storeStats(root) {
60
+ const { db } = await openDatabase(storePath(root));
61
+ const files = db.prepare("select count(distinct path) as n from chunks").get().n;
62
+ const chunks = db.prepare("select count(*) as n from chunks").get().n;
63
+ db.close();
64
+ return { files, chunks };
65
+ }
66
+
67
+ /**
68
+ * One incremental sync pass over the tracked markdown corpus at `root`.
69
+ * Returns `{filesScanned, filesChanged, filesDeleted, chunks}`.
70
+ */
71
+ export async function syncIndex(root) {
72
+ loadConfig(root); // config errors surface here too (usage/IO), even in sync
73
+ const manifest = collectManifest(root);
74
+ const { db } = await openDatabase(storePath(root));
75
+ db.exec(SCHEMA);
76
+
77
+ const stored = storedManifest(db);
78
+ const oldFiles = stored?.files ?? {};
79
+ const changed = [];
80
+ const deleted = [];
81
+ for (const [path, info] of Object.entries(manifest.files)) {
82
+ if (oldFiles[path] === undefined || oldFiles[path].sha256 !== info.sha256) changed.push(path);
83
+ }
84
+ for (const path of Object.keys(oldFiles)) {
85
+ if (manifest.files[path] === undefined) deleted.push(path);
86
+ }
87
+
88
+ const reap = db.prepare("DELETE FROM chunks WHERE path = ?");
89
+ const insert = db.prepare(
90
+ "INSERT INTO chunks (chunk_id, path, section, line_start, line_end, meta, body) VALUES (?, ?, ?, ?, ?, ?, ?)",
91
+ );
92
+ // F51: one transaction for the whole reap/insert pass. Per-row autocommit
93
+ // paid one fsync per chunk on the cold path (~9.6x measured); a single
94
+ // BEGIN/COMMIT — with rollback on throw so a mid-pass failure leaves the
95
+ // previous store state intact — is the fix, never a weakening of the
96
+ // per-file error semantics (the ENOENT-as-deletion branch still throws
97
+ // non-ENOENT errors out of the pass).
98
+ db.exec("BEGIN");
99
+ try {
100
+ for (const path of deleted) reap.run(path);
101
+ for (const path of changed) {
102
+ const src = join(root, path);
103
+ try {
104
+ // Reap existing chunks for this path before re-inserting (original
105
+ // reap.run(path) before the read — preserved for the non-ENOENT path).
106
+ reap.run(path);
107
+ const rows = scanChunks(readFileSync(src, "utf8"), path);
108
+ for (const c of rows) {
109
+ insert.run(c.id, c.path, c.section, c.lines[0], c.lines[1], JSON.stringify(c.meta), c.body);
110
+ }
111
+ } catch (e) {
112
+ if (e.code === "ENOENT") {
113
+ // File deleted in working tree but not yet committed → reap
114
+ // (AC11: treat as deletion).
115
+ reap.run(path);
116
+ deleted.push(path);
117
+ } else throw e;
118
+ }
119
+ }
120
+ db.exec("COMMIT");
121
+ } catch (e) {
122
+ try {
123
+ db.exec("ROLLBACK");
124
+ } catch {
125
+ // the transaction may already be rolled back by the driver
126
+ }
127
+ throw e;
128
+ }
129
+
130
+ // Persist + export the canonical manifest (AC12's compared artifact).
131
+ db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('manifest', ?)").run(canonicalJson(manifest));
132
+ db.close();
133
+ writeFileSync(manifestExportPath(root), `${canonicalJson(manifest)}\n`);
134
+
135
+ const stats = await storeStats(root);
136
+ return {
137
+ filesScanned: Object.keys(manifest.files).length,
138
+ filesChanged: changed.length,
139
+ filesDeleted: deleted.length,
140
+ chunks: stats.chunks,
141
+ };
142
+ }
143
+
144
+ /**
145
+ * Freshness invariant (AC9): manifest hashes + git HEAD checked against the
146
+ * store; stale or missing ⇒ inline incremental sync before answering.
147
+ * Returns `{fresh, synced}`.
148
+ */
149
+ export async function ensureFresh(root) {
150
+ const current = collectManifest(root);
151
+ if (storePresent(root)) {
152
+ const { db } = await openDatabase(storePath(root));
153
+ const stored = storedManifest(db);
154
+ db.close();
155
+ if (stored !== null && canonicalJson(stored) === canonicalJson(current)) {
156
+ return { fresh: true, synced: false };
157
+ }
158
+ }
159
+ await syncIndex(root);
160
+ return { fresh: false, synced: true };
161
+ }
162
+
163
+ /**
164
+ * `--rebuild`: discard the disposable cache entirely (db + WAL/SHM + the
165
+ * manifest export) and resync from scratch. Returns the fresh sync counts
166
+ * with `rebuilt: true`.
167
+ */
168
+ export async function rebuildIndex(root) {
169
+ const base = storePath(root);
170
+ rmSync(base, { force: true });
171
+ rmSync(`${base}-wal`, { force: true });
172
+ rmSync(`${base}-shm`, { force: true });
173
+ rmSync(manifestExportPath(root), { force: true });
174
+ const r = await syncIndex(root);
175
+ return { rebuilt: true, ...r };
176
+ }
@@ -2,9 +2,12 @@
2
2
  * UnitDoc — create and edit single-unit SPEC documents.
3
3
  *
4
4
  * The unit doc is a single Markdown file (docs/features/<NN>-<slug>/SPEC.md)
5
- * containing exactly 13 closed sections in a fixed order. All edits go
5
+ * containing one of two accepted closed section sets in a fixed order (#305
6
+ * added `## Impact`; #308 added the `spec-by-reference` shape). All edits go
6
7
  * through typed operations that validate post-state against the file schema
7
- * before writing.
8
+ * before writing, and validation resolves the shape from the headings the
9
+ * document carries — a legacy doc and a migrated one are both valid, never one
10
+ * of them silently upgraded.
8
11
  */
9
12
 
10
13
  import { readFileSync, writeFileSync, renameSync, existsSync, mkdtempSync, rename } from "node:fs";
@@ -13,11 +16,19 @@ import { tmpdir } from "node:os";
13
16
  import { createHash } from "node:crypto";
14
17
  import {
15
18
  UNIT_DOC_SECTIONS,
19
+ UNIT_DOC_SPEC_REF_SECTIONS,
20
+ UNIT_DOC_SECTION_SHAPES,
16
21
  EVIDENCE_COLUMNS,
17
22
  PROGRESS_ENTRY_REGEX,
23
+ resolveUnitDocShape,
24
+ unitDocSectionsFor,
18
25
  } from "./schema.mjs";
19
26
 
20
- // ── Canonical skeleton matching docs/features/_TEMPLATE/SPEC.md ──────────
27
+ // ── Canonical skeletons matching docs/{features,fix}/_TEMPLATE/SPEC.md ────
28
+ // The legacy shape is emitted by `create`; the re-cut shape by
29
+ // `createSpecByReference`. Neither is derived from the other: a skeleton is a
30
+ // published template, and generating it from the other shape would make the two
31
+ // drift silently (the #305 defect class).
21
32
  const CANONICAL_SKELETON = `# NN — <unit-slug>
22
33
 
23
34
  > One-line: what this unit doc is. Copy to docs/features/NN-<slug>/.
@@ -40,10 +51,28 @@ Numbered list. Each AC is induced from a concrete user scenario ("I do X and obs
40
51
  Make each AC command-verified where possible. If the request is too vague to state an AC,
41
52
  STOP and ask the user with concrete options — never invent one.
42
53
 
54
+ ## Impact
55
+
56
+ What the change touches beyond its own files: what consumes this unit's
57
+ deliverables, what this unit consumes from others, what stops being true when
58
+ the change lands (comments, docs, declared validators, narrations naming the
59
+ old shape), and what must be asked before touching something live on the other
60
+ side. Cut at plan time — the executor sweeps this surface, it is not
61
+ rediscovered at review.
62
+
43
63
  ## Non-goals
44
64
 
45
65
  What this unit is NOT. Findings discovered during implementation never expand scope.
46
66
 
67
+ ## Future
68
+
69
+ Ideas the user deferred ("down the road I'd like…"), captured verbatim with a
70
+ date and a status: \`open\`, \`planned\`, or \`discarded <YYYY-MM-DD>\`. This unit
71
+ never implements, specs, or tasks a row here. Write \`none\` when nothing was
72
+ deferred. Reviewed at unit close, on session resume, and whenever later work
73
+ returns to the same area — each open row is then offered as
74
+ plan-now / keep-deferred / discard.
75
+
47
76
  ## Future cost
48
77
 
49
78
  Standing obligations this unit imposes on future work. Each row: the rule + who it binds.
@@ -85,6 +114,113 @@ The single next action.
85
114
  Issues, roadmap rows, related material. The PR closes absorbed issues via \`Closes #N\`. \`none\` if empty.
86
115
  `;
87
116
 
117
+ // The re-cut skeleton (issue #308). Section bodies state what to write, in
118
+ // positive terms: each `S#` quotes the request verbatim, each task links the
119
+ // requirement it implements, and the log is appended to, never rewritten.
120
+ const CANONICAL_SPEC_REF_SKELETON = `# NN — <unit-slug>
121
+
122
+ > One-line: what this unit doc is. Copy to docs/features/NN-<slug>/.
123
+
124
+ ## Specs
125
+
126
+ Requirements, each numbered \`S#\` and quoting the requester's own words
127
+ verbatim between the quote markers. Cut one requirement per distinct ask, in the
128
+ order the request states them; a later correction is appended under its own id
129
+ (\`S1a\`, \`S2a\`, …) and never rewrites the id it corrects.
130
+
131
+ **S1 — <short title in your own words>.**
132
+ > <the request's words, verbatim and unedited>
133
+
134
+ ## Impact
135
+
136
+ What the change touches beyond its own files: what consumes this unit's
137
+ deliverables, what this unit consumes from others, what stops being true when
138
+ the change lands (comments, docs, declared validators, narrations naming the
139
+ old shape), and what must be asked before touching something live on the other
140
+ side. Cut at plan time — the executor sweeps this surface, it is not
141
+ rediscovered at review.
142
+
143
+ ## Non-goals
144
+
145
+ What this unit is NOT. Findings discovered during implementation never expand scope.
146
+
147
+ ## Future
148
+
149
+ Ideas the user deferred ("down the road I'd like…"), captured verbatim with a
150
+ date and a status: \`open\`, \`planned\`, or \`discarded <YYYY-MM-DD>\`. This unit
151
+ never implements, specs, or tasks a row here. Write \`none\` when nothing was
152
+ deferred. Reviewed at unit close, on session resume, and whenever later work
153
+ returns to the same area — each open row is then offered as
154
+ plan-now / keep-deferred / discard.
155
+
156
+ ## Future cost
157
+
158
+ Standing obligations this unit imposes on future work. Each row: the rule + who it binds.
159
+
160
+ ## Applicable tests
161
+
162
+ The tests this unit will run (triage-decided). Write exactly \`n/a — no tests step for this unit\`
163
+ when there is none.
164
+
165
+ ## Known pre-existing issues
166
+
167
+ Each: <issue/observation> + explicit \`affects\` or \`does-not-affect\` this unit.
168
+ A red gate is never excused by an unrecorded issue.
169
+
170
+ ## Tasks
171
+
172
+ P1…Pn with stable IDs, one line each, smallest first. Final task is verification when the unit has behavior. Each task carries its validator — a backticked command plus its expected outcome — and an \`(Implements: S1, S2)\` line naming the requirements it delivers, plus an optional nested \`Relevant files: <path, path…>\` line naming that task's read set (metadata, never a task).
173
+
174
+ - P1 — <task> (validator: \`node --test scripts/x.test.mjs\` exits 0)
175
+ (Implements: S1)
176
+ Relevant files: <path>
177
+
178
+ ### Planning evidence
179
+
180
+ One row per Engineering claim (the closed column order and vocabularies are owned
181
+ by \`skills/pre-execution-review/references/LEDGERS.md\`). Embedded here for XS/S
182
+ units; for M/L the ledger lives in the unit folder's \`planning-evidence.md\` and
183
+ this section names it instead — never both.
184
+
185
+ ### Obligations
186
+
187
+ One row per normative behaviour, compatibility invariant, affected use case, and
188
+ required failure state (shape owned by
189
+ \`skills/pre-execution-review/references/LEDGERS.md\`). Embedded here for XS/S
190
+ units; for M/L the ledger lives in the unit folder's \`planning-obligations.md\`
191
+ and this section names it — never both. Before the unit ships, every row is
192
+ \`verified\` (or an evidenced \`n/a\`).
193
+
194
+ ## Findings
195
+
196
+ OPEN rows only: a row a review persisted as fix-now work and no fold has closed.
197
+ A folded row leaves this table and becomes a \`## Log\` line. Rows are appended by
198
+ \`review-change\` and \`triage-issue\`.
199
+
200
+ | id | S# / file:line | axis | severity | class | route |
201
+ |---|---|---|---|---|---|
202
+
203
+ ## Log
204
+
205
+ Append-only. \`L1\` is the request verbatim; every later line carries one kind
206
+ token — \`L<n>\` request or correction (a verbatim quote), \`E<n>\` evidence run,
207
+ \`G<n>\` gate run, \`F<n>\` folded finding, \`D<n>\` owner decision, \`P<n>\` phase
208
+ progress. A correction never edits an earlier line: it appends.
209
+
210
+ - **L1** — <YYYY-MM-DD>, the request, verbatim:
211
+ \`\`\`
212
+ <the request as it was made>
213
+ \`\`\`
214
+
215
+ ## Next
216
+
217
+ The single next action.
218
+
219
+ ## References
220
+
221
+ Issues, roadmap rows, related material. The PR closes absorbed issues via \`Closes #N\`. \`none\` if empty.
222
+ `;
223
+
88
224
  // ── Helpers ──────────────────────────────────────────────────────────────
89
225
 
90
226
  function sha256(text) {
@@ -117,7 +253,7 @@ function makeReceipt(service, op, path, schema, before, after, ok) {
117
253
  // ── Public API ───────────────────────────────────────────────────────────
118
254
 
119
255
  /**
120
- * create(dir, slug) — write the unit doc with all 13 sections from the
256
+ * create(dir, slug) — write the unit doc with all 14 sections from the
121
257
  * canonical skeleton. dir is the parent directory (e.g. docs/features);
122
258
  * slug is the kebab-case name. The file lands at docs/features/<slug>/SPEC.md.
123
259
  *
@@ -159,8 +295,11 @@ export function create(dir, slug) {
159
295
  * Returns a receipt. Throws on unknown section.
160
296
  */
161
297
  export function setSection(doc, name, body) {
162
- if (!UNIT_DOC_SECTIONS.includes(name)) {
163
- throw new Error(`Unknown section "${name}"; allowed: ${UNIT_DOC_SECTIONS.join(", ")}`);
298
+ // Both accepted shapes are addressable: a migrated document sets its own
299
+ // sections and a legacy one keeps its own (#308).
300
+ const addressable = [...new Set([...UNIT_DOC_SECTIONS, ...UNIT_DOC_SPEC_REF_SECTIONS])];
301
+ if (!addressable.includes(name)) {
302
+ throw new Error(`Unknown section "${name}"; allowed: ${addressable.join(", ")}`);
164
303
  }
165
304
  const content = readFileSync(doc, "utf8");
166
305
  const beforeHash = sha256(content);
@@ -185,6 +324,37 @@ export function setSection(doc, name, body) {
185
324
  );
186
325
  }
187
326
 
327
+ /**
328
+ * createSpecByReference(dir, slug) — write the unit doc in the re-cut
329
+ * (`spec-by-reference`) shape from its own canonical skeleton (#308). Same
330
+ * contract as `create`: dir is the unit directory, the file lands at
331
+ * dir/SPEC.md, and the receipt reports whether the written content validates.
332
+ *
333
+ * Returns { ok: true, receipt } on success.
334
+ */
335
+ export function createSpecByReference(dir, slug) {
336
+ if (!existsSync(dir)) {
337
+ throw new Error(`Directory does not exist: ${dir}`);
338
+ }
339
+ const target = join(dir, "SPEC.md");
340
+ const content = CANONICAL_SPEC_REF_SKELETON;
341
+ const beforeHash = existsSync(target) ? sha256(readFileSync(target, "utf8")) : "empty";
342
+ atomicWrite(target, content);
343
+ const afterHash = sha256(readFileSync(target, "utf8"));
344
+
345
+ const validation = validate(readFileSync(target, "utf8"));
346
+ const ok = validation.ok && validation.violations.length === 0;
347
+ return makeReceipt(
348
+ "unitDoc",
349
+ "create",
350
+ target,
351
+ "unit-doc-template@1",
352
+ shaPrefix(beforeHash),
353
+ shaPrefix(afterHash),
354
+ ok,
355
+ );
356
+ }
357
+
188
358
  /**
189
359
  * evidence.addRow(doc, { ac, command, exitDigest, output, verifiedBy })
190
360
  * Appends a row to the evidence table in the unit doc.
@@ -299,8 +469,14 @@ export function validate(text) {
299
469
  if (m) foundHeadings.push(m[1]);
300
470
  }
301
471
 
472
+ // Which accepted shape the document asserts (#308). A document satisfying
473
+ // neither is reported against the legacy list, which is the shape every unit
474
+ // predating the re-cut carries.
475
+ const shape = resolveUnitDocShape(foundHeadings);
476
+ const required = unitDocSectionsFor(shape);
477
+
302
478
  // Check for missing sections
303
- for (const section of UNIT_DOC_SECTIONS) {
479
+ for (const section of required) {
304
480
  if (!foundHeadings.includes(section)) {
305
481
  violations.push(`Missing section: ${section}`);
306
482
  }
@@ -316,13 +492,25 @@ export function validate(text) {
316
492
  }
317
493
 
318
494
  // Check for misordered sections (only the ones that exist)
319
- const filtered = UNIT_DOC_SECTIONS.filter((s) => foundHeadings.includes(s));
320
495
  let expectedIdx = 0;
321
496
  for (const found of foundHeadings) {
322
- if (found === UNIT_DOC_SECTIONS[expectedIdx]) {
497
+ if (found === required[expectedIdx]) {
323
498
  expectedIdx++;
324
- } else if (UNIT_DOC_SECTIONS.includes(found)) {
325
- violations.push(`Misordered section: ${found} (expected after ${UNIT_DOC_SECTIONS[expectedIdx - 1]} or before ${UNIT_DOC_SECTIONS[expectedIdx]})`);
499
+ } else if (required.includes(found)) {
500
+ violations.push(`Misordered section: ${found} (expected after ${required[expectedIdx - 1]} or before ${required[expectedIdx]})`);
501
+ }
502
+ }
503
+
504
+ // A half-migrated document carries a section from the other shape: its
505
+ // Evidence rows and its Log would both claim to be the receipt, so it is
506
+ // refused rather than read two ways (the #308 §Scope 4 migration rule).
507
+ if (shape !== null) {
508
+ const foreign = Object.entries(UNIT_DOC_SECTION_SHAPES)
509
+ .filter(([name]) => name !== shape)
510
+ .flatMap(([, sections]) => sections)
511
+ .filter((section) => !required.includes(section) && foundHeadings.includes(section));
512
+ for (const section of new Set(foreign)) {
513
+ violations.push(`Half-migrated section: ${section} belongs to the other accepted shape`);
326
514
  }
327
515
  }
328
516