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

package/dist/finalize/consistency.js

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

package/dist/finalize/core.d.ts

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

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

@@ -26,6 +26,7 @@ import { RootContainmentError, SafeWriteError, createFile, openParent, projectBo
 import { acquireLock } from '../coordinatorium/lock.js';
 import { extractCurrentStory } from '../brief/story.js';
 import { declaresNoActiveStory, maskNonContent } from '../brief/markdown-context.js';
+import { assessConsistency } from './consistency.js';
 import { validDate, validateRelPath } from './proposal.js';
 const MAX_DOC_BYTES = 4 * 1024 * 1024;
 const LOCK_NAME = 'finalize.lock';
@@ -105,28 +106,143 @@ export function renderCapsule(p) {
         `# STORY ${s.id} — ${s.title}`,
         '',
         '## Objective',
+        '',
         w.objective,
         '',
         '## Implementation Summary',
+        '',
         w.implementationSummary,
         '',
         '## Files Changed',
+        '',
         bullets(w.filesChanged),
         '',
         '## Tests',
+        '',
         w.tests,
         '',
         '## Key Decisions',
+        '',
         w.keyDecisions,
         '',
         '## ADRs Written',
+        '',
         bullets(w.adrs),
         '',
         '## Lessons Learned',
+        '',
         w.lessons,
         '',
     ].join('\n');
 }
+/**
+ * Format-equivalence of a capsule (FIN-001, made context-aware by A4-FIN-01).
+ * The capsule is created once and never overwritten, so "already present" used
+ * to mean byte-identical; a formatter pass (Prettier adds a blank line after
+ * every heading) then turned an unchanged capsule into a CONFLICT. Equivalence
+ * is deliberately narrow and NOT a general whitespace-insensitive comparison.
+ * Ignored: line endings (CRLF/LF), trailing whitespace on a line that is plain
+ * prose, a single blank line directly after an ATX heading, and trailing blank
+ * lines at end of file. NOT ignored, because whitespace carries meaning there:
+ *  - anything inside a fenced code block (``` or ~~~), an indented code block /
+ *    4-space-or-tab-indented line, an HTML comment, or YAML frontmatter
+ *    (`---` ... `---` at the very top; an unterminated one protects the whole
+ *    file) — those lines are compared verbatim;
+ *  - a Markdown hard line break (two or more trailing spaces before a line that
+ *    continues the paragraph): kept as a break (any run of 2+ spaces is the
+ *    same break); a backslash break is not whitespace and is always compared;
+ *  - blank lines anywhere else (paragraph breaks).
+ */
+export function capsuleCanonical(s) {
+    const lines = norm(s).split('\n');
+    const verbatim = lines.map(() => false);
+    const fenceOpen = (l) => {
+        const m = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(l);
+        return m !== null && !(m[1][0] === '`' && m[2].includes('`')) ? m : null;
+    };
+    let i = 0;
+    if (lines[0] === '---') {
+        const close = lines.findIndex((l, k) => k > 0 && (l === '---' || l === '...'));
+        const end = close === -1 ? lines.length - 1 : close; // unterminated: cannot tell where it ends
+        for (let k = 0; k <= end; k++)
+            verbatim[k] = true;
+        i = end + 1;
+    }
+    let fence = null;
+    let comment = false;
+    let htmlBlock = false; // an HTML block runs to the next blank line; its content is not Markdown
+    for (; i < lines.length; i++) {
+        const l = lines[i];
+        if (htmlBlock) {
+            if (l.trim() === '')
+                htmlBlock = false;
+            else {
+                verbatim[i] = true;
+                continue;
+            }
+        }
+        if (fence !== null) {
+            verbatim[i] = true;
+            const close = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(l);
+            if (close !== null && close[1][0] === fence.ch && close[1].length >= fence.len)
+                fence = null;
+        }
+        else if (comment) {
+            verbatim[i] = true;
+            if (l.includes('-->'))
+                comment = false;
+        }
+        else {
+            const open = fenceOpen(l);
+            if (open !== null) {
+                verbatim[i] = true;
+                fence = { ch: open[1][0], len: open[1].length };
+            }
+            else if (/^ {0,3}<!--/.test(l)) {
+                verbatim[i] = true;
+                if (!l.includes('-->', l.indexOf('<!--') + 4))
+                    comment = true;
+            }
+            else if (/^ {0,3}<[A-Za-z\/!?]/.test(l)) {
+                verbatim[i] = true;
+                htmlBlock = true;
+            }
+            else if (/^ {0,3}>/.test(l)) {
+                verbatim[i] = true; // blockquote: may hold fences/code whose whitespace we cannot track
+            }
+            else if (/^(?: {4}|\t)/.test(l)) {
+                verbatim[i] = true; // indented code block (or an indented continuation): compared as written
+            }
+        }
+    }
+    const out = [];
+    const outVerbatim = [];
+    let skippable = false; // a blank line right after an ATX heading, at most one
+    for (let k = 0; k < lines.length; k++) {
+        let l = lines[k];
+        if (verbatim[k]) {
+            out.push(l);
+            outVerbatim.push(true);
+            skippable = false;
+            continue;
+        }
+        const next = k + 1 < lines.length ? lines[k + 1] : undefined;
+        const hardBreak = / {2}$/.test(l) && l.trim() !== '' && !/^#{1,6}[ \t]/.test(l) && next !== undefined && next.trim() !== '' && !/^#{1,6}([ \t]|$)/.test(next) && fenceOpen(next) === null;
+        l = l.replace(/[ \t]+$/, '') + (hardBreak ? '  ' : '');
+        if (l === '' && skippable) {
+            skippable = false;
+            continue;
+        }
+        skippable = /^#{1,6}[ \t]/.test(l);
+        out.push(l);
+        outVerbatim.push(false);
+    }
+    while (out.length > 0 && out[out.length - 1] === '' && !outVerbatim[outVerbatim.length - 1]) {
+        out.pop();
+        outVerbatim.pop();
+    }
+    return out.join('\n');
+}
 const capsulePathOf = (root, p) => `${root}/memory/working/phases/${p.story.phase}/stories/${p.story.slug}.md`;
 function historyHeading(p) {
     return `## ${p.story.id} — ${p.story.title} (${p.story.date})`;
@@ -496,6 +612,8 @@ function buildInternals(ctx, p) {
         }
         else if (d.content === content)
             out.push({ target: { ...t, state: 'done', reason: 'capsule already present with identical content', base: 'DONE' } });
+        else if (capsuleCanonical(d.content) === capsuleCanonical(content))
+            out.push({ target: { ...t, state: 'done', reason: 'capsule already present; differs from the rendered form only in formatting (line endings, trailing whitespace, blank lines after headings) — left untouched', base: 'DONE' } });
         else
             out.push({ target: { ...t, state: 'conflict', reason: 'a different file already exists at the capsule path; it is never overwritten', base: d.sha } });
     }
@@ -667,7 +785,28 @@ function plan(ctx, p) {
         evidence: [integrity.sha, governance.sha],
         config: [ctx.config.requiredDocs, ctx.config.allowedDocs],
     }));
-    return { plan: { status, storyId: p.story.id, digest, partial: someDone && !allDone, checks, targets, diagnostics }, internals };
+    const finalText = (rel) => {
+        const it = internals.find((i) => i.target.path === rel);
+        if (it?.write)
+            return it.write.content;
+        const d = readDoc(ctx.projectRoot, rel);
+        return d.kind === 'present' ? d.content : null;
+    };
+    let consistency;
+    try {
+        consistency = assessConsistency({
+            active: finalText(`${ctx.root}/memory/working/active.md`),
+            roadmap: finalText(`${ctx.root}/context/maps/roadmap-index.md`),
+            storyIndex: finalText(`${ctx.root}/memory/working/story-index.md`),
+            writtenPaths: targets.filter((t) => t.kind !== 'capsule' && t.kind !== 'execution-history' && (t.state === 'pending' || t.state === 'done')).map((t) => t.path),
+            projected: !allDone,
+            managedRoot: ctx.root,
+        });
+    }
+    catch (err) {
+        consistency = { status: 'NOT_VERIFIED', projected: !allDone, findings: [], notVerified: [`the assessment failed: ${err.message}`], scope: 'not assessed' };
+    }
+    return { plan: { status, storyId: p.story.id, digest, partial: someDone && !allDone, checks, targets, diagnostics, consistency }, internals };
 }
 export function planFinalization(targetDir, proposal) {
     const c = makeContext(targetDir);

package/dist/ideas/cli.d.ts

@@ -11,6 +11,7 @@ interface AddFlags {
     description?: string;
     context?: string;
     descriptionStdin?: boolean;
+    paths?: string[];
 }
 /** Strict: every flag needs a value, none may repeat, unknown flags and stray arguments are errors. */
 export declare function parseAddArgs(args: string[]): AddFlags;

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/ideas/cli.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAiBvC,UAAU,QAAQ;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAMD,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CA4BrD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,KAAK,GAAE,QAAQ,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyB1G;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,EAAE,KAAK,GAAE,QAAQ,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhJ;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB1F;AAiBD,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1F;AAED,6CAA6C;AAC7C,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7F"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/ideas/cli.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAiBvC,UAAU,QAAQ;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAOD,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CAmCrD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,KAAK,GAAE,QAAQ,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyB1G;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,EAAE,KAAK,GAAE,QAAQ,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhJ;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB1F;AAkBD,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1F;AAED,6CAA6C;AAC7C,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7F"}

package/dist/ideas/cli.js

@@ -9,7 +9,7 @@
 import { reportWriteWarning } from '../root/index.js';
 import { addIdea, getIdea, ideaStore, listIdeas } from './store.js';
 import { IDEA_LIMITS, IdeaError } from './types.js';
-const ADD_USAGE = 'Usage: monolith idea add --title "..." (--description "..." | --description-stdin) [--context "..."]';
+const ADD_USAGE = 'Usage: monolith idea add --title "..." (--description "..." | --description-stdin) [--context "..."] [--path <project-relative document file> ...]';
 /** UTF-8 needs at most 4 bytes per UTF-16 code unit's worth of text; anything larger cannot fit the description limit. */
 const STDIN_MAX_BYTES = IDEA_LIMITS.description * 4;
 const LIST_USAGE = 'Usage: monolith idea list';
@@ -21,7 +21,8 @@ function printable(s) {
 }
 const ADD_FLAGS = ['--title', '--description', '--context'];
 const STDIN_FLAG = '--description-stdin';
-const KNOWN_FLAGS = [...ADD_FLAGS, STDIN_FLAG];
+const PATH_FLAG = '--path';
+const KNOWN_FLAGS = [...ADD_FLAGS, STDIN_FLAG, PATH_FLAG];
 /** Strict: every flag needs a value, none may repeat, unknown flags and stray arguments are errors. */
 export function parseAddArgs(args) {
     const out = {};
@@ -36,6 +37,14 @@ export function parseAddArgs(args) {
             out.descriptionStdin = true;
             continue;
         }
+        if (flag === PATH_FLAG) {
+            const v = args[i + 1];
+            if (v === undefined || KNOWN_FLAGS.includes(v))
+                throw new IdeaError('IDEA_INVALID_INPUT', `${flag} needs a value.\n${ADD_USAGE}`);
+            (out.paths ??= []).push(v);
+            i++;
+            continue;
+        }
         const key = flag.slice(2);
         if (key in out)
             throw new IdeaError('IDEA_INVALID_INPUT', `${flag} was given more than once.\n${ADD_USAGE}`);
@@ -92,7 +101,7 @@ export async function runIdeaAdd(args, targetDir = process.cwd(), stdin = proces
     const flags = parseAddArgs(args);
     const description = flags.descriptionStdin ? await readStdinText(stdin) : flags.description;
     const store = ideaStore(targetDir);
-    const { idea, path } = addIdea(store, { title: flags.title, description, context: flags.context }, { onWarning: (w) => reportWriteWarning(w) });
+    const { idea, path } = addIdea(store, { title: flags.title, description, context: flags.context, ...(flags.paths !== undefined ? { paths: flags.paths } : {}) }, { onWarning: (w) => reportWriteWarning(w) });
     console.log(`Saved ${idea.id} [${idea.status}]: ${printable(idea.title)}`);
     console.log(`  file: ${path}`);
     console.log('Current task and focus are unchanged. Recall with `monolith idea list` / `monolith idea show ' + idea.id + '`.');
@@ -130,6 +139,8 @@ function formatIdea(i) {
     ];
     if (i.tags !== undefined && i.tags.length > 0)
         lines.push(`  tags:       ${i.tags.map(printable).join(', ')}`);
+    if (i.paths !== undefined && i.paths.length > 0)
+        lines.push(`  paths:      ${i.paths.map(printable).join(', ')}`);
     lines.push('  context:    ' + (i.context === undefined ? '(none)' : ''));
     if (i.context !== undefined)
         lines.push(...i.context.split('\n').map((l) => `    ${l}`));

package/dist/ideas/format.d.ts

@@ -9,6 +9,7 @@
  *   createdAt: "2026-..."
  *   context: "..."          (optional)
  *   tags: ["a", "b"]        (optional)
+ *   paths: ["docs/x.md"]  (optional, KA-001: exact document files of the registered artifact; see attributionPathProblem)
  *   ---
  *
  *   ## Description
@@ -21,6 +22,35 @@
  * The description is the body: no escaping, no trimming.
  */
 import { type Idea, type NewIdea } from './types.js';
+/**
+ * KA-001: a registered artifact path. Project-relative, `/`-separated, no
+ * traversal, no globs; a trailing `/` makes it a directory prefix. Returns the
+ * reason it is invalid, or null.
+ */
+export declare function invalidArtifactPath(p: unknown): string | null;
+/** True when `file` is covered by one of the registered `paths` (exact file, or `dir/` prefix). */
+export declare function artifactPathsCover(paths: readonly string[], file: string): boolean;
+/**
+ * Extensions of documents that can be registered as independent knowledge.
+ * Deliberately an allow-list of *document* formats, not of directories: a
+ * strategy paper may live anywhere, but source code, configuration and
+ * scripts never qualify, whatever directory they are in.
+ */
+export declare const KNOWLEDGE_DOCUMENT_EXTENSIONS: readonly string[];
+/**
+ * A4-SEC-03: the policy for a path that is to ATTRIBUTE commits to independent
+ * knowledge (stricter than `invalidArtifactPath`, which only says the path is
+ * well-formed). A registered path must be
+ *  - one exact file: a `dir/` prefix would turn every later change under it into
+ *    "knowledge" (`src/`, the project root, ...);
+ *  - a document (`KNOWLEDGE_DOCUMENT_EXTENSIONS`): registering `src/pay.ts` would
+ *    let an idea id launder ordinary code;
+ *  - outside the MONOLITH root (case-insensitive; `.monolith` is always refused
+ *    too): governance state is never independent knowledge.
+ * Returns the reason a path is refused, or null. Registration says WHICH file a
+ * commit may be explained by; it does not say the change was reviewed or allowed.
+ */
+export declare function attributionPathProblem(p: string, monolithRoot?: string): string | null;
 export declare function isIdeaId(value: string): boolean;
 export declare function ideaNumber(id: string): number;
 export declare function formatIdeaId(n: number): string;
@@ -28,7 +58,7 @@ export declare function formatIdeaId(n: number): string;
 export declare function ideaIdFromFileName(name: string): string | null;
 export declare function ideaFileName(id: string): string;
 /** Validates user input; returns it unchanged (content is never trimmed or rewritten). */
-export declare function validateNewIdea(input: NewIdea): NewIdea;
+export declare function validateNewIdea(input: NewIdea, monolithRoot?: string): NewIdea;
 export declare function serializeIdea(idea: Idea): string;
 /**
  * Parse an idea file. `expectedId` is the id implied by the file name; a

package/dist/ideas/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/ideas/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAyC,KAAK,IAAI,EAAmB,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAS7G,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAG/C;AAaD,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAmBvD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAahD;AAqBD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA0DhE"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/ideas/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAyC,KAAK,IAAI,EAAmB,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAS7G;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAY7D;AAED,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAElF;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAA0C,CAAC;AAOtG;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBtF;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAG/C;AAaD,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CA4B9E;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAchD;AAqBD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAsEhE"}

package/dist/ideas/format.js

@@ -9,6 +9,7 @@
  *   createdAt: "2026-..."
  *   context: "..."          (optional)
  *   tags: ["a", "b"]        (optional)
+ *   paths: ["docs/x.md"]  (optional, KA-001: exact document files of the registered artifact; see attributionPathProblem)
  *   ---
  *
  *   ## Description
@@ -27,6 +28,85 @@ const FILE_RE = /^(IDEA-\d{3,9})\.md$/;
 // C0 controls, DEL and C1 controls (a title is shown in a terminal).
 // eslint-disable-next-line no-control-regex
 const CONTROL_RE = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+/**
+ * KA-001: a registered artifact path. Project-relative, `/`-separated, no
+ * traversal, no globs; a trailing `/` makes it a directory prefix. Returns the
+ * reason it is invalid, or null.
+ */
+export function invalidArtifactPath(p) {
+    if (typeof p !== 'string' || p === '')
+        return 'path must be a non-empty string';
+    if (p.length > IDEA_LIMITS.pathLength)
+        return `path is too long (> ${IDEA_LIMITS.pathLength} characters)`;
+    if (CONTROL_RE.test(p))
+        return 'path must not contain control characters';
+    if (p.includes('"'))
+        return 'path must not contain a double quote';
+    if (p.includes('\\'))
+        return 'path must use "/" separators';
+    if (p.startsWith('/') || /^[A-Za-z]:/.test(p))
+        return 'path must be project-relative';
+    if (/[*?[\]{}]/.test(p))
+        return 'path must not contain glob characters';
+    if (p !== p.trim())
+        return 'path must not start or end with whitespace';
+    const segments = p.endsWith('/') ? p.slice(0, -1).split('/') : p.split('/');
+    if (segments.some((x) => x === '' || x === '.' || x === '..'))
+        return 'path must not contain empty, "." or ".." segments';
+    return null;
+}
+/** True when `file` is covered by one of the registered `paths` (exact file, or `dir/` prefix). */
+export function artifactPathsCover(paths, file) {
+    return paths.some((p) => (p.endsWith('/') ? file.startsWith(p) : file === p));
+}
+/**
+ * Extensions of documents that can be registered as independent knowledge.
+ * Deliberately an allow-list of *document* formats, not of directories: a
+ * strategy paper may live anywhere, but source code, configuration and
+ * scripts never qualify, whatever directory they are in.
+ */
+export const KNOWLEDGE_DOCUMENT_EXTENSIONS = ['.md', '.mdx', '.markdown', '.adoc'];
+/** Directories whose documents steer tools, agents or dependencies; never knowledge (compared lower-case). */
+const KNOWLEDGE_DENIED_DIRS = ['.git', '.claude', '.cursor', '.github', '.vscode', '.husky', 'node_modules'];
+/** Agent-instruction file names (compared lower-case): changing them changes agent behaviour. */
+const KNOWLEDGE_DENIED_NAMES = ['agents.md', 'agent.md', 'claude.md', 'gemini.md', 'skill.md', 'conventions.md', 'codeowners.md', 'copilot-instructions.md', '.cursorrules', '.windsurfrules.md'];
+/**
+ * A4-SEC-03: the policy for a path that is to ATTRIBUTE commits to independent
+ * knowledge (stricter than `invalidArtifactPath`, which only says the path is
+ * well-formed). A registered path must be
+ *  - one exact file: a `dir/` prefix would turn every later change under it into
+ *    "knowledge" (`src/`, the project root, ...);
+ *  - a document (`KNOWLEDGE_DOCUMENT_EXTENSIONS`): registering `src/pay.ts` would
+ *    let an idea id launder ordinary code;
+ *  - outside the MONOLITH root (case-insensitive; `.monolith` is always refused
+ *    too): governance state is never independent knowledge.
+ * Returns the reason a path is refused, or null. Registration says WHICH file a
+ * commit may be explained by; it does not say the change was reviewed or allowed.
+ */
+export function attributionPathProblem(p, monolithRoot) {
+    const syntax = invalidArtifactPath(p);
+    if (syntax !== null)
+        return syntax;
+    if (p.endsWith('/'))
+        return 'a directory prefix is not allowed; register the exact document file';
+    const lower = p.toLowerCase();
+    for (const root of new Set(['.monolith', (monolithRoot ?? '.monolith').replace(/^(\.\/)+/, '').replace(/\/+$/, '').toLowerCase()])) {
+        if (root !== '' && root !== '.' && (lower === root || lower.startsWith(`${root}/`)))
+            return `a path inside the MONOLITH root (${root}) is never independent knowledge`;
+    }
+    if (/[\u200b-\u200f\u2028-\u202e\u2060-\u2064\ufeff\u00a0]/.test(p))
+        return 'path must not contain invisible or look-alike whitespace characters';
+    const segs = lower.split('/');
+    const hiddenDir = segs.slice(0, -1).find((x) => x.startsWith('.') || KNOWLEDGE_DENIED_DIRS.includes(x));
+    if (hiddenDir !== undefined)
+        return `a path under ${hiddenDir}/ (hidden or tool/dependency directory) configures tools or dependencies and is never independent knowledge`;
+    if (KNOWLEDGE_DENIED_NAMES.includes(segs[segs.length - 1]))
+        return 'agent-instruction files cannot be registered as independent knowledge';
+    if (!KNOWLEDGE_DOCUMENT_EXTENSIONS.some((e) => lower.endsWith(e))) {
+        return `only document files (${KNOWLEDGE_DOCUMENT_EXTENSIONS.join(', ')}) can be registered, not source code or configuration`;
+    }
+    return null;
+}
 export function isIdeaId(value) {
     return ID_RE.test(value);
 }
@@ -57,7 +137,7 @@ function wellFormed(s) {
     return !LONE_SURROGATE_RE.test(s);
 }
 /** Validates user input; returns it unchanged (content is never trimmed or rewritten). */
-export function validateNewIdea(input) {
+export function validateNewIdea(input, monolithRoot) {
     const { title, description, context } = input;
     if (typeof title !== 'string' || title.trim() === '')
         throw invalid('title must not be empty.');
@@ -77,6 +157,19 @@ export function validateNewIdea(input) {
             throw invalid(`context is too long (${context.length} > ${IDEA_LIMITS.context} characters).`);
         }
     }
+    if (input.paths !== undefined) {
+        if (!Array.isArray(input.paths) || input.paths.length === 0)
+            throw invalid('paths, when given, must be a non-empty list.');
+        if (input.paths.length > IDEA_LIMITS.paths)
+            throw invalid(`too many paths (${input.paths.length} > ${IDEA_LIMITS.paths}).`);
+        for (const p of input.paths) {
+            const bad = attributionPathProblem(p, monolithRoot);
+            if (bad !== null)
+                throw invalid(`paths: ${bad} (${JSON.stringify(String(p).slice(0, 80))}).`);
+        }
+        if (new Set(input.paths).size !== input.paths.length)
+            throw invalid('paths must not repeat.');
+    }
     for (const [name, v] of [['title', title], ['description', description], ['context', context]]) {
         if (v !== undefined && !wellFormed(v))
             throw invalid(`${name} contains an unpaired surrogate and cannot be stored losslessly.`);
@@ -96,6 +189,8 @@ export function serializeIdea(idea) {
         lines.push(`context: ${JSON.stringify(idea.context)}`);
     if (idea.tags !== undefined && idea.tags.length > 0)
         lines.push(`tags: ${JSON.stringify(idea.tags)}`);
+    if (idea.paths !== undefined && idea.paths.length > 0)
+        lines.push(`paths: ${JSON.stringify(idea.paths)}`);
     lines.push('---');
     return `${lines.join('\n')}\n${BODY_HEADING}${idea.description}\n`;
 }
@@ -190,5 +285,18 @@ export function parseIdea(expectedId, text) {
         }
         idea.tags = tags;
     }
+    if ('paths' in fm) {
+        let paths;
+        try {
+            paths = JSON.parse(fm.paths);
+        }
+        catch {
+            throw corrupt(expectedId, '"paths" is not a JSON array of strings.');
+        }
+        if (!Array.isArray(paths) || paths.length > IDEA_LIMITS.paths || !paths.every((x) => invalidArtifactPath(x) === null)) {
+            throw corrupt(expectedId, '"paths" is not a JSON array of valid project-relative paths.');
+        }
+        idea.paths = paths;
+    }
     return idea;
 }

package/dist/ideas/store.d.ts

@@ -26,6 +26,8 @@ import { type Idea, type IdeaEntry, type NewIdea } from './types.js';
 export interface IdeaStore {
     projectRoot: string;
     rootAbs: string;
+    /** Validated relative MONOLITH root (`.monolith` by default). */
+    monolithRoot: string;
     dirAbs: string;
     boundary: WriteBoundary;
 }

package/dist/ideas/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/ideas/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAWL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAA0B,KAAK,IAAI,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAQ7F,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAetD;AAED,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACrB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AA+DD,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,aAAa,CA4ElG;AAsBD,8GAA8G;AAC9G,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAM1D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,CAiBvD"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/ideas/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAWL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAA0B,KAAK,IAAI,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAQ7F,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAgBtD;AAED,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACrB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AA+DD,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,aAAa,CA6ElG;AAsBD,8GAA8G;AAC9G,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAM1D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,CAiBvD"}

package/dist/ideas/store.js

@@ -45,6 +45,7 @@ export function ideaStore(targetDir) {
     return {
         projectRoot: root.projectRoot,
         rootAbs: root.rootAbs,
+        monolithRoot: root.monolithRoot,
         dirAbs: join(root.rootAbs, IDEAS_REL),
         boundary: projectBoundary(root.projectRoot),
     };
@@ -115,7 +116,7 @@ function reserveId(markers, id, createdAt, opts) {
     }
 }
 export function addIdea(store, input, opts = {}) {
-    validateNewIdea(input);
+    validateNewIdea(input, store.monolithRoot);
     // `add` only creates `memory/long-term/ideas` inside an existing instance; it never invents `.monolith/`.
     let rootStat;
     try {
@@ -164,6 +165,8 @@ export function addIdea(store, input, opts = {}) {
         const idea = { id, title: input.title, description: input.description, createdAt, status: 'inbox' };
         if (input.context !== undefined)
             idea.context = input.context;
+        if (input.paths !== undefined)
+            idea.paths = input.paths;
         const text = serializeIdea(idea);
         // The character limits do not bound the file (UTF-8 and JSON escaping expand text), and the reader refuses
         // files over `fileBytes`: refuse here, before an id is reserved, so nothing is saved that cannot be read back.