@nusoft/nuos-build-catalogue 0.32.0 → 0.33.1

package/dist/cli.js

@@ -436,6 +436,15 @@ Usage:
   nuos-catalogue memory    store     --value="..." [--wu=wu-007] [--agent=architect] [--key="label"]
   nuos-catalogue memory    search    --query="..." [--limit=N]   [--wu=wu-007]       [--agent=architect]
 
+  nuos-catalogue end-of-session
+                          (WU 112 — verify-and-gate: checks the nine end-of-session protocol steps
+                           against disk facts; prints a per-check report; exits non-zero on a blocked
+                           gate; persists step-state in the workflow store for resumability.
+                           Options: --active-wu=<handle>  --date=YYYY-MM-DD  --session-start=<iso>
+                                    --dry-run  [--build-root=<dir>] [--workflows=<file>])
+  nuos-catalogue start-of-session
+                          (reserved — body in a follow-up WU)
+
   nuos-catalogue help
 
 Handles accepted: canonical (wu-111, D046, Q009, P001) or friendly
@@ -629,6 +638,31 @@ async function main() {
             console.error('           memory search --query="..." [--limit=N] [--wu=...] [--agent=...]');
             process.exit(1);
         }
+        case 'end-of-session': {
+            const buildRoot = resolveBuildRoot(args.flags['build-root']);
+            const workflowsPath = resolveWorkflowsPath(buildRoot, args.flags['workflows']);
+            const { createBuildCatalogueRuntime } = await import('./runtime/runtime.js');
+            const { cmdEndOfSession } = await import('./commands/end-of-session.js');
+            const store = await openWorkflowStore(workflowsPath);
+            const runtime = createBuildCatalogueRuntime({ store, catalogueRoot: buildRoot });
+            const result = await cmdEndOfSession(store, runtime, {
+                buildRoot,
+                activeWuHandle: args.flags['active-wu'] ? String(args.flags['active-wu']) : undefined,
+                sessionDate: args.flags['date'] ? String(args.flags['date']) : undefined,
+                sessionStartIso: args.flags['session-start'] ? String(args.flags['session-start']) : undefined,
+                dryRun: Boolean(args.flags['dry-run']),
+            });
+            if (result.output)
+                console.log(result.output);
+            process.exit(result.exitCode);
+            break;
+        }
+        case 'start-of-session': {
+            // Reserved handle — body in a follow-up WU.
+            console.error('start-of-session: not yet implemented (WU 112 reserves the handle; body in a follow-up WU).');
+            process.exit(2);
+            break;
+        }
         case 'help':
         case '--help':
         case '-h':

package/dist/commands/end-of-session.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `nuos-catalogue end-of-session` — runnable CLI driver for the
+ * `end_of_session` verify-and-gate workflow (WU 112 / D130).
+ *
+ * This command:
+ *   1. Gathers `EndOfSessionFacts` from disk (mtimes, file existence, index
+ *      parity, TODAY's date).
+ *   2. Checks for an existing `session.end:<date>` record in the store (resume
+ *      support — if a prior run left the session incomplete, it continues from
+ *      the persisted step-state).
+ *   3. Drives the workflow lifecycle through the NuFlow runtime.
+ *   4. Prints a per-check report (pass/fail per step).
+ *   5. Exits non-zero if the gate blocks (any gating check failed).
+ *
+ * D129/D130-safe: this command writes NO catalogue prose and renders NO
+ * markdown from the store. Its only persistent write is the
+ * `session.end:<date>` step-state record (via the MIS adapter).
+ *
+ * Note: the "what this gate cannot do" boundary is printed in the report —
+ * a green gate proves presence/structure only, not semantic correctness of
+ * STATE.md or the truth of a session-log narrative.
+ */
+import type { NuFlowRuntime } from '@nusoft/nuflow';
+import type { WorkflowStore } from '../migrate/store.js';
+export interface EndOfSessionHandlerResult {
+    output: string;
+    exitCode: number;
+}
+export declare function cmdEndOfSession(store: WorkflowStore, runtime: NuFlowRuntime, args: {
+    buildRoot: string;
+    activeWuHandle?: string;
+    sessionDate?: string;
+    sessionStartIso?: string;
+    dryRun?: boolean;
+}): Promise<EndOfSessionHandlerResult>;

package/dist/commands/end-of-session.js

@@ -0,0 +1,470 @@
+/**
+ * `nuos-catalogue end-of-session` — runnable CLI driver for the
+ * `end_of_session` verify-and-gate workflow (WU 112 / D130).
+ *
+ * This command:
+ *   1. Gathers `EndOfSessionFacts` from disk (mtimes, file existence, index
+ *      parity, TODAY's date).
+ *   2. Checks for an existing `session.end:<date>` record in the store (resume
+ *      support — if a prior run left the session incomplete, it continues from
+ *      the persisted step-state).
+ *   3. Drives the workflow lifecycle through the NuFlow runtime.
+ *   4. Prints a per-check report (pass/fail per step).
+ *   5. Exits non-zero if the gate blocks (any gating check failed).
+ *
+ * D129/D130-safe: this command writes NO catalogue prose and renders NO
+ * markdown from the store. Its only persistent write is the
+ * `session.end:<date>` step-state record (via the MIS adapter).
+ *
+ * Note: the "what this gate cannot do" boundary is printed in the report —
+ * a green gate proves presence/structure only, not semantic correctness of
+ * STATE.md or the truth of a session-log narrative.
+ */
+import { stat, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+const BUILD_MAINTAINER = {
+    kind: 'staff',
+    id: 'build-maintainer',
+    role: 'build-maintainer',
+};
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+export async function cmdEndOfSession(store, runtime, args) {
+    const today = args.sessionDate ?? new Date().toISOString().slice(0, 10);
+    const sessionStartIso = args.sessionStartIso ?? new Date(today + 'T00:00:00.000Z').toISOString();
+    // Resolve the active WU handle — required for step 1 check.
+    const activeWuHandle = args.activeWuHandle ?? resolveActiveWuHandle(store);
+    if (!activeWuHandle) {
+        return {
+            output: [
+                'end-of-session: cannot determine the active WU handle.',
+                'Supply --active-wu=<handle> or run `nuos-catalogue wu start <handle>` first.',
+            ].join('\n'),
+            exitCode: 1,
+        };
+    }
+    // Gather disk facts — this is the only place filesystem access happens
+    // (the workflow itself is pure).
+    const catalogueFacts = await gatherFacts(args.buildRoot, activeWuHandle, sessionStartIso, today);
+    // Check for an existing (incomplete) session.end:<date> record.
+    const existingHandle = `session.end:${today}`;
+    const existingRecord = store.get(existingHandle);
+    let resumeFromStep;
+    if (existingRecord) {
+        try {
+            const stored = JSON.parse(existingRecord.rawMarkdown);
+            if (stored.completed) {
+                return {
+                    output: [
+                        `end-of-session: session ${today} was already marked complete in a prior run.`,
+                        'If you need to re-verify, delete the store record and re-run.',
+                    ].join('\n'),
+                    exitCode: 0,
+                };
+            }
+            // Find the first step that was not yet passed — resume from there.
+            if (stored.steps) {
+                const STEP_ORDER = [
+                    'update_active_wu_notes',
+                    'capture_decisions',
+                    'capture_open_questions',
+                    'capture_risks',
+                    'update_work_units_index',
+                    'update_state_md',
+                    'write_session_log',
+                    'confirm_no_loss',
+                    'report',
+                ];
+                for (const stepId of STEP_ORDER) {
+                    if (stored.steps[stepId]?.status !== 'passed') {
+                        resumeFromStep = stepId;
+                        break;
+                    }
+                }
+            }
+        }
+        catch {
+            // If the existing record is malformed, start fresh.
+        }
+    }
+    const metadata = {
+        sessionDate: today,
+        activeWuHandle,
+        sessionStartIso,
+        catalogueFacts,
+        ...(resumeFromStep ? { resumeFromStep } : {}),
+    };
+    const capture = {
+        channel: 'typed_note',
+        content: `end-of-session for ${today}`,
+        subjects: [{ kind: 'session', id: existingHandle }],
+        metadata: metadata,
+    };
+    // Drive the NuFlow lifecycle: start → confirm → commit.
+    const wf = await runtime.startWorkflow('end_of_session', BUILD_MAINTAINER, capture);
+    if (!wf.writeIntent) {
+        return {
+            output: 'end-of-session: workflow did not produce a writeIntent — unexpected runtime state.',
+            exitCode: 1,
+        };
+    }
+    const payload = wf.writeIntent.payload;
+    if (args.dryRun) {
+        return {
+            output: formatReport(payload, today, resumeFromStep, true),
+            exitCode: payload.failingChecks.length > 0 ? 1 : 0,
+        };
+    }
+    // Confirm and commit to persist the step-state record.
+    const confirmedWf = await runtime.confirmIntent(wf.id, BUILD_MAINTAINER.id);
+    await runtime.commitIntent(confirmedWf.id, BUILD_MAINTAINER.id);
+    return {
+        output: formatReport(payload, today, resumeFromStep, false),
+        exitCode: payload.failingChecks.length > 0 ? 1 : 0,
+    };
+}
+// ---------------------------------------------------------------------------
+// Disk fact gathering — the only place fs access happens
+// ---------------------------------------------------------------------------
+async function gatherFacts(buildRoot, activeWuHandle, sessionStartIso, sessionDate) {
+    const sessionStartMs = new Date(sessionStartIso).getTime();
+    // Step 1: WU notes
+    const { wuNotesTouched, wuNotesHasTodayHeading } = await checkWuNotes(buildRoot, activeWuHandle, sessionStartMs, sessionDate);
+    // Steps 2–4: register parity
+    const decisionsFileIndexParity = await checkRegisterParity(buildRoot, 'decisions', sessionDate, /^D\d+.*\.md$/i);
+    const questionsParity = await checkRegisterParity(buildRoot, 'open-questions', sessionDate, /^Q\d+.*\.md$/i);
+    const risksParity = await checkRisksParity(buildRoot);
+    // Step 5: work-units index
+    const doneMoveOk = await checkWorkUnitsIndex(buildRoot);
+    // Step 6: STATE.md
+    const { stateMdTouched, stateMdLastUpdated, stateMdLastSessionResolves } = await checkStateMd(buildRoot, sessionStartMs, sessionDate);
+    // Step 7: session log
+    const { sessionLogExists, sessionLogIndexed } = await checkSessionLog(buildRoot, sessionDate);
+    return {
+        wuNotesTouched,
+        wuNotesHasTodayHeading,
+        decisionsFileIndexParity,
+        questionsParity,
+        risksParity,
+        doneMoveOk,
+        stateMdTouched,
+        stateMdLastUpdated,
+        stateMdLastSessionResolves,
+        sessionLogExists,
+        sessionLogIndexed,
+    };
+}
+// ---------------------------------------------------------------------------
+// Individual fact checks
+// ---------------------------------------------------------------------------
+async function fileMtime(filePath) {
+    try {
+        const s = await stat(filePath);
+        return s.mtime;
+    }
+    catch {
+        return null;
+    }
+}
+// Returns the file's birth (creation) time, falling back to mtime when
+// birthtime is unreliable (Linux ext4 without `relatime` reports birthtime as
+// epoch 0 or equal to mtime). On macOS (APFS/HFS+) birthtime is always
+// accurate. The fallback means: on those Linux filesystems a hand-edited file
+// created before today but edited today will still appear as "created today" —
+// a known false-positive. The real guarantee is the index-parity check; this
+// filter is a best-effort "did you add something this session" hint only.
+async function fileBirthtime(filePath) {
+    try {
+        const s = await stat(filePath);
+        // birthtimeMs === 0 signals an unsupported filesystem; fall back to mtime.
+        if (s.birthtimeMs === 0)
+            return s.mtime;
+        return s.birthtime;
+    }
+    catch {
+        return null;
+    }
+}
+async function fileContent(filePath) {
+    try {
+        return await readFile(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+async function listDir(dirPath) {
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isFile() && e.name.endsWith('.md'))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function checkWuNotes(buildRoot, activeWuHandle, sessionStartMs, sessionDate) {
+    // Look in work-units/ and work-units/done/ for the WU file.
+    const candidates = [
+        path.join(buildRoot, 'work-units', `${activeWuHandle}.md`),
+        // Handle numeric prefix patterns (e.g. 112-end-of-session-as-nuflow-workflow.md)
+        ...(await findWuFile(buildRoot, activeWuHandle)),
+    ];
+    for (const candidate of candidates) {
+        const mtime = await fileMtime(candidate);
+        if (!mtime)
+            continue;
+        const touched = mtime.getTime() > sessionStartMs;
+        const content = await fileContent(candidate);
+        const hasTodayHeading = content
+            ? content.includes(sessionDate) && /##\s*(Notes|notes)/.test(content)
+            : false;
+        return { wuNotesTouched: touched, wuNotesHasTodayHeading: hasTodayHeading };
+    }
+    return { wuNotesTouched: false, wuNotesHasTodayHeading: false };
+}
+async function findWuFile(buildRoot, activeWuHandle) {
+    const results = [];
+    for (const subdir of ['work-units', path.join('work-units', 'done')]) {
+        const dirPath = path.join(buildRoot, subdir);
+        try {
+            const entries = await readdir(dirPath);
+            for (const name of entries) {
+                if (name.endsWith('.md') && name.includes(activeWuHandle.replace('wu-', ''))) {
+                    results.push(path.join(dirPath, name));
+                }
+            }
+        }
+        catch {
+            // Directory may not exist.
+        }
+    }
+    return results;
+}
+async function checkRegisterParity(buildRoot, registerDir, sessionDate, filePattern) {
+    const dirPath = path.join(buildRoot, registerDir);
+    const indexPath = path.join(dirPath, '_index.md');
+    // Files created today (by birthtime — see fileBirthtime for platform notes).
+    const allFiles = await listDir(dirPath);
+    const todayFiles = [];
+    for (const name of allFiles) {
+        if (!filePattern.test(name))
+            continue;
+        const btime = await fileBirthtime(path.join(dirPath, name));
+        if (btime && btime.toISOString().startsWith(sessionDate)) {
+            todayFiles.push(name);
+        }
+    }
+    // Index rows mentioning today.
+    const indexContent = await fileContent(indexPath);
+    const todayIndexRows = [];
+    if (indexContent) {
+        const lines = indexContent.split('\n');
+        for (const line of lines) {
+            if (line.includes(sessionDate)) {
+                todayIndexRows.push(line.trim());
+            }
+        }
+    }
+    // Bijection check: every today file should appear in the index,
+    // and every today-dated index row should have a corresponding file.
+    const filesWithoutRow = [];
+    for (const file of todayFiles) {
+        const baseName = file.replace('.md', '');
+        const mentioned = todayIndexRows.some((row) => row.includes(baseName) || row.includes(file));
+        if (!mentioned) {
+            filesWithoutRow.push(file);
+        }
+    }
+    const rowsWithoutFile = [];
+    for (const row of todayIndexRows) {
+        // Try to find any today-file mentioned in the row.
+        const mentioned = todayFiles.some((file) => row.includes(file.replace('.md', '')) || row.includes(file));
+        if (!mentioned) {
+            rowsWithoutFile.push(row);
+        }
+    }
+    return { filesWithoutRow, rowsWithoutFile };
+}
+async function checkRisksParity(buildRoot) {
+    // Risks are stored as index entries only (no individual files), so parity
+    // is trivially satisfied — there are no "files" to check against.
+    // This check is present for forward-compat when risks get individual files.
+    return { filesWithoutRow: [], rowsWithoutFile: [] };
+}
+async function checkWorkUnitsIndex(buildRoot) {
+    const indexPath = path.join(buildRoot, 'work-units', '_index.md');
+    const content = await fileContent(indexPath);
+    if (!content)
+        return true; // If no index, no rows to check.
+    // Design A (WU 112 fix-pass): operate on table rows only; check status cell only.
+    // Row shape after split on '|': ['', id, title, status, dependsOn, ...]
+    // (leading empty string from the leading pipe character)
+    const lines = content.split('\n');
+    for (const line of lines) {
+        // Only consider actual table rows (lines starting with '|' after optional whitespace).
+        if (!/^\s*\|/.test(line))
+            continue;
+        const cells = line.split('|');
+        // Need at least 5 cells: [empty, id, title, status, dependsOn, ...] (leading/trailing empty from outer pipes)
+        if (cells.length < 5)
+            continue;
+        // Status is the 3rd content cell (index 3 in the split array, after the leading empty).
+        const statusCell = cells[3];
+        if (!statusCell)
+            continue;
+        // A row is completed only if its STATUS cell contains ✅.
+        // This avoids false-positives from Depends-on column mentions, legend lines, and phase headers.
+        if (!statusCell.includes('✅'))
+            continue;
+        // Completed row: extract the first markdown link from the TITLE cell (index 2).
+        const titleCell = cells[2];
+        if (!titleCell)
+            continue;
+        const linkMatch = titleCell.match(/\[.*?\]\((.*?)\)/);
+        if (!linkMatch) {
+            // No link in the title cell — legacy/sibling WU (lives in a sibling repo, never had a done/ file here).
+            // Skip: not verifiable by this gate (presence-only, D130).
+            continue;
+        }
+        const linkTarget = linkMatch[1];
+        // A completed row linking to a top-level NNN-...md (not done/) is drift: the WU was never moved.
+        if (!linkTarget.includes('done/')) {
+            return false;
+        }
+        // A completed row whose done/ file is missing is also drift.
+        const filePath = path.join(buildRoot, 'work-units', linkTarget);
+        const mtime = await fileMtime(filePath);
+        if (!mtime) {
+            return false;
+        }
+    }
+    return true;
+}
+async function checkStateMd(buildRoot, sessionStartMs, sessionDate) {
+    const stateMdPath = path.join(buildRoot, 'STATE.md');
+    const mtime = await fileMtime(stateMdPath);
+    const stateMdTouched = mtime ? mtime.getTime() > sessionStartMs : false;
+    const content = await fileContent(stateMdPath);
+    let stateMdLastUpdated = '';
+    let stateMdLastSessionResolves = false;
+    if (content) {
+        // Fix 1 (WU 112 fix-pass): accept all three "Last updated" shapes:
+        //   table-row: | Last updated | 2026-05-31 (**Session 115 — ...**) ... |
+        //   bold-colon: **Last updated:** 2026-05-31
+        //   plain-colon: Last updated: 2026-05-31
+        // Anchor on the label text (colon optional), grab the FIRST YYYY-MM-DD on the same logical line.
+        // The [^\n]*? keeps the match within the label's own row.
+        const updatedMatch = content.match(/Last updated[^\n]*?(\d{4}-\d{2}-\d{2})/i);
+        if (updatedMatch) {
+            stateMdLastUpdated = updatedMatch[1];
+        }
+        // Fix 2 (WU 112 fix-pass): the real "Last session" row is narrative prose with NO markdown link.
+        // Real format: | Last session | Session 112 — ...prose... |
+        // Assert only that a non-empty "Last session" row/line is present (D130: do not overclaim).
+        // Link-resolution is dropped because the real format carries no link to resolve.
+        // Session-log existence on disk is independently verified by Step 7 (checkSessionLog).
+        const sessionLineMatch = content.match(/Last session[^\n]*/i);
+        if (sessionLineMatch) {
+            // The row is non-empty if it contains more than just the label itself.
+            const rowText = sessionLineMatch[0].replace(/Last session/i, '').replace(/[|:\s]/g, '');
+            stateMdLastSessionResolves = rowText.length > 0;
+        }
+    }
+    return { stateMdTouched, stateMdLastUpdated, stateMdLastSessionResolves };
+}
+async function checkSessionLog(buildRoot, sessionDate) {
+    const sessionsDir = path.join(buildRoot, 'sessions');
+    const allSessionFiles = await listDir(sessionsDir);
+    // Look for sessions/<sessionDate>-*.md
+    const sessionLogFile = allSessionFiles.find((name) => name.startsWith(sessionDate + '-'));
+    const sessionLogExists = sessionLogFile !== undefined;
+    let sessionLogIndexed = false;
+    if (sessionLogExists && sessionLogFile) {
+        const indexPath = path.join(sessionsDir, '_index.md');
+        const indexContent = await fileContent(indexPath);
+        if (indexContent) {
+            sessionLogIndexed =
+                indexContent.includes(sessionLogFile) || indexContent.includes(sessionDate);
+        }
+    }
+    return { sessionLogExists, sessionLogIndexed };
+}
+// ---------------------------------------------------------------------------
+// Report formatting
+// ---------------------------------------------------------------------------
+function formatReport(payload, today, resumedFrom, dryRun) {
+    const lines = [];
+    lines.push('');
+    lines.push('══════════════════════════════════════════════════════════════════════');
+    lines.push(`  end-of-session: ${today}${dryRun ? ' (dry run)' : ''}`);
+    if (resumedFrom) {
+        lines.push(`  resumed from step: ${resumedFrom}`);
+    }
+    lines.push('══════════════════════════════════════════════════════════════════════');
+    lines.push('');
+    const STEP_LABELS = {
+        update_active_wu_notes: 'Step 1 — WU notes updated',
+        capture_decisions: 'Step 2 — decisions captured',
+        capture_open_questions: 'Step 3 — open questions captured',
+        capture_risks: 'Step 4 — risks captured',
+        update_work_units_index: 'Step 5 — work-units index updated',
+        update_state_md: 'Step 6 — STATE.md updated',
+        write_session_log: 'Step 7 — session log written',
+        confirm_no_loss: 'Step 8 — confirm-no-loss gate',
+        report: 'Step 9 — report',
+    };
+    for (const [stepId, state] of Object.entries(payload.steps)) {
+        const label = STEP_LABELS[stepId] ?? stepId;
+        const icon = state.status === 'passed' ? '  [PASS]' : state.status === 'failed' ? '  [FAIL]' : '  [....] ';
+        lines.push(`${icon} ${label}`);
+        if (state.status === 'failed' && state.evidence) {
+            // Indent the failure detail.
+            for (const evidenceLine of state.evidence.split('\n')) {
+                lines.push(`         ${evidenceLine}`);
+            }
+        }
+    }
+    lines.push('');
+    if (payload.completed) {
+        lines.push('  GATE: PASSED — session marked complete.');
+        lines.push('');
+        lines.push('  NOTE: this gate verifies presence and structure only. It does NOT');
+        lines.push('  assert that STATE.md is factually correct or that session-log');
+        lines.push('  narrative is true. That judgement stays with the AI and operator.');
+    }
+    else {
+        lines.push(`  GATE: BLOCKED — ${payload.failingChecks.length} check(s) failed:`);
+        lines.push('');
+        for (const check of payload.failingChecks) {
+            for (const checkLine of check.split('\n')) {
+                lines.push(`  ${checkLine}`);
+            }
+        }
+        lines.push('');
+        lines.push('  Fix the failing checks (make the artefacts present and well-formed),');
+        lines.push('  then re-run `nuos-catalogue end-of-session` to continue / resume.');
+    }
+    lines.push('══════════════════════════════════════════════════════════════════════');
+    lines.push('');
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveActiveWuHandle(store) {
+    // Try to read the active WU from the wu-active file (WU 136 mechanism).
+    // The wu-active command writes a marker file; we can't read it here without
+    // knowing the project root. Fall back to the most-recently-modified WU record.
+    const wuRecords = store.list().filter((r) => r.register === 'work_unit');
+    if (wuRecords.length === 0)
+        return null;
+    // Return the most recently modified in_progress WU, or any in_progress.
+    const inProgress = wuRecords.filter((r) => (r.status ?? '').includes('in_progress'));
+    if (inProgress.length > 0) {
+        return inProgress.sort((a, b) => (b.fileModifiedAt ?? '').localeCompare(a.fileModifiedAt ?? ''))[0].handle;
+    }
+    return null;
+}

package/dist/commands/init.d.ts

@@ -59,8 +59,28 @@ export interface InitResult {
     output: string;
     exitCode: number;
 }
+export declare const PROTOCOL_FILES: readonly ["start-of-session.md", "end-of-session.md", "wu-new.md", "persona-new.md", "plan-orientation.md", "plan-architecture.md", "plan-uiux.md", "plan-maps.md", "plan-initial-wu.md", "plan-review.md", "build-wu.md"];
+/**
+ * The three AI coding tools the catalogue supports. Each tool reads
+ * project-level commands from a different path with a slightly different
+ * frontmatter shape. The body itself is identical across all three.
+ *
+ * The bundled `templates/protocols/<slug>.md` files are raw bodies (no
+ * frontmatter); `renderForTool` adds tool-appropriate frontmatter.
+ */
+type ToolSlug = 'claude' | 'opencode' | 'codex';
+interface ToolTarget {
+    /** Tool's display name (for logs). */
+    label: string;
+    /** Path relative to project root, given a protocol slug. */
+    destPath: (slug: string) => string;
+    /** Render the file content given the slug and the raw body. */
+    render: (slug: string, body: string) => string;
+}
+export declare const TOOLS: Record<ToolSlug, ToolTarget>;
 export declare function cmdInit(prompt: Prompt, options?: InitOptions): Promise<InitResult>;
 export interface InstallProtocolsOptions {
     cwd?: string;
 }
 export declare function cmdInstallProtocols(prompt: Prompt, options?: InstallProtocolsOptions): Promise<InitResult>;
+export {};

package/dist/commands/init.js

@@ -33,7 +33,7 @@ import { fileURLToPath } from 'node:url';
 const __filename = fileURLToPath(import.meta.url);
 const PACKAGE_ROOT = path.resolve(path.dirname(__filename), '..', '..');
 const TEMPLATES_ROOT = path.resolve(PACKAGE_ROOT, 'templates');
-const PROTOCOL_FILES = [
+export const PROTOCOL_FILES = [
     'start-of-session.md',
     'end-of-session.md',
     'wu-new.md',
@@ -64,7 +64,7 @@ const PROTOCOL_DESCRIPTIONS = {
     'plan-review': 'End-to-end planning review — surfaces gaps, inconsistencies, and optimisations before building starts',
     'build-wu': 'Orchestrate a swarm of agents to build one work unit end-to-end',
 };
-const TOOLS = {
+export const TOOLS = {
     claude: {
         label: 'Claude Code',
         destPath: (slug) => path.join('.claude', 'commands', `${slug}.md`),

package/dist/runtime/mis-adapter.js

@@ -25,7 +25,7 @@
  *   (`active → resolved by D-NNN`) and append a history entry to the
  *   resolving decision.
  */
-import { writeFile, mkdir } from 'node:fs/promises';
+import { writeFile, mkdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { replaceStatusLine, insertStatusLine, appendChangeLog, } from './markdown-edit.js';
 import { tickAcceptanceCriterion, parseAcceptanceCriteria } from './ac-parse.js';
@@ -78,6 +78,12 @@ export function createBuildCatalogueMisAdapter(config) {
                 case 'open_question.resolve':
                     await commitResolveQuestion(store, catalogueRoot, intent);
                     break;
+                case 'end_of_session.step_verified':
+                case 'end_of_session.completed':
+                    // D130/D129: write ONLY the session.end:<date> step-state record in
+                    // the store. No catalogue prose is written; no markdown is rendered.
+                    commitEndOfSessionRecord(store, intent);
+                    break;
                 default:
                     throw new Error(`BuildCatalogueMisAdapter: intent type ${intent.type} is not handled by the build-catalogue pack`);
             }
@@ -98,7 +104,12 @@ function isCreateIntent(intentType) {
     return (intentType === 'work_unit.create' ||
         intentType === 'decision.create' ||
         intentType === 'open_question.create' ||
-        intentType === 'persona.create');
+        intentType === 'persona.create' ||
+        // end_of_session intents create/update the session.end:<date> record;
+        // the subject is not a catalogue artefact in the store, so skip the
+        // existence check.
+        intentType === 'end_of_session.step_verified' ||
+        intentType === 'end_of_session.completed');
 }
 // ---------------------------------------------------------------------------
 // Per-intent commit handlers
@@ -199,10 +210,14 @@ async function commitAdvanceStatus(store, catalogueRoot, intent) {
     }
     // Map workflow status names to user-facing markdown status text.
     const statusEmoji = mapStatusToEmojiText(payload.toStatus);
-    const replaced = replaceStatusLine(record.rawMarkdown, statusEmoji);
+    // D129: read the current on-disk file as the edit base so that hand-edits
+    // made after the last CLI write are preserved, not overwritten by the stale
+    // store snapshot in record.rawMarkdown.
+    const diskBase = await readDiskBase(catalogueRoot, record);
+    const replaced = replaceStatusLine(diskBase, statusEmoji);
     let updatedMarkdown = replaced.replaced
         ? replaced.updated
-        : insertStatusLine(record.rawMarkdown, statusEmoji);
+        : insertStatusLine(diskBase, statusEmoji);
     updatedMarkdown = appendChangeLog(updatedMarkdown, {
         isoTimestamp: new Date().toISOString(),
         summary: `Status advanced ${payload.fromStatus} → ${payload.toStatus}.`,
@@ -219,14 +234,18 @@ async function commitTickAC(store, catalogueRoot, intent) {
     if (!record) {
         throw new Error(`commitTickAC: no record for ${payload.targetHandle}`);
     }
+    // D129: read the current on-disk file as the edit base so that hand-edits
+    // made after the last CLI write are preserved, not overwritten by the stale
+    // store snapshot in record.rawMarkdown.
+    const diskBase = await readDiskBase(catalogueRoot, record);
     // Try to flip the AC line in the markdown. If parsing succeeds we get
     // the structural tick; otherwise we fall back to the audit-log-only
     // approach (older/atypical AC shapes the parser doesn't recognise).
-    let workingMarkdown = record.rawMarkdown;
+    let workingMarkdown = diskBase;
     let acText = payload.criterionText;
     let structuralTick = false;
     try {
-        const acs = parseAcceptanceCriteria(record.rawMarkdown);
+        const acs = parseAcceptanceCriteria(diskBase);
         if (acs.length === 0) {
             // No AC section recognised — audit-log-only.
         }
@@ -235,7 +254,7 @@ async function commitTickAC(store, catalogueRoot, intent) {
         }
         else {
             acText = acText ?? acs[payload.criterionIndex].text;
-            workingMarkdown = tickAcceptanceCriterion(record.rawMarkdown, payload.criterionIndex);
+            workingMarkdown = tickAcceptanceCriterion(diskBase, payload.criterionIndex);
             structuralTick = true;
         }
     }
@@ -270,12 +289,15 @@ async function commitSupersede(store, catalogueRoot, intent) {
     if (!superseding) {
         throw new Error(`commitSupersede: no record for superseding ${payload.supersedingHandle}`);
     }
+    // D129: read current on-disk files as the edit bases.
+    const targetDiskBase = await readDiskBase(catalogueRoot, target);
+    const supersedingDiskBase = await readDiskBase(catalogueRoot, superseding);
     // Target: status accepted → superseded by D-NNN
     const targetStatus = `superseded by ${payload.supersedingHandle}`;
-    const targetReplaced = replaceStatusLine(target.rawMarkdown, targetStatus);
+    const targetReplaced = replaceStatusLine(targetDiskBase, targetStatus);
     let targetMarkdown = targetReplaced.replaced
         ? targetReplaced.updated
-        : insertStatusLine(target.rawMarkdown, targetStatus);
+        : insertStatusLine(targetDiskBase, targetStatus);
     targetMarkdown = appendChangeLog(targetMarkdown, {
         isoTimestamp: new Date().toISOString(),
         summary: `Superseded by ${payload.supersedingHandle}.`,
@@ -284,7 +306,7 @@ async function commitSupersede(store, catalogueRoot, intent) {
     });
     await persist(store, catalogueRoot, target, targetMarkdown, { status: targetStatus });
     // Superseding: append a Build catalogue history entry naming what it supersedes.
-    const supersedingMarkdown = appendChangeLog(superseding.rawMarkdown, {
+    const supersedingMarkdown = appendChangeLog(supersedingDiskBase, {
         isoTimestamp: new Date().toISOString(),
         summary: `Supersedes ${payload.targetHandle}.`,
         details: payload.reason,
@@ -302,11 +324,14 @@ async function commitResolveQuestion(store, catalogueRoot, intent) {
     if (!decision) {
         throw new Error(`commitResolveQuestion: no record for resolving decision ${payload.resolvingDecisionHandle}`);
     }
+    // D129: read current on-disk files as the edit bases.
+    const questionDiskBase = await readDiskBase(catalogueRoot, question);
+    const decisionDiskBase = await readDiskBase(catalogueRoot, decision);
     const questionStatus = `resolved by ${payload.resolvingDecisionHandle}`;
-    const questionReplaced = replaceStatusLine(question.rawMarkdown, questionStatus);
+    const questionReplaced = replaceStatusLine(questionDiskBase, questionStatus);
     let questionMarkdown = questionReplaced.replaced
         ? questionReplaced.updated
-        : insertStatusLine(question.rawMarkdown, questionStatus);
+        : insertStatusLine(questionDiskBase, questionStatus);
     questionMarkdown = appendChangeLog(questionMarkdown, {
         isoTimestamp: new Date().toISOString(),
         summary: `Resolved by ${payload.resolvingDecisionHandle}.`,
@@ -314,7 +339,7 @@ async function commitResolveQuestion(store, catalogueRoot, intent) {
         reference: `intent ${intent.intentId}`,
     });
     await persist(store, catalogueRoot, question, questionMarkdown, { status: questionStatus });
-    const decisionMarkdown = appendChangeLog(decision.rawMarkdown, {
+    const decisionMarkdown = appendChangeLog(decisionDiskBase, {
         isoTimestamp: new Date().toISOString(),
         summary: `Resolves ${payload.targetHandle}.`,
         details: payload.reason,
@@ -325,6 +350,35 @@ async function commitResolveQuestion(store, catalogueRoot, intent) {
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+/**
+ * Read the current on-disk content of `record`'s source file as the edit
+ * base for write commands (D129: disk is canonical in Mode 1).
+ *
+ * Falls back to `record.rawMarkdown` only when the file has never been
+ * written to disk (i.e. `fileExistsMustBeTrue` is false — used for the
+ * create path where the file is written in the same operation). For all
+ * mutation paths (tick, advance, supersede, resolve) the file must already
+ * exist on disk; if it is missing the command refuses with a clear message
+ * rather than silently clobbering with a stale store snapshot.
+ */
+async function readDiskBase(catalogueRoot, record, options = { mustExist: true }) {
+    const sourceAbsolute = path.join(catalogueRoot, record.sourcePath);
+    try {
+        return await readFile(sourceAbsolute, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            if (options.mustExist) {
+                throw new Error(`Store-coherence error: the on-disk file for ${record.handle} ` +
+                    `(${record.sourcePath}) no longer exists. ` +
+                    `Run 'nuos-catalogue migrate' to re-sync the workflow store before writing.`);
+            }
+            // File not yet on disk (create path) — fall back to the store snapshot.
+            return record.rawMarkdown;
+        }
+        throw err;
+    }
+}
 async function persist(store, catalogueRoot, record, newRawMarkdown, fieldUpdates = {}) {
     const sourceAbsolute = path.join(catalogueRoot, record.sourcePath);
     await writeFile(sourceAbsolute, newRawMarkdown, 'utf8');
@@ -338,6 +392,63 @@ async function persist(store, catalogueRoot, record, newRawMarkdown, fieldUpdate
     };
     store.put(updatedRecord);
 }
+/**
+ * Persist the `session.end:<date>` step-state record in the workflow store.
+ *
+ * D130/D129: this function writes NO catalogue prose and renders NO markdown.
+ * Its only write is this record in the JSON workflow store — the workflow's
+ * own bookkeeping. The record is never rendered to a catalogue markdown file.
+ *
+ * The store key is `session.end:<sessionDate>` (the intent's subject id).
+ * The rawMarkdown field carries the step-state JSON (not markdown prose)
+ * so the existing MigratedRecord shape can be reused without schema changes.
+ */
+function commitEndOfSessionRecord(store, intent) {
+    const payload = intent.payload;
+    const sessionDate = payload.sessionDate;
+    const handle = `session.end:${sessionDate}`;
+    const now = new Date().toISOString();
+    // Use the existing record if it exists (preserve startedAt).
+    const existing = store.get(handle);
+    let startedAt = now;
+    if (existing) {
+        try {
+            const parsed = JSON.parse(existing.rawMarkdown);
+            startedAt = parsed.startedAt ?? now;
+        }
+        catch {
+            // If the existing record's JSON is malformed, reset.
+        }
+    }
+    const stepStateWithStarted = JSON.stringify({
+        handle,
+        sessionDate,
+        activeWuHandle: payload.activeWuHandle,
+        steps: payload.steps,
+        completed: payload.completed,
+        failingChecks: payload.failingChecks,
+        startedAt,
+        ...(payload.completed ? { completedAt: now } : {}),
+    }, null, 2);
+    // Store as MigratedRecord with register='session' (cast needed because
+    // Register type doesn't include 'session' — this record is the workflow's
+    // own bookkeeping, not a catalogue artefact, and is never scanned by
+    // the migration runner).
+    const record = {
+        handle,
+        number: 0,
+        register: 'session',
+        title: `End-of-session: ${sessionDate}`,
+        status: payload.completed ? 'completed' : 'in_progress',
+        slug: `end-${sessionDate}`,
+        sourcePath: `.nuos-catalogue/session.end.${sessionDate}.json`,
+        rawMarkdown: stepStateWithStarted,
+        fileModifiedAt: now,
+        migratedAt: existing?.migratedAt ?? now,
+        migratedFrom: 'markdown',
+    };
+    store.put(record);
+}
 function mapStatusToEmojiText(workflowStatus) {
     // The build-catalogue pack uses internal status enum strings
     // (proposed/ready/in_progress/in_review/completed/superseded/...).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.32.0",
+  "version": "0.33.1",
   "description": "NuOS build-catalogue tooling: semantic search (WU 110) + migration runner that lifts markdown artefacts into JSON-backed workflow records (WU 111, Phase G).",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
     "prepublishOnly": "npm run build",
     "verify-storage": "tsx scripts/verify-persistence.ts",
-    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts tests/init.test.ts tests/wu-111-soak-findings.test.ts tests/plan.test.ts tests/mode.test.ts tests/render.test.ts tests/swarm.test.ts tests/setup-progress-bar.test.ts tests/setup-ollama-pull.test.ts tests/setup-run-llm-setup.test.ts tests/wu-active.test.ts tests/install-claude-hooks.test.ts",
+    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts tests/init.test.ts tests/wu-111-soak-findings.test.ts tests/plan.test.ts tests/mode.test.ts tests/render.test.ts tests/swarm.test.ts tests/setup-progress-bar.test.ts tests/setup-ollama-pull.test.ts tests/setup-run-llm-setup.test.ts tests/wu-active.test.ts tests/install-claude-hooks.test.ts tests/protocols-in-sync.test.ts tests/end-of-session.test.ts",
     "typecheck": "tsc --noEmit",
     "index": "tsx src/cli.ts index",
     "search": "tsx src/cli.ts search"

package/scripts/hooks/pre-commit

@@ -68,8 +68,7 @@ check_index_drift() {
   ids_in_tree=$(cd "$REPO_ROOT/$dir" && {
     find . -maxdepth 2 -type f -name "*.md" \
       -not -name "_index.md" \
-      -not -name "*-template.md" \
-      -not -name "*-template-*.md" 2>/dev/null \
+      -not -name "*-template.md" 2>/dev/null \
       | sed -nE "$file_regex" \
       | sort -u
   })

package/scripts/install-hooks.sh

@@ -15,6 +15,64 @@
 
 set -euo pipefail
 
+# ---- Ensure nuos-catalogue CLI is installed --------------------------------
+#
+# The CLI is a global npm tool with no presence in any package.json — it
+# disappears silently when global packages are cleared. Install it here so
+# the build memory system is always ready after a post-clone setup run.
+
+if ! command -v nuos-catalogue &>/dev/null; then
+  echo "▶ nuos-catalogue not found — installing @nusoft/nuos-build-catalogue globally..."
+  npm install -g @nusoft/nuos-build-catalogue
+  echo "✓ nuos-catalogue installed"
+else
+  echo "✓ nuos-catalogue present ($(nuos-catalogue --version 2>/dev/null | head -1 || echo 'version unknown'))"
+fi
+echo
+
+# ---- Patch ~/.claude/settings.json with the Playwright singleton hook ------
+#
+# Each VS Code Claude Code window spawns its own playwright-mcp process. They
+# all share one Chrome profile, and Chrome's singleton lock means only the first
+# one to open Chrome succeeds — every later session gets "browser already in use".
+# This PreToolUse hook kills the locked Chrome before each browser_navigate so
+# the current session always gets a clean launch.
+
+CLAUDE_SETTINGS="$HOME/.claude/settings.json"
+PLAYWRIGHT_HOOK_MARKER="mcp__plugin_playwright_playwright__browser_navigate"
+
+if [[ -f "$CLAUDE_SETTINGS" ]] && ! grep -q "$PLAYWRIGHT_HOOK_MARKER" "$CLAUDE_SETTINGS"; then
+  echo "▶ Patching ~/.claude/settings.json with Playwright singleton hook..."
+  node -e "
+    const fs = require('fs');
+    const path = '$CLAUDE_SETTINGS';
+    const settings = JSON.parse(fs.readFileSync(path, 'utf8'));
+    settings.hooks = settings.hooks || {};
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse || [];
+    const alreadySet = settings.hooks.PreToolUse.some(h => h.matcher === '$PLAYWRIGHT_HOOK_MARKER');
+    if (!alreadySet) {
+      settings.hooks.PreToolUse.push({
+        matcher: '$PLAYWRIGHT_HOOK_MARKER',
+        hooks: [{
+          type: 'command',
+          command: \"pkill -f 'user-data-dir.*mcp-chrome' 2>/dev/null; sleep 0.5; exit 0\",
+          timeout: 5,
+          statusMessage: 'Clearing stale Playwright browser...'
+        }]
+      });
+      fs.writeFileSync(path, JSON.stringify(settings, null, 2) + '\n');
+      console.log('✓ Playwright singleton hook added');
+    } else {
+      console.log('✓ Playwright singleton hook already present');
+    }
+  "
+elif [[ ! -f "$CLAUDE_SETTINGS" ]]; then
+  echo "⚠ ~/.claude/settings.json not found — skipping Playwright hook patch (Claude Code not installed?)"
+else
+  echo "✓ Playwright singleton hook already present in ~/.claude/settings.json"
+fi
+echo
+
 REPO_ROOT="$(git rev-parse --show-toplevel)"
 SOURCE="$REPO_ROOT/scripts/hooks"
 TARGET="$REPO_ROOT/.git/hooks"

package/templates/protocols/build-wu.md

@@ -257,6 +257,12 @@ Tell the operator in plain English:
 
 ---
 
+## Cost guidance
+
+A typical full-feature swarm — architect (Opus, ~30 min) + coder (Sonnet, ~1 hr) + tester (Sonnet, ~30 min) + reviewer (Sonnet, ~15 min) — consumes substantially less of the operator's coding-tool plan budget than running the same work as a continuous Opus conversation. The 80/20 split — heavy reasoning for design and debugging only, lighter models for implementation and verification — is the lever. If a single work unit's swarm is consuming an unusual share of the day's plan budget, surface that to the operator before continuing; the WU is probably bigger than scoped.
+
+---
+
 ## Drift discipline
 
 Every decision made by any agent during the swarm MUST land in the catalogue before the swarm closes — either as a decision file (if it's a project-wide commitment), in the work unit's notes (if scoped to this work), in the swarm audit entry (if it's about how the swarm ran). Decisions made inside agent conversations that don't reach the catalogue are drift.