harnery 0.0.1 → 0.2.1

package/dist/lib/docs-index.d.ts

@@ -0,0 +1,28 @@
+export declare function initDocsContext(opts: {
+    repoRoot: string;
+    submodules: readonly string[];
+}): void;
+/**
+ * Regenerates index READMEs in docs/audits/ and docs/issues/ directories.
+ * Idempotent: safe to run on every commit. Reads the first ~30 lines of
+ * each dated file to extract title and (for issues) status.
+ *
+ * Preserves hand-written preambles. The command updates only the section
+ * between `<!-- BEGIN INDEX -->` and `<!-- END INDEX -->` markers. If a
+ * README exists without markers, the command refuses to overwrite it and
+ * reports it as `needs-markers` so the human can insert them explicitly.
+ * New READMEs (no file yet) are created with a minimal default preamble.
+ */
+export interface IndexOpts {
+    dryRun?: boolean;
+    repo?: string;
+}
+export type IndexStatus = "unchanged" | "updated" | "needs-markers" | "created";
+export interface IndexResult {
+    path: string;
+    status: IndexStatus;
+    before: string;
+    after: string;
+}
+export declare function runIndex(opts: IndexOpts): Promise<IndexResult[]>;
+//# sourceMappingURL=docs-index.d.ts.map

package/dist/lib/docs-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-index.d.ts","sourceRoot":"","sources":["../../src/lib/docs-index.ts"],"names":[],"mappings":"AASA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAG/F;AAcD;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAAC;AAEhF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAsHD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA+CtE"}

package/dist/lib/docs-index.js

@@ -0,0 +1,169 @@
+import { existsSync as __existsSyncForDocs } from "node:fs";
+import { resolve as __resolveForDocs } from "node:path";
+// Module-level docs context, initialized by initDocsContext() before any
+// other function in this file is called. The repo root + submodule list
+// are passed via the context provided to registerDocsCommand.
+let REPO_ROOT = "";
+let SUBMODULES = [];
+export function initDocsContext(opts) {
+    REPO_ROOT = opts.repoRoot;
+    SUBMODULES = opts.submodules;
+}
+function submodulePath(name) {
+    return __resolveForDocs(REPO_ROOT, name);
+}
+function isSubmoduleInitialized(name) {
+    return __existsSyncForDocs(__resolveForDocs(REPO_ROOT, name, ".git"));
+}
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { resolveBinName } from "../core/config.js";
+const DATED_FILE_PATTERN = /^(\d{4}-\d{2}-\d{2})_([a-z0-9][a-z0-9_-]*)\.md$/i;
+function extractTitle(content, fallbackSlug) {
+    const h1Match = content.match(/^#\s+(.+)$/m);
+    if (h1Match)
+        return h1Match[1].trim();
+    // Fallback: slug → Title Case
+    return fallbackSlug.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function extractStatus(content) {
+    const head = content.split("\n").slice(0, 20).join("\n");
+    const match = head.match(/\*\*Status:\*\*\s*([a-zA-Z][a-zA-Z-]*)/);
+    return match ? match[1].toLowerCase() : undefined;
+}
+function readEntries(dir, includeStatus) {
+    if (!existsSync(dir))
+        return [];
+    const entries = [];
+    for (const f of readdirSync(dir)) {
+        if (f === "README.md")
+            continue;
+        const m = f.match(DATED_FILE_PATTERN);
+        if (!m)
+            continue;
+        const [, date, slug] = m;
+        let content = "";
+        try {
+            content = readFileSync(join(dir, f), "utf8");
+        }
+        catch {
+            continue;
+        }
+        entries.push({
+            file: f,
+            date: date,
+            title: extractTitle(content, slug),
+            status: includeStatus ? extractStatus(content) : undefined,
+        });
+    }
+    // Newest first
+    entries.sort((a, b) => b.date.localeCompare(a.date));
+    return entries;
+}
+function renderAuditsTable(entries) {
+    if (entries.length === 0)
+        return "_No audits recorded._\n";
+    const lines = ["| Date | File | Description |", "|------|------|-------------|"];
+    for (const e of entries) {
+        lines.push(`| ${e.date} | [${e.file}](${e.file}) | ${e.title} |`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderIssuesTable(entries) {
+    if (entries.length === 0)
+        return "_No issues recorded._\n";
+    const lines = [
+        "| Date | File | Status | Description |",
+        "|------|------|--------|-------------|",
+    ];
+    for (const e of entries) {
+        const status = e.status ?? "unknown";
+        lines.push(`| ${e.date} | [${e.file}](${e.file}) | ${status} | ${e.title} |`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+const BEGIN_MARKER = "<!-- BEGIN INDEX -->";
+const END_MARKER = "<!-- END INDEX -->";
+function defaultPreamble(kind) {
+    const regen = `The table below is regenerated by \`${resolveBinName()} docs index\`; do not hand-edit it. Add prose above the \`BEGIN INDEX\` marker instead.`;
+    return kind === "audits"
+        ? [
+            "# Audit Documents",
+            "",
+            "Immutable, date-stamped reports. File names follow `YYYY-MM-DD_<slug>.md`.",
+            "",
+            regen,
+            "",
+        ].join("\n")
+        : [
+            "# Issues",
+            "",
+            "Date-stamped post-mortems and investigations. File names follow `YYYY-MM-DD_<slug>.md`.",
+            "Each file carries a `**Status:**` line (open | resolved | wontfix).",
+            "",
+            regen,
+            "",
+        ].join("\n");
+}
+/** Replace ONLY the section between the markers. Never touch content outside them. */
+function spliceBetweenMarkers(existing, body) {
+    const beginIdx = existing.indexOf(BEGIN_MARKER);
+    const endIdx = existing.indexOf(END_MARKER);
+    if (beginIdx < 0 || endIdx < 0 || endIdx < beginIdx) {
+        // Caller should have checked hasMarkers() first; return unchanged as a safe fallback.
+        return existing;
+    }
+    const before = existing.slice(0, beginIdx + BEGIN_MARKER.length);
+    const after = existing.slice(endIdx);
+    return `${before}\n${body}${after}`;
+}
+function hasMarkers(existing) {
+    return existing.includes(BEGIN_MARKER) && existing.includes(END_MARKER);
+}
+function buildNewReadme(kind, body) {
+    return `${defaultPreamble(kind)}\n${BEGIN_MARKER}\n${body}${END_MARKER}\n`;
+}
+export async function runIndex(opts) {
+    const targets = [{ name: "(root)", path: REPO_ROOT }];
+    for (const name of SUBMODULES) {
+        if (!isSubmoduleInitialized(name))
+            continue;
+        targets.push({ name, path: submodulePath(name) });
+    }
+    const filter = opts.repo === "." ? "(root)" : opts.repo;
+    const filtered = filter ? targets.filter((t) => t.name === filter) : targets;
+    const results = [];
+    for (const { name: _name, path } of filtered) {
+        for (const kind of ["audits", "issues"]) {
+            const dir = join(path, "docs", kind);
+            if (!existsSync(dir))
+                continue;
+            const entries = readEntries(dir, kind === "issues");
+            const body = kind === "audits" ? renderAuditsTable(entries) : renderIssuesTable(entries);
+            const readmePath = join(dir, "README.md");
+            const exists = existsSync(readmePath);
+            const before = exists ? readFileSync(readmePath, "utf8") : "";
+            const displayPath = relative(REPO_ROOT, readmePath);
+            let status;
+            let after;
+            if (!exists) {
+                after = buildNewReadme(kind, body);
+                status = "created";
+            }
+            else if (!hasMarkers(before)) {
+                // Hands off: the human-written README has no markers. Don't touch it.
+                after = before;
+                status = "needs-markers";
+            }
+            else {
+                after = spliceBetweenMarkers(before, body);
+                status = before === after ? "unchanged" : "updated";
+            }
+            results.push({ path: displayPath, status, before, after });
+            if (!opts.dryRun && (status === "updated" || status === "created")) {
+                writeFileSync(readmePath, after, "utf8");
+            }
+        }
+    }
+    return results;
+}

package/dist/lib/docs-lint.d.ts

@@ -0,0 +1,26 @@
+export declare function initDocsContext(opts: {
+    repoRoot: string;
+    submodules: readonly string[];
+    extraExcludedPrefixes?: readonly string[];
+}): void;
+/**
+ * Documentation linter. Enforces the docs directory-layout + naming contract.
+ *
+ * Each violation carries a severity: `error` fails the lint, `warning` is
+ * informational. `--fast` mode skips content-reading checks so the pre-commit
+ * hook stays cheap.
+ */
+export type Severity = "error" | "warning";
+export interface Violation {
+    severity: Severity;
+    repo: string;
+    path: string;
+    rule: string;
+    message: string;
+}
+export interface LintOpts {
+    fast?: boolean;
+    repo?: string;
+}
+export declare function runLint(opts: LintOpts): Promise<Violation[]>;
+//# sourceMappingURL=docs-lint.d.ts.map

package/dist/lib/docs-lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAYA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C,GAAG,IAAI,CAIP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAkVD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAoBlE"}

package/dist/lib/docs-lint.js

@@ -0,0 +1,378 @@
+import { existsSync as __existsSyncForDocs } from "node:fs";
+import { resolve as __resolveForDocs } from "node:path";
+import { sh } from "./exec.js";
+// Module-level docs context, initialized by initDocsContext() before any
+// other function in this file is called. Consumers pass repo metadata
+// + an optional list of extra excluded path prefixes for project-specific
+// directories that shouldn't be subject to doc-lint conventions.
+let REPO_ROOT = "";
+let SUBMODULES = [];
+let EXTRA_EXCLUDED_PREFIXES = [];
+export function initDocsContext(opts) {
+    REPO_ROOT = opts.repoRoot;
+    SUBMODULES = opts.submodules;
+    EXTRA_EXCLUDED_PREFIXES = opts.extraExcludedPrefixes ?? [];
+}
+function submodulePath(name) {
+    return __resolveForDocs(REPO_ROOT, name);
+}
+function isSubmoduleInitialized(name) {
+    return __existsSyncForDocs(__resolveForDocs(REPO_ROOT, name, ".git"));
+}
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+/** Files allowed at a submodule root level. Includes:
+ *  - In-repo conventions: README.md, CLAUDE.md, LLM-BRIEFING.md, AGENTS.md
+ *  - GitHub OSS conventions: CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md,
+ *    SECURITY.md, SUPPORT.md, AUTHORS.md, MAINTAINERS.md, PULL_REQUEST_TEMPLATE.md
+ *    (these are recognized by the GitHub UI, and renaming them breaks the integration)
+ */
+const ROOT_FILE_ALLOWLIST = new Set([
+    "README.md",
+    "CLAUDE.md",
+    "LLM-BRIEFING.md",
+    "AGENTS.md",
+    // GitHub-recognized OSS package files
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md",
+    "SUPPORT.md",
+    "AUTHORS.md",
+    "MAINTAINERS.md",
+    "PULL_REQUEST_TEMPLATE.md",
+]);
+/** Paths that are excluded from markdown discipline even when git-tracked.
+ *
+ * Covers auto-generated reference dumps and vendored content pages that happen
+ * to be checked into git but aren't subject to doc conventions. Paths are
+ * relative to the scanned repo root; any file under one of these prefixes is
+ * ignored.
+ *
+ * Note: git-ignored directories (node_modules, .venv, vendor, dbt_packages,
+ * target, dist, build) are already excluded because we use `git ls-files`.
+ */
+// Built-in exclusions: auto-generated/framework dirs that ship in any
+// project. Consumers extend this via `extraExcludedPrefixes` in
+// initDocsContext for their own project-specific dirs (auto-generated
+// API references, vendored content, etc.).
+const EXCLUDED_PREFIXES = [
+    ".agents/", // canonical AI-config sources (skills, subagents, rules, claude-addendum)
+    ".claude/", // Claude Code framework files (SKILL.md, agents)
+    ".harnery/", // harnery coord/skill state
+    ".codex/", // OpenAI Codex framework files (skills/, agents/)
+    ".cursor/", // auto-generated Cursor rules
+];
+/** Filename patterns that should never exist */
+const FORBIDDEN_ROOT_NAMES = new Set([
+    "TODO.md",
+    "PROJECT.md",
+    "VISION.md",
+    "NOTES.md",
+    "DECISIONS.md", // should be docs/decisions.md
+    "CHANGELOG.md", // should be docs/changelogs/YYYY-MM.md
+]);
+/** YYYY-MM-DD_<slug>.md */
+const DATED_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}_[a-z0-9][a-z0-9_-]*\.md$/i;
+/** YYYY-MM.md for changelogs */
+const CHANGELOG_PATTERN = /^\d{4}-\d{2}\.md$/;
+/** SCREAMING_SNAKE_CASE.md, excluding allowlisted entry files */
+const SCREAMING_SNAKE_PATTERN = /^[A-Z][A-Z0-9_]+\.md$/;
+/** kebab-case.md: lowercase letters, digits, hyphens */
+const KEBAB_CASE_PATTERN = /^[a-z0-9][a-z0-9-]*\.md$/;
+/** Target repos to lint: parent + every initialized submodule */
+function getTargetRepos(opts) {
+    const all = [
+        { name: "(root)", path: REPO_ROOT, isSubmodule: false },
+    ];
+    for (const name of SUBMODULES) {
+        if (!isSubmoduleInitialized(name))
+            continue;
+        all.push({ name, path: submodulePath(name), isSubmodule: true });
+    }
+    if (opts.repo) {
+        const filter = opts.repo === "." ? "(root)" : opts.repo;
+        return all.filter((r) => r.name === filter);
+    }
+    return all;
+}
+/** List all tracked .md files in the given repo via `git ls-files`.
+ * Returns paths relative to the repo root. Automatically skips node_modules,
+ * vendor, .venv, dbt_packages, build/ etc. because they're gitignored.
+ */
+async function findMarkdownFiles(root) {
+    const result = await sh('git ls-files --cached "**/*.md" "*.md"', { cwd: root });
+    if (result.exitCode !== 0 || !result.stdout)
+        return [];
+    return result.stdout
+        .split("\n")
+        .filter((f) => f.endsWith(".md"))
+        .filter((f) => 
+    // Framework dirs are excluded at any depth, not just repo root;
+    // in-tree repos (monorepos like harnery) nest .claude/.agents/etc.
+    !EXCLUDED_PREFIXES.some((p) => f.startsWith(p) || f.includes(`/${p}`)) &&
+        !EXTRA_EXCLUDED_PREFIXES.some((p) => f.startsWith(p) || f.includes(`/${p}`)));
+}
+/** Read first N lines of a file for header inspection */
+function readHead(path, lines = 20) {
+    try {
+        const content = readFileSync(path, "utf8");
+        return content.split("\n").slice(0, lines).join("\n");
+    }
+    catch {
+        return "";
+    }
+}
+/** Detect whether a file declares itself an intentional monolith */
+function isDeclaredMonolith(path) {
+    const head = readHead(path, 10);
+    return /INTENTIONAL-MONOLITH/i.test(head);
+}
+/** Detect whether a file carries a Status line in its opening block */
+function hasStatusHeader(path) {
+    const head = readHead(path, 15);
+    return /\*\*Status:\*\*/i.test(head);
+}
+// --- Individual checks ---
+/** Entry tier files exist at the repo root */
+function checkEntryTier(repoName, repoPath, isSubmodule) {
+    const violations = [];
+    // README.md is required for any repo
+    if (!existsSync(join(repoPath, "README.md"))) {
+        violations.push({
+            severity: "error",
+            repo: repoName,
+            path: join(repoName === "(root)" ? "" : repoName, "README.md"),
+            rule: "entry-tier",
+            message: "README.md missing at repo root",
+        });
+    }
+    // CLAUDE.md required for submodules (primary LLM context)
+    if (isSubmodule && !existsSync(join(repoPath, "CLAUDE.md"))) {
+        violations.push({
+            severity: "error",
+            repo: repoName,
+            path: join(repoName, "CLAUDE.md"),
+            rule: "entry-tier",
+            message: "CLAUDE.md missing: primary LLM context file",
+        });
+    }
+    return violations;
+}
+/** No forbidden root-level files */
+function checkRootAllowlist(repoName, repoPath) {
+    const violations = [];
+    let entries;
+    try {
+        entries = readdirSync(repoPath);
+    }
+    catch {
+        return violations;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".md"))
+            continue;
+        if (ROOT_FILE_ALLOWLIST.has(entry))
+            continue;
+        const displayPath = join(repoName === "(root)" ? "" : repoName, entry);
+        if (FORBIDDEN_ROOT_NAMES.has(entry)) {
+            violations.push({
+                severity: "error",
+                repo: repoName,
+                path: displayPath,
+                rule: "forbidden-root-file",
+                message: `${entry} is not allowed at repo root`,
+            });
+        }
+        else if (SCREAMING_SNAKE_PATTERN.test(entry)) {
+            violations.push({
+                severity: "error",
+                repo: repoName,
+                path: displayPath,
+                rule: "root-caps-file",
+                message: `${entry} is an ad-hoc caps file at repo root: entry tier is reserved for README.md / CLAUDE.md / LLM-BRIEFING.md / AGENTS.md`,
+            });
+        }
+    }
+    return violations;
+}
+/** No SCREAMING_SNAKE_CASE filenames anywhere */
+function checkNamingConvention(repoName, _repoPath, files) {
+    const violations = [];
+    for (const rel of files) {
+        const name = basename(rel);
+        // Allowlisted names
+        if (ROOT_FILE_ALLOWLIST.has(name))
+            continue;
+        // Dated files (audits/issues)
+        if (DATED_FILE_PATTERN.test(name))
+            continue;
+        // Changelogs
+        if (CHANGELOG_PATTERN.test(name))
+            continue;
+        // decisions.md, runbook.md: explicit
+        if (name === "decisions.md" || name === "runbook.md")
+            continue;
+        // Known-good kebab-case
+        if (KEBAB_CASE_PATTERN.test(name))
+            continue;
+        // README.md inside a subdir is fine
+        if (name === "README.md")
+            continue;
+        // SCREAMING_SNAKE_CASE violations
+        if (SCREAMING_SNAKE_PATTERN.test(name)) {
+            violations.push({
+                severity: "error",
+                repo: repoName,
+                path: join(repoName === "(root)" ? "" : repoName, rel),
+                rule: "screaming-snake-case",
+                message: `filename ${name} uses SCREAMING_SNAKE_CASE; rename to kebab-case`,
+            });
+            continue;
+        }
+        // Anything else that's not kebab-case is a warning (Title Case, mixed)
+        if (!/^[a-z0-9]/.test(name)) {
+            violations.push({
+                severity: "warning",
+                repo: repoName,
+                path: join(repoName === "(root)" ? "" : repoName, rel),
+                rule: "non-kebab-filename",
+                message: `filename ${name} is not kebab-case`,
+            });
+        }
+    }
+    return violations;
+}
+/** Files in docs/audits/ and docs/issues/ must match YYYY-MM-DD_<slug>.md */
+function checkDatedDirs(repoName, _repoPath, files) {
+    const violations = [];
+    const datedDirs = ["docs/audits/", "docs/issues/"];
+    for (const rel of files) {
+        for (const d of datedDirs) {
+            if (!rel.startsWith(d))
+                continue;
+            const name = basename(rel);
+            // README.md is the index file, allowed
+            if (name === "README.md")
+                continue;
+            if (!DATED_FILE_PATTERN.test(name)) {
+                violations.push({
+                    severity: "error",
+                    repo: repoName,
+                    path: join(repoName === "(root)" ? "" : repoName, rel),
+                    rule: "undated-in-dated-dir",
+                    message: `${d} file must match YYYY-MM-DD_<slug>.md; got ${name}`,
+                });
+            }
+        }
+    }
+    return violations;
+}
+/** Changelog files must match YYYY-MM.md */
+function checkChangelogNames(repoName, _repoPath, files) {
+    const violations = [];
+    for (const rel of files) {
+        if (!rel.startsWith("docs/changelogs/"))
+            continue;
+        const name = basename(rel);
+        if (name === "README.md")
+            continue;
+        if (!CHANGELOG_PATTERN.test(name)) {
+            violations.push({
+                severity: "error",
+                repo: repoName,
+                path: join(repoName === "(root)" ? "" : repoName, rel),
+                rule: "bad-changelog-name",
+                message: `changelog must match YYYY-MM.md; got ${name}`,
+            });
+        }
+    }
+    return violations;
+}
+/** Plans and issues must carry a Status header (content check, slow) */
+function checkStatusHeaders(repoName, repoPath, files) {
+    const violations = [];
+    const targetDirs = ["docs/plans/", "docs/issues/"];
+    for (const rel of files) {
+        const dirMatch = targetDirs.some((d) => rel.startsWith(d));
+        if (!dirMatch)
+            continue;
+        const name = basename(rel);
+        if (name === "README.md")
+            continue;
+        // Skip archive subdir
+        if (rel.includes("/archive/"))
+            continue;
+        const full = join(repoPath, rel);
+        if (!hasStatusHeader(full)) {
+            const kind = rel.startsWith("docs/plans/") ? "plan" : "issue";
+            violations.push({
+                severity: "warning",
+                repo: repoName,
+                path: join(repoName === "(root)" ? "" : repoName, rel),
+                rule: "missing-status-header",
+                message: `${kind} missing **Status:** line in opening block`,
+            });
+        }
+    }
+    return violations;
+}
+/** Intentional monoliths >30KB need a declaration banner */
+function checkMonolithDeclaration(repoName, repoPath, files) {
+    const violations = [];
+    const SIZE_THRESHOLD = 30 * 1024;
+    for (const rel of files) {
+        // Only flag top-level docs/ files, not per-repo entry tier (LLM-BRIEFING
+        // files are monoliths by convention, no banner needed).
+        if (repoName !== "(root)")
+            continue;
+        if (!rel.startsWith("docs/"))
+            continue;
+        if (rel.startsWith("docs/plans/"))
+            continue;
+        if (rel.startsWith("docs/audits/"))
+            continue;
+        if (rel.startsWith("docs/issues/"))
+            continue;
+        if (rel.startsWith("docs/changelogs/"))
+            continue;
+        const full = join(repoPath, rel);
+        let size;
+        try {
+            size = statSync(full).size;
+        }
+        catch {
+            continue;
+        }
+        if (size < SIZE_THRESHOLD)
+            continue;
+        if (isDeclaredMonolith(full))
+            continue;
+        violations.push({
+            severity: "warning",
+            repo: repoName,
+            path: rel,
+            rule: "undeclared-monolith",
+            message: `${(size / 1024).toFixed(0)} KB file has no INTENTIONAL-MONOLITH banner; add one or split`,
+        });
+    }
+    return violations;
+}
+// --- Runner ---
+export async function runLint(opts) {
+    const violations = [];
+    const repos = getTargetRepos(opts);
+    for (const { name, path, isSubmodule } of repos) {
+        violations.push(...checkEntryTier(name, path, isSubmodule));
+        violations.push(...checkRootAllowlist(name, path));
+        const files = await findMarkdownFiles(path);
+        violations.push(...checkNamingConvention(name, path, files));
+        violations.push(...checkDatedDirs(name, path, files));
+        violations.push(...checkChangelogNames(name, path, files));
+        if (!opts.fast) {
+            violations.push(...checkStatusHeaders(name, path, files));
+            violations.push(...checkMonolithDeclaration(name, path, files));
+        }
+    }
+    return violations;
+}

package/dist/lib/docs-sweep.d.ts

@@ -0,0 +1,34 @@
+export declare function initDocsContext(opts: {
+    repoRoot: string;
+    submodules: readonly string[];
+}): void;
+/**
+ * Surfaces stalled lifecycle states across the monorepo: plans in-progress
+ * too long, open issues gone cold, runbooks that haven't been verified, etc.
+ *
+ * This is the opposite of `docs --stale`, which flags file-level freshness.
+ * Sweep only flags items where the lifecycle state (status header + mtime)
+ * suggests attention is needed.
+ *
+ * Audit files and issue files under `docs/audits/` are explicitly **not**
+ * flagged for age; they're immutable records by design.
+ */
+export interface SweepOpts {
+    repo?: string;
+}
+export interface SweepItem {
+    kind: SweepKind;
+    repo: string;
+    path: string;
+    ageDays: number;
+    message: string;
+}
+export type SweepKind = "stalled-plan" | "unarchived-shipped" | "open-issue-cold" | "cold-handoff" | "runbook-unverified" | "topic-doc-stale" | "decisions-dormant";
+export declare function runSweep(opts: SweepOpts): Promise<SweepItem[]>;
+/**
+ * Cheap parent-repo-only count of `cold-handoff` items, used by `docs lint`
+ * to print a one-line nudge without running the full sweep across every
+ * submodule (handoffs live under the parent's docs/handoffs/ by convention).
+ */
+export declare function countColdHandoffs(): Promise<number>;
+//# sourceMappingURL=docs-sweep.d.ts.map

package/dist/lib/docs-sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-sweep.d.ts","sourceRoot":"","sources":["../../src/lib/docs-sweep.ts"],"names":[],"mappings":"AAUA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAG/F;AAaD;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,SAAS,GACjB,cAAc,GACd,oBAAoB,GACpB,iBAAiB,GACjB,cAAc,GACd,oBAAoB,GACpB,iBAAiB,GACjB,mBAAmB,CAAC;AAgQxB,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAuBpE;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAIzD"}