@latysh-development/monolith 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -101,6 +101,29 @@ monolith ui          # Mission Control at http://127.0.0.1:4173 ; Ctrl+C to stop
 instance, and it does not open a browser — open the printed address yourself.
 All commands: [CLI reference](./docs/reference/cli.md).
 
+### 🧠 One More Thing: Give Your AI Chat the Context!
+
+MONOLITH is installed. Now make sure your AI assistant knows how to use it.
+
+Open `.monolith/context/MONOLITH-CHAT-CONTEXT.md` and copy its contents into your ChatGPT Project instructions, Claude conversation, or another AI workspace you use to coordinate development.
+
+It explains MONOLITH's capabilities, project memory, workflows, and limitations.
+
+**Your coding agent gets the protocols. Your working chat gets the context.**
+
+`monolith init` creates this file. Print it from the project root (the directory where you ran `monolith init`):
+
+```bash
+cat .monolith/context/MONOLITH-CHAT-CONTEXT.md
+```
+
+If `monolithRoot` in `monolith.config.json` is not `.monolith`, use that directory instead.
+Projects initialized with an earlier MONOLITH version do not get this file from
+`monolith update`; copy it from the template in this repository (replace
+`{{MONOLITH_ROOT}}` with `.monolith`, otherwise `monolith validate` reports an
+unreplaced placeholder). You can also read the template before installing:
+[`templates/default-instance/monolith/context/MONOLITH-CHAT-CONTEXT.md`](./templates/default-instance/monolith/context/MONOLITH-CHAT-CONTEXT.md).
+
 ## Updating an Existing Project
 
 If a project was initialised with an earlier MONOLITH version, bring it up to the current agent integration (agent entry point and Idea Capture) with:
@@ -160,7 +183,7 @@ listing — not an official partnership, endorsement or certification.
 
 ## Project Status
 
-**Alpha** (`0.1.0-alpha.1`). The API and CLI are experimental and may change
+**Alpha** (`0.1.0-alpha.3`). The API and CLI are experimental and may change
 without notice. Published to npm under the alpha dist-tag. Durable State and the Coordinatorium
 (`monolith durable`, `monolith mission`) are experimental and are not part of
 the Quick Start.

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

@@ -1 +1 @@
-{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/brief/collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwBH,OAAO,KAAK,EACV,UAAU,EAOX,MAAM,YAAY,CAAC;AAiBpB,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,QAAa,CAAC;AA8TnD,wBAAsB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAqEpE"}
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/brief/collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAyBH,OAAO,KAAK,EACV,UAAU,EAOX,MAAM,YAAY,CAAC;AAiBpB,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,QAAa,CAAC;AAiUnD,wBAAsB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAqEpE"}

package/dist/brief/collect.js

@@ -16,6 +16,7 @@ import { readBriefConfig } from './config.js';
 import { resolveMonolithRootValue, checkContainedFile, readBoundedFileStable, isReadSecurityViolation, findWriteArtifacts, describeWriteArtifacts, } from '../root/index.js';
 import { discoverDocs } from './docs.js';
 import { extractCurrentStory } from './story.js';
+import { maskNonContent } from './markdown-context.js';
 import { selectActiveMissions, selectRecentFinishedMissions, selectLatestCheckpoint, hasCheckpointOrderMismatch, } from './selectors.js';
 import { stateFilePath, validateState, createInitialState, MAX_STATE_BYTES } from '../coordinatorium/index.js';
 import { ACTIVE_MD_REL, PARKED_IDEAS_LIMIT, PROTOCOLS_DIR, ROADMAP_INDEX_REL, STORY_INDEX_REL, HANDOFF_REL } from './constants.js';
@@ -202,7 +203,9 @@ function collectStory(targetDir, monolithRoot, root, diagnostics) {
         diagnostics.push({
             code: 'ACTIVE_MD_NO_CURRENT_STORY',
             severity: 'info',
-            message: `${relPath} exists but has no "## Current Story" section.`,
+            message: extraction.ambiguous
+                ? `${relPath} has more than one "## Current Story" section outside code blocks and comments; the section is ambiguous and was not read.`
+                : `${relPath} exists but has no "## Current Story" section.`,
         });
     }
     return {
@@ -273,7 +276,8 @@ function collectFreshness(targetDir, monolithRoot, root, story) {
         roadmapActiveStory: roadmap === null ? null : parseRoadmapActiveStory(roadmap),
         roadmapStatuses: roadmap === null ? new Map() : parseRoadmapStatuses(roadmap),
         storyIndexStatuses: storyIndex === null ? new Map() : parseStoryIndexStatuses(storyIndex),
-        recordedText: [...content.values()].filter((c) => c !== null).join('\n'),
+        // Ids shown only inside code fences or HTML comments are examples, not records.
+        recordedText: [...content.values()].filter((c) => c !== null).map(maskNonContent).join('\n'),
         stateFiles: new Set(stateFiles),
     };
     return { result: evaluateFreshness(evidence), evidence };

package/dist/brief/freshness.d.ts

@@ -19,6 +19,7 @@
  *            absence of an active story alone never produce STALE, and the
  *            absence of an active story never means "project complete".
  */
+import { maskNonContent } from './markdown-context.js';
 export type FreshnessStatus = 'FRESH' | 'STALE' | 'UNKNOWN';
 export type FreshnessReasonCode = 'STATE_CONTRADICTION' | 'UNRECORDED_WORK' | 'GIT_UNAVAILABLE' | 'STATE_NOT_IN_GIT' | 'GIT_HISTORY_TRUNCATED' | 'UNATTRIBUTED_ACTIVITY' | 'NO_ACTIVITY_SINCE_STATE_UPDATE' | 'ACTIVITY_RECORDED';
 export interface FreshnessReason {
@@ -57,8 +58,14 @@ export type StoryClaim = {
 } | {
     kind: 'ids';
     ids: string[];
-} | {
+}
+/**
+ * `contradiction`: the section both says "no active story" and has a
+ * structural `**Story:**` field (PSC-004A) — the field value(s), verbatim.
+ */
+ | {
     kind: 'unknown';
+    contradiction?: string[];
 };
 export interface FreshnessEvidence {
     git: GitSignals;
@@ -92,13 +99,34 @@ export interface FreshnessResult {
 }
 export declare function extractWorkItemIds(text: string): string[];
 export declare function mentionsId(text: string, id: string): boolean;
-/** Interprets the `## Current Story` excerpt of active.md. */
+export { maskNonContent };
+/**
+ * Interprets the `## Current Story` excerpt of active.md.
+ *
+ * Identity comes from the structural `**Story:** <id> …` field only (first
+ * token = id), exactly as DOCSYNC reads it. Ids in titles, prose, code fences
+ * or comments are never identity. Zero usable, several or malformed fields →
+ * `unknown` (never a guess, never STALE on its own).
+ *
+ * Compatibility: a historical section with no `**Story:**` field at all is
+ * still read when its first line is a *bold declaration* of exactly one
+ * work-item id — `**WIDGET-001 — title**`, `**WIDGET-001**` or
+ * `**WIDGET-001** — status` (the form old active.md files used). An unbolded
+ * line (`STORY-001 was completed yesterday.`, `STORY-001 — done`) is
+ * indistinguishable from a sentence that merely mentions a story, so it is
+ * `unknown`, never a confirmed identity.
+ *
+ * "No active story" as the first visible line is `none` only when the section
+ * has no structural `**Story:**` field at all; with one (valid, duplicate or
+ * malformed) the section contradicts itself → `unknown` with `contradiction`
+ * (PSC-004A, same rule as DOCSYNC's `activeStoryIdentity()`).
+ */
 export declare function parseActiveStoryClaim(excerpt: string | null): StoryClaim;
-/** `Active Story: <text>` line of roadmap-index.md. */
+/** `Active Story: <text>` line of roadmap-index.md (outside code fences and comments). */
 export declare function parseRoadmapActiveStory(content: string): string | null;
-/** Table rows `| id | title | STATUS | date |` of roadmap-index.md. */
+/** Table rows `| id | title | STATUS | date |` of roadmap-index.md (outside code fences and comments). */
 export declare function parseRoadmapStatuses(content: string): Map<string, string>;
-/** `### [STORY ]<id> — title` followed by `**Status:** X` in story-index.md. */
+/** `### [STORY ]<id> — title` followed by `**Status:** X` in story-index.md (outside code fences and comments). */
 export declare function parseStoryIndexStatuses(content: string): Map<string, string>;
 export declare function evaluateFreshness(ev: FreshnessEvidence): FreshnessResult;
 //# sourceMappingURL=freshness.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../../src/brief/freshness.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../../src/brief/freshness.ts"],"names":[],"mappings":"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"}

package/dist/brief/freshness.js

@@ -19,6 +19,8 @@
  *            absence of an active story alone never produce STALE, and the
  *            absence of an active story never means "project complete".
  */
+import { isIdeaId } from '../ideas/format.js';
+import { declaresNoActiveStory, maskNonContent } from './markdown-context.js';
 // ---------------------------------------------------------------------------
 // Work-item ids
 // ---------------------------------------------------------------------------
@@ -30,8 +32,14 @@
 const WORK_ITEM_SOURCE = String.raw `(?:[A-Z]{2,}-)+\d{3}[A-Z]?(?:\.\d+)*(?:-[A-Z])?`;
 /** Decision / lesson records are not work items. */
 const NON_WORK_PREFIXES = ['ADR-', 'DEC-', 'LESSON-'];
+/**
+ * Ideas live in their own namespace (`IDEA-NNN`, src/ideas/format.ts) and are
+ * stored in the idea store, not in the state documents. Only the exact idea
+ * grammar is excluded: `IDEA-001A`, `IDEA-001B.1` or `IDEA-003-R` are story
+ * ids that merely share the prefix and stay work items.
+ */
 function isWorkItem(id) {
-    return !NON_WORK_PREFIXES.some((p) => id.startsWith(p));
+    return !NON_WORK_PREFIXES.some((p) => id.startsWith(p)) && !isIdeaId(id);
 }
 export function extractWorkItemIds(text) {
     const re = new RegExp(`(?<![A-Za-z0-9-])${WORK_ITEM_SOURCE}(?![A-Za-z0-9]|\\.\\d|-[A-Z0-9])`, 'g');
@@ -46,29 +54,69 @@ export function mentionsId(text, id) {
     const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     return new RegExp(`(?<![A-Za-z0-9-])${escaped}(?![A-Za-z0-9]|\\.\\d|-[A-Z0-9])`).test(text);
 }
+// `maskNonContent` lives in ./markdown-context.ts (shared with story extraction
+// and DOCSYNC) and is re-exported here for existing importers.
+export { maskNonContent };
 // ---------------------------------------------------------------------------
 // Parsers for the state documents (confirmed structure only)
 // ---------------------------------------------------------------------------
 const NONE_RE = /^\W*(?:no active story|none|unknown)\b|^\s*[—-]\s*$/i;
-/** Interprets the `## Current Story` excerpt of active.md. */
+/** Same id grammar as DOCSYNC's `activeStoryIdentity()`. */
+const STORY_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * Interprets the `## Current Story` excerpt of active.md.
+ *
+ * Identity comes from the structural `**Story:** <id> …` field only (first
+ * token = id), exactly as DOCSYNC reads it. Ids in titles, prose, code fences
+ * or comments are never identity. Zero usable, several or malformed fields →
+ * `unknown` (never a guess, never STALE on its own).
+ *
+ * Compatibility: a historical section with no `**Story:**` field at all is
+ * still read when its first line is a *bold declaration* of exactly one
+ * work-item id — `**WIDGET-001 — title**`, `**WIDGET-001**` or
+ * `**WIDGET-001** — status` (the form old active.md files used). An unbolded
+ * line (`STORY-001 was completed yesterday.`, `STORY-001 — done`) is
+ * indistinguishable from a sentence that merely mentions a story, so it is
+ * `unknown`, never a confirmed identity.
+ *
+ * "No active story" as the first visible line is `none` only when the section
+ * has no structural `**Story:**` field at all; with one (valid, duplicate or
+ * malformed) the section contradicts itself → `unknown` with `contradiction`
+ * (PSC-004A, same rule as DOCSYNC's `activeStoryIdentity()`).
+ */
 export function parseActiveStoryClaim(excerpt) {
     if (excerpt === null)
         return { kind: 'unknown' };
-    const firstLine = excerpt.split('\n').find((l) => l.trim() !== '') ?? '';
-    if (/^\W*no active story\b/i.test(firstLine))
-        return { kind: 'none' };
-    const ids = extractWorkItemIds(excerpt);
-    return ids.length > 0 ? { kind: 'ids', ids } : { kind: 'unknown' };
+    const masked = maskNonContent(excerpt);
+    const firstLine = masked.split('\n').find((l) => l.trim() !== '') ?? '';
+    const fields = masked
+        .split('\n')
+        .map((l) => /^\*\*Story:\*\*[ \t]*(.*)$/.exec(l.replace(/\r$/, '')))
+        .filter((m) => m !== null)
+        .map((m) => m[1].trim());
+    if (declaresNoActiveStory(excerpt))
+        return fields.length === 0 ? { kind: 'none' } : { kind: 'unknown', contradiction: fields };
+    if (fields.length > 0) {
+        if (fields.length > 1)
+            return { kind: 'unknown' };
+        const id = /^(\S+)(?:\s|$)/.exec(fields[0])?.[1];
+        return id !== undefined && STORY_ID_RE.test(id) ? { kind: 'ids', ids: [id] } : { kind: 'unknown' };
+    }
+    const line = firstLine.trim();
+    const idEnd = String.raw `(?![A-Za-z0-9]|\.\d|-[A-Z0-9])`;
+    const declaration = new RegExp(`^\\*\\*(${WORK_ITEM_SOURCE})${idEnd}\\*\\*(?:\\s+[—–-](?:\\s.*)?)?$`).exec(line) ??
+        new RegExp(`^\\*\\*(${WORK_ITEM_SOURCE})${idEnd}\\s+[—–-]\\s.*\\*\\*$`).exec(line);
+    return declaration !== null && extractWorkItemIds(line).length === 1 ? { kind: 'ids', ids: [declaration[1]] } : { kind: 'unknown' };
 }
-/** `Active Story: <text>` line of roadmap-index.md. */
+/** `Active Story: <text>` line of roadmap-index.md (outside code fences and comments). */
 export function parseRoadmapActiveStory(content) {
-    const m = /^Active Story:\s*(.+?)\s*$/m.exec(content);
+    const m = /^Active Story:\s*(.+?)\s*$/m.exec(maskNonContent(content));
     return m ? m[1] : null;
 }
-/** Table rows `| id | title | STATUS | date |` of roadmap-index.md. */
+/** Table rows `| id | title | STATUS | date |` of roadmap-index.md (outside code fences and comments). */
 export function parseRoadmapStatuses(content) {
     const out = new Map();
-    for (const line of content.split('\n')) {
+    for (const line of maskNonContent(content).split('\n')) {
         const cells = line.split('|').map((c) => c.trim());
         // leading and trailing '|' produce empty first/last cells
         if (cells.length < 5 || cells[0] !== '' || cells[cells.length - 1] !== '')
@@ -82,10 +130,10 @@ export function parseRoadmapStatuses(content) {
     }
     return out;
 }
-/** `### [STORY ]<id> — title` followed by `**Status:** X` in story-index.md. */
+/** `### [STORY ]<id> — title` followed by `**Status:** X` in story-index.md (outside code fences and comments). */
 export function parseStoryIndexStatuses(content) {
     const out = new Map();
-    const lines = content.split('\n');
+    const lines = maskNonContent(content).split('\n');
     for (let i = 0; i < lines.length; i++) {
         const h = /^###\s+(?:STORY\s+)?([A-Za-z0-9][A-Za-z0-9.\-]*)\s+—/.exec(lines[i]);
         if (!h)
@@ -117,6 +165,12 @@ function isDone(status) {
 }
 function findContradictions(ev) {
     const out = [];
+    if (ev.activeStory.kind === 'unknown' && ev.activeStory.contradiction !== undefined) {
+        out.push({
+            message: `active.md records no active story, but its Current Story section also has a **Story:** field (${ev.activeStory.contradiction.map((f) => `"${f.slice(0, 40)}"`).join(', ')}).`,
+            documents: ['active.md'],
+        });
+    }
     if (ev.activeStory.kind === 'none' && ev.roadmapActiveStory !== null && !NONE_RE.test(ev.roadmapActiveStory)) {
         out.push({
             message: `active.md records no active story, but roadmap-index.md names "${ev.roadmapActiveStory}".`,

package/dist/brief/markdown-context.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Markdown context shared by the Brief, Freshness, Reconcile and DOCSYNC
+ * readers of the project state documents. Pure, deterministic, no I/O.
+ */
+/**
+ * True when the first visible line of a Current Story excerpt (outside code
+ * fences and HTML comments) declares that there is no active story. Shared by
+ * the Brief and DOCSYNC (PSC-004A): such a declaration next to a structural
+ * `**Story:**` field is a contradiction, never a confirmed "none" and never
+ * a confirmed identity.
+ */
+export declare function declaresNoActiveStory(excerpt: string): boolean;
+/**
+ * Blanks every line (or part of a line) that sits inside a fenced code block
+ * or an HTML comment, keeping the line count. Fence grammar matches DOCSYNC's
+ * `activeStoryIdentity()`: a line that starts with ``` or ~~~ opens a fence,
+ * and only a line made of the same character, at least as long, closes it.
+ * An unterminated fence or comment hides the rest of the text — an example
+ * that cannot be delimited is never read as a claim.
+ */
+export declare function maskNonContent(text: string): string;
+//# sourceMappingURL=markdown-context.d.ts.map

package/dist/brief/markdown-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-context.d.ts","sourceRoot":"","sources":["../../src/brief/markdown-context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuCnD"}

package/dist/brief/markdown-context.js

@@ -0,0 +1,66 @@
+/**
+ * Markdown context shared by the Brief, Freshness, Reconcile and DOCSYNC
+ * readers of the project state documents. Pure, deterministic, no I/O.
+ */
+/**
+ * True when the first visible line of a Current Story excerpt (outside code
+ * fences and HTML comments) declares that there is no active story. Shared by
+ * the Brief and DOCSYNC (PSC-004A): such a declaration next to a structural
+ * `**Story:**` field is a contradiction, never a confirmed "none" and never
+ * a confirmed identity.
+ */
+export function declaresNoActiveStory(excerpt) {
+    const first = maskNonContent(excerpt.replace(/\r\n/g, '\n')).split('\n').find((l) => l.trim() !== '') ?? '';
+    return /^\W*no active story\b/i.test(first);
+}
+/**
+ * Blanks every line (or part of a line) that sits inside a fenced code block
+ * or an HTML comment, keeping the line count. Fence grammar matches DOCSYNC's
+ * `activeStoryIdentity()`: a line that starts with ``` or ~~~ opens a fence,
+ * and only a line made of the same character, at least as long, closes it.
+ * An unterminated fence or comment hides the rest of the text — an example
+ * that cannot be delimited is never read as a claim.
+ */
+export function maskNonContent(text) {
+    let fence = null;
+    let comment = false;
+    const out = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        const f = /^(`{3,}|~{3,})/.exec(line);
+        if (fence !== null) {
+            if (f !== null && f[1][0] === fence[0] && f[1].length >= fence.length && line === f[1])
+                fence = null;
+            out.push('');
+            continue;
+        }
+        if (!comment && f !== null) {
+            fence = f[1];
+            out.push('');
+            continue;
+        }
+        let kept = '';
+        let i = 0;
+        while (i < raw.length) {
+            if (comment) {
+                const end = raw.indexOf('-->', i);
+                if (end === -1)
+                    break;
+                comment = false;
+                i = end + 3;
+            }
+            else {
+                const start = raw.indexOf('<!--', i);
+                if (start === -1) {
+                    kept += raw.slice(i);
+                    break;
+                }
+                kept += raw.slice(i, start);
+                comment = true;
+                i = start + 4;
+            }
+        }
+        out.push(kept);
+    }
+    return out.join('\n');
+}

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

@@ -12,6 +12,7 @@
  *   monolith brief       — deterministic, bounded project context summary
  *   monolith durable     — inspect/verify/maintain Durable State task logs
  *   monolith idea        — capture and recall deferred ideas (add/list/show)
+ *   monolith finalize    — plan/apply a controlled story finalization (documentation sync)
  *   monolith update      — add missing Idea Capture infrastructure to an existing instance
  *   monolith ui          — launch Mission Control (read-only dashboard)
  */
@@ -42,6 +43,8 @@ Commands:
               list | show | assess | packet | verify | retention.
   idea        Capture a deferred thought without leaving the current task, and
               recall it later: add | list | show. Plain Markdown files, no LLM.
+  finalize    Close a story with checked preconditions and controlled documentation
+              updates: plan (read-only) | apply --approve <digest>.
   update      Bring an existing instance up to Idea Capture & Recall. Preview by
               default (changes nothing). --apply creates MONOLITH-managed files
               and may add or refresh managed sections inside your existing
@@ -74,6 +77,10 @@ Idea usage:
   monolith idea list
   monolith idea show <id>
 
+Finalize usage:
+  monolith finalize plan  --proposal <file|-> [--json]
+  monolith finalize apply --proposal <file|-> --approve <digest> [--json]
+
 Update usage:
   monolith update [--apply]
 
@@ -169,6 +176,11 @@ async function main() {
             await runIdeaCommand(args.slice(1));
             break;
         }
+        case 'finalize': {
+            const { runFinalizeCommand } = await import('../finalize/cli.js');
+            process.exitCode = await runFinalizeCommand(args.slice(1));
+            break;
+        }
         case 'update': {
             const { runUpdate } = await import('../update/cli.js');
             process.exitCode = await runUpdate(args.slice(1));

package/dist/finalize/cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `monolith finalize plan|apply` (DOCSYNC-001, ADR-022).
+ *
+ * `plan` is read-only. `apply` writes only with `--approve <digest>` taken from
+ * a `plan` the owner reviewed. Exit codes: 0 ok / already finalized; 1 usage or
+ * unreadable proposal; 2 not ready / refused (nothing written); 3 incomplete
+ * (partially applied — see the output).
+ */
+export declare function runFinalizeCommand(args: string[], targetDir?: string): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

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

@@ -0,0 +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"}

package/dist/finalize/cli.js

@@ -0,0 +1,134 @@
+/* eslint-disable no-console */
+/**
+ * `monolith finalize plan|apply` (DOCSYNC-001, ADR-022).
+ *
+ * `plan` is read-only. `apply` writes only with `--approve <digest>` taken from
+ * a `plan` the owner reviewed. Exit codes: 0 ok / already finalized; 1 usage or
+ * unreadable proposal; 2 not ready / refused (nothing written); 3 incomplete
+ * (partially applied — see the output).
+ */
+import { lstatSync, readFileSync } from 'fs';
+import { applyFinalization, planFinalization } from './core.js';
+import { parseProposal } from './proposal.js';
+const USAGE = `Usage:
+  monolith finalize plan  --proposal <file|-> [--json]
+  monolith finalize apply --proposal <file|-> --approve <digest> [--json]`;
+const MAX_PROPOSAL_BYTES = 4 * 1024 * 1024;
+// eslint-disable-next-line no-control-regex
+const printable = (s) => s.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+function parseFlags(args, allowApprove) {
+    const f = { json: false };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--json')
+            f.json = true;
+        else if (a === '--proposal' || (allowApprove && a === '--approve')) {
+            const v = args[i + 1];
+            if (v === undefined || v.startsWith('--'))
+                throw new Error(`${a} needs a value.\n${USAGE}`);
+            const key = a === '--proposal' ? 'proposal' : 'approve';
+            if (f[key] !== undefined)
+                throw new Error(`${a} was given more than once.\n${USAGE}`);
+            f[key] = v;
+            i++;
+        }
+        else
+            throw new Error(`Unexpected argument ${JSON.stringify(printable(a))}.\n${USAGE}`);
+    }
+    if (f.proposal === undefined)
+        throw new Error(`--proposal is required.\n${USAGE}`);
+    if (allowApprove && f.approve === undefined)
+        throw new Error(`--approve <digest> is required: run \`monolith finalize plan\`, review it, then pass its digest.\n${USAGE}`);
+    return f;
+}
+async function readProposal(src) {
+    let raw;
+    if (src === '-') {
+        const chunks = [];
+        let n = 0;
+        for await (const c of process.stdin) {
+            n += c.length;
+            if (n > MAX_PROPOSAL_BYTES)
+                throw new Error('proposal on stdin is too large.');
+            chunks.push(c);
+        }
+        raw = Buffer.concat(chunks).toString('utf8');
+    }
+    else {
+        const st = lstatSync(src);
+        if (!st.isFile())
+            throw new Error(`${src} is not a regular file.`);
+        if (st.size > MAX_PROPOSAL_BYTES)
+            throw new Error(`${src} is too large.`);
+        raw = readFileSync(src, 'utf8');
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`proposal is not valid JSON: ${err.message}`);
+    }
+    const parsed = parseProposal(json);
+    if (!parsed.ok)
+        throw new Error(`invalid proposal:\n${parsed.errors.map((e) => `  - ${e}`).join('\n')}`);
+    return parsed.proposal;
+}
+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:');
+    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):');
+    for (const t of pl.targets)
+        console.log(`  [${t.state}] ${t.id} → ${printable(t.path)}${t.state === 'done' ? '' : ` — ${printable(t.reason)}`}`);
+    for (const d of pl.diagnostics)
+        console.log(`\nNote: ${printable(d)}`);
+    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.`);
+}
+function printApply(r) {
+    console.log(`Finalization of ${printable(r.storyId)}: ${r.status}`);
+    if (r.applied.length > 0)
+        console.log(`  written: ${r.applied.join(', ')}`);
+    if (r.status !== 'FINALIZED' && r.pending.length > 0)
+        console.log(`  not written: ${r.pending.join(', ')}`);
+    if (r.failed)
+        console.log(`  failed: ${r.failed.target}${r.failed.publication ? ` [${r.failed.publication}]` : ''}: ${printable(r.failed.message)}`);
+    for (const d of r.diagnostics)
+        console.log(`  ${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)}`);
+}
+export async function runFinalizeCommand(args, targetDir = process.cwd()) {
+    const sub = args[0];
+    try {
+        if (sub === 'plan') {
+            const f = parseFlags(args.slice(1), false);
+            const pl = planFinalization(targetDir, await readProposal(f.proposal));
+            if (f.json)
+                console.log(JSON.stringify(pl, null, 2));
+            else
+                printPlan(pl);
+            return pl.status === 'NOT_READY' ? 2 : 0;
+        }
+        if (sub === 'apply') {
+            const f = parseFlags(args.slice(1), true);
+            const r = await applyFinalization(targetDir, await readProposal(f.proposal), f.approve, {
+                onWarning: (w) => console.error(`warning: ${printable(w.message)}`),
+            });
+            if (f.json)
+                console.log(JSON.stringify(r, null, 2));
+            else
+                printApply(r);
+            return r.status === 'FINALIZED' || r.status === 'ALREADY_FINALIZED' ? 0 : r.status === 'REFUSED' ? 2 : 3;
+        }
+        console.error(`Unknown finalize subcommand: ${sub === undefined ? '(none)' : printable(sub)}\n${USAGE}`);
+        return 1;
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}