@isaacriehm/cairn-core 0.1.0

package/dist/gc/scope-coverage.js

@@ -0,0 +1,70 @@
+/**
+ * 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 { existsSync } from "node:fs";
+import { join } from "node:path";
+import { lookupScope, readScopeIndex } from "../ground/scope-index.js";
+import { walkSourceTree } from "./walk-source.js";
+const PASS_ID = "scope-coverage";
+const MAX_FINDINGS_PER_KIND = 50;
+export function runScopeCoverage(opts) {
+    const findings = [];
+    const index = readScopeIndex(opts.repoRoot);
+    if (index === null) {
+        findings.push({
+            pass: PASS_ID,
+            kind: "scope_index_missing",
+            path: ".cairn/ground/scope-index.yaml",
+            detail: "scope-index.yaml not found — run `cairn scope rebuild` to populate",
+            severity: "warn",
+        });
+        return { findings };
+    }
+    // 1. Files in the source tree without an entry.
+    const sourceFiles = walkSourceTree(opts.repoRoot);
+    let uncoveredCount = 0;
+    for (const rel of sourceFiles) {
+        if (uncoveredCount >= MAX_FINDINGS_PER_KIND)
+            break;
+        const entry = lookupScope(index, rel);
+        if (entry === null) {
+            findings.push({
+                pass: PASS_ID,
+                kind: "scope_uncovered",
+                path: rel,
+                detail: `${rel} has no scope-index entry — uncovered by decisions/invariants mapping`,
+                severity: "warn",
+            });
+            uncoveredCount++;
+        }
+        // entry.unscoped === true is fine — the operator explicitly marked it.
+    }
+    // 2. Index entries pointing at missing files.
+    let orphanCount = 0;
+    for (const path of Object.keys(index.files)) {
+        if (orphanCount >= MAX_FINDINGS_PER_KIND)
+            break;
+        const abs = join(opts.repoRoot, path);
+        if (!existsSync(abs)) {
+            findings.push({
+                pass: PASS_ID,
+                kind: "scope_drift_orphan",
+                path,
+                detail: `${path} appears in scope-index but does not exist in the working tree`,
+                severity: "warn",
+            });
+            orphanCount++;
+        }
+    }
+    return { findings };
+}
+//# sourceMappingURL=scope-coverage.js.map

package/dist/gc/scope-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-coverage.js","sourceRoot":"","sources":["../../src/gc/scope-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,OAAO,GAAG,gBAAyB,CAAC;AAC1C,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAUjC,MAAM,UAAU,gBAAgB,CAC9B,IAA0B;IAE1B,MAAM,QAAQ,GAAgB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,qBAAqB;YAC3B,IAAI,EAAE,gCAAgC;YACtC,MAAM,EACJ,oEAAoE;YACtE,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAC;QACH,OAAO,EAAE,QAAQ,EAAE,CAAC;IACtB,CAAC;IAED,gDAAgD;IAChD,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,cAAc,GAAG,CAAC,CAAC;IACvB,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,IAAI,cAAc,IAAI,qBAAqB;YAAE,MAAM;QACnD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACtC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,iBAAiB;gBACvB,IAAI,EAAE,GAAG;gBACT,MAAM,EAAE,GAAG,GAAG,uEAAuE;gBACrF,QAAQ,EAAE,MAAM;aACjB,CAAC,CAAC;YACH,cAAc,EAAE,CAAC;QACnB,CAAC;QACD,uEAAuE;IACzE,CAAC;IAED,8CAA8C;IAC9C,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,IAAI,WAAW,IAAI,qBAAqB;YAAE,MAAM;QAChD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,oBAAoB;gBAC1B,IAAI;gBACJ,MAAM,EAAE,GAAG,IAAI,gEAAgE;gBAC/E,QAAQ,EAAE,MAAM;aACjB,CAAC,CAAC;YACH,WAAW,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtB,CAAC"}

package/dist/gc/stub-hits.d.ts

@@ -0,0 +1,31 @@
+/**
+ * GC pass 3 — stub-catalog hits (full-tree scan).
+ *
+ * Layer A in `cairn/src/sensors/stub-catalog.ts` only flags genuinely-NEW
+ * stubs (added lines per diff). That keeps per-task feedback tight and avoids
+ * paying for pre-existing debt over and over.
+ *
+ * GC closes the loop on accumulated debt: walks the canonical zone and runs
+ * the same regex catalog against every file's CURRENT content. Hits become
+ * findings the operator can triage. Phase 12 v1 surfaces only — opening a
+ * targeted refactor commit (per spec) requires generating a diff that actually
+ * fixes the stub, which needs an agent. That belongs in Phase 14+.
+ */
+import type { SensorLanguage, StubCatalog } from "../sensors/types.js";
+import type { GcFinding } from "./types.js";
+export interface StubCatalogHitsOptions {
+    repoRoot: string;
+    /** Languages active for this profile. Filters which patterns run. */
+    languages?: readonly SensorLanguage[];
+    /** Pre-loaded catalog (smoke convenience). Otherwise loaded from project. */
+    catalog?: StubCatalog;
+    /**
+     * Cap on file size to scan (bytes). Files larger than this are skipped to
+     * keep the pass cheap on big artifacts. Default 256 KB.
+     */
+    maxFileBytes?: number;
+}
+export interface StubCatalogHitsResult {
+    findings: GcFinding[];
+}
+export declare function runStubCatalogHits(opts: StubCatalogHitsOptions): StubCatalogHitsResult;

package/dist/gc/stub-hits.js

@@ -0,0 +1,78 @@
+/**
+ * GC pass 3 — stub-catalog hits (full-tree scan).
+ *
+ * Layer A in `cairn/src/sensors/stub-catalog.ts` only flags genuinely-NEW
+ * stubs (added lines per diff). That keeps per-task feedback tight and avoids
+ * paying for pre-existing debt over and over.
+ *
+ * GC closes the loop on accumulated debt: walks the canonical zone and runs
+ * the same regex catalog against every file's CURRENT content. Hits become
+ * findings the operator can triage. Phase 12 v1 surfaces only — opening a
+ * targeted refactor commit (per spec) requires generating a diff that actually
+ * fixes the stub, which needs an agent. That belongs in Phase 14+.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadStubCatalog } from "../sensors/catalog.js";
+import { detectLanguage } from "../sensors/stub-catalog.js";
+import { walkSourceTree } from "./walk-source.js";
+const PASS_ID = "stub-catalog-hits";
+export function runStubCatalogHits(opts) {
+    const findings = [];
+    const catalog = opts.catalog ?? loadStubCatalog(opts.repoRoot);
+    const allowedLangs = opts.languages;
+    const maxBytes = opts.maxFileBytes ?? 256 * 1024;
+    const files = walkSourceTree(opts.repoRoot);
+    for (const rel of files) {
+        const lang = detectLanguage(rel);
+        if (lang === undefined)
+            continue;
+        if (allowedLangs !== undefined && !allowedLangs.includes(lang))
+            continue;
+        const abs = resolve(opts.repoRoot, rel);
+        let content;
+        try {
+            const buf = readFileSync(abs);
+            if (buf.length > maxBytes)
+                continue;
+            content = buf.toString("utf8");
+        }
+        catch {
+            continue;
+        }
+        if (content.length === 0)
+            continue;
+        for (const pattern of catalog.patterns) {
+            if (!pattern.languages.includes(lang))
+                continue;
+            const re = new RegExp(pattern.regex, "gm");
+            let m;
+            while ((m = re.exec(content)) !== null) {
+                const lineIdx = lineOf(content, m.index);
+                const matched = m[0];
+                findings.push({
+                    pass: PASS_ID,
+                    kind: "stub_hit",
+                    path: rel,
+                    detail: `${rel}:${lineIdx} matches stub pattern \`${pattern.id}\` — ${pattern.description}`,
+                    severity: pattern.severity === "hard" ? "block" : "warn",
+                    pattern_id: pattern.id,
+                    line: lineIdx,
+                    matched_text: matched.length > 200 ? matched.slice(0, 200) + "…" : matched,
+                });
+                if (re.lastIndex === m.index)
+                    re.lastIndex += 1;
+            }
+        }
+    }
+    return { findings };
+}
+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=stub-hits.js.map

package/dist/gc/stub-hits.js.map

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

package/dist/gc/sweep.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Sweep + batch entry points for GC.
+ *
+ * `runGcSweep` composes all five passes against a repo root and returns the
+ * aggregated `GcSweepResult` (findings + commit proposals). Callers decide
+ * whether to apply.
+ *
+ * `runGcBatch` is the apply-side counterpart. Given a sweep result, it
+ * (1) optionally re-classifies each proposal against project globs; (2)
+ * applies proposals whose class is in `applyClasses`; (3) when more than one
+ * proposal lands in the same batch AND `canary` is true, runs
+ * `verifyBatchCanary` against the post-batch state; (4) on canary fail,
+ * rolls back to the pre-batch SHA and returns the batch as `rolled_back`.
+ */
+import type { Profile } from "../profiles/types.js";
+import type { ProjectGlobs, SensorLanguage } from "../sensors/types.js";
+import type { GcAutoMergeClass, GcSweepResult, GcBatchResult } from "./types.js";
+export interface RunGcSweepOptions {
+    repoRoot: string;
+    /** Override stack profile. Defaults to `selectProfile(repoRoot)`. */
+    profile?: Profile;
+    /** Project-extension globs (high_stakes_globs etc). */
+    projectGlobs?: ProjectGlobs;
+    /** Languages active for stub-catalog scan. Default ["typescript"]. */
+    languages?: readonly SensorLanguage[];
+    /** Frontmatter-pass options. */
+    frontmatter?: {
+        warnDays?: number;
+        blockDays?: number;
+        /** Inject for tests. */
+        now?: Date;
+        /**
+         * Phase 12 v1 surfaces stale frontmatter only. Setting this to true also
+         * proposes a verified-at bump as a safe-class commit; the smoke uses
+         * this to exercise the auto-merge end-to-end.
+         */
+        forceRefresh?: boolean;
+    };
+    /** Quality-grades pass options. */
+    qualityRecentRunCount?: number;
+    /** Doc-gardening orphan exception list. */
+    docOrphanExcludes?: readonly string[];
+}
+export declare function runGcSweep(opts: RunGcSweepOptions): Promise<GcSweepResult>;
+export interface RunGcBatchOptions extends RunGcSweepOptions {
+    /** Auto-merge classes that are allowed to apply. Default ["safe"]. */
+    applyClasses?: readonly GcAutoMergeClass[];
+    /** Re-run the canary after the batch lands. Default true. */
+    canary?: boolean;
+    /** Override the commit author. */
+    author?: {
+        name: string;
+        email: string;
+    };
+}
+export declare function runGcBatch(opts: RunGcBatchOptions): Promise<GcBatchResult>;

package/dist/gc/sweep.js

@@ -0,0 +1,205 @@
+/**
+ * Sweep + batch entry points for GC.
+ *
+ * `runGcSweep` composes all five passes against a repo root and returns the
+ * aggregated `GcSweepResult` (findings + commit proposals). Callers decide
+ * whether to apply.
+ *
+ * `runGcBatch` is the apply-side counterpart. Given a sweep result, it
+ * (1) optionally re-classifies each proposal against project globs; (2)
+ * applies proposals whose class is in `applyClasses`; (3) when more than one
+ * proposal lands in the same batch AND `canary` is true, runs
+ * `verifyBatchCanary` against the post-batch state; (4) on canary fail,
+ * rolls back to the pre-batch SHA and returns the batch as `rolled_back`.
+ */
+import { simpleGit } from "simple-git";
+import { logger } from "../logger.js";
+import { selectProfile } from "../profiles/index.js";
+import { applyCommit } from "./apply.js";
+import { verifyBatchCanary } from "./canary.js";
+import { runCitationIntegrity } from "./citation-integrity.js";
+import { classifyAutoMerge } from "./classify.js";
+import { runCompletionIntegrity } from "./completion-integrity.js";
+import { runDocGardening } from "./doc-gardening.js";
+import { runFrontmatterFreshness } from "./frontmatter.js";
+import { runGeneratorDrift } from "./generator-drift.js";
+import { runQualityGradesUpdate } from "./quality-update.js";
+import { runScopeCoverage } from "./scope-coverage.js";
+import { runStubCatalogHits } from "./stub-hits.js";
+const log = logger("gc.sweep");
+export async function runGcSweep(opts) {
+    const startedAt = Date.now();
+    const profile = opts.profile ?? selectProfile(opts.repoRoot);
+    const findings = [];
+    const proposals = [];
+    const passDurations = {
+        "frontmatter-freshness": 0,
+        "generator-drift": 0,
+        "stub-catalog-hits": 0,
+        "doc-gardening": 0,
+        "quality-grades": 0,
+        "scope-coverage": 0,
+        "completion-integrity": 0,
+        "citation-integrity": 0,
+    };
+    // 1. Frontmatter freshness.
+    {
+        const t0 = Date.now();
+        const r = runFrontmatterFreshness({
+            repoRoot: opts.repoRoot,
+            ...(opts.frontmatter?.warnDays !== undefined ? { warnDays: opts.frontmatter.warnDays } : {}),
+            ...(opts.frontmatter?.blockDays !== undefined ? { blockDays: opts.frontmatter.blockDays } : {}),
+            ...(opts.frontmatter?.now !== undefined ? { now: opts.frontmatter.now } : {}),
+            ...(opts.frontmatter?.forceRefresh !== undefined ? { forceRefresh: opts.frontmatter.forceRefresh } : {}),
+        });
+        findings.push(...r.findings);
+        proposals.push(...r.proposals);
+        passDurations["frontmatter-freshness"] = Date.now() - t0;
+    }
+    // 2. Generator drift.
+    {
+        const t0 = Date.now();
+        const r = await runGeneratorDrift({ repoRoot: opts.repoRoot, profile });
+        findings.push(...r.findings);
+        proposals.push(...r.proposals);
+        passDurations["generator-drift"] = Date.now() - t0;
+    }
+    // 3. Stub catalog hits.
+    {
+        const t0 = Date.now();
+        const r = runStubCatalogHits({
+            repoRoot: opts.repoRoot,
+            ...(opts.languages !== undefined ? { languages: opts.languages } : {}),
+        });
+        findings.push(...r.findings);
+        passDurations["stub-catalog-hits"] = Date.now() - t0;
+    }
+    // 4. Doc gardening.
+    {
+        const t0 = Date.now();
+        const r = runDocGardening({
+            repoRoot: opts.repoRoot,
+            ...(opts.docOrphanExcludes !== undefined ? { orphanExcludes: opts.docOrphanExcludes } : {}),
+        });
+        findings.push(...r.findings);
+        passDurations["doc-gardening"] = Date.now() - t0;
+    }
+    // 5. Quality grades.
+    {
+        const t0 = Date.now();
+        const r = runQualityGradesUpdate({
+            repoRoot: opts.repoRoot,
+            ...(opts.qualityRecentRunCount !== undefined ? { recentRunCount: opts.qualityRecentRunCount } : {}),
+        });
+        findings.push(...r.findings);
+        proposals.push(...r.proposals);
+        passDurations["quality-grades"] = Date.now() - t0;
+    }
+    // 6. Completion integrity.
+    {
+        const t0 = Date.now();
+        const r = await runCompletionIntegrity({ repoRoot: opts.repoRoot });
+        findings.push(...r.findings);
+        passDurations["completion-integrity"] = Date.now() - t0;
+    }
+    // 7. Scope coverage.
+    {
+        const t0 = Date.now();
+        const r = runScopeCoverage({ repoRoot: opts.repoRoot });
+        findings.push(...r.findings);
+        passDurations["scope-coverage"] = Date.now() - t0;
+    }
+    // 8. Citation integrity.
+    {
+        const t0 = Date.now();
+        const r = runCitationIntegrity({ repoRoot: opts.repoRoot });
+        findings.push(...r.findings);
+        passDurations["citation-integrity"] = Date.now() - t0;
+    }
+    // Re-classify proposals against project globs (passes set defaults; this
+    // ensures high-stakes hits dominate when a stale-frontmatter doc happens to
+    // live under a high-stakes glob).
+    for (const p of proposals) {
+        p.class = classifyAutoMerge({
+            paths: p.paths,
+            ...(opts.projectGlobs !== undefined ? { projectGlobs: opts.projectGlobs } : {}),
+        });
+    }
+    const result = {
+        generated: new Date().toISOString(),
+        findings,
+        proposals,
+        pass_durations: passDurations,
+        duration_ms: Date.now() - startedAt,
+    };
+    log.info({
+        repo: opts.repoRoot,
+        profile: profile.id,
+        findings: findings.length,
+        proposals: proposals.length,
+        duration_ms: result.duration_ms,
+    }, "gc sweep complete");
+    return result;
+}
+export async function runGcBatch(opts) {
+    const applyClasses = opts.applyClasses ?? ["safe"];
+    const canaryEnabled = opts.canary ?? true;
+    const sweep = await runGcSweep(opts);
+    const git = simpleGit({ baseDir: opts.repoRoot });
+    const preBatchSha = (await git.revparse(["HEAD"])).trim();
+    const toApply = [];
+    const surfaced = [];
+    for (const p of sweep.proposals) {
+        if (applyClasses.includes(p.class)) {
+            toApply.push(p);
+        }
+        else {
+            surfaced.push(p);
+        }
+    }
+    const applied = [];
+    for (const p of toApply) {
+        const r = await applyCommit({
+            repoRoot: opts.repoRoot,
+            proposal: p,
+            ...(opts.author !== undefined ? { author: opts.author } : {}),
+        });
+        applied.push({
+            pass: p.pass,
+            class: p.class,
+            commit_sha: r.commit_sha,
+            commit_message: p.commit_message,
+            paths: p.paths,
+        });
+    }
+    let canaryResult;
+    let rolledBack = false;
+    if (canaryEnabled && applied.length >= 2) {
+        canaryResult = verifyBatchCanary({ repoRoot: opts.repoRoot });
+        if (!canaryResult.ok) {
+            // Roll back to pre-batch SHA — undoes every commit applied in this
+            // batch atomically.
+            await git.reset(["--hard", preBatchSha]);
+            rolledBack = true;
+            log.warn({
+                repo: opts.repoRoot,
+                pre_batch_sha: preBatchSha,
+                applied_count: applied.length,
+                failures: canaryResult.failures,
+            }, "gc batch rolled back — canary failed");
+        }
+    }
+    const postBatchSha = rolledBack
+        ? preBatchSha
+        : (await git.revparse(["HEAD"])).trim();
+    return {
+        applied: rolledBack ? [] : applied,
+        surfaced: rolledBack ? [...surfaced, ...toApply] : surfaced,
+        pre_batch_sha: preBatchSha,
+        post_batch_sha: postBatchSha,
+        canary_ok: canaryResult ? canaryResult.ok : true,
+        canary_failures: canaryResult?.failures ?? [],
+        rolled_back: rolledBack,
+    };
+}
+//# sourceMappingURL=sweep.js.map

package/dist/gc/sweep.js.map

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

package/dist/gc/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Phase 12 — garbage collection cadence.
+ *
+ * GC runs five passes (per PRIMER §12.1) against the canonical zone of an
+ * adopted project's mirror checkout:
+ *
+ *   1. frontmatter-freshness — verified-at >30d warn, >60d block
+ *   2. generator-drift       — re-run profile.extractors, diff against ground
+ *   3. stub-catalog-hits     — full-tree scan against stub-patterns.yaml
+ *   4. doc-gardening         — broken markdown links, orphan paths
+ *   5. quality-grades        — rebuild .cairn/ground/quality-grades.yaml
+ *
+ * Each pass returns `GcFinding[]` and may attach a `GcCommitProposal` when the
+ * fix is mechanical (frontmatter refresh, generator regen, quality-grades
+ * rebuild). The sweep composer produces a `GcSweepResult` that the CLI / cron
+ * decides how to apply.
+ *
+ * Auto-merge classes per PRIMER §12.2:
+ *   safe        — formatting, doc regen, frontmatter refresh, generated content,
+ *                 archive moves, stub-catalog additions. Push, no UAT.
+ *   code        — touches *.ts outside generator-managed files. Sensors +
+ *                 reviewer + UAT 🟢 → push.
+ *   high-stakes — touches projectGlobs.high_stakes_globs. Above + E2E + Layer E.
+ */
+export type GcPassId = "frontmatter-freshness" | "generator-drift" | "stub-catalog-hits" | "doc-gardening" | "quality-grades" | "scope-coverage" | "completion-integrity" | "citation-integrity";
+export type GcFindingKind = "frontmatter_stale" | "generator_drift" | "stub_hit" | "broken_link" | "orphan_path" | "quality_update" | "scope_uncovered" | "scope_drift_orphan" | "scope_index_missing" | "task_integrity_error" | "orphaned_citation" | "superseded_citation" | "banned_dec_comment";
+export type GcAutoMergeClass = "safe" | "code" | "high-stakes";
+export interface GcFinding {
+    pass: GcPassId;
+    kind: GcFindingKind;
+    /** Repo-relative path the finding applies to. */
+    path: string;
+    /** Human-readable, one-line summary. */
+    detail: string;
+    /** warn = surface; block = sensor-equivalent failure. info = neutral. */
+    severity: "warn" | "block" | "info";
+    /** Days since verified-at (frontmatter pass only). */
+    age_days?: number;
+    /** Stub-pattern id when kind = "stub_hit". */
+    pattern_id?: string;
+    /** Line number when relevant (1-based). */
+    line?: number;
+    /** Verbatim text that triggered the finding. */
+    matched_text?: string;
+}
+/**
+ * A mechanical patch the pass can produce. The CLI / cron applies it as a
+ * single `chore(gc): ...` commit when the proposal's class is enabled.
+ * Patches are absolute file rewrites — keys are repo-relative paths, values
+ * are the full new content. Empty-string content means "delete this file".
+ */
+export interface GcCommitProposal {
+    pass: GcPassId;
+    class: GcAutoMergeClass;
+    /** Files this commit touches. */
+    paths: string[];
+    /** path → full new content. Empty value = delete. */
+    patch: Record<string, string>;
+    /** Conventional-commits-shaped subject + body. */
+    commit_message: string;
+    /** Findings this commit resolves (for audit log + Discord summary). */
+    findings: GcFinding[];
+}
+export interface GcSweepResult {
+    generated: string;
+    /** All findings across passes. Includes those covered by proposals. */
+    findings: GcFinding[];
+    /** Mechanical patches the passes produced. */
+    proposals: GcCommitProposal[];
+    /** Per-pass timing (ms). */
+    pass_durations: Record<GcPassId, number>;
+    duration_ms: number;
+}
+/**
+ * Outcome of `runGcBatch` — one or more proposals applied, optional canary
+ * verification, optional rollback on failure. The CLI uses this to print the
+ * summary and (when configured) push the resulting commits.
+ */
+export interface GcBatchResult {
+    /** Applied commits with their resulting SHA. */
+    applied: {
+        pass: GcPassId;
+        class: GcAutoMergeClass;
+        commit_sha: string;
+        commit_message: string;
+        paths: string[];
+    }[];
+    /** Proposals NOT applied (class not enabled, or canary failed). */
+    surfaced: GcCommitProposal[];
+    /** Pre-batch SHA — used for rollback. */
+    pre_batch_sha: string;
+    /** Post-batch SHA when canary passed; equal to pre_batch_sha when nothing applied or rolled back. */
+    post_batch_sha: string;
+    /** True when verifyBatchCanary passed (or wasn't run because <2 applied). */
+    canary_ok: boolean;
+    /** Canary failure details when canary_ok = false. */
+    canary_failures: string[];
+    /** True when batch was rolled back due to canary fail. */
+    rolled_back: boolean;
+}
+/**
+ * Synthetic context used by verifyBatchCanary to render workflow.md against
+ * a known-good fixture. The fixture mirrors the values the orchestrator would
+ * inject for a real run — if any of these tokens fail to resolve, the batch
+ * has broken the prompt template and must not be pushed.
+ */
+export interface CanarySyntheticContext {
+    agent_role: string;
+    project_name: string;
+    run_id: string;
+    mirror_path: string;
+    sha_pin: string;
+    tightened_spec_body: string;
+    acceptance_criteria: string[];
+    in_scope_decisions: {
+        id: string;
+        title: string;
+        scope_summary: string;
+    }[];
+    in_scope_invariants: {
+        id: string;
+        title: string;
+    }[];
+    off_limits: string[];
+    scoped_sensors: {
+        id: string;
+        description: string;
+    }[];
+}

package/dist/gc/types.js

@@ -0,0 +1,26 @@
+/**
+ * Phase 12 — garbage collection cadence.
+ *
+ * GC runs five passes (per PRIMER §12.1) against the canonical zone of an
+ * adopted project's mirror checkout:
+ *
+ *   1. frontmatter-freshness — verified-at >30d warn, >60d block
+ *   2. generator-drift       — re-run profile.extractors, diff against ground
+ *   3. stub-catalog-hits     — full-tree scan against stub-patterns.yaml
+ *   4. doc-gardening         — broken markdown links, orphan paths
+ *   5. quality-grades        — rebuild .cairn/ground/quality-grades.yaml
+ *
+ * Each pass returns `GcFinding[]` and may attach a `GcCommitProposal` when the
+ * fix is mechanical (frontmatter refresh, generator regen, quality-grades
+ * rebuild). The sweep composer produces a `GcSweepResult` that the CLI / cron
+ * decides how to apply.
+ *
+ * Auto-merge classes per PRIMER §12.2:
+ *   safe        — formatting, doc regen, frontmatter refresh, generated content,
+ *                 archive moves, stub-catalog additions. Push, no UAT.
+ *   code        — touches *.ts outside generator-managed files. Sensors +
+ *                 reviewer + UAT 🟢 → push.
+ *   high-stakes — touches projectGlobs.high_stakes_globs. Above + E2E + Layer E.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/gc/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/gc/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/dist/gc/walk-source.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared file-tree walker for GC passes that need a flat repo-relative listing.
+ *
+ * Mirrors the strategy of `walkCanonical` but without the canonical-zone glob
+ * filter — used by passes that scan the entire source tree (stub-catalog hits,
+ * scope-coverage, etc.).
+ */
+/** Directories the scan never descends into. */
+export declare const SOURCE_TREE_SKIP_DIRS: Set<string>;
+/**
+ * Walk every file in repoRoot, yielding repo-relative paths sorted
+ * alphabetically. Returns an empty array if `repoRoot` does not exist.
+ */
+export declare function walkSourceTree(repoRoot: string): string[];