@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.1

package/dist/brief/docs.js

@@ -0,0 +1,229 @@
+/**
+ * Generic, deterministic markdown-frontmatter discovery used for both
+ * Mandatory Protocols (section 7) and ADR Discovery (section 8). Reuses
+ * Scriptorium's existing frontmatter parser (per the brief contract) — does
+ * NOT use `compileMarkdownArtifact()` or the ERG graph builder, both of
+ * which are explicitly out of scope here.
+ *
+ * Resilience (review findings F-2/F-3): a single unreadable directory,
+ * unreadable file, dangling symlink, symlink cycle, or a configured
+ * directory that escapes the project root must never crash the whole brief
+ * or silently disappear. Each failure is caught, reported as a diagnostic
+ * (forcing Completeness: INCOMPLETE), and discovery continues with
+ * whatever else is readable.
+ *
+ * Symlinks (file or directory entries) are never followed while walking —
+ * this is what makes a symlink cycle (ELOOP) impossible by construction,
+ * and is also the first line of defense against using a nested symlink to
+ * tunnel outside a configured directory. The *top-level* directories named
+ * in `dirs` (i.e. `contextGateway.adrDirs` and the standard protocols
+ * dir) get an explicit containment check in addition: both a string-level
+ * check (rejects `..` segments in the configured path itself) and a
+ * real-path check after resolving symlinks (rejects a configured directory
+ * that is itself a symlink escaping the project root). Neither check alone
+ * is treated as sufficient — path.join()/path.relative() string comparison
+ * alone does not account for symlinks on disk.
+ *
+ * `monolithRoot` itself, and the fixed files below it (state.json,
+ * active.md), are vetted separately by the shared resolver in src/root
+ * (SEC-001A); this check covers document directories only.
+ */
+import { readdirSync, existsSync, lstatSync, realpathSync } from 'fs';
+import { join, relative, isAbsolute, resolve } from 'path';
+import { readBoundedFileStable } from '../root/index.js';
+import { parseFrontmatter } from '../scriptorium/frontmatter.js';
+import { compareStrings } from './selectors.js';
+/** SEC-001B.1: protocol / ADR documents (largest in this repo is ~80 KB). */
+export const MAX_MARKDOWN_DOC_BYTES = 1024 * 1024;
+const H1_RE = /^#\s+(.+?)\s*$/;
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** True if `candidateAbs` is `baseAbs` itself or strictly inside it. */
+function isContained(baseAbs, candidateAbs) {
+    const rel = relative(baseAbs, candidateAbs);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/**
+ * Resolves `relDir` (relative to targetDir) to an absolute path, rejecting
+ * it — with a diagnostic, never silently — if it is not contained within
+ * targetDir. See the module doc comment for why both a string-level and a
+ * real-path (symlink-resolved) check are performed.
+ */
+function resolveContainedDir(targetDir, relDir, diagnostics) {
+    const targetAbs = resolve(targetDir);
+    const requestedAbs = resolve(join(targetDir, relDir));
+    if (!isContained(targetAbs, requestedAbs)) {
+        diagnostics.push({
+            code: 'DOC_DIR_OUTSIDE_PROJECT',
+            severity: 'error',
+            message: `Configured directory "${relDir}" resolves outside the project root and was skipped.`,
+        });
+        return null;
+    }
+    // `lstat`, not `existsSync`: existsSync follows symlinks, so a DANGLING symlink would
+    // read as "absent" and be skipped silently (SEC-001B.1-R, M-1). Only ENOENT on the
+    // path itself means "not created yet"; a dangling link falls through to realpath below
+    // and is reported as DOC_DIR_UNREADABLE.
+    try {
+        lstatSync(requestedAbs);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            // Not an error: an ADR/protocol directory that hasn't been created yet is routine.
+            return requestedAbs;
+        }
+        diagnostics.push({
+            code: 'DOC_DIR_UNREADABLE',
+            severity: 'error',
+            message: `"${relDir}" could not be inspected: ${errMsg(err)}`,
+        });
+        return null;
+    }
+    let realRequested;
+    try {
+        realRequested = realpathSync(requestedAbs);
+    }
+    catch (err) {
+        diagnostics.push({
+            code: 'DOC_DIR_UNREADABLE',
+            severity: 'error',
+            message: `"${relDir}" could not be resolved: ${errMsg(err)}`,
+        });
+        return null;
+    }
+    let realTarget;
+    try {
+        realTarget = realpathSync(targetAbs);
+    }
+    catch {
+        realTarget = targetAbs;
+    }
+    if (!isContained(realTarget, realRequested)) {
+        diagnostics.push({
+            code: 'DOC_DIR_OUTSIDE_PROJECT',
+            severity: 'error',
+            message: `Configured directory "${relDir}" escapes the project root via a symlink and was skipped.`,
+        });
+        return null;
+    }
+    return requestedAbs;
+}
+/**
+ * All `.md` files under `dir`, sorted deterministically (not FS traversal
+ * order). Never follows symlinks — a symlinked file or directory entry is
+ * skipped outright, which also makes a symlink cycle harmless (it is never
+ * entered to begin with). Directory read failures (EACCES, ELOOP from a
+ * symlink that isn't itself recognized as one by readdir's dirent type,
+ * etc.) are reported and that subtree is skipped; sibling subtrees are
+ * still walked.
+ */
+function walkMarkdownFilesSorted(dir, targetDir, diagnostics) {
+    const results = [];
+    if (!existsSync(dir))
+        return results;
+    function walk(d) {
+        let entries;
+        try {
+            entries = readdirSync(d, { withFileTypes: true });
+        }
+        catch (err) {
+            diagnostics.push({
+                code: 'DOC_DIR_UNREADABLE',
+                severity: 'error',
+                message: `"${relative(targetDir, d)}" could not be read: ${errMsg(err)}`,
+            });
+            return;
+        }
+        const sorted = entries.slice().sort((a, b) => compareStrings(a.name, b.name));
+        for (const entry of sorted) {
+            if (entry.isSymbolicLink())
+                continue; // never follow symlinks — files or directories
+            const full = join(d, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                results.push(full);
+            }
+        }
+    }
+    walk(dir);
+    return results.sort(compareStrings);
+}
+function firstH1(bodyLines) {
+    for (const line of bodyLines) {
+        const match = H1_RE.exec(line.trim());
+        if (match)
+            return match[1];
+    }
+    return undefined;
+}
+function parseDoc(absPath, targetDir, diagnostics) {
+    const read = readBoundedFileStable(absPath, `"${relative(targetDir, absPath)}"`, { boundary: targetDir, maxBytes: MAX_MARKDOWN_DOC_BYTES, allowEmpty: true }, true);
+    if (!read.ok) {
+        diagnostics.push({
+            code: 'DOC_FILE_UNREADABLE',
+            severity: 'error',
+            message: `"${relative(targetDir, absPath)}" could not be read: ${read.code}: ${read.detail}`,
+            readCode: read.code,
+        });
+        return null;
+    }
+    const content = 'content' in read ? read.content : '';
+    const lines = content.split('\n');
+    const fm = parseFrontmatter(lines);
+    if (!fm)
+        return null;
+    const fields = new Map();
+    let frontmatterTitle;
+    let id;
+    for (const field of fm.fields) {
+        if (field.values[0] !== undefined)
+            fields.set(field.key, field.values[0]);
+        if (field.key === 'title' && field.values[0])
+            frontmatterTitle = field.values[0];
+        if (field.key === 'id' && field.values[0])
+            id = field.values[0];
+    }
+    const resolvedTitle = frontmatterTitle ?? firstH1(lines.slice(fm.bodyStartLine));
+    return {
+        relPath: relative(targetDir, absPath).split('\\').join('/'),
+        id,
+        resolvedTitle,
+        fields,
+    };
+}
+function resolveTitle(doc) {
+    return doc.resolvedTitle ?? doc.id ?? doc.relPath;
+}
+/**
+ * Discover documents under `dirs` (relative to targetDir, deduplicated,
+ * each walked recursively) whose frontmatter matches `predicate`. Only
+ * documents with a usable frontmatter `id:` are included — a markdown file
+ * without one isn't a candidate ADR/protocol record, it's silently excluded
+ * from this listing (not an error). `diagnostics` collects every resilience
+ * finding described in the module doc comment; callers that don't care can
+ * omit it.
+ */
+export function discoverDocs(targetDir, dirs, predicate, diagnostics = []) {
+    const seenAbsDirs = new Set();
+    const refs = [];
+    for (const relDir of dirs) {
+        const absDir = resolveContainedDir(targetDir, relDir, diagnostics);
+        if (!absDir)
+            continue;
+        if (seenAbsDirs.has(absDir))
+            continue;
+        seenAbsDirs.add(absDir);
+        for (const absPath of walkMarkdownFilesSorted(absDir, targetDir, diagnostics)) {
+            const doc = parseDoc(absPath, targetDir, diagnostics);
+            if (!doc || !doc.id)
+                continue;
+            if (!predicate(doc.fields))
+                continue;
+            refs.push({ id: doc.id, title: resolveTitle(doc), path: doc.relPath });
+        }
+    }
+    return refs.sort((a, b) => compareStrings(a.id, b.id) || compareStrings(a.path, b.path));
+}

package/dist/brief/freshness.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Project State Freshness (SELF-AWARENESS-001).
+ *
+ * `Completeness` says whether the brief lost data while being rendered.
+ * `Freshness` says whether the recorded project state can still be trusted.
+ * They are independent: `Completeness: COMPLETE` + `Freshness: STALE` is a
+ * valid combination, and nothing here ever changes `Completeness`.
+ *
+ * `evaluateFreshness()` is pure: it takes already-gathered evidence and
+ * returns a verdict. Git is a signal, never the only source of truth:
+ *
+ *   STALE    only on a concrete, named discrepancy — either the state
+ *            documents contradict each other, or git history references
+ *            work items that no state document mentions.
+ *   FRESH    only on positive evidence — git is readable, the last state
+ *            update is located, and every commit after it either touches
+ *            only the state documents or belongs to a recorded work item.
+ *   UNKNOWN  everything else. Git activity alone, an old date alone, or the
+ *            absence of an active story alone never produce STALE, and the
+ *            absence of an active story never means "project complete".
+ */
+export type FreshnessStatus = 'FRESH' | 'STALE' | 'UNKNOWN';
+export type FreshnessReasonCode = 'STATE_CONTRADICTION' | 'UNRECORDED_WORK' | 'GIT_UNAVAILABLE' | 'STATE_NOT_IN_GIT' | 'GIT_HISTORY_TRUNCATED' | 'UNATTRIBUTED_ACTIVITY' | 'NO_ACTIVITY_SINCE_STATE_UPDATE' | 'ACTIVITY_RECORDED';
+export interface FreshnessReason {
+    code: FreshnessReasonCode;
+    message: string;
+    /** STATE_CONTRADICTION only: the state documents (by file name) that disagree. */
+    documents?: string[];
+}
+/** One commit after the last state update, as seen by git. */
+export interface GitCommitSignal {
+    sha: string;
+    /** ISO-8601 committer date. Informational only — never compared with "now". */
+    date: string;
+    subject: string;
+    /** 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 GitSignals = {
+    status: 'unavailable';
+    reason: GitUnavailableReason;
+} | {
+    status: 'ok';
+    /** The newest commit that touched any state document; null if none ever did. */
+    lastStateUpdate: {
+        sha: string;
+        date: string;
+    } | null;
+    /** Commits reachable from HEAD but not from `lastStateUpdate`, newest first. */
+    commitsSince: GitCommitSignal[];
+    /** True when git history was cut at the read limit — the picture is partial. */
+    truncated: boolean;
+};
+export type StoryClaim = {
+    kind: 'none';
+} | {
+    kind: 'ids';
+    ids: string[];
+} | {
+    kind: 'unknown';
+};
+export interface FreshnessEvidence {
+    git: GitSignals;
+    /** What `active.md` says is current. `unknown` when the file/section is unreadable or says nothing parseable. */
+    activeStory: StoryClaim;
+    /** What `roadmap-index.md` says is the active story ("Active Story: ..."), or null if the line is absent. */
+    roadmapActiveStory: string | null;
+    /** Work-item status by id as declared by roadmap-index.md and story-index.md (uppercased status). */
+    roadmapStatuses: ReadonlyMap<string, string>;
+    storyIndexStatuses: ReadonlyMap<string, string>;
+    /** Concatenated text of the state documents that were readable; used to decide whether an id is "recorded". */
+    recordedText: string;
+    /** Repo-relative-to-project paths that are state documents (their own commits are not "activity"). */
+    stateFiles: ReadonlySet<string>;
+}
+export interface FreshnessResult {
+    status: FreshnessStatus;
+    reasons: FreshnessReason[];
+    /** Human-readable, single-line warnings (never fatal). */
+    warnings: string[];
+    recommendation: string;
+    activeStory: 'none-recorded' | 'recorded' | 'unknown';
+    lastStateUpdate: {
+        sha: string;
+        date: string;
+    } | null;
+    /** Commits after the last state update that touched something other than state documents. */
+    activityCount: number | null;
+    /** Work-item ids seen in git after the last state update and absent from every state document. */
+    unrecordedWork: string[];
+}
+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 declare function parseActiveStoryClaim(excerpt: string | null): StoryClaim;
+/** `Active Story: <text>` line of roadmap-index.md. */
+export declare function parseRoadmapActiveStory(content: string): string | null;
+/** Table rows `| id | title | STATUS | date |` of roadmap-index.md. */
+export declare function parseRoadmapStatuses(content: string): Map<string, string>;
+/** `### [STORY ]<id> — title` followed by `**Status:** X` in story-index.md. */
+export declare function parseStoryIndexStatuses(content: string): Map<string, string>;
+export declare function evaluateFreshness(ev: FreshnessEvidence): FreshnessResult;
+//# sourceMappingURL=freshness.d.ts.map

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

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

package/dist/brief/freshness.js

@@ -0,0 +1,263 @@
+/**
+ * Project State Freshness (SELF-AWARENESS-001).
+ *
+ * `Completeness` says whether the brief lost data while being rendered.
+ * `Freshness` says whether the recorded project state can still be trusted.
+ * They are independent: `Completeness: COMPLETE` + `Freshness: STALE` is a
+ * valid combination, and nothing here ever changes `Completeness`.
+ *
+ * `evaluateFreshness()` is pure: it takes already-gathered evidence and
+ * returns a verdict. Git is a signal, never the only source of truth:
+ *
+ *   STALE    only on a concrete, named discrepancy — either the state
+ *            documents contradict each other, or git history references
+ *            work items that no state document mentions.
+ *   FRESH    only on positive evidence — git is readable, the last state
+ *            update is located, and every commit after it either touches
+ *            only the state documents or belongs to a recorded work item.
+ *   UNKNOWN  everything else. Git activity alone, an old date alone, or the
+ *            absence of an active story alone never produce STALE, and the
+ *            absence of an active story never means "project complete".
+ */
+// ---------------------------------------------------------------------------
+// Work-item ids
+// ---------------------------------------------------------------------------
+/**
+ * Work-item id: an upper-case, dash-separated prefix, a number, then optional
+ * sub-story qualifiers — UI-002D, SEC-001B.1-R, LOCK-RELEASE-001, CONTEXT-001A.
+ * Deliberately narrow: an id that is not matched is simply not evidence.
+ */
+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-'];
+function isWorkItem(id) {
+    return !NON_WORK_PREFIXES.some((p) => id.startsWith(p));
+}
+export function extractWorkItemIds(text) {
+    const re = new RegExp(`(?<![A-Za-z0-9-])${WORK_ITEM_SOURCE}(?![A-Za-z0-9]|\\.\\d|-[A-Z0-9])`, 'g');
+    const seen = new Set();
+    for (const m of text.matchAll(re)) {
+        if (isWorkItem(m[0]))
+            seen.add(m[0]);
+    }
+    return [...seen];
+}
+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);
+}
+// ---------------------------------------------------------------------------
+// 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. */
+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' };
+}
+/** `Active Story: <text>` line of roadmap-index.md. */
+export function parseRoadmapActiveStory(content) {
+    const m = /^Active Story:\s*(.+?)\s*$/m.exec(content);
+    return m ? m[1] : null;
+}
+/** Table rows `| id | title | STATUS | date |` of roadmap-index.md. */
+export function parseRoadmapStatuses(content) {
+    const out = new Map();
+    for (const line of 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] !== '')
+            continue;
+        const id = cells[1];
+        const status = cells[3];
+        if (!/^[A-Za-z0-9][A-Za-z0-9.\-]*$/.test(id) || !/^[A-Z][A-Z _]+$/.test(status))
+            continue;
+        if (!out.has(id))
+            out.set(id, status);
+    }
+    return out;
+}
+/** `### [STORY ]<id> — title` followed by `**Status:** X` in story-index.md. */
+export function parseStoryIndexStatuses(content) {
+    const out = new Map();
+    const lines = 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)
+            continue;
+        for (let j = i + 1; j < Math.min(lines.length, i + 6); j++) {
+            if (/^#{1,3}\s/.test(lines[j]))
+                break;
+            const s = /^\*\*Status:\*\*\s*([A-Z][A-Z _]*)/.exec(lines[j]);
+            if (s) {
+                if (!out.has(h[1]))
+                    out.set(h[1], s[1].trim());
+                break;
+            }
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Evaluation
+// ---------------------------------------------------------------------------
+const MAX_LISTED = 5;
+function listIds(ids) {
+    if (ids.length <= MAX_LISTED)
+        return ids.join(', ');
+    return `${ids.slice(0, MAX_LISTED).join(', ')} and ${ids.length - MAX_LISTED} more`;
+}
+function isDone(status) {
+    return status === 'COMPLETED' || status === 'DONE';
+}
+function findContradictions(ev) {
+    const out = [];
+    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}".`,
+            documents: ['active.md', 'roadmap-index.md'],
+        });
+    }
+    if (ev.activeStory.kind === 'ids') {
+        for (const id of ev.activeStory.ids) {
+            if (isDone(ev.roadmapStatuses.get(id))) {
+                out.push({
+                    message: `active.md treats ${id} as current, but roadmap-index.md marks it ${ev.roadmapStatuses.get(id)}.`,
+                    documents: ['active.md', 'roadmap-index.md'],
+                });
+            }
+            else if (isDone(ev.storyIndexStatuses.get(id))) {
+                out.push({
+                    message: `active.md treats ${id} as current, but story-index.md marks it ${ev.storyIndexStatuses.get(id)}.`,
+                    documents: ['active.md', 'story-index.md'],
+                });
+            }
+        }
+    }
+    for (const [id, roadmapStatus] of ev.roadmapStatuses) {
+        const indexStatus = ev.storyIndexStatuses.get(id);
+        if (indexStatus !== undefined && indexStatus !== roadmapStatus) {
+            out.push({
+                message: `${id} is ${roadmapStatus} in roadmap-index.md but ${indexStatus} in story-index.md.`,
+                documents: ['roadmap-index.md', 'story-index.md'],
+            });
+        }
+    }
+    return out;
+}
+const REVIEW_RECOMMENDATION = 'Review project state before relying on this brief.';
+export function evaluateFreshness(ev) {
+    const reasons = [];
+    const warnings = [];
+    const base = {
+        activeStory: ev.activeStory.kind === 'none' ? 'none-recorded' : ev.activeStory.kind === 'ids' ? 'recorded' : 'unknown',
+        lastStateUpdate: ev.git.status === 'ok' ? ev.git.lastStateUpdate : null,
+        activityCount: null,
+        unrecordedWork: [],
+    };
+    // 1. Internal contradictions need no git at all.
+    const contradictions = findContradictions(ev);
+    for (const c of contradictions)
+        reasons.push({ code: 'STATE_CONTRADICTION', message: c.message, documents: c.documents });
+    // 2. Git-derived signals.
+    let gitVerdict = null;
+    if (ev.git.status === 'unavailable') {
+        const why = {
+            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',
+        };
+        reasons.push({ code: 'GIT_UNAVAILABLE', message: `Cannot compare state with history: ${why[ev.git.reason]}.` });
+        gitVerdict = 'unknown';
+    }
+    else if (ev.git.lastStateUpdate === null) {
+        reasons.push({
+            code: 'STATE_NOT_IN_GIT',
+            message: 'No commit touches the state documents, so the last state update cannot be located.',
+        });
+        gitVerdict = 'unknown';
+    }
+    else {
+        const activity = ev.git.commitsSince.filter((c) => c.files.some((f) => !ev.stateFiles.has(f)));
+        base.activityCount = activity.length;
+        const referenced = new Set();
+        let unattributed = 0;
+        for (const c of activity) {
+            const ids = extractWorkItemIds(c.subject);
+            if (ids.length === 0)
+                unattributed++;
+            for (const id of ids)
+                referenced.add(id);
+        }
+        const unrecorded = [...referenced].filter((id) => !mentionsId(ev.recordedText, id)).sort();
+        base.unrecordedWork = unrecorded;
+        if (unrecorded.length > 0) {
+            reasons.push({
+                code: 'UNRECORDED_WORK',
+                message: `${activity.length} commit(s) after the last state update (${ev.git.lastStateUpdate.sha.slice(0, 7)}, ${ev.git.lastStateUpdate.date.slice(0, 10)}) ` +
+                    `reference ${unrecorded.length} work item(s) that no state document mentions: ${listIds(unrecorded)}.`,
+            });
+            gitVerdict = 'stale';
+        }
+        else if (ev.git.truncated) {
+            reasons.push({
+                code: 'GIT_HISTORY_TRUNCATED',
+                message: 'Git history after the last state update was cut at the read limit; the check is partial.',
+            });
+            gitVerdict = 'unknown';
+        }
+        else if (unattributed > 0) {
+            reasons.push({
+                code: 'UNATTRIBUTED_ACTIVITY',
+                message: `${unattributed} commit(s) after the last state update touch project files without naming a work item; ` +
+                    `whether the recorded state still describes them cannot be determined.`,
+            });
+            gitVerdict = 'unknown';
+        }
+        else if (activity.length === 0) {
+            reasons.push({
+                code: 'NO_ACTIVITY_SINCE_STATE_UPDATE',
+                message: 'No commit after the last state update changed anything beyond the state documents.',
+            });
+            gitVerdict = 'fresh';
+        }
+        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.`,
+            });
+            gitVerdict = 'fresh';
+        }
+        if (activity.length > 0 && ev.activeStory.kind === 'none') {
+            warnings.push('Git activity exists after the last recorded state update, but no active story is recorded.');
+        }
+    }
+    // 3. Combine. A contradiction or unrecorded work is concrete evidence of staleness;
+    //    FRESH needs positive evidence and no contradiction.
+    let status;
+    if (contradictions.length > 0 || gitVerdict === 'stale')
+        status = 'STALE';
+    else if (gitVerdict === 'fresh')
+        status = 'FRESH';
+    else
+        status = 'UNKNOWN';
+    if (status !== 'FRESH') {
+        if (status === 'STALE')
+            warnings.unshift('Project state may be outdated.');
+        else
+            warnings.unshift('Freshness could not be established from the available evidence.');
+        if (ev.activeStory.kind === 'none') {
+            warnings.push('No active story is recorded; this does not mean the project is complete.');
+        }
+        else if (ev.activeStory.kind === 'unknown') {
+            warnings.push('The active story could not be determined from active.md.');
+        }
+    }
+    const recommendation = status === 'FRESH' ? 'No action needed.' : status === 'STALE' ? REVIEW_RECOMMENDATION : `${REVIEW_RECOMMENDATION} Freshness is unverified, not confirmed outdated.`;
+    return { status, reasons, warnings, recommendation, ...base };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Read-only git signals for the freshness check (SELF-AWARENESS-001).
+ *
+ * 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.
+ */
+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;
+/**
+ * @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;
+//# sourceMappingURL=git-signals.d.ts.map

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

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