@latysh-development/monolith 0.1.0-alpha.2 → 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.2`). 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/finalize/core.d.ts

@@ -101,6 +101,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;

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

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

package/dist/finalize/core.js

@@ -25,6 +25,7 @@ import { dirname, join } from 'path';
 import { RootContainmentError, SafeWriteError, createFile, openParent, projectBoundary, readConfigFile, readProjectFile, replaceFile, resolveMonolithRoot, } from '../root/index.js';
 import { acquireLock } from '../coordinatorium/lock.js';
 import { extractCurrentStory } from '../brief/story.js';
+import { declaresNoActiveStory, maskNonContent } from '../brief/markdown-context.js';
 import { validDate, validateRelPath } from './proposal.js';
 const MAX_DOC_BYTES = 4 * 1024 * 1024;
 const LOCK_NAME = 'finalize.lock';
@@ -169,11 +170,16 @@ function activeBodies(root, p) {
 // Text transforms (pure)
 // ---------------------------------------------------------------------------
 const eolOf = (s) => (s.includes('\r\n') ? '\r\n' : '\n');
-/** Boundaries as in brief/story.ts: the next heading or a `---` rule ends a section. */
-function findSection(lines, re) {
+/**
+ * Boundaries as in brief/story.ts: the next heading or a `---` rule ends a
+ * section, and headings inside code fences or HTML comments do not count.
+ * `structural` is the same text with fenced / commented lines blanked (same
+ * line count), so reading and writing agree on which section is "Current Story".
+ */
+function findSection(lines, structural, re) {
     const hits = [];
-    lines.forEach((l, i) => {
-        if (re.test(l.trim()))
+    structural.forEach((l, i) => {
+        if (re.test(l.trim()) && l.trim() === lines[i].trim())
             hits.push(i);
     });
     if (hits.length === 0)
@@ -182,7 +188,7 @@ function findSection(lines, re) {
         return 'ambiguous';
     let end = lines.length;
     for (let i = hits[0] + 1; i < lines.length; i++) {
-        const t = lines[i].trim();
+        const t = structural[i].trim();
         if (/^#{1,6}\s+/.test(t) || /^-{3,}\s*$/.test(t)) {
             end = i;
             break;
@@ -199,8 +205,9 @@ const CURRENT_RE = /^##\s+Current Story\s*$/i;
 const LAST_RE = /^##\s+Last Finalization\s*$/i;
 function editActive(content, bodies) {
     const lines = content.split('\n');
-    const cur = findSection(lines, CURRENT_RE);
-    const last = findSection(lines, LAST_RE);
+    const structural = maskNonContent(content).split('\n');
+    const cur = findSection(lines, structural, CURRENT_RE);
+    const last = findSection(lines, structural, LAST_RE);
     for (const [name, s] of [['## Current Story', cur], ['## Last Finalization', last]]) {
         if (s === 'absent')
             return { state: 'conflict', reason: `active.md has no "${name}" section; it is never created automatically.` };
@@ -295,37 +302,13 @@ const FIX_HINT = 'To finalize, put exactly one line "**Story:** <id> — <title>
  * 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 function activeStoryIdentity(currentStoryBody) {
-    const found = [];
-    let fence = null;
-    let comment = false;
-    for (const raw of norm(currentStoryBody).split('\n')) {
-        const line = raw.trim();
-        if (comment) {
-            if (line.includes('-->'))
-                comment = false;
-            continue;
-        }
-        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;
-            continue;
-        }
-        if (f !== null) {
-            fence = f[1];
-            continue;
-        }
-        if (line.startsWith('<!--')) {
-            if (!line.includes('-->'))
-                comment = true;
-            continue;
-        }
-        const m = /^\*\*Story:\*\*[ \t]*(.*)$/.exec(raw.replace(/\r$/, ''));
-        if (m !== null)
-            found.push(m[1].trim());
-    }
+    const found = structuralStoryFields(currentStoryBody);
+    if (found.length > 0 && declaresNoActiveStory(currentStoryBody))
+        return { ok: false, reason: `the Current Story section says there is no active story but also has ${found.length === 1 ? 'a "**Story:**" line' : `${found.length} "**Story:**" lines`} (${found.map((x) => `"${x.slice(0, 40)}"`).join(', ')}): contradictory identity. ${FIX_HINT}` };
     if (found.length === 0)
         return { ok: false, reason: `the Current Story section has no "**Story:** <id>" line, so the active story cannot be identified (ids in free text, headings, comments or code blocks are not identity). ${FIX_HINT}` };
     if (found.length > 1)
@@ -335,6 +318,19 @@ export function activeStoryIdentity(currentStoryBody) {
         return { ok: false, reason: `the "**Story:**" line ("${found[0].slice(0, 60)}") does not start with a valid story id. ${FIX_HINT}` };
     return { ok: true, id };
 }
+/** Values of the structural `**Story:**` field lines (outside code fences and HTML comments). */
+function structuralStoryFields(currentStoryBody) {
+    const found = [];
+    // Same fence / HTML-comment grammar as the brief's story extraction and
+    // freshness readers (one shared helper): text inside a code fence or an HTML
+    // comment, including a comment opened mid-line, is never identity.
+    for (const raw of maskNonContent(norm(currentStoryBody)).split('\n')) {
+        const m = /^\*\*Story:\*\*[ \t]*(.*)$/.exec(raw.replace(/\r$/, ''));
+        if (m !== null)
+            found.push(m[1].trim());
+    }
+    return found;
+}
 /**
  * Attested evidence. Contract: exactly one `**Status:**` (PASS or FAIL, nothing
  * else on the line), exactly one `**Story:**` whose FIRST token is the story id,
@@ -612,13 +608,23 @@ function plan(ctx, p) {
             let ok;
             let want;
             let why = '';
-            if (exp === 'none')
-                (ok = ex.hasCurrentStorySection && /no active story/i.test(excerpt)), (want = 'no active story');
+            const visible = maskNonContent(excerpt);
+            if (exp === 'none') {
+                // Same rule as the brief: the first visible line says "no active story"
+                // and no structural **Story:** field (valid, duplicate or malformed)
+                // contradicts it (PSC-004A). Text inside code fences or comments is
+                // not a statement.
+                (ok = ex.hasCurrentStorySection && declaresNoActiveStory(excerpt) && structuralStoryFields(excerpt).length === 0), (want = 'no active story');
+                if (!ok && ex.hasCurrentStorySection && declaresNoActiveStory(excerpt))
+                    why = ' The section also has a "**Story:**" field: contradictory identity. ' + FIX_HINT;
+            }
             else {
                 const ident = activeStoryIdentity(excerpt);
                 want = `Current Story containing "${exp.contains}" whose "**Story:**" field is exactly ${p.story.id}`;
-                if (!excerpt.includes(exp.contains))
-                    (ok = false), (why = ' The expected text is not in the Current Story section.');
+                if (ex.ambiguous)
+                    (ok = false), (why = ' active.md has more than one "## Current Story" section outside code blocks and comments; the active story is ambiguous. ' + FIX_HINT);
+                else if (!visible.includes(exp.contains))
+                    (ok = false), (why = ` The expected text is not in the Current Story section${ident.ok ? '.' : `, and ${ident.reason}`}`);
                 else if (!ident.ok)
                     (ok = false), (why = ` ${ident.reason}`);
                 else if (ident.id !== p.story.id)