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

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.4`). 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/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/brief/cli.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,iGAAiG;IACjG,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,YAAY,CAAC;AAIzD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CA6C9D;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BvF"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/brief/cli.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;GAcG;AAOH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,iGAAiG;IACjG,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,YAAY,CAAC;AAIzD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CA6C9D;AAQD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BvF"}

package/dist/brief/cli.js

@@ -14,6 +14,7 @@
  * -> 0, whatever the Freshness; usage error -> 1). It does not combine with
  * `--strict`, whose meaning (Completeness) belongs to the brief.
  */
+import { colorEnabled, paint, tintStatuses } from '../cli/style.js';
 import { collect } from './collect.js';
 import { render, DEFAULT_MAX_CHARS } from './render.js';
 import { reconcile, renderReconciliation } from './reconcile.js';
@@ -60,6 +61,11 @@ export function parseBriefArgs(args) {
     }
     return reconcileMode ? { ok: true, maxChars, strict, reconcile: true } : { ok: true, maxChars, strict };
 }
+/** Interactive terminals only: tints the Freshness / Completeness verdict words; plain text otherwise (byte for byte). */
+function tintBrief(text) {
+    const on = colorEnabled();
+    return tintStatuses(on ? text.replace(/^MONOLITH [A-Z ]+$/m, (h) => paint(h, 'head', true)) : text, on, ['Freshness', 'Completeness']);
+}
 export async function runBrief(args, targetDir = process.cwd()) {
     const parsed = parseBriefArgs(args);
     if (!parsed.ok) {
@@ -70,11 +76,11 @@ export async function runBrief(args, targetDir = process.cwd()) {
         if (!model.freshness || !model.freshnessEvidence) {
             throw new Error('monolith brief --reconcile: no freshness evidence could be collected.');
         }
-        process.stdout.write(renderReconciliation(reconcile(model.freshnessEvidence, model.freshness), parsed.maxChars).text);
+        process.stdout.write(tintBrief(renderReconciliation(reconcile(model.freshnessEvidence, model.freshness), parsed.maxChars).text));
         process.exit(0);
     }
     const { text, completeness } = render(model, parsed.maxChars);
-    process.stdout.write(text);
+    process.stdout.write(tintBrief(text));
     if (completeness === 'INCOMPLETE') {
         console.error('monolith brief: result is INCOMPLETE — see the Diagnostics section above.');
     }

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;AAmBpB,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,QAAa,CAAC;AAwUnD,wBAAsB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAqEpE"}

package/dist/brief/collect.js

@@ -16,11 +16,13 @@ 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';
-import { evaluateFreshness, parseActiveStoryClaim, parseRoadmapActiveStory, parseRoadmapStatuses, parseStoryIndexStatuses, } from './freshness.js';
-import { readGitSignals } from './git-signals.js';
+import { evaluateFreshness, extractWorkItemIds, parseActiveStoryClaim, parseRoadmapActiveStory, parseRoadmapStatuses, parseStoryIndexStatuses, } from './freshness.js';
+import { readBlobAt, readGitSignals } from './git-signals.js';
+import { attributeKnowledge } from './knowledge.js';
 import { ideaStore, listIdeas } from '../ideas/index.js';
 import { ideaNumber } from '../ideas/format.js';
 const RECENT_FINISHED_MISSIONS_LIMIT = 5;
@@ -202,7 +204,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 {
@@ -267,13 +271,21 @@ function collectFreshness(targetDir, monolithRoot, root, story) {
     const content = new Map(docs.map((rel) => [rel, readStateDocument(targetDir, monolithRoot, root, rel)]));
     const roadmap = content.get(ROADMAP_INDEX_REL) ?? null;
     const storyIndex = content.get(STORY_INDEX_REL) ?? null;
+    const git = readGitSignals(targetDir, stateFiles);
     const evidence = {
-        git: readGitSignals(targetDir, stateFiles),
+        git,
+        knowledge: attributeKnowledge(git, {
+            monolithRoot,
+            stateFiles: new Set(stateFiles),
+            readBlob: (sha, rel) => readBlobAt(targetDir, sha, rel),
+            hasWorkItem: (subject) => extractWorkItemIds(subject).length > 0,
+        }),
         activeStory: story.fileExists && story.hasCurrentStorySection ? parseActiveStoryClaim(story.excerpt) : { kind: 'unknown' },
         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,8 +19,10 @@
  *            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';
+import type { KnowledgeEvidence } from './knowledge.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 type FreshnessReasonCode = 'STATE_CONTRADICTION' | 'UNRECORDED_WORK' | 'GIT_UNAVAILABLE' | 'STATE_NOT_IN_GIT' | 'GIT_HISTORY_TRUNCATED' | 'GIT_HISTORY_SHALLOW' | 'UNATTRIBUTED_ACTIVITY' | 'NO_ACTIVITY_SINCE_STATE_UPDATE' | 'ACTIVITY_RECORDED';
 export interface FreshnessReason {
     code: FreshnessReasonCode;
     message: string;
@@ -36,7 +38,7 @@ export interface GitCommitSignal {
     /** Paths changed by the commit, relative to the project directory. Empty for plain merges. */
     files: string[];
 }
-export type GitUnavailableReason = 'GIT_NOT_INSTALLED' | 'NOT_A_GIT_REPOSITORY' | 'GIT_FAILED';
+export type GitUnavailableReason = 'GIT_NOT_INSTALLED' | 'NOT_A_GIT_REPOSITORY' | 'GIT_FAILED' | 'GIT_OUTPUT_INVALID';
 export type GitSignals = {
     status: 'unavailable';
     reason: GitUnavailableReason;
@@ -51,14 +53,22 @@ export type GitSignals = {
     commitsSince: GitCommitSignal[];
     /** True when git history was cut at the read limit — the picture is partial. */
     truncated: boolean;
+    /** True in a shallow clone: history before the boundary is absent, so "no later activity" proves nothing. */
+    shallow?: boolean;
 };
 export type StoryClaim = {
     kind: 'none';
 } | {
     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;
@@ -73,6 +83,8 @@ export interface FreshnessEvidence {
     recordedText: string;
     /** Repo-relative-to-project paths that are state documents (their own commits are not "activity"). */
     stateFiles: ReadonlySet<string>;
+    /** KA-001: commits explained by registered independent knowledge. Absent = none (older callers). */
+    knowledge?: KnowledgeEvidence;
 }
 export interface FreshnessResult {
     status: FreshnessStatus;
@@ -92,13 +104,44 @@ 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 interface Contradiction {
+    message: string;
+    documents: string[];
+}
+/**
+ * Contradictions between the state documents. Shared by `brief` (freshness /
+ * `--reconcile`) and `finalize` (FIN-002 consistency assessment) so that there
+ * is exactly one definition of "these documents disagree".
+ */
+export declare function findContradictions(ev: Pick<FreshnessEvidence, 'activeStory' | 'roadmapActiveStory' | 'roadmapStatuses' | 'storyIndexStatuses'>): Contradiction[];
 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)
@@ -115,8 +163,19 @@ function listIds(ids) {
 function isDone(status) {
     return status === 'COMPLETED' || status === 'DONE';
 }
-function findContradictions(ev) {
+/**
+ * Contradictions between the state documents. Shared by `brief` (freshness /
+ * `--reconcile`) and `finalize` (FIN-002 consistency assessment) so that there
+ * is exactly one definition of "these documents disagree".
+ */
+export 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}".`,
@@ -171,6 +230,7 @@ export function evaluateFreshness(ev) {
             GIT_NOT_INSTALLED: 'git is not installed or not runnable',
             NOT_A_GIT_REPOSITORY: 'the project is not inside a git repository',
             GIT_FAILED: 'git could not be queried',
+            GIT_OUTPUT_INVALID: 'git returned history that could not be parsed unambiguously',
         };
         reasons.push({ code: 'GIT_UNAVAILABLE', message: `Cannot compare state with history: ${why[ev.git.reason]}.` });
         gitVerdict = 'unknown';
@@ -187,9 +247,12 @@ export function evaluateFreshness(ev) {
         base.activityCount = activity.length;
         const referenced = new Set();
         let unattributed = 0;
+        let knowledgeCommits = 0;
         for (const c of activity) {
             const ids = extractWorkItemIds(c.subject);
-            if (ids.length === 0)
+            if (ids.length === 0 && ev.knowledge?.attributed.has(c.sha))
+                knowledgeCommits++;
+            else if (ids.length === 0)
                 unattributed++;
             for (const id of ids)
                 referenced.add(id);
@@ -211,6 +274,13 @@ export function evaluateFreshness(ev) {
             });
             gitVerdict = 'unknown';
         }
+        else if (ev.git.shallow === true) {
+            reasons.push({
+                code: 'GIT_HISTORY_SHALLOW',
+                message: 'The repository is a shallow clone: history before its boundary is not available, so the check cannot be complete.',
+            });
+            gitVerdict = 'unknown';
+        }
         else if (unattributed > 0) {
             reasons.push({
                 code: 'UNATTRIBUTED_ACTIVITY',
@@ -229,11 +299,13 @@ export function evaluateFreshness(ev) {
         else {
             reasons.push({
                 code: 'ACTIVITY_RECORDED',
-                message: `All ${activity.length} commit(s) after the last state update reference work items that the state documents mention.`,
+                message: knowledgeCommits === 0
+                    ? `All ${activity.length} commit(s) after the last state update reference work items that the state documents mention.`
+                    : `All ${activity.length} commit(s) after the last state update either reference work items that the state documents mention (${activity.length - knowledgeCommits}) or are attributed to registered independent knowledge (${knowledgeCommits}).`,
             });
             gitVerdict = 'fresh';
         }
-        if (activity.length > 0 && ev.activeStory.kind === 'none') {
+        if (activity.length - knowledgeCommits > 0 && ev.activeStory.kind === 'none') {
             warnings.push('Git activity exists after the last recorded state update, but no active story is recorded.');
         }
     }

package/dist/brief/git-signals.d.ts

@@ -1,17 +1,44 @@
 /**
- * Read-only git signals for the freshness check (SELF-AWARENESS-001).
+ * Read-only, local, offline git signals for the freshness check
+ * (SELF-AWARENESS-001, hardened in alpha.4 by A4-SEC-01/02).
  *
- * Runs only `git log` and `git rev-parse`, never a command that writes, never
- * through a shell, with config that could launch helper programs switched off.
- * Any failure degrades to `{ status: 'unavailable' }` — git being absent,
- * broken or refusing the directory must never fail the brief.
+ * Contract:
+ *  - Only `git log`, `git rev-list`, `git diff-tree`, `git rev-parse` and
+ *    `git cat-file` are run; never a command that writes, never through a shell.
+ *  - Offline: lazy fetch of missing objects (partial clones) is disabled
+ *    (`GIT_NO_LAZY_FETCH=1`) and every transport is refused
+ *    (`GIT_ALLOW_PROTOCOL=none`), so a missing object is an error here, never a
+ *    download, an object-store write, or a program started from remote config.
+ *    (`-c protocol.allow=never` alone was tested and does NOT stop a `file`
+ *    promisor remote; it is kept only as an additional layer.)
+ *  - Structural parsing: output that carries attacker-influenced text (commit
+ *    subjects, file names) is never split on characters that text can contain.
+ *    Records use NUL (`-z`), which neither a subject nor a path can contain;
+ *    commit metadata and file lists come from separate commands; shas and dates
+ *    are validated against strict patterns; the commit list is cross-checked
+ *    against `git rev-list`. Anything unexpected is `GIT_OUTPUT_INVALID`.
+ *  - Fail closed: every failure degrades to `{ status: 'unavailable' }`, which
+ *    freshness turns into UNKNOWN. Git being absent, broken, refusing the
+ *    directory or returning something unparseable never fails the brief and is
+ *    never evidence of FRESH.
  */
 import type { GitSignals } from './freshness.js';
 /** Upper bound on commits read after the last state update. Hitting it marks the result truncated. */
 export declare const MAX_COMMITS_SINCE = 500;
+/** Largest blob `readBlobAt` will read; checked with `git cat-file -s` before the content is requested. */
+export declare const MAX_BLOB_BYTES: number;
+export declare function isGitSha(s: string): boolean;
 /**
  * @param targetDir project directory (git is run from here; paths are relative to it)
  * @param stateFiles state documents, relative to `targetDir`. Only existing ones need be passed.
  */
 export declare function readGitSignals(targetDir: string, stateFiles: string[]): GitSignals;
+/**
+ * Contents of `relPath` (relative to `targetDir`) as of commit `sha`, or null
+ * when the file does not exist there, is larger than `MAX_BLOB_BYTES`, is not
+ * available locally (a partial clone's missing blob is NOT fetched) or cannot be
+ * read. `git cat-file` only: read-only, no textconv, no shell. Used by KA-001 to
+ * judge an idea registration as it was when the commit was made.
+ */
+export declare function readBlobAt(targetDir: string, sha: string, relPath: string): string | null;
 //# sourceMappingURL=git-signals.d.ts.map

package/dist/brief/git-signals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-signals.d.ts","sourceRoot":"","sources":["../../src/brief/git-signals.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,gBAAgB,CAAC;AAElE,sGAAsG;AACtG,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAgCrC;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,UAAU,CAqDlF"}
+{"version":3,"file":"git-signals.d.ts","sourceRoot":"","sources":["../../src/brief/git-signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,gBAAgB,CAAC;AAElE,sGAAsG;AACtG,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,2GAA2G;AAC3G,eAAO,MAAM,cAAc,QAAa,CAAC;AAqDzC,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE3C;AAyDD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,UAAU,CA6DlF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUzF"}