@latysh-development/monolith 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/brief/reconcile.js

@@ -62,6 +62,7 @@ export function reconcile(ev, result) {
     }
     // 2. Git-derived evidence.
     const untrackedWork = [];
+    const independentKnowledge = [];
     let mentionedWork = [];
     if (ev.git.status === 'unavailable') {
         findings.push({ kind: 'unknown', code: 'GIT_UNAVAILABLE', summary: reasonMessage(result, 'GIT_UNAVAILABLE'), evidence: [] });
@@ -77,8 +78,20 @@ export function reconcile(ev, result) {
         const activity = ev.git.commitsSince.filter((c) => c.files.some((f) => !ev.stateFiles.has(f)));
         const byId = new Map();
         const unattributed = [];
+        const knowledgeBy = new Map();
         for (const c of activity) {
             const ids = extractWorkItemIds(c.subject);
+            const k = ids.length === 0 ? ev.knowledge?.attributed.get(c.sha) : undefined;
+            if (k !== undefined) {
+                const key = k.ideaIds.join(', ');
+                const entry = knowledgeBy.get(key) ?? { paths: [], lines: [] };
+                entry.lines.push(commitLine(c));
+                for (const p of k.paths)
+                    if (!entry.paths.includes(p))
+                        entry.paths.push(p);
+                knowledgeBy.set(key, entry);
+                continue;
+            }
             if (ids.length === 0)
                 unattributed.push(c);
             for (const id of ids)
@@ -117,11 +130,21 @@ export function reconcile(ev, result) {
                 kind: 'suspected',
                 code: 'UNATTRIBUTED_ACTIVITY',
                 summary: `${unattributed.length} commit(s) after the last state update change project files without naming a work item; whether the state documents cover them cannot be determined.`,
-                evidence: unattributed.slice(0, MAX_COMMITS_PER_ITEM).map(commitLine),
+                evidence: unattributed.slice(0, MAX_COMMITS_PER_ITEM).map((c) => {
+                    const why = ev.knowledge?.rejected.get(c.sha);
+                    return why === undefined ? commitLine(c) : `${commitLine(c)} — names an idea but is not attributed: ${why.reason}`;
+                }),
             });
             actions.push(`Review the ${unattributed.length} commit(s) that name no work item and decide whether the recorded state covers them.`);
         }
-        if (activity.length > 0 && ev.activeStory.kind === 'none') {
+        for (const [ids, entry] of knowledgeBy) {
+            independentKnowledge.push({ ideaIds: ids.split(', '), paths: entry.paths, commits: entry.lines });
+        }
+        if (knowledgeBy.size > 0) {
+            limitations.push('Commits attributed to independent knowledge are explained by a registered idea and its declared document paths; this is attribution, not approval or review, and says nothing about any work item or the active story.');
+        }
+        const explainedByKnowledge = [...knowledgeBy.values()].reduce((n, e) => n + e.lines.length, 0);
+        if (activity.length - explainedByKnowledge > 0 && ev.activeStory.kind === 'none') {
             findings.push({
                 kind: 'suspected',
                 code: 'ACTIVITY_WITHOUT_ACTIVE_STORY',
@@ -131,6 +154,11 @@ export function reconcile(ev, result) {
             review('active.md', 'no active story recorded while git shows later activity');
             actions.push('Review the active story: confirm whether any work is current. No active story does not mean the project is complete.');
         }
+        if (ev.git.shallow === true) {
+            findings.push({ kind: 'unknown', code: 'GIT_HISTORY_SHALLOW', summary: reasonMessage(result, 'GIT_HISTORY_SHALLOW'), evidence: [] });
+            limitations.push('The repository is a shallow clone; history before its boundary is absent, so the report cannot show what happened earlier.');
+            actions.push('Deepen the clone (git fetch --unshallow) or run this from a full checkout, then re-run.');
+        }
         if (ev.git.truncated) {
             findings.push({ kind: 'unknown', code: 'GIT_HISTORY_TRUNCATED', summary: reasonMessage(result, 'GIT_HISTORY_TRUNCATED'), evidence: [] });
             limitations.push('Git history after the last state update was cut at the read limit; older commits are not examined.');
@@ -156,6 +184,7 @@ export function reconcile(ev, result) {
         findings,
         untrackedWork,
         mentionedWork,
+        independentKnowledge,
         documents,
         limitations,
         actions,
@@ -219,6 +248,17 @@ export function renderReconciliation(report, maxChars) {
         }
         sections.push(bullets(title, lines));
     }
+    if (report.independentKnowledge.length > 0) {
+        const lines = [];
+        for (const k of report.independentKnowledge.slice(0, MAX_LISTED_ITEMS)) {
+            lines.push(`- ${san(k.ideaIds.join(', '))} (${k.commits.length} commit(s))`);
+            const shownPaths = k.paths.slice(0, MAX_LISTED_ITEMS).map(san).join(', ');
+            lines.push(`    declared paths: ${shownPaths}${k.paths.length > MAX_LISTED_ITEMS ? ` and ${k.paths.length - MAX_LISTED_ITEMS} more` : ''}`);
+            for (const c of k.commits.slice(0, MAX_COMMITS_PER_ITEM))
+                lines.push(`    ${san(c)}`);
+        }
+        sections.push(bullets('Attributed to registered independent knowledge (no work item, active story unaffected):', lines));
+    }
     if (report.documents.length > 0) {
         const lines = [];
         for (const d of report.documents)

package/dist/brief/story.d.ts

@@ -1,18 +1,10 @@
-/**
- * Extracts the "## Current Story" section from
- * `.monolith/memory/working/active.md` — confirmed structure only, no
- * heuristic Markdown interpretation (section 5 of the brief contract).
- *
- * Only two things are recognized: a line that is exactly a level-1..6
- * heading, and a line that is exactly `---` (used in active.md as a visual
- * section separator). The "Current Story" section's content is everything
- * between its own heading line and the next such boundary.
- */
 export interface StoryExtraction {
     hasCurrentStorySection: boolean;
     excerpt: string | null;
     /** 1-indexed inclusive line range, e.g. "24-29". */
     lineRange: string | null;
+    /** More than one real "## Current Story" heading; no section is returned. */
+    ambiguous?: boolean;
 }
 export declare function extractCurrentStory(content: string): StoryExtraction;
 //# sourceMappingURL=story.d.ts.map

package/dist/brief/story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../src/brief/story.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,WAAW,eAAe;IAC9B,sBAAsB,EAAE,OAAO,CAAC;IAChC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oDAAoD;IACpD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAoDpE"}
+{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../src/brief/story.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,eAAe;IAC9B,sBAAsB,EAAE,OAAO,CAAC;IAChC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oDAAoD;IACpD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CA0DpE"}

package/dist/brief/story.js

@@ -7,25 +7,39 @@
  * heading, and a line that is exactly `---` (used in active.md as a visual
  * section separator). The "Current Story" section's content is everything
  * between its own heading line and the next such boundary.
+ *
+ * Headings and separators are structural only outside fenced code blocks and
+ * HTML comments (PSC-004): a `## Current Story` shown inside a Markdown
+ * example is not the section. If more than one real heading exists the
+ * section is ambiguous and is NOT read (`ambiguous: true`, no section): no
+ * consumer may guess which one is the project's current story.
  */
+import { maskNonContent } from './markdown-context.js';
 const CURRENT_STORY_HEADING_RE = /^##\s+Current Story\s*$/i;
 const HEADING_RE = /^#{1,6}\s+/;
 const RULE_RE = /^-{3,}\s*$/;
 export function extractCurrentStory(content) {
     const lines = content.split('\n');
-    let headingLineIdx = -1;
+    // Same line count as `lines`; fenced / commented text is blank.
+    const structural = maskNonContent(content).split('\n');
+    const headings = [];
     for (let i = 0; i < lines.length; i++) {
-        if (CURRENT_STORY_HEADING_RE.test(lines[i].trim())) {
-            headingLineIdx = i;
-            break;
-        }
+        // The heading line must be untouched by masking: a line carrying (or
+        // opening) an HTML comment is not a heading, so no comment state can leak
+        // from it into the section body.
+        if (CURRENT_STORY_HEADING_RE.test(structural[i].trim()) && structural[i].trim() === lines[i].trim())
+            headings.push(i);
     }
-    if (headingLineIdx === -1) {
+    if (headings.length === 0) {
         return { hasCurrentStorySection: false, excerpt: null, lineRange: null };
     }
+    if (headings.length > 1) {
+        return { hasCurrentStorySection: false, excerpt: null, lineRange: null, ambiguous: true };
+    }
+    const headingLineIdx = headings[0];
     let endIdx = lines.length;
     for (let i = headingLineIdx + 1; i < lines.length; i++) {
-        const trimmed = lines[i].trim();
+        const trimmed = structural[i].trim();
         if (HEADING_RE.test(trimmed) || RULE_RE.test(trimmed)) {
             endIdx = i;
             break;

package/dist/cli/index.js

@@ -73,7 +73,7 @@ Durable usage:
   monolith durable retention --retain-days N [--compact-after N] [--apply]
 
 Idea usage:
-  monolith idea add --title "..." (--description "..." | --description-stdin) [--context "..."]
+  monolith idea add --title "..." (--description "..." | --description-stdin) [--context "..."] [--path <project-relative document file> ...]
   monolith idea list
   monolith idea show <id>
 

package/dist/cli/style.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Semantic terminal colour (CLI-UX-001). Presentation only.
+ *
+ * Colour never carries meaning alone: every status word (PASS, FAIL, FRESH, …)
+ * is printed as text first and merely tinted. ANSI is emitted only to an
+ * interactive terminal; `NO_COLOR` (any non-empty value), `TERM=dumb`, pipes,
+ * redirects and `--json` output stay plain. No dependency, no state.
+ */
+export type Tone = 'good' | 'warn' | 'bad' | 'dim' | 'head';
+/** Status word → tone. Words not listed are never tinted. */
+export declare const STATUS_TONE: Readonly<Record<string, Tone>>;
+export interface TextStream {
+    isTTY?: boolean;
+}
+/** True only for an interactive terminal that has not opted out. */
+export declare function colorEnabled(stream?: TextStream, env?: NodeJS.ProcessEnv): boolean;
+export declare function paint(text: string, tone: Tone, enabled: boolean): string;
+/** Tints a bare status word; unknown words and a disabled style return it unchanged. */
+export declare function statusWord(word: string, enabled: boolean): string;
+/**
+ * Tints status tokens in a block of already-rendered text: the value after
+ * `Label: ` on the given labels, and `[STATUS]` markers at line start. Text is
+ * otherwise untouched, so disabling colour returns the input byte for byte.
+ */
+export declare function tintStatuses(text: string, enabled: boolean, labels?: readonly string[]): string;
+//# sourceMappingURL=style.d.ts.map

package/dist/cli/style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"style.d.ts","sourceRoot":"","sources":["../../src/cli/style.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAU5D,6DAA6D;AAC7D,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CA2BtD,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,MAAM,GAAE,UAA2B,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAK/G;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAExE;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAGjE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,CAOnG"}

package/dist/cli/style.js

@@ -0,0 +1,76 @@
+/**
+ * Semantic terminal colour (CLI-UX-001). Presentation only.
+ *
+ * Colour never carries meaning alone: every status word (PASS, FAIL, FRESH, …)
+ * is printed as text first and merely tinted. ANSI is emitted only to an
+ * interactive terminal; `NO_COLOR` (any non-empty value), `TERM=dumb`, pipes,
+ * redirects and `--json` output stay plain. No dependency, no state.
+ */
+const CODES = {
+    good: '32', // green
+    warn: '33', // yellow
+    bad: '31', // red
+    dim: '90', // grey
+    head: '1;35', // bold purple
+};
+/** Status word → tone. Words not listed are never tinted. */
+export const STATUS_TONE = {
+    PASS: 'good',
+    COMPLETE: 'good',
+    COMPLETED: 'good',
+    FRESH: 'good',
+    READY: 'good',
+    FINALIZED: 'good',
+    ALREADY_FINALIZED: 'good',
+    CONSISTENT: 'good',
+    done: 'good',
+    NOT_VERIFIED: 'warn',
+    UNKNOWN: 'warn',
+    WARNING: 'warn',
+    UPDATE: 'warn',
+    INCOMPLETE: 'warn',
+    pending: 'warn',
+    FAIL: 'bad',
+    CONFLICT: 'bad',
+    conflict: 'bad',
+    STALE: 'bad',
+    INCONSISTENT: 'bad',
+    REFUSED: 'bad',
+    NOT_READY: 'bad',
+    missing: 'bad',
+    unreadable: 'bad',
+    UNCHANGED: 'dim',
+    SKIP: 'dim',
+};
+/** True only for an interactive terminal that has not opted out. */
+export function colorEnabled(stream = process.stdout, env = process.env) {
+    if (stream.isTTY !== true)
+        return false;
+    if ((env.NO_COLOR ?? '') !== '')
+        return false;
+    if (env.TERM === 'dumb')
+        return false;
+    return true;
+}
+export function paint(text, tone, enabled) {
+    return enabled ? `\u001b[${CODES[tone]}m${text}\u001b[0m` : text;
+}
+/** Tints a bare status word; unknown words and a disabled style return it unchanged. */
+export function statusWord(word, enabled) {
+    const tone = STATUS_TONE[word];
+    return tone === undefined ? word : paint(word, tone, enabled);
+}
+/**
+ * Tints status tokens in a block of already-rendered text: the value after
+ * `Label: ` on the given labels, and `[STATUS]` markers at line start. Text is
+ * otherwise untouched, so disabling colour returns the input byte for byte.
+ */
+export function tintStatuses(text, enabled, labels = []) {
+    if (!enabled)
+        return text;
+    let out = text.replace(/^(\s*)\[([A-Za-z_]+)\]/gm, (m, sp, w) => (STATUS_TONE[w] ? `${sp}[${statusWord(w, true)}]` : m));
+    for (const label of labels) {
+        out = out.replace(new RegExp(`^(${label}: )([A-Za-z_]+)`, 'gm'), (_m, pre, w) => `${pre}${statusWord(w, true)}`);
+    }
+    return out;
+}

package/dist/cli/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/cli/ui.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AAWH,kDAAkD;AAClD,qBAAa,aAAc,SAAQ,KAAK;CAAG;AAE3C,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACjC;AAMD,yGAAyG;AACzG,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAqB/D;AAiBD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAuBvE;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAoD1E;AAED,sGAAsG;AACtG,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8C3D"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/cli/ui.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AAYH,kDAAkD;AAClD,qBAAa,aAAc,SAAQ,KAAK;CAAG;AAE3C,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACjC;AAMD,yGAAyG;AACzG,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAqB/D;AA2CD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqBvE;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAuD1E;AAED,sGAAsG;AACtG,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8C3D"}

package/dist/cli/ui.js

@@ -17,6 +17,7 @@ import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { startDashboardServer, loadUiAssets, UiAssetsError } from '../http/index.js';
 import { RootContainmentError, resolveMonolithRoot } from '../root/index.js';
+import { colorEnabled, paint, statusWord } from './style.js';
 import { DEFAULT_DEV_UI_PORT, DEFAULT_UI_PORT, UI_DEV_USAGE, UI_USAGE, parseUiArgs } from './ui-args.js';
 /** Thrown for expected, user-fixable failures. */
 export class UiLaunchError extends Error {
@@ -47,6 +48,31 @@ export function assertMonolithProject(projectRoot) {
         throw new UiLaunchError(`No MONOLITH instance found in ${projectRoot} (expected directory ${rootAbs}). Run 'monolith init' here, or cd into a MONOLITH project.`);
     }
 }
+/**
+ * The launch block (CLI-UX-001). Printed only after the server is actually
+ * listening, so READY is never shown for a failed start (failures throw before
+ * this and are reported on stderr). The first line is the alpha.3 machine-readable
+ * `MONOLITH Mission Control: <url>` (scripts that parse it keep working); the URL
+ * also stands on a line of its own for copying. The CLI does not open a browser
+ * and says so by asking the user to.
+ */
+function announce(log, info) {
+    const on = colorEnabled();
+    for (const line of [
+        // Compatibility (A4-CLI-02): the first line stays the machine-readable `<title>: <url>` that alpha.3 scripts parse.
+        `${paint(info.title, 'head', on)}: ${info.url}`,
+        `Status: ${statusWord('READY', on)}`,
+        '',
+        'Open in your browser:',
+        `  ${info.url}`,
+        '',
+        `Project: ${info.projectRoot}`,
+        info.note,
+        'Press Ctrl+C to stop.',
+    ]) {
+        log(line);
+    }
+}
 async function listen(projectRoot, port, assets) {
     try {
         return await startDashboardServer({ projectRoot, port, assets });
@@ -77,9 +103,7 @@ export async function launchUi(opts) {
         throw err;
     }
     const server = await listen(projectRoot, opts.port, assets);
-    log(`MONOLITH Mission Control: ${server.url}`);
-    log(`Project: ${projectRoot}`);
-    log('Read-only. Listening on 127.0.0.1 only. Press Ctrl+C to stop.');
+    announce(log, { title: 'MONOLITH Mission Control', url: server.url, projectRoot, note: 'Read-only. Listening on 127.0.0.1 only.' });
     return {
         url: server.url,
         stop: () => server.close(),
@@ -124,9 +148,12 @@ export async function launchUiDev(opts) {
         await stop();
         return code;
     });
-    log(`MONOLITH Mission Control (dev, HMR): http://127.0.0.1:${opts.port}`);
-    log(`Project: ${projectRoot}  (dashboard API on ${api.url}, read-only)`);
-    log('Listening on 127.0.0.1 only. Press Ctrl+C to stop.');
+    announce(log, {
+        title: 'MONOLITH Mission Control (dev, HMR)',
+        url: `http://127.0.0.1:${opts.port}`,
+        projectRoot,
+        note: `Read-only dashboard API on ${api.url}. Listening on 127.0.0.1 only.`,
+    });
     return { url: `http://127.0.0.1:${opts.port}`, stop, ended };
 }
 /** CLI entry for `monolith ui ...`. Resolves with the process exit code once the launch has ended. */

package/dist/coordinatorium/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/coordinatorium/cli.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,EAAgE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAChH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAwBhD;;;;;;;;;;;;GAYG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAG,SAAS,CAAU;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,QAAQ,EAAE,cAAc,GAAG,iBAAiB;CAiBzD;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAS5E;AA8BD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAS9F;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB9F;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7F;AAeD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBnG;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAepG;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe/F"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/coordinatorium/cli.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,EAAgE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAChH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAwBhD;;;;;;;;;;;;GAYG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAG,SAAS,CAAU;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,QAAQ,EAAE,cAAc,GAAG,iBAAiB;CAiBzD;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAS5E;AA8BD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAS9F;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB9F;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7F;AA8BD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBnG;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAepG;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe/F"}

package/dist/coordinatorium/cli.js

@@ -155,7 +155,20 @@ function formatCheckpoint(c) {
     ];
     return lines.join('\n');
 }
+const CHECKPOINT_VALUE_FLAGS = ['--summary', '--remaining', '--context'];
+/** `mission checkpoint` takes only its documented options; an unknown `--option` is an error, not silently dropped. */
+function rejectUnknownCheckpointFlags(args) {
+    for (let i = 1; i < args.length; i++) {
+        if (CHECKPOINT_VALUE_FLAGS.includes(args[i]))
+            i++; // its value, whatever it looks like
+        else if (args[i].startsWith('--')) {
+            throw new Error(`Unknown option ${JSON.stringify(args[i].slice(0, 40))} for mission checkpoint.\n` +
+                'Usage: monolith mission checkpoint <missionId> --summary "..." [--remaining "..." ...] [--context "..."]');
+        }
+    }
+}
 export async function runMissionCheckpoint(args, targetDir = process.cwd()) {
+    rejectUnknownCheckpointFlags(args);
     const missionId = args[0];
     const summary = parseFlag(args, '--summary');
     if (!missionId || !summary) {

package/dist/finalize/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/finalize/cli.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAuFH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBnG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/finalize/cli.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAsGH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBnG"}

package/dist/finalize/cli.js

@@ -9,6 +9,7 @@
  */
 import { lstatSync, readFileSync } from 'fs';
 import { applyFinalization, planFinalization } from './core.js';
+import { colorEnabled, tintStatuses } from '../cli/style.js';
 import { parseProposal } from './proposal.js';
 const USAGE = `Usage:
   monolith finalize plan  --proposal <file|-> [--json]
@@ -74,32 +75,48 @@ async function readProposal(src) {
         throw new Error(`invalid proposal:\n${parsed.errors.map((e) => `  - ${e}`).join('\n')}`);
     return parsed.proposal;
 }
+function printConsistency(c) {
+    if (c === undefined)
+        return;
+    say(`\nState consistency (${c.projected ? 'projected after apply' : 'actual'}): ${c.status}`);
+    for (const f of c.findings)
+        say(`  [CONFLICT] ${printable(f.message)}\n         → ${printable(f.remediation)}`);
+    for (const n of c.notVerified)
+        say(`  [NOT_VERIFIED] ${printable(n)}`);
+    if (c.status !== 'CONSISTENT')
+        say('  This does not change the outcome of the finalization; MONOLITH edits none of the documents above on its own.');
+    say(`  Scope: ${printable(c.scope)}`);
+}
+const say = (line) => console.log(tintStatuses(line, colorEnabled(), ['Finalization plan for [^:]+', 'Finalization of [^:]+', 'State consistency [^:]+']));
 function printPlan(pl) {
-    console.log(`Finalization plan for ${printable(pl.storyId)}: ${pl.status}${pl.partial ? ' (PARTIAL: an earlier run was interrupted; apply rolls it forward)' : ''}`);
-    console.log('\nPreconditions:');
+    say(`Finalization plan for ${printable(pl.storyId)}: ${pl.status}${pl.partial ? ' (PARTIAL: an earlier run was interrupted; apply rolls it forward)' : ''}`);
+    say('\nPreconditions:');
     for (const c of pl.checks)
-        console.log(`  [${c.status}] ${c.id}: ${printable(c.detail)}\n         source: ${printable(c.source)}`);
-    console.log('\nTargets (in write order, active.md last):');
+        say(`  [${c.status}] ${c.id}: ${printable(c.detail)}\n         source: ${printable(c.source)}`);
+    say('\nTargets (in write order, active.md last):');
     for (const t of pl.targets)
-        console.log(`  [${t.state}] ${t.id} → ${printable(t.path)}${t.state === 'done' ? '' : ` — ${printable(t.reason)}`}`);
+        say(`  [${t.state}] ${t.id} → ${printable(t.path)}${t.state === 'done' ? '' : ` — ${printable(t.reason)}`}`);
     for (const d of pl.diagnostics)
-        console.log(`\nNote: ${printable(d)}`);
+        say(`\nNote: ${printable(d)}`);
+    printConsistency(pl.consistency);
     if (pl.status === 'READY')
-        console.log(`\nDigest: ${pl.digest}\nOwner approval: monolith finalize apply --proposal <same file> --approve ${pl.digest}\nThe digest shows this plan is unchanged; it does not prove who approves it. Do not run apply unless the owner approved this exact plan.`);
+        say(`\nDigest: ${pl.digest}\nOwner approval: monolith finalize apply --proposal <same file> --approve ${pl.digest}\nThe digest shows this plan is unchanged; it does not prove who approves it. Do not run apply unless the owner approved this exact plan.`);
 }
 function printApply(r) {
-    console.log(`Finalization of ${printable(r.storyId)}: ${r.status}`);
+    say(`Finalization of ${printable(r.storyId)}: ${r.status}`);
     if (r.applied.length > 0)
-        console.log(`  written: ${r.applied.join(', ')}`);
+        say(`  written: ${r.applied.join(', ')}`);
     if (r.status !== 'FINALIZED' && r.pending.length > 0)
-        console.log(`  not written: ${r.pending.join(', ')}`);
+        say(`  not written: ${r.pending.join(', ')}`);
     if (r.failed)
-        console.log(`  failed: ${r.failed.target}${r.failed.publication ? ` [${r.failed.publication}]` : ''}: ${printable(r.failed.message)}`);
+        say(`  failed: ${r.failed.target}${r.failed.publication ? ` [${r.failed.publication}]` : ''}: ${printable(r.failed.message)}`);
     for (const d of r.diagnostics)
-        console.log(`  ${printable(d)}`);
+        say(`  ${printable(d)}`);
     if (r.status === 'REFUSED')
         for (const c of r.plan.checks.filter((x) => x.status !== 'PASS'))
-            console.log(`  [${c.status}] ${c.id}: ${printable(c.detail)}`);
+            say(`  [${c.status}] ${c.id}: ${printable(c.detail)}`);
+    if (r.status === 'FINALIZED' || r.status === 'ALREADY_FINALIZED')
+        printConsistency(r.plan.consistency);
 }
 export async function runFinalizeCommand(args, targetDir = process.cwd()) {
     const sub = args[0];

package/dist/finalize/consistency.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Consistency assessment of the state documents around a finalization (FIN-002).
+ *
+ * `finalize` writes a fixed, small set of documents (story-index.md, active.md,
+ * and whatever the owner listed in `docUpdates` / HANDOFF). It deliberately does
+ * NOT write roadmap-index.md, so a roadmap row that still says IN PROGRESS for
+ * the story that was just finalized used to survive a successful `apply`
+ * unnoticed. This module reports such disagreements; it never edits anything
+ * and never changes the outcome of the operation.
+ *
+ * It reuses `findContradictions()` of `monolith brief` — the single definition
+ * of "state documents disagree" — and feeds it the text the documents have (or
+ * will have, for a plan) after finalization. Four things are kept apart:
+ *   - operation success            → plan/apply `status` (unchanged)
+ *   - managed documents            → written by this finalization
+ *   - external documents           → not written by it; remediation is advice only
+ *   - completeness of the evidence → NOT_VERIFIED when a document cannot be read
+ */
+export type ConsistencyStatus = 'CONSISTENT' | 'INCONSISTENT' | 'NOT_VERIFIED';
+export interface ConsistencyFinding {
+    message: string;
+    /** State documents (file names) that disagree. */
+    documents: string[];
+    /** The subset of `documents` that this finalization does not write. */
+    externalDocuments: string[];
+    /** What a person can do; MONOLITH does not do it. */
+    remediation: string;
+}
+export interface ConsistencyAssessment {
+    status: ConsistencyStatus;
+    /** true: computed from the texts a pending plan would write; false: read from disk. */
+    projected: boolean;
+    findings: ConsistencyFinding[];
+    /** Why the check could not be completed (NOT_VERIFIED). */
+    notVerified: string[];
+    /** What this check does not cover. */
+    scope: string;
+}
+export interface ConsistencyInput {
+    /** Text of each state document as it is / will be; null = missing or unreadable. */
+    active: string | null;
+    roadmap: string | null;
+    storyIndex: string | null;
+    /** Project-relative paths this finalization writes (or has written). */
+    writtenPaths: string[];
+    projected: boolean;
+    /** The MONOLITH root (project-relative); documents are matched by their full canonical path. */
+    managedRoot?: string;
+}
+export declare function assessConsistency(input: ConsistencyInput): ConsistencyAssessment;
+//# sourceMappingURL=consistency.d.ts.map

package/dist/finalize/consistency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consistency.d.ts","sourceRoot":"","sources":["../../src/finalize/consistency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,cAAc,GAAG,cAAc,CAAC;AAE/E,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,uEAAuE;IACvE,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,uFAAuF;IACvF,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,2DAA2D;IAC3D,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wEAAwE;IACxE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,qBAAqB,CAmChF"}

package/dist/finalize/consistency.js

@@ -0,0 +1,57 @@
+/**
+ * Consistency assessment of the state documents around a finalization (FIN-002).
+ *
+ * `finalize` writes a fixed, small set of documents (story-index.md, active.md,
+ * and whatever the owner listed in `docUpdates` / HANDOFF). It deliberately does
+ * NOT write roadmap-index.md, so a roadmap row that still says IN PROGRESS for
+ * the story that was just finalized used to survive a successful `apply`
+ * unnoticed. This module reports such disagreements; it never edits anything
+ * and never changes the outcome of the operation.
+ *
+ * It reuses `findContradictions()` of `monolith brief` — the single definition
+ * of "state documents disagree" — and feeds it the text the documents have (or
+ * will have, for a plan) after finalization. Four things are kept apart:
+ *   - operation success            → plan/apply `status` (unchanged)
+ *   - managed documents            → written by this finalization
+ *   - external documents           → not written by it; remediation is advice only
+ *   - completeness of the evidence → NOT_VERIFIED when a document cannot be read
+ */
+import { findContradictions, parseActiveStoryClaim, parseRoadmapActiveStory, parseRoadmapStatuses, parseStoryIndexStatuses } from '../brief/freshness.js';
+import { extractCurrentStory } from '../brief/story.js';
+const SCOPE = 'Checks only structural agreement between active.md, roadmap-index.md and story-index.md (the same rules as `monolith brief`). It does not read prose, HANDOFF.md, or any other project document.';
+const DOC_DIR = { 'active.md': 'memory/working/', 'story-index.md': 'memory/working/', 'roadmap-index.md': 'context/maps/' };
+export function assessConsistency(input) {
+    const notVerified = [];
+    if (input.active === null)
+        notVerified.push('active.md is missing or unreadable');
+    if (input.roadmap === null)
+        notVerified.push('roadmap-index.md is missing or unreadable');
+    if (input.storyIndex === null)
+        notVerified.push('story-index.md is missing or unreadable');
+    const story = input.active === null ? null : extractCurrentStory(input.active);
+    const activeStory = story !== null && story.hasCurrentStorySection ? parseActiveStoryClaim(story.excerpt) : { kind: 'unknown' };
+    if (input.active !== null && activeStory.kind === 'unknown')
+        notVerified.push('the active story could not be determined from active.md');
+    const found = findContradictions({
+        activeStory,
+        roadmapActiveStory: input.roadmap === null ? null : parseRoadmapActiveStory(input.roadmap),
+        roadmapStatuses: input.roadmap === null ? new Map() : parseRoadmapStatuses(input.roadmap),
+        storyIndexStatuses: input.storyIndex === null ? new Map() : parseStoryIndexStatuses(input.storyIndex),
+    });
+    const written = new Set(input.writtenPaths);
+    const findings = found.map((c) => {
+        const externalDocuments = c.documents.filter((d) => !(input.managedRoot !== undefined && written.has(`${input.managedRoot}/${DOC_DIR[d] ?? ''}${d}`)));
+        return {
+            message: c.message,
+            documents: c.documents,
+            externalDocuments,
+            remediation: externalDocuments.length === 0
+                ? `Both documents are written by this finalization; review the proposal.`
+                : `${externalDocuments.join(', ')} ${externalDocuments.length === 1 ? 'is' : 'are'} not written by finalization. Update ${externalDocuments.length === 1 ? 'it' : 'them'} yourself, or list ${externalDocuments.length === 1 ? 'it' : 'them'} in monolith.config.json finalization.allowedDocs and pass a docUpdates entry in a new proposal.`,
+        };
+    });
+    // A concrete contradiction is reported as such even when other evidence is missing;
+    // CONSISTENT requires that nothing was left unchecked.
+    const status = findings.length > 0 ? 'INCONSISTENT' : notVerified.length > 0 ? 'NOT_VERIFIED' : 'CONSISTENT';
+    return { status, projected: input.projected, findings, notVerified, scope: SCOPE };
+}

package/dist/finalize/core.d.ts

@@ -21,6 +21,7 @@
  */
 import { type ConfigRead, type FsOps, type WriteWarning } from '../root/index.js';
 import { type LockOptions } from '../coordinatorium/lock.js';
+import { type ConsistencyAssessment } from './consistency.js';
 import { type FinalizationProposal } from './proposal.js';
 export type CheckStatus = 'PASS' | 'FAIL' | 'NOT_VERIFIED';
 export type TargetKind = 'capsule' | 'execution-history' | 'story-index' | 'doc' | 'handoff' | 'active';
@@ -56,6 +57,12 @@ export interface FinalizationPlan {
     checks: Check[];
     targets: PlannedTarget[];
     diagnostics: string[];
+    /**
+     * FIN-002: whether the state documents agree with each other in the state
+     * this plan leads to (projected before apply, actual once every target is
+     * done). Informational: it never changes `status`, the digest or exit codes.
+     */
+    consistency?: ConsistencyAssessment;
 }
 export interface ApplyResult {
     status: ApplyStatus;
@@ -86,6 +93,25 @@ export interface FinalizeConfig {
 }
 export declare function readFinalizeConfig(config: ConfigRead): FinalizeConfig;
 export declare function renderCapsule(p: FinalizationProposal): string;
+/**
+ * Format-equivalence of a capsule (FIN-001, made context-aware by A4-FIN-01).
+ * The capsule is created once and never overwritten, so "already present" used
+ * to mean byte-identical; a formatter pass (Prettier adds a blank line after
+ * every heading) then turned an unchanged capsule into a CONFLICT. Equivalence
+ * is deliberately narrow and NOT a general whitespace-insensitive comparison.
+ * Ignored: line endings (CRLF/LF), trailing whitespace on a line that is plain
+ * prose, a single blank line directly after an ATX heading, and trailing blank
+ * lines at end of file. NOT ignored, because whitespace carries meaning there:
+ *  - anything inside a fenced code block (``` or ~~~), an indented code block /
+ *    4-space-or-tab-indented line, an HTML comment, or YAML frontmatter
+ *    (`---` ... `---` at the very top; an unterminated one protects the whole
+ *    file) — those lines are compared verbatim;
+ *  - a Markdown hard line break (two or more trailing spaces before a line that
+ *    continues the paragraph): kept as a break (any run of 2+ spaces is the
+ *    same break); a backslash break is not whitespace and is always compared;
+ *  - blank lines anywhere else (paragraph breaks).
+ */
+export declare function capsuleCanonical(s: string): string;
 /** Evidence older than this many days before the finalization date is not accepted. */
 export declare const EVIDENCE_MAX_AGE_DAYS = 7;
 export type ActiveIdentity = {
@@ -101,6 +127,8 @@ export type ActiveIdentity = {
  * evidence files and `## Last Finalization`); its FIRST token is the id. Ids
  * mentioned in titles, descriptions, comments, code fences or other fields carry
  * no authority. Zero, several, or malformed field lines → no identity (fail closed).
+ * A section whose first visible line says "no active story" AND that has a
+ * structural field is contradictory → no identity (PSC-004A).
  */
 export declare function activeStoryIdentity(currentStoryBody: string): ActiveIdentity;
 export declare function planFinalization(targetDir: string, proposal: FinalizationProposal): FinalizationPlan;