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

package/dist/brief/git-signals.js

@@ -1,14 +1,32 @@
 /**
- * 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 { execFileSync } from 'child_process';
 /** Upper bound on commits read after the last state update. Hitting it marks the result truncated. */
 export const MAX_COMMITS_SINCE = 500;
+/** Largest blob `readBlobAt` will read; checked with `git cat-file -s` before the content is requested. */
+export const MAX_BLOB_BYTES = 256 * 1024;
 const GIT_TIMEOUT_MS = 10_000;
 const GIT_MAX_BUFFER = 8 * 1024 * 1024;
 const SAFE_CONFIG = [
@@ -16,18 +34,37 @@ const SAFE_CONFIG = [
     '-c', 'core.pager=cat',
     '-c', 'log.showSignature=false',
     '-c', 'diff.external=',
+    '-c', 'core.quotepath=off',
+    '-c', 'protocol.allow=never',
+    '-c', 'protocol.file.allow=never',
 ];
+const SAFE_ENV = {
+    GIT_OPTIONAL_LOCKS: '0',
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_EXTERNAL_DIFF: '',
+    /** git >= 2.44: a missing object is an error instead of a fetch from the promisor remote. */
+    GIT_NO_LAZY_FETCH: '1',
+    /** Older git has no GIT_NO_LAZY_FETCH; refusing every transport stops the fetch itself. */
+    GIT_ALLOW_PROTOCOL: 'none',
+    /** State-document names come from config: never git pathspec magic. */
+    GIT_LITERAL_PATHSPECS: '1',
+    /** Replace refs would change the history this check reports. */
+    GIT_NO_REPLACE_OBJECTS: '1',
+};
 class GitMissingError extends Error {
 }
-function git(cwd, args) {
+class GitOutputError extends Error {
+}
+function git(cwd, args, opts = {}) {
     try {
         return execFileSync('git', [...SAFE_CONFIG, ...args], {
             cwd,
             encoding: 'utf8',
             timeout: GIT_TIMEOUT_MS,
-            maxBuffer: GIT_MAX_BUFFER,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0', GIT_EXTERNAL_DIFF: '' },
+            maxBuffer: opts.maxBuffer ?? GIT_MAX_BUFFER,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            input: opts.input ?? '',
+            env: { ...process.env, ...SAFE_ENV },
         });
     }
     catch (err) {
@@ -36,8 +73,76 @@ function git(cwd, args) {
         throw err;
     }
 }
-const RS = '\x1e'; // record separator, starts each commit
-const US = '\x1f'; // unit separator, between header fields
+const SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:Z|[+-]\d{2}:\d{2})$/;
+/** `:oldmode newmode sha sha STATUS` (and the combined-diff form `::m m m sha sha sha SS`). Never a file name: names are consumed as the token after one. */
+const RAW_HEADER_RE = /^:+[0-7]{6}(?: [0-7]{6})* [0-9a-f]{4,64}(?: [0-9a-f]{4,64})* [A-Z]+[0-9]*$/;
+export function isGitSha(s) {
+    return SHA_RE.test(s);
+}
+/** Tokens of NUL-terminated output. The output must be empty or end with NUL. */
+function nulTokens(out) {
+    if (out === '')
+        return [];
+    if (!out.endsWith('\0'))
+        throw new GitOutputError('output is not NUL-terminated');
+    return out.slice(0, -1).split('\0');
+}
+/** `git log -z --no-patch --format=%H%x00%cI%x00%s`: strict triples. */
+function parseCommitTriples(out) {
+    const t = nulTokens(out);
+    if (t.length % 3 !== 0)
+        throw new GitOutputError('commit records are not complete triples');
+    const seen = new Set();
+    const commits = [];
+    for (let i = 0; i < t.length; i += 3) {
+        const [sha, date, subject] = [t[i], t[i + 1], t[i + 2]];
+        if (!SHA_RE.test(sha))
+            throw new GitOutputError('a commit id is not a valid object name');
+        if (!DATE_RE.test(date))
+            throw new GitOutputError('a commit date is not an ISO-8601 date');
+        if (seen.has(sha))
+            throw new GitOutputError('a commit appears twice');
+        seen.add(sha);
+        commits.push({ sha, date, subject });
+    }
+    return commits;
+}
+/**
+ * `git diff-tree --stdin -z --raw`: `<sha> NUL` then zero or more
+ * `<:raw-header> NUL <path> NUL`. A path is only ever read as the token after a
+ * raw header, so no file name (spaces, newlines, control characters, even a
+ * 40-hex string) can be mistaken for a commit id or a header. Commits without
+ * changes (clean merges, empty commits) may be absent; order must be preserved.
+ */
+function parseFileLists(out, expected, prefix) {
+    const t = nulTokens(out);
+    const files = new Map();
+    let next = 0; // index into `expected` the next sha must be at or after
+    let i = 0;
+    while (i < t.length) {
+        const sha = t[i++];
+        const at = SHA_RE.test(sha) ? expected.indexOf(sha, next) : -1;
+        if (at === -1)
+            throw new GitOutputError('a file list belongs to an unexpected or out-of-order commit');
+        next = at + 1;
+        const list = [];
+        while (i < t.length && t[i].startsWith(':')) {
+            if (!RAW_HEADER_RE.test(t[i]) || i + 1 >= t.length)
+                throw new GitOutputError('a raw diff entry is malformed');
+            // `--relative` is ignored for combined (merge) entries, which start with `::`: make them project-relative here.
+            if (t[i].startsWith('::')) {
+                if (t[i + 1].startsWith(prefix))
+                    list.push(t[i + 1].slice(prefix.length));
+            }
+            else
+                list.push(t[i + 1]);
+            i += 2;
+        }
+        files.set(sha, list);
+    }
+    return files;
+}
 /**
  * @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.
@@ -56,46 +161,71 @@ export function readGitSignals(targetDir, stateFiles) {
     }
     try {
         // A repository without commits has no HEAD: nothing to compare with.
+        let head;
         try {
-            git(targetDir, ['rev-parse', '--verify', '--quiet', 'HEAD']);
+            head = git(targetDir, ['rev-parse', '--verify', '--quiet', 'HEAD']).trim();
         }
         catch {
             return { status: 'ok', lastStateUpdate: null, commitsSince: [], truncated: false };
         }
+        if (!SHA_RE.test(head))
+            throw new GitOutputError('HEAD did not resolve to an object name');
+        // A shallow clone has no history before its boundary: "no later commit" proves nothing.
+        const shallowOut = git(targetDir, ['rev-parse', '--is-shallow-repository']).trim();
+        if (shallowOut !== 'true' && shallowOut !== 'false')
+            throw new GitOutputError('unexpected shallow-repository answer');
+        const shallow = shallowOut === 'true';
         let lastStateUpdate = null;
         if (stateFiles.length > 0) {
-            const out = git(targetDir, ['log', '-1', `--format=%H${US}%cI`, '--', ...stateFiles]).trim();
-            if (out) {
-                const [sha, date] = out.split(US);
-                lastStateUpdate = { sha, date };
+            const t = nulTokens(git(targetDir, ['log', '-1', '-z', '--no-patch', '--format=%H%x00%cI', head, '--', ...stateFiles]));
+            if (t.length !== 0) {
+                if (t.length !== 2 || !SHA_RE.test(t[0]) || !DATE_RE.test(t[1]))
+                    throw new GitOutputError('the last state update is not a valid record');
+                lastStateUpdate = { sha: t[0], date: t[1] };
             }
         }
         if (!lastStateUpdate)
-            return { status: 'ok', lastStateUpdate: null, commitsSince: [], truncated: false };
-        const raw = git(targetDir, [
-            'log',
-            `-n${MAX_COMMITS_SINCE + 1}`,
-            '--no-ext-diff',
-            '--no-textconv',
-            '--relative',
-            '--name-only',
-            `--format=${RS}%H${US}%cI${US}%s`,
-            `${lastStateUpdate.sha}..HEAD`,
-        ]);
-        const commits = [];
-        for (const rec of raw.split(RS)) {
-            if (!rec.trim())
-                continue;
-            const nl = rec.indexOf('\n');
-            const header = nl === -1 ? rec : rec.slice(0, nl);
-            const [sha, date, subject] = header.split(US);
-            const files = (nl === -1 ? '' : rec.slice(nl + 1)).split('\n').filter((l) => l.trim() !== '');
-            commits.push({ sha, date, subject: subject ?? '', files });
+            return { status: 'ok', lastStateUpdate: null, commitsSince: [], truncated: false, shallow };
+        const range = `${lastStateUpdate.sha}..${head}`;
+        const limit = `-n${MAX_COMMITS_SINCE + 1}`;
+        const commits = parseCommitTriples(git(targetDir, ['log', '-z', '--no-patch', limit, '--format=%H%x00%cI%x00%s', range]));
+        // Independent cross-check of the commit list: same range, no free text in the output.
+        const listed = nulTokens(git(targetDir, ['rev-list', '-z', limit, range]));
+        if (listed.length !== commits.length || listed.some((s, k) => s !== commits[k].sha)) {
+            throw new GitOutputError('the commit list disagrees with git rev-list');
+        }
+        let fileLists = new Map();
+        if (commits.length > 0) {
+            const prefix = git(targetDir, ['rev-parse', '--show-prefix']).replace(/\n$/, '');
+            const raw = git(targetDir, ['diff-tree', '--stdin', '-z', '-r', '--raw', '-c', '--root', '--no-renames', '--no-ext-diff', '--no-textconv', '--ignore-submodules=none', '--relative'], { input: `${commits.map((c) => c.sha).join('\n')}\n` });
+            fileLists = parseFileLists(raw, commits.map((c) => c.sha), prefix);
         }
-        const truncated = commits.length > MAX_COMMITS_SINCE;
-        return { status: 'ok', lastStateUpdate, commitsSince: commits.slice(0, MAX_COMMITS_SINCE), truncated };
+        const signals = commits.map((c) => ({ sha: c.sha, date: c.date, subject: c.subject, files: fileLists.get(c.sha) ?? [] }));
+        const truncated = signals.length > MAX_COMMITS_SINCE;
+        return { status: 'ok', lastStateUpdate, commitsSince: signals.slice(0, MAX_COMMITS_SINCE), truncated, shallow };
+    }
+    catch (err) {
+        return { status: 'unavailable', reason: err instanceof GitOutputError ? 'GIT_OUTPUT_INVALID' : 'GIT_FAILED' };
+    }
+}
+/**
+ * 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 function readBlobAt(targetDir, sha, relPath) {
+    if (!SHA_RE.test(sha) || relPath.includes('\0') || relPath.startsWith('-'))
+        return null;
+    const spec = `${sha}:./${relPath}`;
+    try {
+        const size = git(targetDir, ['cat-file', '-s', spec]).trim();
+        if (!/^\d{1,9}$/.test(size) || Number(size) > MAX_BLOB_BYTES)
+            return null;
+        return git(targetDir, ['cat-file', 'blob', spec], { maxBuffer: MAX_BLOB_BYTES + 1024 });
     }
     catch {
-        return { status: 'unavailable', reason: 'GIT_FAILED' };
+        return null;
     }
 }

package/dist/brief/knowledge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Independent knowledge attribution (KA-001).
+ *
+ * A project may keep knowledge that belongs to no work item — a strategy
+ * paper, a vision note — without that being "unattributed activity" and
+ * without pretending it is part of the active story. The registration is an
+ * idea of the Idea Store (`IDEA-NNN`) that declares the artifact's `paths`.
+ *
+ * A commit is attributed to independent knowledge only when ALL hold:
+ *   1. its subject names no work item (a work item keeps its own semantics);
+ *   2. it names at least one `IDEA-NNN` that is a valid idea file **in the
+ *      tree of that very commit** (so registering an idea later never
+ *      legalises older commits, and a commit that registers or edits the idea
+ *      is itself never attributed — its own files are not covered);
+ *   3. the ideas it names declare `paths`, every declared path passes the
+ *      attribution policy (exact document files only — no directory prefixes, no
+ *      source code, nothing inside the MONOLITH root; `attributionPathProblem`),
+ *      and EVERY file the commit changed (other than state documents) is covered
+ *      by those paths;
+ *   4. no changed file lies inside the MONOLITH root;
+ *   5. it names at most MAX_IDEA_IDS_PER_COMMIT ideas, and the run stays inside a
+ *      fixed budget of blob reads (each read is a git subprocess).
+ * Attribution only EXPLAINS a commit. It is not approval: a registered, correctly
+ * attributed change may still be wrong or unreviewed.
+ * Anything else stays exactly what it was: unattributed activity. Nothing here
+ * activates a story, touches the roadmap or marks anything done; it only
+ * decides whether a commit is *explained*. No LLM, no network, read-only git.
+ */
+import type { GitSignals } from './freshness.js';
+export interface KnowledgeAttribution {
+    /** Idea ids named in the subject that were valid in the commit's tree. */
+    ideaIds: string[];
+    /** The paths those ideas declared (what the attribution rests on), in declaration order, without repeats. */
+    paths: string[];
+}
+export interface KnowledgeRejection {
+    /** One short reason a person can check. */
+    reason: string;
+}
+export interface KnowledgeEvidence {
+    /** Commit sha → attribution. Only commits that satisfied every rule. */
+    attributed: ReadonlyMap<string, KnowledgeAttribution>;
+    /** Commit sha → why a commit that NAMED an idea was not attributed. */
+    rejected: ReadonlyMap<string, KnowledgeRejection>;
+}
+export declare const EMPTY_KNOWLEDGE: KnowledgeEvidence;
+/** Upper bound of commits examined; beyond it the rest simply stay unattributed. */
+export declare const MAX_KNOWLEDGE_COMMITS = 200;
+/** A subject naming more ideas than this is refused without any git call (A4-SEC-05). */
+export declare const MAX_IDEA_IDS_PER_COMMIT = 8;
+/** Total blob reads (git subprocesses) per run; beyond it commits stay unattributed. */
+export declare const MAX_KNOWLEDGE_BLOB_READS = 64;
+export declare function ideaIdsInSubject(subject: string): string[];
+/** Reads `relPath` as of commit `sha`; null when it does not exist there (or cannot be read). */
+export type BlobReader = (sha: string, relPath: string) => string | null;
+export declare function attributeKnowledge(git: GitSignals, opts: {
+    monolithRoot: string;
+    stateFiles: ReadonlySet<string>;
+    readBlob: BlobReader;
+    hasWorkItem: (subject: string) => boolean;
+}): KnowledgeEvidence;
+//# sourceMappingURL=knowledge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/brief/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAmB,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6GAA6G;IAC7G,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IACtD,uEAAuE;IACvE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CACnD;AAED,eAAO,MAAM,eAAe,EAAE,iBAAkE,CAAC;AAEjG,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,yFAAyF;AACzF,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,wFAAwF;AACxF,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAI3C,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAE1D;AAED,iGAAiG;AACjG,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAEzE,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,UAAU,EACf,IAAI,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAA;CAAE,GAC/H,iBAAiB,CAyBnB"}

package/dist/brief/knowledge.js

@@ -0,0 +1,123 @@
+/**
+ * Independent knowledge attribution (KA-001).
+ *
+ * A project may keep knowledge that belongs to no work item — a strategy
+ * paper, a vision note — without that being "unattributed activity" and
+ * without pretending it is part of the active story. The registration is an
+ * idea of the Idea Store (`IDEA-NNN`) that declares the artifact's `paths`.
+ *
+ * A commit is attributed to independent knowledge only when ALL hold:
+ *   1. its subject names no work item (a work item keeps its own semantics);
+ *   2. it names at least one `IDEA-NNN` that is a valid idea file **in the
+ *      tree of that very commit** (so registering an idea later never
+ *      legalises older commits, and a commit that registers or edits the idea
+ *      is itself never attributed — its own files are not covered);
+ *   3. the ideas it names declare `paths`, every declared path passes the
+ *      attribution policy (exact document files only — no directory prefixes, no
+ *      source code, nothing inside the MONOLITH root; `attributionPathProblem`),
+ *      and EVERY file the commit changed (other than state documents) is covered
+ *      by those paths;
+ *   4. no changed file lies inside the MONOLITH root;
+ *   5. it names at most MAX_IDEA_IDS_PER_COMMIT ideas, and the run stays inside a
+ *      fixed budget of blob reads (each read is a git subprocess).
+ * Attribution only EXPLAINS a commit. It is not approval: a registered, correctly
+ * attributed change may still be wrong or unreviewed.
+ * Anything else stays exactly what it was: unattributed activity. Nothing here
+ * activates a story, touches the roadmap or marks anything done; it only
+ * decides whether a commit is *explained*. No LLM, no network, read-only git.
+ */
+import { artifactPathsCover, attributionPathProblem, isIdeaId, parseIdea } from '../ideas/format.js';
+export const EMPTY_KNOWLEDGE = { attributed: new Map(), rejected: new Map() };
+/** Upper bound of commits examined; beyond it the rest simply stay unattributed. */
+export const MAX_KNOWLEDGE_COMMITS = 200;
+/** A subject naming more ideas than this is refused without any git call (A4-SEC-05). */
+export const MAX_IDEA_IDS_PER_COMMIT = 8;
+/** Total blob reads (git subprocesses) per run; beyond it commits stay unattributed. */
+export const MAX_KNOWLEDGE_BLOB_READS = 64;
+const IDEA_REF_RE = /(?<![A-Za-z0-9-])IDEA-\d{3,9}(?![A-Za-z0-9]|\.\d|-[A-Z0-9])/g;
+export function ideaIdsInSubject(subject) {
+    return [...new Set(subject.match(IDEA_REF_RE) ?? [])].filter(isIdeaId);
+}
+export function attributeKnowledge(git, opts) {
+    if (git.status !== 'ok')
+        return EMPTY_KNOWLEDGE;
+    const attributed = new Map();
+    const rejected = new Map();
+    const root = opts.monolithRoot.replace(/^(\.\/)+/, '').replace(/\/+$/, '');
+    const rootPrefix = root === '' || root === '.' ? '' : `${root}/`;
+    let examined = 0;
+    const budget = { reads: MAX_KNOWLEDGE_BLOB_READS };
+    for (const c of git.commitsSince) {
+        const files = c.files.filter((f) => !opts.stateFiles.has(f));
+        if (files.length === 0)
+            continue; // not activity
+        if (opts.hasWorkItem(c.subject))
+            continue; // work items keep their own semantics
+        const named = ideaIdsInSubject(c.subject);
+        if (named.length === 0)
+            continue;
+        if (++examined > MAX_KNOWLEDGE_COMMITS)
+            break;
+        if (named.length > MAX_IDEA_IDS_PER_COMMIT) {
+            rejected.set(c.sha, { reason: `it names ${named.length} ideas (more than ${MAX_IDEA_IDS_PER_COMMIT}); no registration was read` });
+            continue;
+        }
+        const verdict = judge(c, files, named, rootPrefix, root, opts.readBlob, budget);
+        if ('ideaIds' in verdict)
+            attributed.set(c.sha, verdict);
+        else
+            rejected.set(c.sha, verdict);
+    }
+    return { attributed, rejected };
+}
+function judge(c, files, named, rootPrefix, monolithRoot, readBlob, budget) {
+    const unjudgeable = files.find((f) => /^\.?\.?\//.test(f));
+    if (unjudgeable !== undefined)
+        return { reason: `a changed path (${unjudgeable.slice(0, 40)}) is not project-relative and cannot be judged` };
+    const inRoot = (rootPrefix === '' ? files[0] : files.find((f) => f.toLowerCase().startsWith(rootPrefix.toLowerCase())));
+    if (inRoot !== undefined)
+        return { reason: `it changes ${inRoot}, inside the MONOLITH root; knowledge attribution never covers that` };
+    const valid = [];
+    const paths = [];
+    const problems = [];
+    for (const id of named) {
+        if (budget.reads <= 0) {
+            problems.push(`${id} was not checked: the per-run limit of ${MAX_KNOWLEDGE_BLOB_READS} registration reads was reached`);
+            continue;
+        }
+        budget.reads--;
+        const text = readBlob(c.sha, `${monolithRoot}/memory/long-term/ideas/${id}.md`);
+        if (text === null) {
+            problems.push(`${id} is not a registered idea in this commit (or its content is not available locally)`);
+            continue;
+        }
+        try {
+            const idea = parseIdea(id, text);
+            if (idea.paths === undefined || idea.paths.length === 0)
+                problems.push(`${id} declares no paths`);
+            else {
+                const refused = idea.paths.map((p) => ({ p, why: attributionPathProblem(p, monolithRoot) })).find((x) => x.why !== null);
+                if (refused !== undefined) {
+                    problems.push(`${id} declares a path that cannot attribute knowledge (${refused.p.slice(0, 60)}): ${refused.why}`);
+                    continue;
+                }
+                valid.push(id);
+                for (const p of idea.paths)
+                    if (!paths.includes(p))
+                        paths.push(p);
+            }
+        }
+        catch {
+            problems.push(`${id} is not a readable idea in this commit`);
+        }
+    }
+    // Strict: every idea the subject names must be valid; a bad id is never silently ignored.
+    if (problems.length > 0)
+        return { reason: problems.join('; ') };
+    const outside = files.filter((f) => !artifactPathsCover(paths, f));
+    if (outside.length > 0) {
+        const shown = outside.slice(0, 3).join(', ');
+        return { reason: `${shown}${outside.length > 3 ? ` and ${outside.length - 3} more` : ''} not covered by the declared paths of ${valid.join(', ')}` };
+    }
+    return { ideaIds: valid, paths };
+}

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/reconcile.d.ts

@@ -22,7 +22,7 @@
  */
 import { type FreshnessEvidence, type FreshnessResult, type FreshnessStatus } from './freshness.js';
 export type FindingKind = 'confirmed' | 'suspected' | 'unknown';
-export type FindingCode = 'STATE_CONTRADICTION' | 'UNRECORDED_WORK' | 'UNATTRIBUTED_ACTIVITY' | 'ACTIVITY_WITHOUT_ACTIVE_STORY' | 'GIT_UNAVAILABLE' | 'STATE_NOT_IN_GIT' | 'GIT_HISTORY_TRUNCATED' | 'ACTIVE_STORY_UNKNOWN';
+export type FindingCode = 'STATE_CONTRADICTION' | 'UNRECORDED_WORK' | 'UNATTRIBUTED_ACTIVITY' | 'ACTIVITY_WITHOUT_ACTIVE_STORY' | 'GIT_UNAVAILABLE' | 'STATE_NOT_IN_GIT' | 'GIT_HISTORY_TRUNCATED' | 'GIT_HISTORY_SHALLOW' | 'ACTIVE_STORY_UNKNOWN';
 export interface ReconciliationFinding {
     kind: FindingKind;
     code: FindingCode;
@@ -54,6 +54,12 @@ export interface ReconciliationReport {
     untrackedWork: UntrackedWorkItem[];
     /** Ids git references that some state document mentions. Mentioned is not correct. Sorted. */
     mentionedWork: string[];
+    /** KA-001: commits explained by registered independent knowledge (not part of any work item). */
+    independentKnowledge: {
+        ideaIds: string[];
+        paths: string[];
+        commits: string[];
+    }[];
     documents: ReviewDocument[];
     limitations: string[];
     actions: string[];

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

@@ -1 +1 @@
-{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/brief/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,eAAe,EAErB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;AAEhE,MAAM,MAAM,WAAW,GACnB,qBAAqB,GACrB,iBAAiB,GACjB,uBAAuB,GACvB,+BAA+B,GAC/B,iBAAiB,GACjB,kBAAkB,GAClB,uBAAuB,GACvB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,eAAe,CAAC;IAC3B,eAAe,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtD,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,wGAAwG;IACxG,aAAa,EAAE,iBAAiB,EAAE,CAAC;IACnC,8FAA8F;IAC9F,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAiBtC,wBAAgB,SAAS,CAAC,EAAE,EAAE,iBAAiB,EAAE,MAAM,EAAE,eAAe,GAAG,oBAAoB,CAmI9F;AAiBD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAoF3G"}
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/brief/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,eAAe,EAErB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;AAEhE,MAAM,MAAM,WAAW,GACnB,qBAAqB,GACrB,iBAAiB,GACjB,uBAAuB,GACvB,+BAA+B,GAC/B,iBAAiB,GACjB,kBAAkB,GAClB,uBAAuB,GACvB,qBAAqB,GACrB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,eAAe,CAAC;IAC3B,eAAe,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtD,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,wGAAwG;IACxG,aAAa,EAAE,iBAAiB,EAAE,CAAC;IACnC,8FAA8F;IAC9F,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,iGAAiG;IACjG,oBAAoB,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAClF,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAiBtC,wBAAgB,SAAS,CAAC,EAAE,EAAE,iBAAiB,EAAE,MAAM,EAAE,eAAe,GAAG,oBAAoB,CAkK9F;AAiBD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CA+F3G"}