@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.
- package/README.md +56 -2
- package/bin/agentic-workflow.mjs +71 -1
- package/package.json +7 -4
- package/src/doc/chunks.mjs +154 -0
- package/src/doc/config.mjs +108 -0
- package/src/doc/embeddings.mjs +162 -0
- package/src/doc/envelope.mjs +120 -0
- package/src/doc/grammar.mjs +109 -0
- package/src/doc/manifest.mjs +84 -0
- package/src/doc/query.mjs +327 -0
- package/src/doc/retrieval.mjs +95 -0
- package/src/doc/sqlite.mjs +34 -0
- package/src/doc/store.mjs +55 -0
- package/src/doc/sync.mjs +176 -0
- package/src/edit/UnitDoc.mjs +199 -11
- package/src/edit/schema.mjs +45 -1
- package/src/memory/probe.mjs +388 -0
|
@@ -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
|
+
}
|
package/src/doc/sync.mjs
ADDED
|
@@ -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
|
+
}
|
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
|
|