@gtrabanco/agentic-workflow 0.4.0 → 4.10.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.
@@ -21,12 +21,12 @@
21
21
  * that blocks the caller (feature 66, AC2).
22
22
  */
23
23
 
24
- import { readFileSync } from "node:fs";
25
- import { join, resolve, basename } from "node:path";
24
+ import { readFileSync, existsSync } from "node:fs";
25
+ import { join, resolve, basename, dirname } from "node:path";
26
26
 
27
27
  // Import SDK modules
28
28
  import { create, setSection, evidence_addRow, progress_logEntry, validate } from "../src/edit/UnitDoc.mjs";
29
- import { rowUpsert, annotate as roadmapAnnotate } from "../src/edit/Roadmap.mjs";
29
+ import { rowUpsert, annotate as roadmapAnnotate, checkUnitDoc, ROADMAP_CHECK_CODES } from "../src/edit/Roadmap.mjs";
30
30
  import { rowAdd } from "../src/edit/Changelog.mjs";
31
31
  import { ceilingRebase } from "../src/edit/Budgets.mjs";
32
32
  import { skillAdd, skillRemove } from "../src/edit/Manifest.mjs";
@@ -68,6 +68,21 @@ function refuse(reason) {
68
68
  process.exit(2);
69
69
  }
70
70
 
71
+ /**
72
+ * Walk up from a unit doc to the repo root until the default index (e.g.
73
+ * `docs/features/ROADMAP.md`) exists; null when no ancestor carries it.
74
+ */
75
+ function findUpIndex(docPath, relativeIndex) {
76
+ let dir = dirname(docPath);
77
+ for (;;) {
78
+ const candidate = join(dir, relativeIndex);
79
+ if (existsSync(candidate)) return candidate;
80
+ const parent = dirname(dir);
81
+ if (parent === dir) return null;
82
+ dir = parent;
83
+ }
84
+ }
85
+
71
86
  // ── Router ───────────────────────────────────────────────────────────────
72
87
 
73
88
  const command = process.argv[2];
@@ -210,6 +225,14 @@ switch (command) {
210
225
 
211
226
  // ── roadmap ──────────────────────────────────────────────────────────
212
227
  case "roadmap": {
228
+ // `rowUpsert`/`annotate` take a table path first: a bare first positional is
229
+ // a missing path, never a filename. Resolving the subcommand word would make
230
+ // `roadmap rowUpsert …` open a file literally named `rowUpsert` and refuse
231
+ // with ENOENT, which reads as a missing table instead of a usage error.
232
+ if (rawArgs[0] === "rowUpsert" || rawArgs[0] === "annotate") {
233
+ process.stderr.write(`usage: agentic-workflow roadmap <table-path> ${rawArgs[0]} <json>\n`);
234
+ process.exit(2);
235
+ }
213
236
  const filePath = rawArgs[0] ? resolve(rawArgs[0]) : join(process.cwd(), "ROADMAP.md");
214
237
 
215
238
  if (rawArgs[0] === "rowUpsert" || (rawArgs[0] && rawArgs[1] === "rowUpsert")) {
@@ -232,6 +255,60 @@ switch (command) {
232
255
  } catch (e) {
233
256
  refuse(e.message);
234
257
  }
258
+ } else if (rawArgs[0] === "check" || (rawArgs[0] && rawArgs[1] === "check")) {
259
+ // roadmap check <unit-doc-path> [--roadmap <file>] [--index <file>] [--json]
260
+ // Cross-document check (issue #316): the unit doc's own facts (NN,
261
+ // slug, PR URL) against its index row. Exit contract: 0 consistent,
262
+ // 1 violations (named codes), 2 usage.
263
+ const docArg = rawArgs[1] === "check" ? rawArgs[2] : rawArgs[1];
264
+ if (!docArg) {
265
+ process.stderr.write("usage: agentic-workflow roadmap check <unit-doc-path> [--roadmap <file>] [--index <file>] [--json]\n");
266
+ process.exit(2);
267
+ }
268
+ const flag = (name) => {
269
+ const i = restArgs.indexOf(name);
270
+ return i !== -1 ? restArgs[i + 1] : undefined;
271
+ };
272
+ try {
273
+ const docPath = resolve(docArg);
274
+ const docText = readFileSync(docPath, "utf8");
275
+ // Kind and index defaults follow the doc's own tree position:
276
+ // docs/features → the roadmap, docs/fix → the fix index (its rows are
277
+ // removed once merged, so a missing row there is convention, not
278
+ // contradiction).
279
+ const parts = docPath.split("/");
280
+ const isFix = parts.includes("docs") && parts[parts.indexOf("docs") + 1] === "fix";
281
+ const defaultIndex = isFix ? "docs/fix/README.md" : "docs/features/ROADMAP.md";
282
+ const indexArg = flag("--roadmap") ?? flag("--index");
283
+ const indexPath = indexArg
284
+ ? resolve(indexArg)
285
+ : findUpIndex(docPath, defaultIndex.split("/").pop());
286
+ if (!indexPath) {
287
+ refuse(`index not found for ${docArg} — pass --roadmap <file>`);
288
+ }
289
+ const dirName = basename(dirname(docPath));
290
+ const nn = /^(\d+)/.exec(dirName)?.[1] ?? "";
291
+ const slug = dirName.replace(/^\d+-/, "");
292
+ const result = checkUnitDoc({ nn, slug, kind: isFix ? "fix" : "feature", docText, indexText: readFileSync(indexPath, "utf8") });
293
+ if (parsed.json) {
294
+ console.log(
295
+ JSON.stringify(
296
+ { service: "roadmap", op: "check", path: docPath, schema: "roadmap-table@1", codes: ROADMAP_CHECK_CODES, ok: result.ok, violations: result.violations },
297
+ null,
298
+ 2,
299
+ ),
300
+ );
301
+ } else {
302
+ for (const v of result.violations) {
303
+ console.log(`roadmap-check: ${docPath}:${v.line} ${v.code} — ${v.detail}`);
304
+ }
305
+ console.log(`verdict: ${result.ok ? "PASS" : "FAIL"}`);
306
+ console.log(`violations: ${result.violations.length}`);
307
+ }
308
+ process.exit(result.ok ? 0 : 1);
309
+ } catch (e) {
310
+ refuse(e.message);
311
+ }
235
312
  } else {
236
313
  refuse(`Unknown roadmap operation`);
237
314
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gtrabanco/agentic-workflow",
3
- "version": "0.4.0",
3
+ "version": "4.10.0",
4
4
  "description": "Deterministic runner for the agentic-workflow lane: file services (agwo edit), sensors, guards and receipts. One pinned pure-JS dependency, no native deps, no build step.",
5
5
  "license": "MIT",
6
6
  "author": "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>",
@@ -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 (contains "|---|")
58
- const separatorLine = content.split("\n").find((l) => l.includes("|---|"));
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.