@isaacriehm/cairn-core 0.1.0

package/dist/gc/doc-gardening.d.ts

@@ -0,0 +1,29 @@
+/**
+ * GC pass 4 — doc gardening.
+ *
+ * Walks every markdown in the canonical zone and surfaces:
+ *   - broken-link findings: `[text](relative/path.md)` whose target doesn't exist
+ *     under repoRoot. Absolute URLs (https://...) are skipped.
+ *   - orphan-path findings: markdown files that are not referenced by any other
+ *     markdown in the canonical zone. Orientation files (AGENTS.md, CLAUDE.md,
+ *     README.md, RESUME_PROMPT.md) and explicitly-allowed roots are excluded.
+ *
+ * Phase 12 v1 surfaces only — moving orphans to `.archive/` per the original
+ * spec needs operator confirmation (it's a non-trivial canonical-zone change).
+ * The proposal type is set up so a future revision can attach an archive-move
+ * commit when the operator opts in.
+ */
+import type { GcFinding } from "./types.js";
+export interface DocGardeningOptions {
+    repoRoot: string;
+    /**
+     * Additional repo-relative paths to treat as orphan-allowed roots. Useful
+     * for project-specific entry-point docs that nothing links to (e.g. wiki
+     * landing pages).
+     */
+    orphanExcludes?: readonly string[];
+}
+export interface DocGardeningResult {
+    findings: GcFinding[];
+}
+export declare function runDocGardening(opts: DocGardeningOptions): DocGardeningResult;

package/dist/gc/doc-gardening.js

@@ -0,0 +1,146 @@
+/**
+ * GC pass 4 — doc gardening.
+ *
+ * Walks every markdown in the canonical zone and surfaces:
+ *   - broken-link findings: `[text](relative/path.md)` whose target doesn't exist
+ *     under repoRoot. Absolute URLs (https://...) are skipped.
+ *   - orphan-path findings: markdown files that are not referenced by any other
+ *     markdown in the canonical zone. Orientation files (AGENTS.md, CLAUDE.md,
+ *     README.md, RESUME_PROMPT.md) and explicitly-allowed roots are excluded.
+ *
+ * Phase 12 v1 surfaces only — moving orphans to `.archive/` per the original
+ * spec needs operator confirmation (it's a non-trivial canonical-zone change).
+ * The proposal type is set up so a future revision can attach an archive-move
+ * commit when the operator opts in.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, posix, resolve } from "node:path";
+import { walkCanonical } from "../ground/walk.js";
+const PASS_ID = "doc-gardening";
+const ORPHAN_ROOT_EXCLUDES = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "README.md",
+    "RESUME_PROMPT.md",
+    ".cairn/config/workflow.md",
+    ".cairn/config/sensors.yaml",
+    ".cairn/config/stub-patterns.yaml",
+    ".cairn/config/trust-policy.yaml",
+];
+export function runDocGardening(opts) {
+    const findings = [];
+    const allFiles = walkCanonical(opts.repoRoot);
+    const mdFiles = allFiles.filter((p) => p.endsWith(".md"));
+    const referenced = new Set();
+    for (const rel of mdFiles) {
+        const abs = resolve(opts.repoRoot, rel);
+        let source;
+        try {
+            source = readFileSync(abs, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const links = extractMarkdownLinks(source);
+        for (const link of links) {
+            if (link.url.length === 0)
+                continue;
+            if (isExternalUrl(link.url))
+                continue;
+            if (link.url.startsWith("#"))
+                continue; // intra-page anchor
+            const target = resolveLinkTarget(opts.repoRoot, rel, link.url);
+            if (target === null)
+                continue;
+            if (!fileExists(opts.repoRoot, target)) {
+                findings.push({
+                    pass: PASS_ID,
+                    kind: "broken_link",
+                    path: rel,
+                    detail: `${rel}:${link.line} → \`${link.url}\` (target ${target} missing)`,
+                    severity: "warn",
+                    line: link.line,
+                    matched_text: link.url,
+                });
+            }
+            else if (target.endsWith(".md")) {
+                referenced.add(target);
+            }
+        }
+    }
+    // Orphan detection — markdowns not referenced by any other markdown.
+    const allowOrphan = new Set([
+        ...ORPHAN_ROOT_EXCLUDES,
+        ...(opts.orphanExcludes ?? []),
+    ]);
+    for (const rel of mdFiles) {
+        if (allowOrphan.has(rel))
+            continue;
+        if (!referenced.has(rel)) {
+            findings.push({
+                pass: PASS_ID,
+                kind: "orphan_path",
+                path: rel,
+                detail: `${rel} is not referenced by any other markdown in the canonical zone — candidate for .archive/ move`,
+                severity: "warn",
+            });
+        }
+    }
+    return { findings };
+}
+function extractMarkdownLinks(source) {
+    // Match ](url) part of an inline link. Allow spaces inside text. Skip
+    // images (preceded by `!`) and reference-style links.
+    const out = [];
+    // Build line-index map.
+    const re = /(!?)\[([^\]\n]+)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+        const isImage = m[1] === "!";
+        const text = m[2] ?? "";
+        const url = m[3] ?? "";
+        if (isImage)
+            continue;
+        out.push({ text, url, line: lineOf(source, m.index) });
+    }
+    return out;
+}
+function isExternalUrl(url) {
+    return /^[a-z]+:\/\//i.test(url) || url.startsWith("mailto:");
+}
+function resolveLinkTarget(repoRoot, fromRel, url) {
+    // Strip fragment.
+    const hashIdx = url.indexOf("#");
+    const cleanUrl = hashIdx === -1 ? url : url.slice(0, hashIdx);
+    if (cleanUrl.length === 0)
+        return null;
+    // Absolute paths inside the repo (rare, but tolerated).
+    if (cleanUrl.startsWith("/")) {
+        return cleanUrl.replace(/^\/+/, "");
+    }
+    const fromDir = dirname(fromRel);
+    const joined = posix.normalize(posix.join(fromDir, cleanUrl));
+    if (joined.startsWith(".."))
+        return null; // escapes repo root
+    return joined;
+}
+function fileExists(repoRoot, rel) {
+    const abs = resolve(repoRoot, rel);
+    if (!existsSync(abs))
+        return false;
+    try {
+        return statSync(abs).isFile() || statSync(abs).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function lineOf(text, charIndex) {
+    let line = 1;
+    for (let i = 0; i < charIndex && i < text.length; i++) {
+        if (text.charCodeAt(i) === 10 /* \n */)
+            line += 1;
+    }
+    return line;
+}
+//# sourceMappingURL=doc-gardening.js.map

package/dist/gc/doc-gardening.js.map

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

package/dist/gc/frontmatter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * GC pass 1 — frontmatter freshness.
+ *
+ * Walks the canonical zone via `walkCanonical`, parses each markdown's
+ * provenance frontmatter, and surfaces docs whose `verified-at` exceeds the
+ * configured warn (30d) / block (60d) thresholds.
+ *
+ * Phase 12 v1 surfaces only — it does NOT auto-bump verified-at, because a
+ * timestamp bump without re-verification is a lie. Future revisions may add
+ * an opt-in "refresh-and-bump" proposal for safe-class docs whose content
+ * sha hasn't changed since the last verified-at, but that's out of v1 scope.
+ *
+ * Exception: when `forceRefresh: true` is passed (smoke / dev only), the pass
+ * proposes a frontmatter-only verified-at bump as a safe-class commit. The
+ * smoke uses this path to exercise the auto-merge end-to-end.
+ */
+import type { GcCommitProposal, GcFinding } from "./types.js";
+export interface FrontmatterFreshnessOptions {
+    repoRoot: string;
+    warnDays?: number;
+    blockDays?: number;
+    /** Default = new Date(); injected for tests. */
+    now?: Date;
+    /**
+     * When true, produce a frontmatter-only safe-class commit proposal that
+     * bumps verified-at to `now` for every stale doc. Off by default — see
+     * module header. Smoke uses this.
+     */
+    forceRefresh?: boolean;
+}
+export interface FrontmatterFreshnessResult {
+    findings: GcFinding[];
+    proposals: GcCommitProposal[];
+}
+export declare function runFrontmatterFreshness(opts: FrontmatterFreshnessOptions): FrontmatterFreshnessResult;

package/dist/gc/frontmatter.js

@@ -0,0 +1,105 @@
+/**
+ * GC pass 1 — frontmatter freshness.
+ *
+ * Walks the canonical zone via `walkCanonical`, parses each markdown's
+ * provenance frontmatter, and surfaces docs whose `verified-at` exceeds the
+ * configured warn (30d) / block (60d) thresholds.
+ *
+ * Phase 12 v1 surfaces only — it does NOT auto-bump verified-at, because a
+ * timestamp bump without re-verification is a lie. Future revisions may add
+ * an opt-in "refresh-and-bump" proposal for safe-class docs whose content
+ * sha hasn't changed since the last verified-at, but that's out of v1 scope.
+ *
+ * Exception: when `forceRefresh: true` is passed (smoke / dev only), the pass
+ * proposes a frontmatter-only verified-at bump as a safe-class commit. The
+ * smoke uses this path to exercise the auto-merge end-to-end.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { evaluateFreshness, parseFrontmatter } from "../ground/frontmatter.js";
+import { walkCanonical } from "../ground/walk.js";
+const PASS_ID = "frontmatter-freshness";
+export function runFrontmatterFreshness(opts) {
+    const warnDays = opts.warnDays ?? 30;
+    const blockDays = opts.blockDays ?? 60;
+    const now = opts.now ?? new Date();
+    const findings = [];
+    const refreshes = [];
+    const files = walkCanonical(opts.repoRoot);
+    for (const rel of files) {
+        if (!rel.endsWith(".md"))
+            continue;
+        const abs = resolve(opts.repoRoot, rel);
+        const source = readFileSync(abs, "utf8");
+        const parsed = parseFrontmatter(source);
+        if (!parsed.frontmatter)
+            continue;
+        const verdict = evaluateFreshness(parsed.frontmatter, warnDays, blockDays, now);
+        if (verdict.status === "fresh" || verdict.status === "unknown")
+            continue;
+        findings.push({
+            pass: PASS_ID,
+            kind: "frontmatter_stale",
+            path: rel,
+            detail: verdict.status === "block"
+                ? `verified-at is ${verdict.ageDays}d old (>=${blockDays}d block threshold) — re-verify before relying`
+                : `verified-at is ${verdict.ageDays}d old (>=${warnDays}d warn threshold)`,
+            severity: verdict.status === "block" ? "block" : "warn",
+            ...(verdict.ageDays !== null ? { age_days: verdict.ageDays } : {}),
+        });
+        if (opts.forceRefresh) {
+            const refreshed = bumpVerifiedAt(source, now);
+            refreshes.push({ path: rel, content: refreshed });
+        }
+    }
+    const proposals = [];
+    if (refreshes.length > 0) {
+        const patch = {};
+        for (const r of refreshes)
+            patch[r.path] = r.content;
+        const paths = refreshes.map((r) => r.path).sort();
+        proposals.push({
+            pass: PASS_ID,
+            class: "safe",
+            paths,
+            patch,
+            commit_message: composeCommitMessage(paths.length, now),
+            findings: findings.filter((f) => paths.includes(f.path)),
+        });
+    }
+    return { findings, proposals };
+}
+/**
+ * Rewrite the frontmatter block with verified-at bumped to `now`. Preserves
+ * key order by replacing only the `verified-at:` line (or inserting it
+ * directly after `generated:` when missing).
+ */
+function bumpVerifiedAt(source, now) {
+    const iso = now.toISOString();
+    // Frontmatter is fenced by `---` lines at the top of the file; replace the
+    // first `verified-at:` line in the fence region. If none, insert it after
+    // `generated:` if present, else at the end of the fence block.
+    const fenceEndIdx = source.indexOf("\n---", 3);
+    if (fenceEndIdx === -1)
+        return source;
+    const fenceText = source.slice(0, fenceEndIdx);
+    const restText = source.slice(fenceEndIdx);
+    const verifiedAtRe = /^verified-at:.*$/m;
+    if (verifiedAtRe.test(fenceText)) {
+        return fenceText.replace(verifiedAtRe, `verified-at: ${iso}`) + restText;
+    }
+    // Insert after generated: line if present.
+    const generatedRe = /^(generated:.*)$/m;
+    if (generatedRe.test(fenceText)) {
+        return fenceText.replace(generatedRe, `$1\nverified-at: ${iso}`) + restText;
+    }
+    return fenceText + `\nverified-at: ${iso}` + restText;
+}
+function composeCommitMessage(count, now) {
+    const ymd = now.toISOString().slice(0, 10);
+    const subject = `chore(gc): refresh frontmatter verified-at on ${count} doc${count === 1 ? "" : "s"} (${ymd})`;
+    const body = "GC frontmatter-freshness pass — content unchanged; bumping verified-at to today.\n" +
+        "Auto-applied as safe-class per L16 (PRIMER §12.2).\n";
+    return `${subject}\n\n${body}`;
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/gc/frontmatter.js.map

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

package/dist/gc/generator-drift.d.ts

@@ -0,0 +1,28 @@
+/**
+ * GC pass 2 — generator drift.
+ *
+ * Iterates every `Profile.extractors` and re-runs them. For each extractor:
+ *   - run(ctx) → newContent | null
+ *   - read existing file at outputRelPath → currentContent
+ *   - if differ → emit a finding + a safe-class commit proposal that
+ *     overwrites outputRelPath with newContent.
+ *
+ * Per spec: "auto-regenerate; commit `chore(gc): regenerate <artifact>` if no
+ * source change required". A regenerated artifact whose deterministic output
+ * matches the spec but doesn't match disk is exactly drift — replace it.
+ *
+ * The unknown profile has zero extractors, so on a vanilla repo this pass is
+ * a no-op. Future profiles (typescript-next-nest, etc.) wire their extractors
+ * via `registerProfile()` and they show up here automatically.
+ */
+import type { Profile } from "../profiles/types.js";
+import type { GcCommitProposal, GcFinding } from "./types.js";
+export interface GeneratorDriftOptions {
+    repoRoot: string;
+    profile: Profile;
+}
+export interface GeneratorDriftResult {
+    findings: GcFinding[];
+    proposals: GcCommitProposal[];
+}
+export declare function runGeneratorDrift(opts: GeneratorDriftOptions): Promise<GeneratorDriftResult>;

package/dist/gc/generator-drift.js

@@ -0,0 +1,53 @@
+/**
+ * GC pass 2 — generator drift.
+ *
+ * Iterates every `Profile.extractors` and re-runs them. For each extractor:
+ *   - run(ctx) → newContent | null
+ *   - read existing file at outputRelPath → currentContent
+ *   - if differ → emit a finding + a safe-class commit proposal that
+ *     overwrites outputRelPath with newContent.
+ *
+ * Per spec: "auto-regenerate; commit `chore(gc): regenerate <artifact>` if no
+ * source change required". A regenerated artifact whose deterministic output
+ * matches the spec but doesn't match disk is exactly drift — replace it.
+ *
+ * The unknown profile has zero extractors, so on a vanilla repo this pass is
+ * a no-op. Future profiles (typescript-next-nest, etc.) wire their extractors
+ * via `registerProfile()` and they show up here automatically.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+const PASS_ID = "generator-drift";
+export async function runGeneratorDrift(opts) {
+    const findings = [];
+    const proposals = [];
+    for (const extractor of opts.profile.extractors) {
+        const newContent = await extractor.run({ repoRoot: opts.repoRoot });
+        if (newContent === null)
+            continue; // extractor opted to skip
+        const outAbs = resolve(opts.repoRoot, extractor.outputRelPath);
+        const currentContent = existsSync(outAbs) ? readFileSync(outAbs, "utf8") : "";
+        if (currentContent === newContent)
+            continue;
+        const finding = {
+            pass: PASS_ID,
+            kind: "generator_drift",
+            path: extractor.outputRelPath,
+            detail: `extractor \`${extractor.id}\` produces output that differs from on-disk content (${currentContent.length === 0 ? "missing" : "stale"}) — regenerating`,
+            severity: "warn",
+        };
+        findings.push(finding);
+        proposals.push({
+            pass: PASS_ID,
+            class: "safe",
+            paths: [extractor.outputRelPath],
+            patch: { [extractor.outputRelPath]: newContent },
+            commit_message: `chore(gc): regenerate ${extractor.outputRelPath}\n\n` +
+                `GC generator-drift pass — extractor \`${extractor.id}\` produces output that differs from on-disk.\n` +
+                `Auto-applied as safe-class per PRIMER §12.2.\n`,
+            findings: [finding],
+        });
+    }
+    return { findings, proposals };
+}
+//# sourceMappingURL=generator-drift.js.map

package/dist/gc/generator-drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator-drift.js","sourceRoot":"","sources":["../../src/gc/generator-drift.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,MAAM,OAAO,GAAG,iBAA0B,CAAC;AAY3C,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAA2B;IAE3B,MAAM,QAAQ,GAAgB,EAAE,CAAC;IACjC,MAAM,SAAS,GAAuB,EAAE,CAAC;IAEzC,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QAChD,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACpE,IAAI,UAAU,KAAK,IAAI;YAAE,SAAS,CAAC,0BAA0B;QAE7D,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;QAC/D,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAE9E,IAAI,cAAc,KAAK,UAAU;YAAE,SAAS;QAE5C,MAAM,OAAO,GAAc;YACzB,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,iBAAiB;YACvB,IAAI,EAAE,SAAS,CAAC,aAAa;YAC7B,MAAM,EAAE,eAAe,SAAS,CAAC,EAAE,yDACjC,cAAc,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAC5C,kBAAkB;YAClB,QAAQ,EAAE,MAAM;SACjB,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEvB,SAAS,CAAC,IAAI,CAAC;YACb,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,MAAM;YACb,KAAK,EAAE,CAAC,SAAS,CAAC,aAAa,CAAC;YAChC,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,aAAa,CAAC,EAAE,UAAU,EAAE;YAChD,cAAc,EACZ,yBAAyB,SAAS,CAAC,aAAa,MAAM;gBACtD,yCAAyC,SAAS,CAAC,EAAE,iDAAiD;gBACtG,gDAAgD;YAClD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC"}

package/dist/gc/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Phase 12 — garbage collection cadence.
+ *
+ * Public surface:
+ *   - runGcSweep(opts)          → composes all five passes
+ *   - runGcBatch(opts)          → sweep + classify + apply + canary
+ *   - applyCommit(opts)         → apply a single proposal
+ *   - verifyBatchCanary(opts)   → standalone canary check
+ *   - classifyAutoMerge(args)   → safe | code | high-stakes
+ *   - runFrontmatterFreshness, runGeneratorDrift, runStubCatalogHits,
+ *     runDocGardening, runQualityGradesUpdate — direct pass entry points
+ *
+ * Used by the CLI (`cairn gc run`) and the smoke test
+ * (`cairn/scripts/smoke-gc.ts`). Future cron / `/loop` integration consumes
+ * the same surface.
+ */
+export type { GcAutoMergeClass, GcBatchResult, GcCommitProposal, GcFinding, GcFindingKind, GcPassId, GcSweepResult, CanarySyntheticContext, } from "./types.js";
+export { applyCommit } from "./apply.js";
+export type { ApplyCommitOptions, ApplyCommitResult } from "./apply.js";
+export { verifyBatchCanary, buildSyntheticContext, } from "./canary.js";
+export type { BatchCanaryResult, BatchCanaryOptions, } from "./canary.js";
+export { runCitationIntegrity } from "./citation-integrity.js";
+export type { CitationIntegrityOptions, CitationIntegrityResult, } from "./citation-integrity.js";
+export { classifyAutoMerge } from "./classify.js";
+export type { ClassifyArgs } from "./classify.js";
+export { runCompletionIntegrity } from "./completion-integrity.js";
+export type { CompletionIntegrityOptions, CompletionIntegrityResult, } from "./completion-integrity.js";
+export { runDocGardening } from "./doc-gardening.js";
+export type { DocGardeningOptions, DocGardeningResult, } from "./doc-gardening.js";
+export { runFrontmatterFreshness, } from "./frontmatter.js";
+export type { FrontmatterFreshnessOptions, FrontmatterFreshnessResult, } from "./frontmatter.js";
+export { runGeneratorDrift } from "./generator-drift.js";
+export type { GeneratorDriftOptions, GeneratorDriftResult, } from "./generator-drift.js";
+export { runQualityGradesUpdate } from "./quality-update.js";
+export type { QualityUpdateOptions, QualityUpdateResult, } from "./quality-update.js";
+export { runScopeCoverage } from "./scope-coverage.js";
+export type { ScopeCoverageOptions, ScopeCoverageResult, } from "./scope-coverage.js";
+export { runStubCatalogHits } from "./stub-hits.js";
+export type { StubCatalogHitsOptions, StubCatalogHitsResult, } from "./stub-hits.js";
+export { runGcBatch, runGcSweep } from "./sweep.js";
+export type { RunGcBatchOptions, RunGcSweepOptions, } from "./sweep.js";
+export { walkSourceTree, SOURCE_TREE_SKIP_DIRS } from "./walk-source.js";

package/dist/gc/index.js

@@ -0,0 +1,30 @@
+/**
+ * Phase 12 — garbage collection cadence.
+ *
+ * Public surface:
+ *   - runGcSweep(opts)          → composes all five passes
+ *   - runGcBatch(opts)          → sweep + classify + apply + canary
+ *   - applyCommit(opts)         → apply a single proposal
+ *   - verifyBatchCanary(opts)   → standalone canary check
+ *   - classifyAutoMerge(args)   → safe | code | high-stakes
+ *   - runFrontmatterFreshness, runGeneratorDrift, runStubCatalogHits,
+ *     runDocGardening, runQualityGradesUpdate — direct pass entry points
+ *
+ * Used by the CLI (`cairn gc run`) and the smoke test
+ * (`cairn/scripts/smoke-gc.ts`). Future cron / `/loop` integration consumes
+ * the same surface.
+ */
+export { applyCommit } from "./apply.js";
+export { verifyBatchCanary, buildSyntheticContext, } from "./canary.js";
+export { runCitationIntegrity } from "./citation-integrity.js";
+export { classifyAutoMerge } from "./classify.js";
+export { runCompletionIntegrity } from "./completion-integrity.js";
+export { runDocGardening } from "./doc-gardening.js";
+export { runFrontmatterFreshness, } from "./frontmatter.js";
+export { runGeneratorDrift } from "./generator-drift.js";
+export { runQualityGradesUpdate } from "./quality-update.js";
+export { runScopeCoverage } from "./scope-coverage.js";
+export { runStubCatalogHits } from "./stub-hits.js";
+export { runGcBatch, runGcSweep } from "./sweep.js";
+export { walkSourceTree, SOURCE_TREE_SKIP_DIRS } from "./walk-source.js";
+//# sourceMappingURL=index.js.map

package/dist/gc/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gc/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EACL,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAK/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAKnE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAKrD,OAAO,EACL,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAKzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAK7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAKvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAKpD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAKpD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/gc/quality-update.d.ts

@@ -0,0 +1,23 @@
+/**
+ * GC pass 5 — quality grades update.
+ *
+ * Rebuilds `.cairn/ground/quality-grades.yaml` from terminal-run history at
+ * `.cairn/runs/terminal/*`. The grounding daemon also writes this file on
+ * watch events, so GC's job is to ensure a fresh write lands on the GC cron
+ * and that any drift between the file's content and the latest reality is
+ * captured as a safe-class commit.
+ *
+ * Implementation: build the grades structure in-memory, compare against the
+ * file currently on disk (modules array as JSON, ignoring `generated:`
+ * timestamp churn), and emit a commit proposal only when content differs.
+ */
+import type { GcCommitProposal, GcFinding } from "./types.js";
+export interface QualityUpdateOptions {
+    repoRoot: string;
+    recentRunCount?: number;
+}
+export interface QualityUpdateResult {
+    findings: GcFinding[];
+    proposals: GcCommitProposal[];
+}
+export declare function runQualityGradesUpdate(opts: QualityUpdateOptions): QualityUpdateResult;

package/dist/gc/quality-update.js

@@ -0,0 +1,69 @@
+/**
+ * GC pass 5 — quality grades update.
+ *
+ * Rebuilds `.cairn/ground/quality-grades.yaml` from terminal-run history at
+ * `.cairn/runs/terminal/*`. The grounding daemon also writes this file on
+ * watch events, so GC's job is to ensure a fresh write lands on the GC cron
+ * and that any drift between the file's content and the latest reality is
+ * captured as a safe-class commit.
+ *
+ * Implementation: build the grades structure in-memory, compare against the
+ * file currently on disk (modules array as JSON, ignoring `generated:`
+ * timestamp churn), and emit a commit proposal only when content differs.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { buildQualityGrades } from "../ground/quality-grades.js";
+import { qualityGradesPath } from "../ground/paths.js";
+const PASS_ID = "quality-grades";
+export function runQualityGradesUpdate(opts) {
+    const findings = [];
+    const proposals = [];
+    const grades = buildQualityGrades({
+        repoRoot: opts.repoRoot,
+        ...(opts.recentRunCount !== undefined ? { recentRunCount: opts.recentRunCount } : {}),
+    });
+    const newContent = stringifyYaml(grades);
+    const filePath = qualityGradesPath(opts.repoRoot);
+    const relPath = ".cairn/ground/quality-grades.yaml";
+    const existing = existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
+    const existingModules = existing.length > 0 ? safeParseModules(existing) : [];
+    const existingModulesJson = JSON.stringify(existingModules);
+    const newModulesJson = JSON.stringify(grades.modules);
+    if (existingModulesJson === newModulesJson) {
+        return { findings, proposals };
+    }
+    const finding = {
+        pass: PASS_ID,
+        kind: "quality_update",
+        path: relPath,
+        detail: `quality-grades.yaml modules changed (${grades.modules.length} module${grades.modules.length === 1 ? "" : "s"} graded)`,
+        severity: "info",
+    };
+    findings.push(finding);
+    proposals.push({
+        pass: PASS_ID,
+        class: "safe",
+        paths: [relPath],
+        patch: { [relPath]: newContent },
+        commit_message: `chore(gc): refresh quality-grades.yaml (${grades.modules.length} modules)\n\n` +
+            `GC quality-grades pass — recomputed from .cairn/runs/terminal/.\n` +
+            `Auto-applied as safe-class per PRIMER §12.2.\n`,
+        findings: [finding],
+    });
+    return { findings, proposals };
+}
+function safeParseModules(text) {
+    try {
+        const parsed = parseYaml(text);
+        if (typeof parsed === "object" && parsed !== null) {
+            const m = parsed.modules;
+            return Array.isArray(m) ? m : [];
+        }
+    }
+    catch {
+        // fall through
+    }
+    return [];
+}
+//# sourceMappingURL=quality-update.js.map

package/dist/gc/quality-update.js.map

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

package/dist/gc/scope-coverage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * GC pass — scope-coverage.
+ *
+ * Surfaces drift between the source tree and `.cairn/ground/scope-index.yaml`:
+ *   1. Source files with no scope-index entry → `scope_uncovered`.
+ *   2. Index entries pointing at paths that no longer exist → `scope_drift_orphan`.
+ *
+ * If the scope-index file itself is missing, emits a single
+ * `scope_index_missing` finding telling the operator to rebuild it.
+ *
+ * Spec: docs/DOCS_SPEC.md §3.8.
+ */
+import type { GcFinding } from "./types.js";
+export interface ScopeCoverageOptions {
+    repoRoot: string;
+}
+export interface ScopeCoverageResult {
+    findings: GcFinding[];
+}
+export declare function runScopeCoverage(opts: ScopeCoverageOptions): ScopeCoverageResult;