@gtrabanco/agentic-workflow 0.2.0 → 0.5.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 +50 -0
- package/bin/agentic-workflow.mjs +109 -4
- package/package.json +3 -3
- package/src/doc/chunks.mjs +5 -1
- package/src/doc/config.mjs +63 -19
- package/src/doc/query.mjs +57 -9
- package/src/doc/retrieval.mjs +15 -2
- package/src/doc/store.mjs +7 -9
- package/src/doc/sync.mjs +34 -17
- package/src/edit/Roadmap.mjs +135 -2
- package/src/edit/UnitDoc.mjs +199 -11
- package/src/edit/schema.mjs +45 -1
- package/src/memory/probe.mjs +388 -0
package/src/edit/Roadmap.mjs
CHANGED
|
@@ -10,6 +10,17 @@
|
|
|
10
10
|
import { readFileSync, writeFileSync } from "node:fs";
|
|
11
11
|
import { createHash } from "node:crypto";
|
|
12
12
|
|
|
13
|
+
/**
|
|
14
|
+
* The separator rule matches the table that exists in this repository
|
|
15
|
+
* (`|----|------|…`), not only the literal `|---|` — issue #316 found the
|
|
16
|
+
* writer refusing the repo's own roadmap on the old literal match.
|
|
17
|
+
*/
|
|
18
|
+
const SEPARATOR_RE = /^\s*\|[-: |]+\|?\s*$/;
|
|
19
|
+
|
|
20
|
+
function isSeparatorLine(line) {
|
|
21
|
+
return SEPARATOR_RE.test(line) && (line.match(/-/g) || []).length >= 3;
|
|
22
|
+
}
|
|
23
|
+
|
|
13
24
|
// ── Helpers ──────────────────────────────────────────────────────────────
|
|
14
25
|
|
|
15
26
|
function sha256(text) {
|
|
@@ -54,8 +65,8 @@ export function rowUpsert(table, { nn, slug, status, dependsOn, description }) {
|
|
|
54
65
|
throw new Error("Roadmap table header not found (expected line with | NN |)");
|
|
55
66
|
}
|
|
56
67
|
|
|
57
|
-
// Find the separator line (
|
|
58
|
-
const separatorLine = content.split("\n").find(
|
|
68
|
+
// Find the separator line (a rule of pipes, dashes, colons and spaces)
|
|
69
|
+
const separatorLine = content.split("\n").find(isSeparatorLine);
|
|
59
70
|
if (!separatorLine) {
|
|
60
71
|
throw new Error("Roadmap table separator not found (expected line with |---|)");
|
|
61
72
|
}
|
|
@@ -101,6 +112,128 @@ export function rowUpsert(table, { nn, slug, status, dependsOn, description }) {
|
|
|
101
112
|
);
|
|
102
113
|
}
|
|
103
114
|
|
|
115
|
+
/**
|
|
116
|
+
* findRow(table, nn) — the full cell parse of one row, for callers that need
|
|
117
|
+
* to re-emit the row through rowUpsert without clobbering the cells they do
|
|
118
|
+
* not touch (the settle write: status changes, everything else preserved).
|
|
119
|
+
*
|
|
120
|
+
* Returns { nn, slug, status, dependsOn, description, line } or null when the
|
|
121
|
+
* row is absent. slug keeps the raw cell (backticks included); callers that
|
|
122
|
+
* compare slugs strip them.
|
|
123
|
+
*/
|
|
124
|
+
export function findRow(table, nn) {
|
|
125
|
+
const content = readFileSync(table, "utf8");
|
|
126
|
+
const line = content.split("\n").find((l) => l.trim().startsWith(`| ${nn} |`) && /^\| (\d+) \|/.test(l.trim()));
|
|
127
|
+
if (!line) return null;
|
|
128
|
+
const cells = line.split("|").map((c) => c.trim());
|
|
129
|
+
return {
|
|
130
|
+
nn: cells[1] ?? "",
|
|
131
|
+
slug: cells[2] ?? "",
|
|
132
|
+
status: cells[3] ?? "",
|
|
133
|
+
dependsOn: cells[4] ?? "",
|
|
134
|
+
description: cells[5] ?? "",
|
|
135
|
+
line,
|
|
136
|
+
};
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* The closed vocabulary of `roadmap check`. Adding a code is a change to this
|
|
141
|
+
* constant and its tests, never a new string somewhere else.
|
|
142
|
+
*/
|
|
143
|
+
export const ROADMAP_CHECK_CODES = Object.freeze(["row-missing", "slug-mismatch", "pr-url-unsettled"]);
|
|
144
|
+
|
|
145
|
+
/** First cell's unit number: roadmap rows carry it bare, fix-index rows link it. */
|
|
146
|
+
function rowNumber(cell) {
|
|
147
|
+
if (/^\d+$/.test(cell)) return cell;
|
|
148
|
+
const m = /issues\/(\d+)|#(\d+)/.exec(cell);
|
|
149
|
+
return m ? m[1] ?? m[2] : null;
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
function parseIndexRows(indexText) {
|
|
153
|
+
const rows = new Map();
|
|
154
|
+
for (const line of indexText.split("\n")) {
|
|
155
|
+
if (!line.startsWith("|")) continue;
|
|
156
|
+
const cells = line.split("|").map((c) => c.trim());
|
|
157
|
+
if (cells.length < 4) continue;
|
|
158
|
+
const nn = rowNumber(cells[1] ?? "");
|
|
159
|
+
if (!nn) continue;
|
|
160
|
+
rows.set(nn, { status: cells[3] ?? "", slug: (cells[2] ?? "").replace(/`/g, "") });
|
|
161
|
+
}
|
|
162
|
+
return rows;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** The status cell's bare token: the decoration (` · [#N](url)`) never carries it. */
|
|
166
|
+
function statusToken(cell) {
|
|
167
|
+
return cell.replace(/[`*]/g, "").split("·")[0].trim();
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* PR URLs on the doc's own lifecycle surfaces: the `## Next`, `## Log` and
|
|
172
|
+
* `## Evidence` sections and the References `- PR:` line the release step
|
|
173
|
+
* writes. URLs quoted elsewhere (cross-references in References prose) are
|
|
174
|
+
* other units' PRs and are never treated as this doc's own.
|
|
175
|
+
*/
|
|
176
|
+
function ownPrUrls(docText) {
|
|
177
|
+
const urls = [];
|
|
178
|
+
let section = null;
|
|
179
|
+
docText.split("\n").forEach((line, i) => {
|
|
180
|
+
const heading = /^##\s+(.*)/.exec(line);
|
|
181
|
+
if (heading) section = heading[1].trim();
|
|
182
|
+
const isReferencePr = /^-\s*PR:/.test(line);
|
|
183
|
+
const own = (section && /^(Next|Log|Evidence)\b/i.test(section)) || isReferencePr;
|
|
184
|
+
if (!own) return;
|
|
185
|
+
for (const m of line.matchAll(/https?:\/\/\S*\/pull\/(\d+)/g)) {
|
|
186
|
+
urls.push({
|
|
187
|
+
pr: Number(m[1]),
|
|
188
|
+
url: m[0].replace(/[`),.]+$/, ""),
|
|
189
|
+
line: i + 1,
|
|
190
|
+
where: isReferencePr ? "References" : section,
|
|
191
|
+
});
|
|
192
|
+
}
|
|
193
|
+
});
|
|
194
|
+
return urls;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* checkUnitDoc({ nn, slug, kind, docText, indexText }) — the cross-document
|
|
199
|
+
* comparison between a unit doc's own facts and its index row (issue #316).
|
|
200
|
+
*
|
|
201
|
+
* kind is "feature" (roadmap-indexed) or "fix" (fix-index rows are removed
|
|
202
|
+
* once merged, so an absent row is that index's own convention, not a
|
|
203
|
+
* contradiction). Returns { ok, violations } where every violation carries a
|
|
204
|
+
* code from ROADMAP_CHECK_CODES, the doc line it was detected on and a detail
|
|
205
|
+
* naming the expected settle form `done · [#N](<same url>)`.
|
|
206
|
+
*/
|
|
207
|
+
export function checkUnitDoc({ nn, slug, kind, docText, indexText }) {
|
|
208
|
+
const violations = [];
|
|
209
|
+
const row = parseIndexRows(indexText).get(String(nn));
|
|
210
|
+
if (!row) {
|
|
211
|
+
if (kind !== "fix") {
|
|
212
|
+
violations.push({ code: "row-missing", line: 1, detail: `no roadmap row for NN ${nn}` });
|
|
213
|
+
}
|
|
214
|
+
return { ok: violations.length === 0, violations };
|
|
215
|
+
}
|
|
216
|
+
if (slug && row.slug && row.slug !== slug) {
|
|
217
|
+
violations.push({ code: "slug-mismatch", line: 1, detail: `doc folder says '${slug}', row says '${row.slug}'` });
|
|
218
|
+
}
|
|
219
|
+
for (const { pr, url, line, where } of ownPrUrls(docText)) {
|
|
220
|
+
const token = statusToken(row.status);
|
|
221
|
+
// The settle link is backtick-tolerant: the fix index decorates rows as
|
|
222
|
+
// `done` · [`#302`](…), the roadmap as done · [#212](…). Both are the same
|
|
223
|
+
// settle; only the exact URL is compared, never the decoration.
|
|
224
|
+
const settled =
|
|
225
|
+
token === "done" &&
|
|
226
|
+
new RegExp(`\\[\`?#${pr}\`?\\]\\(${url.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\)`).test(row.status);
|
|
227
|
+
if (settled) continue;
|
|
228
|
+
violations.push({
|
|
229
|
+
code: "pr-url-unsettled",
|
|
230
|
+
line,
|
|
231
|
+
detail: `doc carries its PR URL (${where}); row status is '${row.status}' — expected 'done · [#${pr}](${url})'`,
|
|
232
|
+
});
|
|
233
|
+
}
|
|
234
|
+
return { ok: violations.length === 0, violations };
|
|
235
|
+
}
|
|
236
|
+
|
|
104
237
|
/**
|
|
105
238
|
* annotate(nn, note) — appends a note to the description cell of the row
|
|
106
239
|
* identified by nn. The note is appended with a newline and "—" prefix.
|
package/src/edit/UnitDoc.mjs
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
|
|
163
|
-
|
|
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
|
|
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 ===
|
|
497
|
+
if (found === required[expectedIdx]) {
|
|
323
498
|
expectedIdx++;
|
|
324
|
-
} else if (
|
|
325
|
-
violations.push(`Misordered section: ${found} (expected after ${
|
|
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
|
|
package/src/edit/schema.mjs
CHANGED
|
@@ -10,12 +10,13 @@
|
|
|
10
10
|
* package as owner.
|
|
11
11
|
*/
|
|
12
12
|
|
|
13
|
-
// ── Unit doc:
|
|
13
|
+
// ── Unit doc: 14 closed sections (ordered, #305) — the legacy shape ─────
|
|
14
14
|
export const UNIT_DOC_SECTIONS = [
|
|
15
15
|
"Objective",
|
|
16
16
|
"Why",
|
|
17
17
|
"User outcome",
|
|
18
18
|
"Acceptance criteria",
|
|
19
|
+
"Impact",
|
|
19
20
|
"Non-goals",
|
|
20
21
|
"Future cost",
|
|
21
22
|
"Applicable tests",
|
|
@@ -27,6 +28,49 @@ export const UNIT_DOC_SECTIONS = [
|
|
|
27
28
|
"References",
|
|
28
29
|
];
|
|
29
30
|
|
|
31
|
+
// ── Unit doc: the re-cut shape (spec-by-reference, #308) ────────────────
|
|
32
|
+
// `## Specs` numbers the owner's requirements verbatim, `## Findings` holds the
|
|
33
|
+
// OPEN rows `review-findings.md` used to carry, and `## Log` appends every
|
|
34
|
+
// request, correction, evidence run, gate run and folded finding. The re-cut adds
|
|
35
|
+
// three headings and drops the six they replace; the rest is shared, so a migrated
|
|
36
|
+
// doc and a closed one are read by the same code.
|
|
37
|
+
export const UNIT_DOC_SPEC_REF_SECTIONS = [
|
|
38
|
+
"Specs",
|
|
39
|
+
"Impact",
|
|
40
|
+
"Non-goals",
|
|
41
|
+
"Future cost",
|
|
42
|
+
"Applicable tests",
|
|
43
|
+
"Known pre-existing issues",
|
|
44
|
+
"Tasks",
|
|
45
|
+
"Findings",
|
|
46
|
+
"Log",
|
|
47
|
+
"Next",
|
|
48
|
+
"References",
|
|
49
|
+
];
|
|
50
|
+
|
|
51
|
+
// One shape table, resolved by the headings a document actually carries. Kept in
|
|
52
|
+
// parity with `UNIT_DOC_SECTION_SHAPES` in
|
|
53
|
+
// packages/agentic-workflow-schema/src/pre-execution.ts by
|
|
54
|
+
// `scripts/unit-doc-contract.test.mjs`; the duplicate is deliberate — this
|
|
55
|
+
// package ships without a dependency on the schema package.
|
|
56
|
+
export const UNIT_DOC_SECTION_SHAPES = Object.freeze({
|
|
57
|
+
legacy: UNIT_DOC_SECTIONS,
|
|
58
|
+
"spec-by-reference": UNIT_DOC_SPEC_REF_SECTIONS,
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
/** The accepted shape a set of headings satisfies, or `null` when it satisfies neither. */
|
|
62
|
+
export function resolveUnitDocShape(headings) {
|
|
63
|
+
for (const [name, sections] of Object.entries(UNIT_DOC_SECTION_SHAPES)) {
|
|
64
|
+
if (sections.every((section) => headings.includes(section))) return name;
|
|
65
|
+
}
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** The section list of a resolved shape, defaulting to the legacy list. */
|
|
70
|
+
export function unitDocSectionsFor(shape) {
|
|
71
|
+
return shape === null ? UNIT_DOC_SECTIONS : UNIT_DOC_SECTION_SHAPES[shape];
|
|
72
|
+
}
|
|
73
|
+
|
|
30
74
|
// ── Unit doc: evidence-table@1 columns ───────────────────────────────────
|
|
31
75
|
export const EVIDENCE_COLUMNS = [
|
|
32
76
|
"AC",
|