codictator 0.0.0-stage → 0.1.2

package/dist/features/records/docs-structure.js

@@ -0,0 +1,223 @@
+// SPEC §4.9.2: doc shape checks — router/leaf topology, size, breadth.
+// Line vocabulary lives in docs-lines.ts. All functions are pure over
+// caller-supplied trees; this module never touches the filesystem
+// (SPEC §3.3, §10.3 item 3).
+import { normalizeText } from "../../kernel/index.js";
+import { isHeading, isLinkOnlyLine, isTableRow, stripFences, } from "./docs-lines.js";
+export { isTableRow } from "./docs-lines.js";
+// SPEC §5.10: the tunable defaults the limits ship with.
+export const DEFAULT_DOC_LIMITS = {
+    maxBytes: 40000,
+    maxLines: 500,
+    maxH2: 15,
+    maxFilesPerFolder: 40,
+    maxSentenceWords: 40,
+    maxParagraphSentences: 6,
+};
+const LEAF_NAME_PATTERN = /^\d{2}(-\d{2})?-[A-Z0-9]+(-[A-Z0-9]+)*\.md$/;
+function routerLinkTargets(routerText) {
+    const targets = [];
+    const pattern = /\[[^\]]*\]\(([^)#\s]+\.md)(?:#[^)\s]*)?\)/g;
+    let match = pattern.exec(routerText);
+    while (match !== null) {
+        targets.push(match[1] ?? "");
+        match = pattern.exec(routerText);
+    }
+    return targets;
+}
+function expectedNavLine(routerPath, previous, next) {
+    const routerName = routerPath.split("/").pop() ?? routerPath;
+    const prev = previous === undefined ? "(first)" : `[◀ ${previous}](${previous})`;
+    const following = next === undefined ? "(last)" : `[${next} ▶](${next})`;
+    return `**${prev}** · [${routerName}](${routerPath}) · **${following}**`;
+}
+function firstContentLine(text) {
+    for (const raw of normalizeText(text).split("\n")) {
+        const line = raw.trim();
+        if (line !== "" && !isHeading(raw)) {
+            return raw;
+        }
+    }
+    return "";
+}
+function navSlots(line) {
+    const slots = [];
+    const pattern = /\[[^\]]*\]\(([^)#\s]+)(?:#[^)\s]*)?\)|\(\s*(first|last)\s*\)/g;
+    let match = pattern.exec(line);
+    while (match !== null) {
+        if (match[1] !== undefined) {
+            slots.push(match[1].split("/").pop() ?? match[1]);
+        }
+        else {
+            slots.push(`(${match[2] ?? ""})`);
+        }
+        match = pattern.exec(line);
+    }
+    return slots;
+}
+function routerIntroFindings(tree) {
+    const routerName = tree.routerPath.split("/").pop() ?? tree.routerPath;
+    const prose = normalizeText(tree.routerText)
+        .split("\n")
+        .filter((line) => line.trim() !== "" &&
+        !isHeading(line) &&
+        !isTableRow(line) &&
+        !isLinkOnlyLine(line));
+    if (prose.length <= 1) {
+        return [];
+    }
+    return [
+        {
+            ruleId: "core/doc-router-leaf",
+            path: tree.routerPath,
+            message: `router holds prose beyond its one-line intro: ${routerName}`,
+            remediation: `Keep only the H1, a single intro line and tables in ${tree.routerPath}; move the paragraph to a leaf.`,
+        },
+    ];
+}
+function leafNameFindings(tree) {
+    const findings = [];
+    for (const leaf of tree.leaves) {
+        if (LEAF_NAME_PATTERN.test(leaf.name)) {
+            continue;
+        }
+        findings.push({
+            ruleId: "core/doc-router-leaf",
+            path: `${tree.routerPath}`,
+            message: `leaf name outside the router pattern: ${leaf.name}`,
+            remediation: `Rename the leaf to NN-NAME.md or NN-MM-NAME.md with uppercase segments, e.g. 04-09-RECORDS.md.`,
+        });
+    }
+    return findings;
+}
+function leafLinkFindings(tree, leafNames, linked) {
+    const findings = [];
+    for (const name of leafNames) {
+        const seen = linked.filter((target) => (target.split("/").pop() ?? target) === name).length;
+        if (seen === 1) {
+            continue;
+        }
+        const detail = seen === 0 ? "missing from router" : `linked ${seen} times in router`;
+        findings.push({
+            ruleId: "core/doc-router-leaf",
+            path: tree.routerPath,
+            message: `leaf ${detail}: ${name}`,
+            remediation: `Link [${name}](${name}) exactly once in ${tree.routerPath}, in file-name order.`,
+        });
+    }
+    const routerName = tree.routerPath.split("/").pop() ?? tree.routerPath;
+    const ordered = linked
+        .map((target) => target.split("/").pop() ?? target)
+        .filter((leaf) => leafNames.includes(leaf));
+    const expectedOrder = leafNames.filter((leaf) => ordered.includes(leaf));
+    if (ordered.join("\n") !== expectedOrder.join("\n")) {
+        findings.push({
+            ruleId: "core/doc-router-leaf",
+            path: tree.routerPath,
+            message: `router leaf links out of file-name order in ${routerName}`,
+            remediation: `Order the leaf links in ${tree.routerPath} as: ${expectedOrder.join(", ")}.`,
+        });
+    }
+    return findings;
+}
+// Slots are previous (link or "(first)"), the router link, next
+// (link or "(last)"), matching router order.
+function navExpected(routerPath, previous, next) {
+    const routerBase = routerPath.split("/").pop() ?? routerPath;
+    const first = previous === undefined ? "(first)" : previous;
+    const last = next === undefined ? "(last)" : next;
+    return [first, routerBase, last];
+}
+function checkNavLines(tree, leafNames) {
+    const findings = [];
+    for (const [index, name] of leafNames.entries()) {
+        const leaf = tree.leaves.find((entry) => entry.name === name);
+        if (leaf === undefined) {
+            continue;
+        }
+        const previous = index === 0 ? undefined : leafNames[index - 1];
+        const next = index === leafNames.length - 1 ? undefined : leafNames[index + 1];
+        const expected = navExpected(tree.routerPath, previous, next);
+        const actual = navSlots(firstContentLine(leaf.text)).slice(0, 3);
+        if (actual.join("\n") === expected.join("\n")) {
+            continue;
+        }
+        findings.push({
+            ruleId: "core/doc-router-leaf",
+            path: tree.routerPath,
+            message: `nav line of ${name} points at the wrong neighbours`,
+            remediation: expectedNavLine(tree.routerPath, previous, next),
+        });
+    }
+    return findings;
+}
+// SPEC §4.9.2 core/doc-router-leaf: the router holds only an H1, an
+// optional one-line intro and tables; every leaf links exactly once in
+// file-name order; every leaf carries the matching nav line.
+export function checkDocRouterLeaf(tree) {
+    const leafNames = tree.leaves.map((leaf) => leaf.name).sort();
+    const linked = routerLinkTargets(tree.routerText).filter((target) => target.split("/").pop());
+    return [
+        ...routerIntroFindings(tree),
+        ...leafNameFindings(tree),
+        ...leafLinkFindings(tree, leafNames, linked),
+        ...checkNavLines(tree, leafNames),
+    ];
+}
+// SPEC §4.9.2 core/doc-size: bytes and lines per file.
+export function checkDocSize(files, limits = DEFAULT_DOC_LIMITS) {
+    const findings = [];
+    for (const file of files) {
+        const text = normalizeText(file.text);
+        const bytes = new TextEncoder().encode(text).length;
+        const lines = text === "" ? 0 : text.split("\n").length;
+        if (bytes > limits.maxBytes) {
+            findings.push({
+                ruleId: "core/doc-size",
+                path: file.path,
+                message: `doc over the byte limit: ${file.path} holds ${bytes} bytes, limit ${limits.maxBytes}`,
+                remediation: `Split ${file.path} under ${limits.maxBytes} bytes; one fact lives in one leaf (SPEC §1.4).`,
+            });
+        }
+        if (lines > limits.maxLines) {
+            findings.push({
+                ruleId: "core/doc-size",
+                path: file.path,
+                message: `doc over the line limit: ${file.path} holds ${lines} lines, limit ${limits.maxLines}`,
+                remediation: `Split ${file.path} under ${limits.maxLines} lines; one fact lives in one leaf (SPEC §1.4).`,
+            });
+        }
+    }
+    return findings;
+}
+// SPEC §4.9.2 core/doc-breadth: ## headings per file, files per folder.
+export function checkDocBreadth(files, filesPerFolder = {}, limits = DEFAULT_DOC_LIMITS) {
+    const findings = [];
+    for (const file of files) {
+        let headings = 0;
+        for (const line of stripFences(file.text).split("\n")) {
+            if (/^##(?!#)\s/.test(line.trimStart())) {
+                headings += 1;
+            }
+        }
+        if (headings > limits.maxH2) {
+            findings.push({
+                ruleId: "core/doc-breadth",
+                path: file.path,
+                message: `doc over the heading limit: ${file.path} holds ${headings} ## headings, limit ${limits.maxH2}`,
+                remediation: `Split ${file.path} under ${limits.maxH2} ## headings; one fact lives in one leaf (SPEC §1.4).`,
+            });
+        }
+    }
+    for (const [folder, count] of Object.entries(filesPerFolder)) {
+        if (count > limits.maxFilesPerFolder) {
+            findings.push({
+                ruleId: "core/doc-breadth",
+                path: folder,
+                message: `folder over the file limit: ${folder} holds ${count} markdown files, limit ${limits.maxFilesPerFolder}`,
+                remediation: `Split ${folder} under ${limits.maxFilesPerFolder} markdown files.`,
+            });
+        }
+    }
+    return findings;
+}

package/dist/features/records/docs.d.ts

@@ -0,0 +1,9 @@
+import type { CheckContext, Finding } from "../engine/index.ts";
+import type { DocFile } from "./docs-structure.ts";
+export type DocClass = "record" | "managed" | "router" | "leaf" | "single";
+export declare function classifyDoc(path: string, knownDirs?: ReadonlySet<string>, managed?: ReadonlySet<string>): DocClass;
+export declare function checkDocPlacement(paths: ReadonlyArray<string>, allowedGlobs?: ReadonlyArray<string>): Array<Finding>;
+export declare function checkDocOneLevel(paths: ReadonlyArray<string>): Array<Finding>;
+export declare function checkDocNoInlineChangelog(files: ReadonlyArray<DocFile>): Array<Finding>;
+export declare function checkDocSingleOwner(files: ReadonlyArray<DocFile>): Array<Finding>;
+export declare function checkDocs(_ctx: CheckContext, paths: ReadonlyArray<string>, contents?: Readonly<Record<string, string>>): Promise<Array<Finding>>;

package/dist/features/records/docs.js

@@ -0,0 +1,238 @@
+// SPEC §4.9.1–§4.9.2: doc classification, placement, changelog and
+// single-owner checks plus the evaluation-path entry. Shape checks live in
+// docs-structure.ts, prose checks in docs-prose.ts. All functions are pure
+// over caller-supplied trees: the evaluation path passes the staged file
+// list plus the contents the layer already read (SPEC §3.3, §10.3 item 3).
+import { globMatch, normalizeText } from "../../kernel/index.js";
+import { checkDocDensity, checkDocLinksValid, checkDocNoCorpusCounts, densityParagraphs, splitSentences, wordsOf, } from "./docs-prose.js";
+import { checkDocBreadth, checkDocRouterLeaf, checkDocSize, isTableRow, } from "./docs-structure.js";
+const ROOT_DOCS = new Set([
+    "README.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+]);
+const HARNESS_DIRS = [
+    ".agents",
+    ".claude",
+    ".github",
+    ".cursor",
+    ".gemini",
+    ".opencode",
+    ".muse",
+];
+// SPEC §4.9.1: first match wins. knownDirs holds the repo's directory set so
+// a router is recognised without filesystem access; managed holds the
+// guardrail manifest paths (§4.14.1).
+export function classifyDoc(path, knownDirs = new Set(), managed = new Set()) {
+    if (managed.has(path)) {
+        return "managed";
+    }
+    if (path.startsWith("docs/HISTORY/") || path.startsWith("docs/BUGS/")) {
+        return "record";
+    }
+    const routerMatch = /^docs\/([^/]+)\.md$/.exec(path);
+    if (routerMatch !== null) {
+        const name = routerMatch[1] ?? "";
+        return knownDirs.has(`docs/${name}`) ? "router" : "single";
+    }
+    if (/^docs\/[^/]+\/.+/.test(path)) {
+        return "leaf";
+    }
+    return "single";
+}
+function placementFinding(path, reason) {
+    return {
+        ruleId: "core/doc-placement",
+        path,
+        message: `markdown file outside its placed locations: ${path} (${reason})`,
+        remediation: `Move ${path} to docs/, docs/<NAME>/, packages/*/README.md or an allowed glob, or add an allowedGlobs entry.`,
+    };
+}
+// SPEC §4.9.2 core/doc-placement: the never-files docs/HISTORY.md and
+// docs/BUGS.md are rejected even though docs/*.md is otherwise allowed.
+export function checkDocPlacement(paths, allowedGlobs = []) {
+    const findings = [];
+    for (const path of paths) {
+        if (!path.endsWith(".md")) {
+            continue;
+        }
+        if (path === "docs/HISTORY.md" || path === "docs/BUGS.md") {
+            findings.push(placementFinding(path, "record folders have no top-level file"));
+            continue;
+        }
+        if (!path.includes("/") && ROOT_DOCS.has(path)) {
+            continue;
+        }
+        if (/^docs\/[^/]+\.md$/.test(path) || /^docs\/[^/]+\/.+/.test(path)) {
+            continue;
+        }
+        if (/^packages\/[^/]+\/README\.md$/.test(path)) {
+            continue;
+        }
+        if (HARNESS_DIRS.some((dir) => path === dir || path.startsWith(`${dir}/`)) ||
+            path.startsWith(".codictator/")) {
+            continue;
+        }
+        if (allowedGlobs.some((glob) => globMatch(glob, path))) {
+            continue;
+        }
+        findings.push(placementFinding(path, "outside its allowed locations"));
+    }
+    return findings;
+}
+// SPEC §4.9.2 core/doc-one-level: no folder below docs/<NAME>/.
+export function checkDocOneLevel(paths) {
+    const findings = [];
+    for (const path of paths) {
+        if (!path.endsWith(".md")) {
+            continue;
+        }
+        const match = /^docs\/([^/]+)\/([^/]+)\//.exec(path);
+        if (match === null) {
+            continue;
+        }
+        const folder = match[1] ?? "";
+        if (folder === "HISTORY" || folder === "BUGS") {
+            continue;
+        }
+        findings.push({
+            ruleId: "core/doc-one-level",
+            path,
+            message: `doc nested below docs/${folder}/: ${path}`,
+            remediation: `Move ${path} directly under docs/${folder}/; docs/<NAME>/ takes no subfolders.`,
+        });
+    }
+    return findings;
+}
+// \x27 keeps the apostrophe out of the literal: the pack lexer blanks
+// strings without regex awareness, so a quote char would hide later code.
+const CHANGELOG_HEADING = /^(change ?log|history|revisions?|what\x27s new|updates?)$/i;
+const CHANGELOG_LINE = /^[-*]?\s*(updated|changed|added|revised|amended)( on)?\s+\d{4}-\d{2}-\d{2}/i;
+// SPEC §4.9.2 core/doc-no-inline-changelog: the per-doc changelog lives in
+// the history entry (Docs field), never inline.
+export function checkDocNoInlineChangelog(files) {
+    const findings = [];
+    for (const file of files) {
+        normalizeText(file.text)
+            .split("\n")
+            .forEach((line, index) => {
+            const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line.trim());
+            if (heading !== null && CHANGELOG_HEADING.test(heading[1] ?? "")) {
+                findings.push({
+                    ruleId: "core/doc-no-inline-changelog",
+                    path: file.path,
+                    line: index + 1,
+                    message: `inline changelog heading in ${file.path} line ${index + 1}`,
+                    remediation: `Remove the changelog section from ${file.path}; record the change in the history entry Docs field.`,
+                });
+                return;
+            }
+            if (!isTableRow(line) && CHANGELOG_LINE.test(line.trim())) {
+                findings.push({
+                    ruleId: "core/doc-no-inline-changelog",
+                    path: file.path,
+                    line: index + 1,
+                    message: `inline changelog line in ${file.path} line ${index + 1}`,
+                    remediation: `Remove the dated change line from ${file.path}; record the change in the history entry Docs field.`,
+                });
+            }
+        });
+    }
+    return findings;
+}
+function normaliseSentence(sentence) {
+    return sentence.replace(/\s+/g, " ").trim().toLowerCase();
+}
+// SPEC §4.9.2 core/doc-single-owner: no sentence of twelve or more words
+// repeats across two non-record docs. Record docs hold generated history,
+// so they are exempt both as sources and as carriers.
+export function checkDocSingleOwner(files) {
+    const seen = new Map();
+    const findings = [];
+    for (const file of [...files].sort((a, b) => (a.path < b.path ? -1 : 1))) {
+        for (const paragraph of densityParagraphs(file.text)) {
+            for (const sentence of splitSentences(paragraph)) {
+                if (wordsOf(sentence).length < 12) {
+                    continue;
+                }
+                const key = normaliseSentence(sentence);
+                const owner = seen.get(key);
+                if (owner === undefined) {
+                    seen.set(key, file.path);
+                }
+                else if (owner !== file.path) {
+                    findings.push({
+                        ruleId: "core/doc-single-owner",
+                        path: file.path,
+                        message: `sentence of twelve or more words repeats ${owner} in ${file.path}`,
+                        remediation: `Keep the fact in ${owner} and link to it from ${file.path} (SPEC §1.4: one fact, one owner).`,
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+// The evaluation-path entry: path-decidable checks always run; content
+// checks run on the supplied tree, with routers inferred from the union of
+// staged paths and supplied contents.
+export function checkDocs(_ctx, paths, contents = {}) {
+    const findings = [
+        ...checkDocPlacement(paths),
+        ...checkDocOneLevel(paths),
+    ];
+    const texts = new Map(Object.entries(contents));
+    if (texts.size === 0) {
+        return Promise.resolve(findings);
+    }
+    const knownDirs = new Set();
+    for (const path of [...paths, ...texts.keys()]) {
+        const pieces = path.split("/");
+        for (let depth = 1; depth < pieces.length; depth += 1) {
+            knownDirs.add(pieces.slice(0, depth).join("/"));
+        }
+    }
+    const byClass = new Map();
+    for (const path of texts.keys()) {
+        byClass.set(path, classifyDoc(path, knownDirs));
+    }
+    const routers = [...texts.keys()].filter((path) => byClass.get(path) === "router");
+    for (const routerPath of routers) {
+        const prefix = routerPath.replace(/\.md$/, "/");
+        const leaves = [...texts.entries()]
+            .filter(([path]) => path.startsWith(prefix))
+            .map(([path, text]) => ({
+            name: path.slice(prefix.length),
+            text,
+        }))
+            .filter((leaf) => !leaf.name.includes("/"));
+        findings.push(...checkDocRouterLeaf({
+            routerPath,
+            routerText: texts.get(routerPath) ?? "",
+            leaves,
+        }));
+    }
+    const known = new Map(texts.entries());
+    const leafFiles = [];
+    const singleFiles = [];
+    for (const [path, text] of texts.entries()) {
+        const kind = byClass.get(path);
+        if (kind === "leaf") {
+            leafFiles.push({ path, text });
+        }
+        else if (kind === "single") {
+            singleFiles.push({ path, text });
+        }
+    }
+    for (const file of [...leafFiles, ...singleFiles]) {
+        findings.push(...checkDocSize([file]), ...checkDocBreadth([file]), ...checkDocDensity([file]), ...checkDocLinksValid([file], known), ...checkDocNoInlineChangelog([file]), ...checkDocNoCorpusCounts([file]));
+    }
+    findings.push(...checkDocSingleOwner([...leafFiles, ...singleFiles]), ...checkDocSize([...texts.entries()]
+        .filter(([path]) => byClass.get(path) === "record")
+        .map(([path, text]) => ({ path, text }))));
+    return Promise.resolve(findings);
+}

package/dist/features/records/history-checks.d.ts

@@ -0,0 +1,6 @@
+import type { Finding } from "../engine/index.ts";
+import type { HistoryEntry } from "./history-parse.ts";
+export declare function entryFinding(ruleId: string, message: string, path: string): Finding;
+export declare function checkHistoryEntryCount(text: string, path: string, commitSubject?: string): Array<Finding>;
+export declare function checkHistoryEntryComplete(entry: HistoryEntry, path: string): Array<Finding>;
+export declare function checkHistoryAppendOnly(baseText: string, headText: string, path: string): Array<Finding>;

package/dist/features/records/history-checks.js

@@ -0,0 +1,94 @@
+// SPEC §4.9.3: history entry checks (count, completeness, append-only).
+// Pure over caller-supplied text.
+import { normalizeText } from "../../kernel/index.js";
+import { FILE_TITLE, parseHistoryEntries } from "./history-parse.js";
+export function entryFinding(ruleId, message, path) {
+    return {
+        ruleId,
+        path,
+        message,
+        remediation: `Add exactly one history entry whose Subject equals the commit subject, with the Kind, Task, Why and kind-required fields of SPEC §7.7, to ${path}.`,
+    };
+}
+// SPEC §4.9.3 core/history-entry: the staged diff adds exactly one entry
+// whose Subject equals the message subject.
+export function checkHistoryEntryCount(text, path, commitSubject) {
+    const parsed = parseHistoryEntries(text);
+    const problems = [...parsed.errors];
+    if (parsed.entries.length !== 1) {
+        return [
+            entryFinding("core/history-entry", `history change holds ${parsed.entries.length} entries, want exactly one: ${path}`, path),
+        ];
+    }
+    if (commitSubject !== undefined &&
+        parsed.entries[0]?.subject !== commitSubject) {
+        return [
+            entryFinding("core/history-entry", `history Subject "${parsed.entries[0]?.subject ?? ""}" differs from the commit subject "${commitSubject}"`, path),
+        ];
+    }
+    return problems.map((message) => entryFinding("core/history-entry", message, path));
+}
+// SPEC §4.9.3 core/history-entry-complete: the kind-required fields are
+// present and non-empty. Bug is required by the registry check, which knows
+// the commit type; completeness covers the kind shape only.
+export function checkHistoryEntryComplete(entry, path) {
+    const required = entry.kind === "code"
+        ? ["Kind", "Task", "Why", "What went wrong", "Trade-offs", "Lessons"]
+        : entry.kind === "docs"
+            ? ["Kind", "Task", "Why", "Docs"]
+            : entry.kind === "deps"
+                ? ["Kind", "Task", "Why"]
+                : entry.kind === "guardrail"
+                    ? ["Kind", "Task", "Why"]
+                    : ["Kind", "Task", "Why"];
+    const findings = [];
+    for (const name of required) {
+        const value = entry.fields.get(name);
+        if (value === undefined || value.trim() === "") {
+            findings.push({
+                ruleId: "core/history-entry-complete",
+                path,
+                message: `history entry misses its ${name} field: ${entry.subject}`,
+                remediation: `Fill the ${name} field of the "${entry.subject}" entry in ${path}; a field not required is omitted, a required one is never empty.`,
+            });
+        }
+    }
+    if (entry.kind === "deps" && entry.depsLines.length === 0) {
+        findings.push({
+            ruleId: "core/history-entry-complete",
+            path,
+            message: `deps history entry holds no Deps line: ${entry.subject}`,
+            remediation: `Add one Deps line per dependency change to the "${entry.subject}" entry in ${path}.`,
+        });
+    }
+    return findings;
+}
+// SPEC §4.9.3 core/history-append-only: the base content after the title
+// line is a suffix of the head content after normalisation, so new entries
+// are prepended directly under the title and existing entries are never
+// edited.
+function bodyAfterTitle(text) {
+    const end = text.indexOf("\n");
+    if (end < 0) {
+        return undefined;
+    }
+    if (FILE_TITLE.exec(text.slice(0, end).trim()) === null) {
+        return undefined;
+    }
+    return text.slice(end + 1);
+}
+export function checkHistoryAppendOnly(baseText, headText, path) {
+    const baseBody = bodyAfterTitle(normalizeText(baseText));
+    const headBody = bodyAfterTitle(normalizeText(headText));
+    if (baseBody !== undefined && headBody?.endsWith(baseBody) === true) {
+        return [];
+    }
+    return [
+        {
+            ruleId: "core/history-append-only",
+            path,
+            message: `history file edited in place: ${path} head no longer holds its base entries untouched under the title`,
+            remediation: `Prepend the new entry directly under the title of ${path} without touching earlier entries; history is newest-first.`,
+        },
+    ];
+}

package/dist/features/records/history-parse.d.ts

@@ -0,0 +1,16 @@
+export type HistoryKind = "code" | "docs" | "deps" | "guardrail";
+export interface HistoryEntry {
+    readonly date: string;
+    readonly subject: string;
+    readonly kind: HistoryKind | undefined;
+    readonly task: string | undefined;
+    readonly bug: string | undefined;
+    readonly fields: ReadonlyMap<string, string>;
+    readonly depsLines: ReadonlyArray<string>;
+}
+export interface HistoryParse {
+    readonly entries: ReadonlyArray<HistoryEntry>;
+    readonly errors: ReadonlyArray<string>;
+}
+export declare const FILE_TITLE: RegExp;
+export declare function parseHistoryEntries(text: string): HistoryParse;