@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.
- package/bin/agentic-workflow.mjs +80 -3
- package/package.json +1 -1
- package/src/edit/Roadmap.mjs +135 -2
package/bin/agentic-workflow.mjs
CHANGED
|
@@ -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": "
|
|
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>",
|
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.
|