harnery 0.5.0 → 0.7.0

package/dist/lib/docs-lint.js

@@ -1,5 +1,6 @@
 import { existsSync as __existsSyncForDocs } from "node:fs";
 import { resolve as __resolveForDocs } from "node:path";
+import { hasYamlStatus } from "./docs-frontmatter.js";
 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
@@ -8,10 +9,12 @@ import { sh } from "./exec.js";
 let REPO_ROOT = "";
 let SUBMODULES = [];
 let EXTRA_EXCLUDED_PREFIXES = [];
+let DOCS_ROOT_ALLOWLIST = [];
 export function initDocsContext(opts) {
     REPO_ROOT = opts.repoRoot;
     SUBMODULES = opts.submodules;
     EXTRA_EXCLUDED_PREFIXES = opts.extraExcludedPrefixes ?? [];
+    DOCS_ROOT_ALLOWLIST = opts.docsRootAllowlist ?? [];
 }
 function submodulePath(name) {
     return __resolveForDocs(REPO_ROOT, name);
@@ -128,10 +131,14 @@ 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);
+/** Detect whether a file carries lifecycle status in leading YAML frontmatter. */
+export function hasStatusHeader(path) {
+    try {
+        return hasYamlStatus(readFileSync(path, "utf8"));
+    }
+    catch {
+        return false;
+    }
 }
 // --- Individual checks ---
 /** Entry tier files exist at the repo root */
@@ -196,6 +203,52 @@ function checkRootAllowlist(repoName, repoPath) {
     }
     return violations;
 }
+/**
+ * The host project's `docs/` root is an entry tier: only allowlisted files may
+ * sit loose there; topic docs belong in `docs/<topic>/` subdirs. Config-gated —
+ * a no-op unless the host supplies `docsRootAllowlist`. Parent-repo only:
+ * submodule `docs/` roots have their own entry tiers, not this one.
+ */
+function checkDocsRootAllowlist(repoName, repoPath) {
+    const violations = [];
+    if (DOCS_ROOT_ALLOWLIST.length === 0)
+        return violations; // opt-in
+    if (repoName !== "(root)")
+        return violations; // parent repo only
+    const allow = new Set(DOCS_ROOT_ALLOWLIST);
+    const docsDir = join(repoPath, "docs");
+    let entries;
+    try {
+        entries = readdirSync(docsDir);
+    }
+    catch {
+        return violations; // no docs/ dir — nothing to check
+    }
+    for (const entry of entries) {
+        // Subdirs are the intended home for topic docs; only loose files matter.
+        let isFile;
+        try {
+            isFile = statSync(join(docsDir, entry)).isFile();
+        }
+        catch {
+            continue;
+        }
+        if (!isFile)
+            continue;
+        if (!(entry.endsWith(".md") || entry.endsWith(".json")))
+            continue;
+        if (allow.has(entry))
+            continue;
+        violations.push({
+            severity: "error",
+            repo: repoName,
+            path: join("docs", entry),
+            rule: "docs-root-file",
+            message: `${entry} is not allowed loose at docs/ root — move it into a docs/<topic>/ subdir (or add it to context.docsRootAllowlist if it's a genuine entry-tier doc)`,
+        });
+    }
+    return violations;
+}
 /** No SCREAMING_SNAKE_CASE filenames anywhere */
 function checkNamingConvention(repoName, _repoPath, files) {
     const violations = [];
@@ -295,10 +348,10 @@ function checkChangelogNames(repoName, _repoPath, files) {
     }
     return violations;
 }
-/** Plans and issues must carry a Status header (content check, slow) */
+/** Plans, issues, and handoffs must carry YAML lifecycle status (content check, slow). */
 function checkStatusHeaders(repoName, repoPath, files) {
     const violations = [];
-    const targetDirs = ["docs/plans/", "docs/issues/"];
+    const targetDirs = ["docs/plans/", "docs/issues/", "docs/handoffs/"];
     for (const rel of files) {
         const dirMatch = targetDirs.some((d) => rel.startsWith(d));
         if (!dirMatch)
@@ -306,18 +359,19 @@ function checkStatusHeaders(repoName, repoPath, files) {
         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";
+            const kind = rel.startsWith("docs/plans/")
+                ? "plan"
+                : rel.startsWith("docs/issues/")
+                    ? "issue"
+                    : "handoff";
             violations.push({
-                severity: "warning",
+                severity: "error",
                 repo: repoName,
                 path: join(repoName === "(root)" ? "" : repoName, rel),
                 rule: "missing-status-header",
-                message: `${kind} missing **Status:** line in opening block`,
+                message: `${kind} missing status in leading YAML frontmatter`,
             });
         }
     }
@@ -371,6 +425,7 @@ export async function runLint(opts) {
     for (const { name, path, isSubmodule } of repos) {
         violations.push(...checkEntryTier(name, path, isSubmodule));
         violations.push(...checkRootAllowlist(name, path));
+        violations.push(...checkDocsRootAllowlist(name, path));
         const files = await findMarkdownFiles(path);
         violations.push(...checkNamingConvention(name, path, files));
         violations.push(...checkDatedDirs(name, path, files));

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

@@ -0,0 +1,14 @@
+export interface DocsMetadata {
+    path: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Read the leading YAML frontmatter from a markdown file.
+ *
+ * Relative paths resolve from the host repo root so the command behaves the
+ * same no matter which directory invoked it.
+ */
+export declare function readDocsMetadata(repoRoot: string, inputPath: string): DocsMetadata;
+/** Read one top-level metadata key, failing when the key is absent. */
+export declare function readDocsMetadataKey(metadata: Record<string, unknown>, key: string, inputPath: string): unknown;
+//# sourceMappingURL=docs-meta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docs-meta.d.ts","sourceRoot":"","sources":["../../src/lib/docs-meta.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAgBlF;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,OAAO,CAKT"}

package/dist/lib/docs-meta.js

@@ -0,0 +1,34 @@
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { parseFrontmatter } from "./docs-frontmatter.js";
+/**
+ * Read the leading YAML frontmatter from a markdown file.
+ *
+ * Relative paths resolve from the host repo root so the command behaves the
+ * same no matter which directory invoked it.
+ */
+export function readDocsMetadata(repoRoot, inputPath) {
+    const path = isAbsolute(inputPath) ? resolve(inputPath) : resolve(repoRoot, inputPath);
+    try {
+        if (!statSync(path).isFile())
+            throw new Error("not a file");
+    }
+    catch {
+        throw new Error(`Documentation file not found: ${inputPath}`);
+    }
+    const parsed = parseFrontmatter(readFileSync(path, "utf8"));
+    if (parsed.raw === null) {
+        throw new Error(`Documentation file has no leading YAML frontmatter: ${inputPath}`);
+    }
+    if (Object.keys(parsed.data).length === 0) {
+        throw new Error(`Documentation frontmatter is empty or malformed: ${inputPath}`);
+    }
+    return { path, data: parsed.data };
+}
+/** Read one top-level metadata key, failing when the key is absent. */
+export function readDocsMetadataKey(metadata, key, inputPath) {
+    if (!Object.hasOwn(metadata, key)) {
+        throw new Error(`Documentation frontmatter key '${key}' not found: ${inputPath}`);
+    }
+    return metadata[key];
+}

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

@@ -12,6 +12,10 @@ export declare function initDocsContext(opts: {
  *
  * Audit files and issue files under `docs/audits/` are explicitly **not**
  * flagged for age; they're immutable records by design.
+ *
+ * Performance: ages come from one `git log --name-only` per repo (not one
+ * `git log` per file). A naive per-file spawn was ~1min+ on large hosts
+ * (thousands of topic docs) and looked hung when piped.
  */
 export interface SweepOpts {
     repo?: string;
@@ -24,6 +28,13 @@ export interface SweepItem {
     message: string;
 }
 export type SweepKind = "stalled-plan" | "unarchived-shipped" | "open-issue-cold" | "cold-handoff" | "runbook-unverified" | "topic-doc-stale" | "decisions-dormant";
+type AgeMap = Map<string, number>;
+/**
+ * Parse a `git log --format="COMMIT %aI" --name-only` body into
+ * repo-relative path → age in days. Newest commit wins.
+ * Exported for unit tests.
+ */
+export declare function parseDocsAgeLog(stdout: string, nowMs?: number): AgeMap;
 export declare function runSweep(opts: SweepOpts): Promise<SweepItem[]>;
 /**
  * Cheap parent-repo-only count of `cold-handoff` items, used by `docs lint`
@@ -31,4 +42,5 @@ export declare function runSweep(opts: SweepOpts): Promise<SweepItem[]>;
  * submodule (handoffs live under the parent's docs/handoffs/ by convention).
  */
 export declare function countColdHandoffs(): Promise<number>;
+export {};
 //# sourceMappingURL=docs-sweep.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"docs-sweep.d.ts","sourceRoot":"","sources":["../../src/lib/docs-sweep.ts"],"names":[],"mappings":"AAWA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAG/F;AAaD;;;;;;;;;;;;;;GAcG;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;AAUxB,KAAK,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,MAAM,CAgBlF;AAsND,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CA4BpE;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAKzD"}

package/dist/lib/docs-sweep.js

@@ -1,5 +1,6 @@
 import { existsSync as __existsSyncForDocs } from "node:fs";
 import { resolve as __resolveForDocs } from "node:path";
+import { readDocStatus } from "./docs-frontmatter.js";
 import { sh } from "./exec.js";
 // Module-level docs context, initialized by initDocsContext() before any
 // other function in this file is called. The repo root + submodule list
@@ -16,7 +17,7 @@ function submodulePath(name) {
 function isSubmoduleInitialized(name) {
     return __existsSyncForDocs(__resolveForDocs(REPO_ROOT, name, ".git"));
 }
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 const STALLED_PLAN_DAYS = 90;
 const UNARCHIVED_SHIPPED_DAYS = 180;
@@ -25,13 +26,48 @@ const COLD_HANDOFF_DAYS = 30;
 const RUNBOOK_DAYS = 180;
 const TOPIC_DOC_DAYS = 365;
 const DECISIONS_DORMANT_DAYS = 180;
-/** Days since last git commit touching a file */
-async function lastCommitAgeDays(cwd, file) {
-    const result = await sh(`git log -1 --format=%aI -- "${file}"`, { cwd });
+/**
+ * Parse a `git log --format="COMMIT %aI" --name-only` body into
+ * repo-relative path → age in days. Newest commit wins.
+ * Exported for unit tests.
+ */
+export function parseDocsAgeLog(stdout, nowMs = Date.now()) {
+    const ages = new Map();
+    let currentAge = null;
+    for (const line of stdout.split("\n")) {
+        if (line.startsWith("COMMIT ")) {
+            const iso = line.slice("COMMIT ".length).trim();
+            const ms = Date.parse(iso);
+            currentAge = Number.isNaN(ms) ? null : Math.floor((nowMs - ms) / (1000 * 60 * 60 * 24));
+            continue;
+        }
+        if (!line || currentAge == null)
+            continue;
+        if (!line.endsWith(".md"))
+            continue;
+        // First (newest) sighting wins
+        if (!ages.has(line))
+            ages.set(line, currentAge);
+    }
+    return ages;
+}
+/**
+ * One `git log --name-only` for the whole docs/ tree. Docs histories are
+ * small even without --since (a large host's full docs log is ~5k lines / <100ms),
+ * so we take the full history for accurate ages on old files.
+ */
+async function loadDocsAges(cwd) {
+    const result = await sh(`git log --format="COMMIT %aI" --name-only -- docs/`, {
+        cwd,
+        timeout: 120_000,
+    });
     if (result.exitCode !== 0 || !result.stdout.trim())
-        return null;
-    const ms = Date.now() - new Date(result.stdout.trim()).getTime();
-    return Math.floor(ms / (1000 * 60 * 60 * 24));
+        return new Map();
+    return parseDocsAgeLog(result.stdout);
+}
+/** Age for a tracked path, or null if untracked / never under docs/. */
+function ageDays(ages, rel) {
+    return ages.has(rel) ? ages.get(rel) : null;
 }
 /** Days since ANY commit in the repo (measures repo activity) */
 async function lastRepoCommitAgeDays(cwd) {
@@ -41,48 +77,36 @@ async function lastRepoCommitAgeDays(cwd) {
     const ms = Date.now() - new Date(result.stdout.trim()).getTime();
     return Math.floor(ms / (1000 * 60 * 60 * 24));
 }
-function readStatus(filePath) {
-    try {
-        const content = readFileSync(filePath, "utf8");
-        const head = content.split("\n").slice(0, 20).join("\n");
-        const m = head.match(/\*\*Status:\*\*\s*([a-zA-Z][a-zA-Z-]*)/);
-        return m ? m[1].toLowerCase() : null;
-    }
-    catch {
-        return null;
+function walkMdFiles(dir, skipReadme = false) {
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            out.push(...walkMdFiles(full, skipReadme));
+        }
+        else if (entry.endsWith(".md") && !(skipReadme && entry === "README.md")) {
+            out.push(full);
+        }
     }
+    return out;
 }
-async function sweepPlans(repoName, repoPath, items) {
+function sweepPlans(repoName, repoPath, ages, items) {
     const plansDir = join(repoPath, "docs", "plans");
     if (!existsSync(plansDir))
         return;
-    const walk = (dir) => {
-        const out = [];
-        for (const entry of readdirSync(dir)) {
-            const full = join(dir, entry);
-            let st;
-            try {
-                st = statSync(full);
-            }
-            catch {
-                continue;
-            }
-            if (st.isDirectory()) {
-                out.push(...walk(full));
-            }
-            else if (entry.endsWith(".md") && entry !== "README.md") {
-                out.push(full);
-            }
-        }
-        return out;
-    };
-    const files = walk(plansDir);
-    for (const full of files) {
+    for (const full of walkMdFiles(plansDir, true)) {
         const rel = relative(repoPath, full);
         const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
         const isArchived = rel.includes("/archive/");
-        const status = readStatus(full);
-        const age = await lastCommitAgeDays(repoPath, rel);
+        const status = readDocStatus(full, "plan");
+        const age = ageDays(ages, rel);
         if (age == null)
             continue;
         if (!isArchived && status === "in-progress" && age > STALLED_PLAN_DAYS) {
@@ -105,7 +129,7 @@ async function sweepPlans(repoName, repoPath, items) {
         }
     }
 }
-async function sweepIssues(repoName, repoPath, items) {
+function sweepIssues(repoName, repoPath, ages, items) {
     const issuesDir = join(repoPath, "docs", "issues");
     if (!existsSync(issuesDir))
         return;
@@ -115,10 +139,10 @@ async function sweepIssues(repoName, repoPath, items) {
         const full = join(issuesDir, entry);
         const rel = join("docs", "issues", entry);
         const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
-        const status = readStatus(full);
+        const status = readDocStatus(full, "issue");
         if (status !== "open")
             continue;
-        const age = await lastCommitAgeDays(repoPath, rel);
+        const age = ageDays(ages, rel);
         if (age == null || age <= OPEN_ISSUE_DAYS)
             continue;
         items.push({
@@ -130,36 +154,16 @@ async function sweepIssues(repoName, repoPath, items) {
         });
     }
 }
-async function sweepHandoffs(repoName, repoPath, items) {
+function sweepHandoffs(repoName, repoPath, ages, items) {
     const handoffsDir = join(repoPath, "docs", "handoffs");
     if (!existsSync(handoffsDir))
         return;
-    const walk = (dir) => {
-        const out = [];
-        for (const entry of readdirSync(dir)) {
-            const full = join(dir, entry);
-            let st;
-            try {
-                st = statSync(full);
-            }
-            catch {
-                continue;
-            }
-            if (st.isDirectory()) {
-                out.push(...walk(full));
-            }
-            else if (entry.endsWith(".md")) {
-                out.push(full);
-            }
-        }
-        return out;
-    };
-    for (const full of walk(handoffsDir)) {
+    for (const full of walkMdFiles(handoffsDir)) {
         const rel = relative(repoPath, full);
-        const status = readStatus(full);
+        const status = readDocStatus(full, "handoff");
         if (status !== "open")
             continue;
-        const age = await lastCommitAgeDays(repoPath, rel);
+        const age = ageDays(ages, rel);
         if (age == null || age <= COLD_HANDOFF_DAYS)
             continue;
         const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
@@ -172,11 +176,11 @@ async function sweepHandoffs(repoName, repoPath, items) {
         });
     }
 }
-async function sweepRunbook(repoName, repoPath, items) {
+function sweepRunbook(repoName, repoPath, ages, items) {
     const runbook = join(repoPath, "docs", "runbook.md");
     if (!existsSync(runbook))
         return;
-    const age = await lastCommitAgeDays(repoPath, "docs/runbook.md");
+    const age = ageDays(ages, "docs/runbook.md");
     if (age == null || age <= RUNBOOK_DAYS)
         return;
     const displayPath = join(repoName === "(root)" ? "" : repoName, "docs/runbook.md");
@@ -188,17 +192,22 @@ async function sweepRunbook(repoName, repoPath, items) {
         message: `runbook hasn't been edited in ${age}d; re-verify procedures`,
     });
 }
-async function sweepTopicDocs(repoName, repoPath, items) {
+function sweepTopicDocs(repoName, repoPath, ages, items) {
     const docsDir = join(repoPath, "docs");
     if (!existsSync(docsDir))
         return;
-    // Skip known date-stamped or lifecycle-managed dirs
+    // Skip known date-stamped or lifecycle-managed dirs (and vendor dumps).
+    // handoffs/inquiries are lifecycle-managed elsewhere; vendors match the
+    // docs freshness scanner's IGNORE_DIRS.
     const skipDirs = new Set([
         "audits",
         "issues",
         "plans",
         "changelogs",
         "emails", // parent-specific
+        "handoffs",
+        "inquiries",
+        "vendors",
     ]);
     for (const entry of readdirSync(docsDir)) {
         if (skipDirs.has(entry))
@@ -213,28 +222,9 @@ async function sweepTopicDocs(repoName, repoPath, items) {
         }
         if (!st.isDirectory())
             continue;
-        // For each topic dir, find .md files and check age
-        const walk = (dir) => {
-            const out = [];
-            for (const f of readdirSync(dir)) {
-                const fp = join(dir, f);
-                let s;
-                try {
-                    s = statSync(fp);
-                }
-                catch {
-                    continue;
-                }
-                if (s.isDirectory())
-                    out.push(...walk(fp));
-                else if (f.endsWith(".md"))
-                    out.push(fp);
-            }
-            return out;
-        };
-        for (const full2 of walk(full)) {
+        for (const full2 of walkMdFiles(full)) {
             const rel = relative(repoPath, full2);
-            const age = await lastCommitAgeDays(repoPath, rel);
+            const age = ageDays(ages, rel);
             if (age == null || age <= TOPIC_DOC_DAYS)
                 continue;
             const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
@@ -248,11 +238,11 @@ async function sweepTopicDocs(repoName, repoPath, items) {
         }
     }
 }
-async function sweepDecisions(repoName, repoPath, items) {
+async function sweepDecisions(repoName, repoPath, ages, items) {
     const decisions = join(repoPath, "docs", "decisions.md");
     if (!existsSync(decisions))
         return;
-    const age = await lastCommitAgeDays(repoPath, "docs/decisions.md");
+    const age = ageDays(ages, "docs/decisions.md");
     const repoAge = await lastRepoCommitAgeDays(repoPath);
     if (age == null || repoAge == null)
         return;
@@ -280,13 +270,17 @@ export async function runSweep(opts) {
     const filter = opts.repo === "." ? "(root)" : opts.repo;
     const filtered = filter ? targets.filter((t) => t.name === filter) : targets;
     const items = [];
-    for (const { name, path } of filtered) {
-        await sweepPlans(name, path, items);
-        await sweepIssues(name, path, items);
-        await sweepHandoffs(name, path, items);
-        await sweepRunbook(name, path, items);
-        await sweepTopicDocs(name, path, items);
-        await sweepDecisions(name, path, items);
+    // Load ages per repo in parallel — one git log each, not one per file.
+    const ageMaps = await Promise.all(filtered.map((t) => loadDocsAges(t.path)));
+    for (let i = 0; i < filtered.length; i++) {
+        const { name, path } = filtered[i];
+        const ages = ageMaps[i];
+        sweepPlans(name, path, ages, items);
+        sweepIssues(name, path, ages, items);
+        sweepHandoffs(name, path, ages, items);
+        sweepRunbook(name, path, ages, items);
+        sweepTopicDocs(name, path, ages, items);
+        await sweepDecisions(name, path, ages, items);
     }
     // Sort by severity proxy: oldest first within kind
     items.sort((a, b) => b.ageDays - a.ageDays);
@@ -299,6 +293,7 @@ export async function runSweep(opts) {
  */
 export async function countColdHandoffs() {
     const items = [];
-    await sweepHandoffs("(root)", REPO_ROOT, items);
+    const ages = await loadDocsAges(REPO_ROOT);
+    sweepHandoffs("(root)", REPO_ROOT, ages, items);
     return items.length;
 }

package/dist/lib/format.js

@@ -50,7 +50,7 @@ export function colorJson(value, indent = 0) {
             // Class instances that define toJSON() (Big.js, Decimal.js, Date, etc.)
             // would render as their raw internal shape if we walked Object.keys
             // directly. Unwrap once so callers see the intended representation
-            // (Big.js → "1.97" instead of {s,e,c} from BigQuery NUMERIC fields).
+            // (e.g. Big.js → "1.97" instead of its internal {s,e,c} fields).
             const maybeJsonable = v;
             if (typeof maybeJsonable.toJSON === "function") {
                 return fmt(maybeJsonable.toJSON(), depth);
@@ -109,7 +109,7 @@ function stringify(val) {
     if (typeof val === "object") {
         if (val instanceof Date)
             return val.toISOString();
-        // BigQuery returns { value: "..." } for some types
+        // Some data sources wrap a scalar as { value: "..." }; unwrap to the inner value.
         if ("value" in val && Object.keys(val).length === 1) {
             return String(val.value);
         }

package/dist/lib/http/index.d.ts

@@ -1,2 +1,3 @@
 export { type FetchOptions, type FetchResult, fetchWithJar } from "./client.js";
+export * from "./request.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/http/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChF,cAAc,cAAc,CAAC"}

package/dist/lib/http/index.js

@@ -1 +1,2 @@
 export { fetchWithJar } from "./client.js";
+export * from "./request.js";

package/dist/lib/http/request.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Retrying JSON-API request — the toolkit-tier HTTP primitive for host CLIs'
+ * vendor clients.
+ *
+ * Extracted from the first embedding host, where ten vendor clients carried
+ * byte-similar copies of the same loop: abort-controller timeout, retry on
+ * 429/5xx with exponential backoff + jitter, `Retry-After` honored when sane,
+ * vendor-specific error taxonomy applied by the caller. This module owns the
+ * loop; callers keep their auth headers and error classes:
+ *
+ *   const r = await requestWithRetries(url, {
+ *     method, body,
+ *     headers: { Authorization: `ApiKey ${key}`, Accept: "application/json" },
+ *     timeoutMs: this.timeoutMs,
+ *     maxRetries: this.maxRetries,
+ *     onResponse: ({ status }) => log(`${method} ${url} → ${status}`),
+ *     networkError: (msg) => new VendorError("network_error", msg),
+ *   });
+ *   if (!r.ok) throw makeHttpError(r.status, url, r.text, r.headers);
+ *
+ * Design choices, so they survive review:
+ *   - Terminal non-2xx responses RETURN (`ok: false`) rather than throw — the
+ *     vendor error taxonomy belongs to the caller, not this module.
+ *   - Only terminal NETWORK failures throw (after retries), because there is
+ *     no response to hand back; `networkError` lets the caller keep its class.
+ *   - The response body is always read (even on retried statuses) so keep-alive
+ *     sockets are released.
+ */
+export interface RetryingResponse {
+    /** `status` in the 2xx range. */
+    ok: boolean;
+    status: number;
+    /** Response body as text; callers handle JSON parsing. */
+    text: string;
+    url: string;
+    headers: Headers;
+}
+export interface RequestWithRetriesOptions {
+    /** HTTP method. Default GET. */
+    method?: string;
+    /** Extra headers. Content-Type defaults to application/json when a non-string body is given. */
+    headers?: Record<string, string>;
+    /**
+     * Request body. Strings, Uint8Array, FormData, Blob, and ReadableStream pass
+     * through untouched; any other value is JSON.stringify'd (with a
+     * Content-Type: application/json default).
+     */
+    body?: unknown;
+    /** Per-attempt timeout (AbortController). Default 30s. */
+    timeoutMs?: number;
+    /** Retries after the first attempt. Default 3. */
+    maxRetries?: number;
+    /** Which statuses to retry. Default: 429 and 5xx. */
+    shouldRetry?: (status: number) => boolean;
+    /** Delay before retry `attempt` (0-based). Default `backoffDelayMs`. */
+    delayMs?: (attempt: number, retryAfterSeconds?: number | null) => number;
+    /** Observability hook — fires once per received response (every attempt). */
+    onResponse?: (info: {
+        method: string;
+        url: string;
+        status: number;
+        attempt: number;
+    }) => void;
+    /**
+     * Wrap a terminal network failure (fetch threw on the last attempt) in the
+     * caller's error class. Default: a plain Error with the message.
+     */
+    networkError?: (message: string, url: string, retries: number) => Error;
+}
+/**
+ * Exponential backoff with jitter: 500ms · 2^attempt, capped at 30s, plus up
+ * to 250ms of jitter. A sane `Retry-After` (0 < s < 60) short-circuits the
+ * curve — the server knows better than the guess.
+ */
+export declare function backoffDelayMs(attempt: number, retryAfterSeconds?: number | null): number;
+export declare function requestWithRetries(url: string, opts?: RequestWithRetriesOptions): Promise<RetryingResponse>;
+//# sourceMappingURL=request.d.ts.map

package/dist/lib/http/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../../src/lib/http/request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAC;IACzE,6EAA6E;IAC7E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC9F;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;CACzE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAMzF;AAMD,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,gBAAgB,CAAC,CAkE3B"}