loopgraph 0.1.0

package/dist/cli/commands/inspect.js

@@ -0,0 +1,35 @@
+import { join } from "node:path";
+import { loadModel } from "../../loader/load-model.js";
+import { writeSideChannel } from "../../query/side-channel.js";
+import { sliceModel } from "../../query/slice.js";
+import { renderSliceMarkdown, summarizeSlice } from "../../query/summary.js";
+const DEFAULT_DEPTH = 2;
+/**
+ * `loopgraph inspect <node-id>`: slice the model around one node and write a
+ * staleness-stamped side-channel file, returning a compact summary for stdout
+ * (proposal 001 §4.2 shape: summary + workspace file path). Throws on an
+ * unknown id or unparseable model — the CLI turns those into exit code 1.
+ */
+export async function runInspect(targetDir, nodeId, options = {}) {
+    const depth = options.depth ?? DEFAULT_DEPTH;
+    if (!Number.isInteger(depth) || depth < 0) {
+        throw new Error(`--depth must be a non-negative integer, got "${depth}"`);
+    }
+    const load = await loadModel(join(targetDir, "model"));
+    if (load.parseErrors.length > 0) {
+        throw new Error(`model has ${load.parseErrors.length} parse error(s) — run "loopgraph check" first`);
+    }
+    const slice = sliceModel(load.graph, nodeId, depth);
+    if (!slice) {
+        throw new Error(`unknown node id "${nodeId}" — not a feature/flow/loop/junction/scenario/debt`);
+    }
+    // node ids match the id-regex charset (L1 / C1 / J-x / GWT-x), all filename-safe.
+    const { outputPath, staleWarning } = await writeSideChannel(targetDir, `inspect-${nodeId}`, (banner) => renderSliceMarkdown(slice, banner));
+    return {
+        rootId: nodeId,
+        outputPath,
+        summary: summarizeSlice(slice, outputPath),
+        ...(staleWarning ? { staleWarning } : {}),
+    };
+}
+//# sourceMappingURL=inspect.js.map

package/dist/cli/commands/snapshot.d.ts

@@ -0,0 +1,121 @@
+import type { ImplementationFact, SignalKind } from "../../adapters/agenthub/extract.js";
+import { type Inv1CheckResult } from "../../validate/inv1/check.js";
+import type { T0Result } from "../../validate/types.js";
+export declare const SNAPSHOT_SCHEMA_VERSION: 1;
+/**
+ * A fact's stable identity for drift comparison. Deliberately DROPS the source
+ * `line` — the extractor documents line as "not a stable anchor", so a cosmetic
+ * line shift must NOT register as drift. `detail`/`unanalyzable` ARE compared:
+ * a queue that becomes env-suffixed, or a name that goes unanalyzable, is a real
+ * change worth surfacing.
+ */
+export interface FactDigest {
+    signal: SignalKind;
+    name: string;
+    filePath: string;
+    detail?: string;
+    unanalyzable?: boolean;
+}
+/**
+ * The T2 nightly artifact (Proposal 006 D2). A machine-readable full-scan
+ * snapshot: the facts inventory plus T0/INV-1 health, stamped with the adapter
+ * version and the scanned commit. Two uses: (1) a PR job reads it as a warm
+ * starting point instead of re-scanning from cold; (2) two snapshots diff into a
+ * drift report. 001 §6 red line: T2 NEVER gates a PR — this command is
+ * standalone and `check` never calls it.
+ */
+export interface Snapshot {
+    schemaVersion: typeof SNAPSHOT_SCHEMA_VERSION;
+    /** The adapter that produced the facts — a bump here explains fact churn that isn't real drift. */
+    adapterVersion: string;
+    /** HEAD of the scanned repo when known (git rev-parse), else undefined. */
+    commit?: string;
+    /** ISO timestamp; injected so the artifact is reproducible in tests. */
+    generatedAt: string;
+    t0: {
+        ok: boolean;
+        errors: number;
+        warnings: number;
+    };
+    inv1: {
+        ran: boolean;
+        skippedReason?: string;
+        violations: number;
+        unanalyzable: number;
+        writePoints: number;
+    };
+    /** Sorted fact inventory (identity fields only — see FactDigest). */
+    facts: FactDigest[];
+    factCount: number;
+    timingMs: number;
+}
+export interface SnapshotDrift {
+    /** true when the adapter version differs — fact changes below may be extractor churn, not real drift. */
+    adapterBumped: boolean;
+    addedFacts: FactDigest[];
+    removedFacts: FactDigest[];
+    /** same identity (signal+name+filePath), different detail/unanalyzable. */
+    changedFacts: {
+        before: FactDigest;
+        after: FactDigest;
+    }[];
+    t0Delta: {
+        errors: number;
+        warnings: number;
+    };
+    /**
+     * INV-1 deltas. `unanalyzable` matters as much as `violations`: a write point
+     * the canonical-writer scan can no longer analyze is a real loss of coverage,
+     * not a no-op — it must not report as "no drift".
+     */
+    inv1Delta: {
+        violations: number;
+        unanalyzable: number;
+    };
+    /**
+     * true when nothing in the TARGET changed (facts, T0, INV-1). An adapter
+     * version bump alone does NOT make it dirty (it's a tooling change, not target
+     * drift) — but `renderDrift` still surfaces the bump so it's never hidden.
+     */
+    clean: boolean;
+}
+/**
+ * Assemble a Snapshot from already-run scan results. PURE — all non-determinism
+ * (commit, timestamp, adapter version) is passed in, so it is fully unit-testable.
+ */
+export declare function buildSnapshot(meta: {
+    adapterVersion: string;
+    commit?: string | undefined;
+    generatedAt: string;
+    timingMs: number;
+}, t0: T0Result, facts: ImplementationFact[], inv1: Inv1CheckResult | undefined): Snapshot;
+/**
+ * Diff two snapshots into a drift report. PURE. Compares the fact inventory by
+ * stable identity (added/removed/value-changed) and the T0/INV-1 counts.
+ */
+export declare function diffSnapshots(prev: Snapshot, curr: Snapshot): SnapshotDrift;
+export interface SnapshotOptions {
+    repoRoot?: string | undefined;
+    /** Machine cache dir for facts (B3); null disables. Default: the shared cache. */
+    cacheDir?: string | null | undefined;
+    /** Injected for reproducibility; defaults to now. */
+    generatedAt?: string | undefined;
+    /** Injected for tests; defaults to `git rev-parse HEAD` of repoRoot. */
+    commit?: string | undefined;
+}
+/**
+ * Run a full T2 scan and build the snapshot (Proposal 006 D2): T0 over the
+ * model, facts over the repo (which also WARMS the machine cache — the whole
+ * point of the nightly run), and a full INV-1 pass. Returns the snapshot; the
+ * CLI persists it. Never called from the PR-gate `check` path (001 §6).
+ */
+export declare function runSnapshot(targetDir: string, options?: SnapshotOptions): Promise<Snapshot>;
+/** Load a previously-written snapshot (for drift comparison). undefined if absent/unreadable. */
+export declare function loadSnapshot(path: string): Promise<Snapshot | undefined>;
+/** One-line human summary of a snapshot's health. */
+export declare function renderSnapshotSummary(s: Snapshot): string;
+/** Human drift report between two snapshots (Proposal 006 D2). */
+export declare function renderDrift(drift: SnapshotDrift): string[];
+/** Persist a snapshot as pretty JSON, atomically (temp file + rename). */
+export declare function writeSnapshot(path: string, snapshot: Snapshot): Promise<void>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/cli/commands/view.d.ts

@@ -0,0 +1,34 @@
+import type { StalenessStamp } from "../../staleness.js";
+import type { MermaidValidationResult } from "../../views/validate-mermaid.js";
+export interface ViewOptions {
+    /**
+     * Actually render the generated mermaid with mmdc and report whether
+     * it parses (Decision record 004 技术点 5). Off by default: mmdc needs
+     * a real puppeteer-launched browser, which isn't a fair default
+     * runtime requirement for every consumer of `loopgraph view` — see
+     * src/views/validate-mermaid.ts's docstring.
+     */
+    validate?: boolean;
+}
+export interface ViewResult {
+    flowId: string;
+    outputPath: string;
+    mermaid: string;
+    stamp: StalenessStamp;
+    validation?: MermaidValidationResult;
+}
+/**
+ * Generates a mermaid view for one Flow (Phase 1 scope: C1 only, per
+ * proposal 001 §12) and writes it, staleness-stamped, to the
+ * `.loopgraph/ws/` side-channel (proposal 001 §5 — query-side-channel
+ * output, gitignored, regenerated on demand, not a cache).
+ *
+ * Always writes the file, even when `--validate` reports the diagram
+ * invalid — same posture as `loopgraph check`, which reports violations
+ * rather than refusing to run: hiding the broken output would remove
+ * the one artifact useful for debugging what went wrong. The CLI layer
+ * (src/cli/run.ts) is what turns an "invalid" validation result into a
+ * non-zero exit code.
+ */
+export declare function runView(targetDir: string, flowId: string, options?: ViewOptions): Promise<ViewResult>;
+//# sourceMappingURL=view.d.ts.map

package/dist/cli/commands/view.js

@@ -0,0 +1,45 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadModel } from "../../loader/load-model.js";
+import { computeStalenessStamp, formatStalenessBanner } from "../../staleness.js";
+import { renderFlowMermaid } from "../../views/flow-mermaid.js";
+import { validateMermaid } from "../../views/validate-mermaid.js";
+/**
+ * Generates a mermaid view for one Flow (Phase 1 scope: C1 only, per
+ * proposal 001 §12) and writes it, staleness-stamped, to the
+ * `.loopgraph/ws/` side-channel (proposal 001 §5 — query-side-channel
+ * output, gitignored, regenerated on demand, not a cache).
+ *
+ * Always writes the file, even when `--validate` reports the diagram
+ * invalid — same posture as `loopgraph check`, which reports violations
+ * rather than refusing to run: hiding the broken output would remove
+ * the one artifact useful for debugging what went wrong. The CLI layer
+ * (src/cli/run.ts) is what turns an "invalid" validation result into a
+ * non-zero exit code.
+ */
+export async function runView(targetDir, flowId, options = {}) {
+    const modelDir = join(targetDir, "model");
+    const load = await loadModel(modelDir);
+    if (load.parseErrors.length > 0) {
+        throw new Error(`model has ${load.parseErrors.length} parse error(s) — run "loopgraph check" first`);
+    }
+    const mermaid = renderFlowMermaid(load.graph, flowId);
+    const stamp = await computeStalenessStamp(modelDir, targetDir);
+    const wsDir = join(targetDir, ".loopgraph", "ws");
+    await mkdir(wsDir, { recursive: true });
+    const outputPath = join(wsDir, `view-${flowId}.md`);
+    const body = [
+        formatStalenessBanner(stamp),
+        "",
+        `# ${flowId} view`,
+        "",
+        "```mermaid",
+        mermaid,
+        "```",
+        "",
+    ].join("\n");
+    await writeFile(outputPath, body, "utf8");
+    const validation = options.validate ? await validateMermaid(mermaid) : undefined;
+    return { flowId, outputPath, mermaid, stamp, ...(validation ? { validation } : {}) };
+}
+//# sourceMappingURL=view.js.map

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { run } from "./run.js";
+const io = {
+    log: (line) => {
+        process.stdout.write(`${line}\n`);
+    },
+    error: (line) => {
+        process.stderr.write(`${line}\n`);
+    },
+};
+run(process.argv.slice(2), io)
+    .then((exitCode) => {
+    process.exitCode = exitCode;
+})
+    .catch((err) => {
+    io.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/run.d.ts

@@ -0,0 +1,11 @@
+export interface CliIO {
+    log: (line: string) => void;
+    error: (line: string) => void;
+}
+/**
+ * Core dispatch, factored out of the process entry point so tests can
+ * drive it in-process (real filesystem via temp dirs, no subprocess
+ * spawning, no mocking process.argv/stdout).
+ */
+export declare function run(argv: string[], io: CliIO): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.js

@@ -0,0 +1,329 @@
+import { runFacts } from "../adapters/agenthub/facts.js";
+import { loadModel } from "../loader/load-model.js";
+import { startMcpServer } from "../mcp/server.js";
+import { runQuery } from "../query/run-query.js";
+import { inv1ViolationsFrom } from "../validate/inv1/check.js";
+import { reconcileFacts } from "../validate/unregistered.js";
+import { parseFlags } from "./args.js";
+import { runCheck } from "./commands/check.js";
+import { runImport } from "./commands/import.js";
+import { runInit } from "./commands/init.js";
+import { runInspect } from "./commands/inspect.js";
+import { diffSnapshots, loadSnapshot, renderDrift, renderSnapshotSummary, runSnapshot, writeSnapshot, } from "./commands/snapshot.js";
+import { runView } from "./commands/view.js";
+const QUERY_COMMANDS = [
+    "impact",
+    "plan",
+    "scenario",
+    "evidence",
+    "matrix",
+];
+function formatViolation(v) {
+    const marker = v.severity === "error" ? "✗" : "⚠"; // ✗ / ⚠
+    const loc = v.file ? ` [${v.file}]` : v.nodeId ? ` [${v.nodeId}]` : "";
+    return `${marker} ${v.check}${loc}: ${v.message}`;
+}
+const USAGE = "usage: loopgraph <init|import|check> [dir] [--adapter name] [--repo-root path] [--strict-anchors] [--diff base-ref]\n" +
+    "       loopgraph view <flow-id> [dir] [--validate]\n" +
+    "       loopgraph inspect <node-id> [dir] [--depth n]\n" +
+    "       loopgraph <impact|plan|scenario|evidence|matrix> <id> [dir]\n" +
+    "       loopgraph mcp [dir]   # start the stdio MCP server\n" +
+    "       loopgraph facts [repo]   # extract implementation facts (pg-boss queues, pollers)\n" +
+    "       loopgraph snapshot [dir] --repo-root path [--out file] [--drift prior.json]   # T2 nightly scan artifact";
+/**
+ * Reads a `--flag value` string option. Returns `{ error }` when the flag
+ * was given with no value (parseFlags then records it as boolean `true`)
+ * — that's a malformed invocation (e.g. `--repo-root` as the last arg,
+ * or immediately followed by another `--flag`) and must be rejected
+ * loudly, not silently treated as "flag not given" (which previously let
+ * `check --repo-root` with a missing value quietly skip anchor-existence
+ * checking instead of erroring on the typo).
+ */
+function readStringFlag(flags, name) {
+    const raw = flags[name];
+    if (raw === undefined)
+        return { value: undefined };
+    if (typeof raw === "string")
+        return { value: raw };
+    return { value: undefined, error: `--${name} requires a value` };
+}
+/**
+ * Core dispatch, factored out of the process entry point so tests can
+ * drive it in-process (real filesystem via temp dirs, no subprocess
+ * spawning, no mocking process.argv/stdout).
+ */
+export async function run(argv, io) {
+    const [command, ...rest] = argv;
+    const { positionals, flags } = parseFlags(rest);
+    const targetDir = positionals[0] ?? process.cwd();
+    switch (command) {
+        case "init": {
+            const result = await runInit(targetDir);
+            for (const c of result.created)
+                io.log(`created ${c}`);
+            for (const s of result.skipped)
+                io.log(`skipped ${s} (already exists)`);
+            return 0;
+        }
+        case "import": {
+            const adapterFlag = readStringFlag(flags, "adapter");
+            if (adapterFlag.error) {
+                io.error(`${adapterFlag.error}. ${USAGE}`);
+                return 1;
+            }
+            const adapter = adapterFlag.value ?? "agenthub";
+            const result = await runImport(targetDir, adapter);
+            io.log(`imported "${result.adapter}" seed into ${result.destination}`);
+            return 0;
+        }
+        case "check": {
+            const repoRootFlag = readStringFlag(flags, "repo-root");
+            if (repoRootFlag.error) {
+                io.error(`${repoRootFlag.error}. ${USAGE}`);
+                return 1;
+            }
+            const repoRoot = repoRootFlag.value;
+            const strictAnchorExistence = flags["strict-anchors"] === true;
+            const diffFlag = readStringFlag(flags, "diff");
+            if (diffFlag.error) {
+                io.error(`${diffFlag.error}. ${USAGE}`);
+                return 1;
+            }
+            const { t0, inv1, inv1ConfigError, diff, baselineViolations } = await runCheck(targetDir, {
+                repoRoot,
+                strictAnchorExistence,
+                diffBase: diffFlag.value,
+            });
+            const violations = [...t0.violations];
+            if (baselineViolations)
+                violations.push(...baselineViolations);
+            if (inv1)
+                violations.push(...inv1ViolationsFrom(inv1));
+            for (const v of violations)
+                io.log(formatViolation(v));
+            if (diff) {
+                if (!diff.changed) {
+                    io.log(`⚠ --diff ${diff.baseRef}: could not resolve diff (bad ref / not git) — full scan`);
+                }
+                else {
+                    io.log(`--diff ${diff.baseRef}: ${diff.changed.length} changed file(s), ${diff.affected.length} affected model node(s)${diff.incremental ? " (INV-1 incremental)" : ""}`);
+                    for (const a of diff.affected)
+                        io.log(`  affects ${a.nodeId} (${a.kind}) via ${a.anchor}`);
+                }
+            }
+            if (inv1ConfigError)
+                io.error(`✗ inv1-config: ${inv1ConfigError}`);
+            if (inv1) {
+                if (!inv1.ran) {
+                    io.log(`⚠ INV-1 scan skipped: ${inv1.skippedReason}`);
+                }
+                else {
+                    const byVerdict = inv1.writePoints.reduce((acc, w) => {
+                        acc[w.verdict] = (acc[w.verdict] ?? 0) + 1;
+                        return acc;
+                    }, {});
+                    io.log(`INV-1 scan: ${inv1.filesScanned}/${inv1.candidateFiles} candidate file(s), ` +
+                        `${byVerdict.allowed ?? 0} allowed / ${byVerdict.violation ?? 0} violation(s) / ${byVerdict.unanalyzable ?? 0} unanalyzable, ` +
+                        `${inv1.timingMs.toFixed(0)}ms`);
+                }
+            }
+            const errorCount = violations.filter((v) => v.severity === "error").length;
+            const warningCount = violations.length - errorCount;
+            const ok = errorCount === 0 && !inv1ConfigError;
+            io.log(ok
+                ? `T0 passed (${warningCount} warning(s))`
+                : `T0 failed (${errorCount} error(s), ${warningCount} warning(s))`);
+            return ok ? 0 : 1;
+        }
+        case "view": {
+            // Unlike init/import/check, positionals[0] here is the required
+            // <flow-id>, not the target dir — the shared `targetDir` computed
+            // above (which assumes positionals[0] is a dir) doesn't apply.
+            const flowId = positionals[0];
+            if (!flowId) {
+                io.error(`missing <flow-id>. ${USAGE}`);
+                return 1;
+            }
+            const viewTargetDir = positionals[1] ?? process.cwd();
+            const validate = flags.validate === true;
+            let result;
+            try {
+                result = await runView(viewTargetDir, flowId, { validate });
+            }
+            catch (err) {
+                io.error(err instanceof Error ? err.message : String(err));
+                return 1;
+            }
+            io.log(`wrote ${result.outputPath}`);
+            if (!result.validation)
+                return 0;
+            if (result.validation.status === "valid") {
+                io.log("mermaid validation: ok");
+                return 0;
+            }
+            if (result.validation.status === "unavailable") {
+                io.log(`⚠ mermaid validation skipped: ${result.validation.reason}`);
+                return 0;
+            }
+            io.log(`✗ mermaid validation failed: ${result.validation.error}`);
+            return 1;
+        }
+        case "inspect": {
+            // positionals[0] is the required <node-id>, not the target dir.
+            const nodeId = positionals[0];
+            if (!nodeId) {
+                io.error(`missing <node-id>. ${USAGE}`);
+                return 1;
+            }
+            const inspectTargetDir = positionals[1] ?? process.cwd();
+            const depthFlag = readStringFlag(flags, "depth");
+            if (depthFlag.error) {
+                io.error(`${depthFlag.error}. ${USAGE}`);
+                return 1;
+            }
+            let depth;
+            if (depthFlag.value !== undefined) {
+                depth = Number(depthFlag.value);
+                if (!Number.isInteger(depth) || depth < 0) {
+                    io.error(`--depth must be a non-negative integer, got "${depthFlag.value}". ${USAGE}`);
+                    return 1;
+                }
+            }
+            let result;
+            try {
+                result = await runInspect(inspectTargetDir, nodeId, depth === undefined ? {} : { depth });
+            }
+            catch (err) {
+                io.error(err instanceof Error ? err.message : String(err));
+                return 1;
+            }
+            if (result.staleWarning)
+                io.log(`⚠ ${result.staleWarning}`);
+            io.log(result.summary);
+            io.log(`wrote ${result.outputPath}`);
+            return 0;
+        }
+        case "mcp": {
+            // Long-lived stdio server: it owns stdout for the JSON-RPC protocol, so
+            // nothing else may write there. targetDir is positionals[0] (the dir with
+            // model/), defaulting to cwd.
+            const mcpTargetDir = positionals[0] ?? process.cwd();
+            await startMcpServer(mcpTargetDir);
+            return 0; // returns when the transport closes
+        }
+        case "facts": {
+            // Extract implementation facts from a target repo (positionals[0] = repo
+            // root, defaulting to cwd). `--no-cache` disables the B3 content cache.
+            const repo = positionals[0] ?? process.cwd();
+            const result = await runFacts(repo, flags["no-cache"] === true ? { cacheDir: null } : {});
+            if (!result.ran) {
+                io.log(`⚠ facts extraction skipped: ${result.skippedReason}`);
+                return 0;
+            }
+            const bySignal = {};
+            for (const f of result.facts) {
+                const list = bySignal[f.signal] ?? [];
+                list.push(f);
+                bySignal[f.signal] = list;
+            }
+            for (const [signal, list] of Object.entries(bySignal)) {
+                io.log(`${signal} (${list.length}):`);
+                for (const f of list) {
+                    const detail = f.detail ? `  [${f.detail}${f.unanalyzable ? ", unanalyzable" : ""}]` : "";
+                    io.log(`  ${f.name}  ${f.filePath}:${f.line}${detail}`);
+                }
+            }
+            io.log(`extracted ${result.facts.length} fact(s) from ${result.filesScanned}/${result.candidateFiles} candidate file(s), ${result.timingMs.toFixed(0)}ms`);
+            return 0;
+        }
+        case "reconcile": {
+            // C2 T1 (advisory): which extracted facts no model node registers.
+            // `loopgraph reconcile <model-dir> --repo-root <repo>`. Exits 0 always
+            // (T1 is report-tier until C3 promotes it); `--strict` flips unregistered
+            // facts into a non-zero exit for opt-in local use.
+            const repoRootFlag = readStringFlag(flags, "repo-root");
+            if (repoRootFlag.error || !repoRootFlag.value) {
+                io.error(`reconcile needs --repo-root <repo>. ${USAGE}`);
+                return 1;
+            }
+            const model = await loadModel(`${targetDir}/model`);
+            const factsResult = await runFacts(repoRootFlag.value, flags["no-cache"] === true ? { cacheDir: null } : {});
+            if (!factsResult.ran) {
+                io.log(`⚠ reconcile skipped: ${factsResult.skippedReason}`);
+                return 0;
+            }
+            const { registered, dormantSuppressed, unregistered, coveredFiles, unmatchedConsumedQueues } = reconcileFacts(factsResult.facts, model.graph);
+            for (const f of unregistered)
+                io.log(`⚠ unregistered ${f.signal}: ${f.name}  ${f.filePath}:${f.line}`);
+            for (const f of dormantSuppressed)
+                io.log(`· dormant-suppressed ${f.signal}: ${f.name}  ${f.filePath}:${f.line}`);
+            for (const q of unmatchedConsumedQueues)
+                io.log(`⚠ dangling consumes_queues: "${q}" matches no extracted queue (typo/stale?)`);
+            const total = factsResult.facts.length;
+            const pct = total === 0 ? 0 : Math.round((unregistered.length / total) * 100);
+            const dormantNote = dormantSuppressed.length > 0 ? `, ${dormantSuppressed.length} dormant-suppressed` : "";
+            // registered + dormantSuppressed + unregistered === total (disjoint).
+            io.log(`reconcile: ${registered.length}/${total} fact(s) registered${dormantNote}, ${unregistered.length} unregistered (${pct}%), ` +
+                `${coveredFiles.length} model-covered file(s)`);
+            return flags.strict === true && unregistered.length > 0 ? 1 : 0;
+        }
+        case "snapshot": {
+            // T2 nightly full-scan artifact (Proposal 006 D2). NEVER a PR gate
+            // (001 §6): this always exits 0 — drift is reported, not failed on.
+            const repoRootFlag = readStringFlag(flags, "repo-root");
+            const outFlag = readStringFlag(flags, "out");
+            const driftFlag = readStringFlag(flags, "drift");
+            for (const f of [repoRootFlag, outFlag, driftFlag]) {
+                if (f.error) {
+                    io.error(`${f.error}. ${USAGE}`);
+                    return 1;
+                }
+            }
+            const snapshot = await runSnapshot(targetDir, {
+                repoRoot: repoRootFlag.value,
+                ...(flags["no-cache"] === true ? { cacheDir: null } : {}),
+            });
+            io.log(renderSnapshotSummary(snapshot));
+            if (driftFlag.value) {
+                const prior = await loadSnapshot(driftFlag.value);
+                if (!prior) {
+                    io.log(`⚠ --drift: no readable prior snapshot at ${driftFlag.value} — skipping drift`);
+                }
+                else {
+                    for (const line of renderDrift(diffSnapshots(prior, snapshot)))
+                        io.log(line);
+                }
+            }
+            const outPath = outFlag.value ?? `${targetDir}/.loopgraph/snapshot.json`;
+            await writeSnapshot(outPath, snapshot);
+            io.log(`wrote ${outPath}`);
+            return 0;
+        }
+        default: {
+            if (command && QUERY_COMMANDS.includes(command)) {
+                // impact / plan / scenario / evidence <id> [dir]
+                const id = positionals[0];
+                if (!id) {
+                    io.error(`missing <id> for \`${command}\`. ${USAGE}`);
+                    return 1;
+                }
+                const queryTargetDir = positionals[1] ?? process.cwd();
+                let result;
+                try {
+                    result = await runQuery(queryTargetDir, command, id);
+                }
+                catch (err) {
+                    io.error(err instanceof Error ? err.message : String(err));
+                    return 1;
+                }
+                if (result.staleWarning)
+                    io.log(`⚠ ${result.staleWarning}`);
+                io.log(result.summary);
+                return 0;
+            }
+            io.error(`unknown command "${command ?? ""}". ${USAGE}`);
+            return 1;
+        }
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/loader/find-yaml-files.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pure error-code → message mapping, factored out of findYamlFiles so
+ * every branch (ENOENT/ENOTDIR/EACCES/EPERM/unknown) is directly
+ * unit-testable without needing to actually reproduce each condition on
+ * a real filesystem — reproducing EACCES portably (across macOS/Linux/CI
+ * containers, some of which run as root and ignore chmod) is exactly the
+ * kind of flaky test this sidesteps. Returns undefined for an
+ * unrecognized/missing error code, signaling "rethrow as-is".
+ */
+export declare function formatModelDirReadError(dir: string, code: string | undefined): string | undefined;
+/**
+ * An unreadable model directory (missing, wrong permissions, or not
+ * actually a directory) is a setup error, not "zero nodes". Treating it
+ * as an empty model would make `runT0` trivially pass with zero
+ * violations — a false "T0 passed" that implies something was checked
+ * when nothing was. This surfaces a clear, actionable error instead of
+ * whatever raw errno a bare `readdir` would throw.
+ *
+ * Lives in its own module (not inlined in load-model.ts) because it's
+ * reused by src/staleness.ts (computeModelContentHash needs the same
+ * "every *.yaml/*.yml file under a model dir" listing to hash) — a
+ * second, unrelated caller that has no business depending on
+ * `loadModel`'s own orchestration module.
+ */
+export declare function findYamlFiles(dir: string): Promise<string[]>;
+//# sourceMappingURL=find-yaml-files.d.ts.map