@shrkcrft/cli 0.1.0-alpha.23 → 0.1.0-alpha.24

package/dist/diff/collect-changed-paths.d.ts

@@ -1,7 +1,7 @@
 /**
- * CLI-side `--since <ref>` helper. Thin wrapper over `git diff
- * --name-status <ref>...HEAD` that returns the changed file set + a
- * deleted file set + an `isAvailable` flag so callers can fall back
+ * CLI-side `--since <ref>` helper. Thin wrapper over a two-dot `git diff
+ * --name-status <ref>` (working tree vs `<ref>`) that returns the changed file
+ * set + a deleted file set + an `isAvailable` flag so callers can fall back
  * to whole-tree mode cleanly.
  *
  * Default ref resolution when `--since` is passed without a value:
@@ -23,5 +23,7 @@ export declare function resolveDefaultSinceRef(cwd: string): string | undefined;
 export declare function collectChangedPaths(opts: {
     cwd: string;
     ref?: string;
+    /** Read the staged (index) diff instead of diffing against a ref. */
+    staged?: boolean;
 }): IChangedPaths;
 //# sourceMappingURL=collect-changed-paths.d.ts.map

package/dist/diff/collect-changed-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collect-changed-paths.d.ts","sourceRoot":"","sources":["../../src/diff/collect-changed-paths.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYtE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,aAAa,CA+ChB"}
+{"version":3,"file":"collect-changed-paths.d.ts","sourceRoot":"","sources":["../../src/diff/collect-changed-paths.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOtE;AAoCD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,aAAa,CAwDhB"}

package/dist/diff/collect-changed-paths.js

@@ -1,22 +1,72 @@
-import { execSync } from 'node:child_process';
 import * as nodePath from 'node:path';
+import { runGitLines } from '@shrkcrft/shared';
 const DEFAULT_REF_CANDIDATES = ['origin/main', 'main', 'origin/master', 'master'];
 const PER_PROCESS_CACHE = new Map();
 export function resolveDefaultSinceRef(cwd) {
     for (const candidate of DEFAULT_REF_CANDIDATES) {
-        try {
-            execSync(`git -C "${cwd}" rev-parse --verify --quiet "${candidate}"`, {
-                stdio: 'pipe',
-            });
+        if (runGitLines(cwd, ['rev-parse', '--verify', '--quiet', candidate]).ok) {
             return candidate;
         }
-        catch {
-            // try next
-        }
     }
     return undefined;
 }
+function toPosix(path) {
+    return nodePath.normalize(path).split(nodePath.sep).join('/');
+}
+/**
+ * Split `git diff --name-status` lines into changed vs deleted POSIX paths.
+ * Rename/copy detection is ON by default for `git diff`, so a rename emits a
+ * TAB-separated `R<score>\t<old>\t<new>` (copy: `C<score>\t<old>\t<new>`) — the
+ * status field is `R100`, not a bare letter. The old path of a RENAME is gone
+ * (so the orphan check must treat it as deleted); a COPY keeps its source. Every
+ * other status (A/M/T/…) carries a single path. Parsing the status by its first
+ * letter + splitting on TAB is what makes a `git mv` that orphans an importer
+ * visible to `check orphans` / `finish` instead of silently dropped.
+ */
+function parseNameStatus(lines) {
+    const changed = [];
+    const deleted = [];
+    for (const line of lines) {
+        const parts = line.split('\t');
+        if (parts.length < 2)
+            continue;
+        const code = parts[0][0];
+        if (code === 'D') {
+            deleted.push(toPosix(parts[1]));
+        }
+        else if ((code === 'R' || code === 'C') && parts.length >= 3) {
+            // R<score>\t<old>\t<new> (rename) / C<score>\t<old>\t<new> (copy).
+            if (code === 'R')
+                deleted.push(toPosix(parts[1])); // old path renamed away
+            changed.push(toPosix(parts[2])); // new path is added
+        }
+        else {
+            changed.push(toPosix(parts[1]));
+        }
+    }
+    return { changed, deleted };
+}
 export function collectChangedPaths(opts) {
+    if (opts.staged) {
+        const cacheKey = `${opts.cwd}::staged`;
+        const cached = PER_PROCESS_CACHE.get(cacheKey);
+        if (cached)
+            return cached;
+        const out = runGitLines(opts.cwd, ['diff', '--name-status', '--cached']);
+        if (!out.ok) {
+            return {
+                ref: 'STAGED',
+                changed: [],
+                deleted: [],
+                isAvailable: false,
+                ...(out.error ? { error: out.error } : {}),
+            };
+        }
+        const { changed, deleted } = parseNameStatus(out.lines);
+        const result = { ref: 'STAGED', changed, deleted, isAvailable: true };
+        PER_PROCESS_CACHE.set(cacheKey, result);
+        return result;
+    }
     const ref = opts.ref ?? resolveDefaultSinceRef(opts.cwd);
     if (!ref) {
         return {
@@ -27,42 +77,29 @@ export function collectChangedPaths(opts) {
             error: 'no resolvable default branch (tried origin/main, main, origin/master, master)',
         };
     }
-    const cacheKey = `${opts.cwd}::${ref}`;
+    // Namespace the ref cache key so a branch/tag literally named `staged` can't
+    // collide with the `::staged` index-diff key above.
+    const cacheKey = `${opts.cwd}::ref::${ref}`;
     const cached = PER_PROCESS_CACHE.get(cacheKey);
     if (cached)
         return cached;
-    try {
-        // Two-dot diff against the ref to match the inspector's
-        // `getChangedFiles({ since })` behavior — includes both committed
-        // changes and the working tree relative to <ref>.
-        const stdout = execSync(`git -C "${opts.cwd}" diff --name-status "${ref}"`, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
-        const changed = [];
-        const deleted = [];
-        for (const line of stdout.split('\n')) {
-            const trimmed = line.trim();
-            if (!trimmed)
-                continue;
-            const m = trimmed.match(/^(\w)\s+(.+)$/);
-            if (!m)
-                continue;
-            const [, status, path] = m;
-            const norm = nodePath.normalize(path).split(nodePath.sep).join('/');
-            if (status === 'D')
-                deleted.push(norm);
-            else
-                changed.push(norm);
-        }
-        const result = { ref, changed, deleted, isAvailable: true };
-        PER_PROCESS_CACHE.set(cacheKey, result);
-        return result;
-    }
-    catch (e) {
+    // Two-dot diff against the ref to match the inspector's
+    // `getChangedFiles({ since })` behavior — includes both committed
+    // changes and the working tree relative to <ref>. `runGitLines` is
+    // shell-free + high-maxBuffer, so a large changeset no longer ENOBUFS-crashes
+    // the `impact --deleted` orphan check (this is its only write-safety guard).
+    const out = runGitLines(opts.cwd, ['diff', '--name-status', ref]);
+    if (!out.ok) {
         return {
             ref,
             changed: [],
             deleted: [],
             isAvailable: false,
-            error: e instanceof Error ? e.message : String(e),
+            ...(out.error ? { error: out.error } : {}),
         };
     }
+    const { changed, deleted } = parseNameStatus(out.lines);
+    const result = { ref, changed, deleted, isAvailable: true };
+    PER_PROCESS_CACHE.set(cacheKey, result);
+    return result;
 }

package/dist/diff/deleted-orphans.d.ts

@@ -0,0 +1,42 @@
+import type { IDeletedOrphanReport } from '@shrkcrft/impact-engine';
+/**
+ * Why the scan could not produce an orphan report (so callers pick an exit
+ * code / message): the diff was unavailable (no resolvable ref, git error) or
+ * the code-graph store is missing.
+ */
+export type DeletedOrphanScanFailure = 'diff-unavailable' | 'graph-missing';
+/** Result of {@link computeDeletedOrphans}. */
+export interface IDeletedOrphanScan {
+    /** True when the diff resolved (and, when anything was deleted, the graph too). */
+    readonly ok: boolean;
+    /** What was diffed: `'STAGED'` for `--staged`, otherwise the resolved ref. */
+    readonly ref: string;
+    /** Deleted files read from the diff (empty list is a valid, clean result). */
+    readonly deleted: readonly string[];
+    /**
+     * The alias-resolved orphan report. Present iff `ok` AND something was
+     * deleted — when `deleted` is empty the scan short-circuits clean without
+     * loading the graph, so there is no report (and none is needed).
+     */
+    readonly report?: IDeletedOrphanReport;
+    /** Why the scan failed. Present iff not `ok`. */
+    readonly reason?: DeletedOrphanScanFailure;
+    /** Human-readable failure detail. */
+    readonly error?: string;
+}
+/**
+ * Diff-driven reverse-closure: read the files DELETED in the changeset (vs
+ * `since`, or the staged index when `staged`), then query the code-graph
+ * snapshot for surviving files that still import them or reference a symbol
+ * they declared (alias-resolved, incl. barrel re-exports). The shared core
+ * behind `impact --deleted`, `check orphans`, and the composite `finish` gate.
+ *
+ * Never throws: a bad diff → `{ reason: 'diff-unavailable' }`, a missing index
+ * → `{ reason: 'graph-missing' }`. Graph + engine are imported lazily so a
+ * command that never hits the orphan path doesn't pay to load them.
+ */
+export declare function computeDeletedOrphans(cwd: string, opts: {
+    since?: string;
+    staged?: boolean;
+}): Promise<IDeletedOrphanScan>;
+//# sourceMappingURL=deleted-orphans.d.ts.map

package/dist/diff/deleted-orphans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deleted-orphans.d.ts","sourceRoot":"","sources":["../../src/diff/deleted-orphans.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAGpE;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAE5E,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IACvC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAC3C,qCAAqC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACzC,OAAO,CAAC,kBAAkB,CAAC,CAmC7B"}

package/dist/diff/deleted-orphans.js

@@ -0,0 +1,46 @@
+import { collectChangedPaths } from "./collect-changed-paths.js";
+/**
+ * Diff-driven reverse-closure: read the files DELETED in the changeset (vs
+ * `since`, or the staged index when `staged`), then query the code-graph
+ * snapshot for surviving files that still import them or reference a symbol
+ * they declared (alias-resolved, incl. barrel re-exports). The shared core
+ * behind `impact --deleted`, `check orphans`, and the composite `finish` gate.
+ *
+ * Never throws: a bad diff → `{ reason: 'diff-unavailable' }`, a missing index
+ * → `{ reason: 'graph-missing' }`. Graph + engine are imported lazily so a
+ * command that never hits the orphan path doesn't pay to load them.
+ */
+export async function computeDeletedOrphans(cwd, opts) {
+    const changed = collectChangedPaths({
+        cwd,
+        ...(opts.since ? { ref: opts.since } : {}),
+        ...(opts.staged ? { staged: true } : {}),
+    });
+    if (!changed.isAvailable) {
+        return {
+            ok: false,
+            ref: changed.ref,
+            deleted: [],
+            reason: 'diff-unavailable',
+            ...(changed.error ? { error: changed.error } : {}),
+        };
+    }
+    // Nothing deleted → clean by definition; don't pay to load the graph (and
+    // don't fail when no index exists — there is nothing to check).
+    if (changed.deleted.length === 0) {
+        return { ok: true, ref: changed.ref, deleted: [] };
+    }
+    const { GraphStore, GraphQueryApi } = await import('@shrkcrft/graph');
+    if (!new GraphStore(cwd).exists()) {
+        return {
+            ok: false,
+            ref: changed.ref,
+            deleted: changed.deleted,
+            reason: 'graph-missing',
+            error: 'code-graph store missing — run `shrk graph index` first.',
+        };
+    }
+    const { findDeletedOrphans } = await import('@shrkcrft/impact-engine');
+    const report = findDeletedOrphans(GraphQueryApi.fromStore(cwd), changed.deleted);
+    return { ok: true, ref: changed.ref, deleted: changed.deleted, report };
+}

package/dist/finish/run-finish.d.ts

@@ -0,0 +1,62 @@
+import { type IChangedScopeOptions } from '@shrkcrft/inspector';
+export declare const FINISH_SCHEMA: "sharkcraft.finish/v1";
+/** Outcome of one sub-gate. `skipped` = nothing to evaluate (loud, never silent green). */
+export type FinishGateStatus = 'pass' | 'fail' | 'skipped';
+/** One failing/relevant item, with file:line where the engine provides it. */
+export interface IFinishItem {
+    readonly file?: string;
+    readonly line?: number;
+    readonly message: string;
+}
+export interface IFinishGate {
+    readonly name: 'boundaries' | 'imports' | 'wiring' | 'policy' | 'orphans';
+    readonly status: FinishGateStatus;
+    /** One-line reason (e.g. why skipped, or the error/warning counts). */
+    readonly detail: string;
+    readonly errors: number;
+    readonly warnings: number;
+    /** Failing/notable items (capped by the renderer, full in JSON). */
+    readonly items: readonly IFinishItem[];
+}
+export interface IFinishImpact {
+    readonly ran: boolean;
+    readonly risk?: string;
+    readonly directDependents?: number;
+    readonly transitiveDependents?: number;
+    /** Why the summary could not run (no graph index / no changed files). */
+    readonly note?: string;
+}
+export interface IFinishReport {
+    readonly schema: typeof FINISH_SCHEMA;
+    readonly scope: {
+        readonly mode: 'worktree' | 'staged' | 'since' | 'files';
+        readonly files: readonly string[];
+        readonly fileCount: number;
+    };
+    readonly gates: readonly IFinishGate[];
+    readonly impact: IFinishImpact;
+    /** `fail` iff any gate failed OR the config could not load; else `pass`. */
+    readonly verdict: 'pass' | 'fail';
+    /** Total warning-severity findings across gates (non-blocking). */
+    readonly warnings: number;
+    /** Set when sharkcraft.config.ts could not be loaded — forces a `fail`. */
+    readonly configError?: string;
+    readonly summary: string;
+    readonly nextAction: string;
+}
+export interface IRunFinishInput {
+    readonly cwd: string;
+    readonly mode: 'worktree' | 'staged' | 'since' | 'files';
+    readonly scope: IChangedScopeOptions;
+}
+/**
+ * The composite "is this changeset safe to finish?" orchestrator. Runs every
+ * deterministic CHANGED-ONLY gate inline — boundaries + import-hygiene + wiring
+ * + policy + deleted-orphans — plus a best-effort impact summary, and folds
+ * them into ONE pass/fail. This is the single trustworthy "done?" call an
+ * autonomous agent needs and can't reliably assemble by hand (only shrk can run
+ * the alias-resolved layer/wiring gates). Honors the `0-rules → skipped`
+ * semantics so a no-op sub-check is reported, never silently passed. Read-only.
+ */
+export declare function runFinishGates(input: IRunFinishInput): Promise<IFinishReport>;
+//# sourceMappingURL=run-finish.d.ts.map

package/dist/finish/run-finish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-finish.d.ts","sourceRoot":"","sources":["../../src/finish/run-finish.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAa7B,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAE7D,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC1E,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAYD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAkHnF"}

package/dist/finish/run-finish.js

@@ -0,0 +1,239 @@
+import { buildImportHygieneReport, filterViolationsToChangedScope, inspectSharkcraft, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { evaluateBoundaries, loadTsconfigPaths, runPolicyLint, runWiring, scanImports, } from '@shrkcrft/boundaries';
+import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
+export const FINISH_SCHEMA = 'sharkcraft.finish/v1';
+/** Map the changed-scope onto the orphan check's diff inputs. */
+function orphanOptsFor(input) {
+    if (input.mode === 'files')
+        return undefined; // a file list has no diff to read deletions from
+    if (input.mode === 'staged')
+        return { staged: true };
+    if (input.mode === 'since' && input.scope.since)
+        return { since: input.scope.since };
+    // Worktree mode: diff deletions vs HEAD so the orphan gate's "deleted" set
+    // matches the working-tree scope the other gates use (not the whole branch).
+    return { since: 'HEAD' };
+}
+/**
+ * The composite "is this changeset safe to finish?" orchestrator. Runs every
+ * deterministic CHANGED-ONLY gate inline — boundaries + import-hygiene + wiring
+ * + policy + deleted-orphans — plus a best-effort impact summary, and folds
+ * them into ONE pass/fail. This is the single trustworthy "done?" call an
+ * autonomous agent needs and can't reliably assemble by hand (only shrk can run
+ * the alias-resolved layer/wiring gates). Honors the `0-rules → skipped`
+ * semantics so a no-op sub-check is reported, never silently passed. Read-only.
+ */
+export async function runFinishGates(input) {
+    const { cwd } = input;
+    const changed = resolveChangedFiles(input.scope);
+    const changedFiles = changed.files;
+    const gates = [];
+    // ── boundaries (changed-only) ────────────────────────────────────────
+    const inspection = await inspectSharkcraft({ cwd });
+    const boundaryRules = inspection.boundaryRegistry.list();
+    if (boundaryRules.length === 0) {
+        gates.push(skip('boundaries', 'no boundary rules configured'));
+    }
+    else if (changedFiles.length === 0) {
+        gates.push(skip('boundaries', 'no files in changed scope'));
+    }
+    else {
+        const scan = scanImports({ projectRoot: cwd });
+        const tsconfigPaths = loadTsconfigPaths(cwd);
+        const evalResult = evaluateBoundaries(scan, boundaryRules, {
+            ...(tsconfigPaths.aliases.size > 0 ? { tsconfigPaths } : {}),
+        });
+        const filtered = filterViolationsToChangedScope(evalResult.violations, input.scope);
+        const errors = filtered.includedViolations.filter((v) => v.severity === 'error');
+        const warnings = filtered.includedViolations.filter((v) => v.severity === 'warning');
+        gates.push({
+            name: 'boundaries',
+            status: errors.length > 0 ? 'fail' : 'pass',
+            detail: `${errors.length} error(s), ${warnings.length} warning(s) across ${changedFiles.length} changed file(s)`,
+            errors: errors.length,
+            warnings: warnings.length,
+            items: [...errors, ...warnings].map((v) => ({
+                file: v.file,
+                line: v.line,
+                message: `[${v.severity}] ${v.ruleId}: ${v.message}`,
+            })),
+        });
+    }
+    // ── import hygiene (changed-only) ────────────────────────────────────
+    if (changedFiles.length === 0) {
+        gates.push(skip('imports', 'no files in changed scope'));
+    }
+    else {
+        const report = buildImportHygieneReport(cwd, { files: changedFiles });
+        const errors = report.counts?.['error'] ?? (report.verdict === 'errors' ? report.findings.length : 0);
+        const warnings = report.counts?.['warning'] ?? (report.verdict === 'warnings' ? report.findings.length : 0);
+        gates.push({
+            name: 'imports',
+            status: report.verdict === 'errors' ? 'fail' : 'pass',
+            detail: `verdict=${report.verdict} (${report.findings.length} finding(s))`,
+            errors,
+            warnings,
+            items: report.findings.map((f) => ({
+                file: f.file,
+                line: f.line,
+                message: `${f.kind}: ${f.suggestedFix || f.reason || f.snippet}`.trim(),
+            })),
+        });
+    }
+    // ── wiring + policy (changed-only, from resolved config) ─────────────
+    const loaded = await resolveProjectConfig(cwd);
+    let configError;
+    if (!loaded.ok) {
+        // A MALFORMED config in a real sharkcraft project is a fail (the wiring/
+        // policy gates can't be trusted). The mere ABSENCE of a sharkcraft/ folder
+        // is not — those gates simply don't apply, so skip them without failing.
+        const isSharkcraftProject = existsSync(nodePath.join(cwd, 'sharkcraft'));
+        if (isSharkcraftProject)
+            configError = loaded.error.message;
+        const detail = isSharkcraftProject
+            ? `config did not load: ${loaded.error.message}`
+            : 'no sharkcraft config (gate not applicable)';
+        gates.push(skip('wiring', detail));
+        gates.push(skip('policy', detail));
+    }
+    else {
+        gates.push(wiringGate(cwd, loaded.value.config.wiringRules ?? [], changedFiles), policyGate(cwd, loaded.value.config.policyRules ?? [], changedFiles));
+    }
+    // ── deleted-orphans (write-safety) ───────────────────────────────────
+    gates.push(await orphansGate(input));
+    // ── impact summary (informational, best-effort) ──────────────────────
+    const impact = await impactSummary(cwd, changedFiles);
+    // ── fold into one verdict ────────────────────────────────────────────
+    const failed = gates.filter((g) => g.status === 'fail');
+    const warnings = gates.reduce((n, g) => n + g.warnings, 0);
+    const verdict = failed.length > 0 || configError ? 'fail' : 'pass';
+    const skipped = gates.filter((g) => g.status === 'skipped').map((g) => g.name);
+    const summary = verdict === 'fail'
+        ? `Not safe to finish: ${configError ? 'config failed to load; ' : ''}${failed.map((g) => `${g.name} (${g.errors} error(s))`).join(', ') || 'see gates'}.`
+        : changedFiles.length === 0 && input.mode !== 'files'
+            ? 'No files in the changed scope — nothing to gate.'
+            : `Safe to finish: every applicable gate passed${warnings > 0 ? ` (${warnings} non-blocking warning(s))` : ''}${skipped.length > 0 ? `; skipped: ${skipped.join(', ')}` : ''}.`;
+    const nextAction = verdict === 'fail'
+        ? 'Fix every failing gate item (each carries file:line), then re-run `shrk finish`.'
+        : 'Safe to declare done.';
+    return {
+        schema: FINISH_SCHEMA,
+        scope: { mode: input.mode, files: changedFiles, fileCount: changedFiles.length },
+        gates,
+        impact,
+        verdict,
+        warnings,
+        ...(configError ? { configError } : {}),
+        summary,
+        nextAction,
+    };
+}
+function skip(name, detail) {
+    return { name, status: 'skipped', detail, errors: 0, warnings: 0, items: [] };
+}
+function wiringGate(cwd, rules, changedFiles) {
+    if (rules.length === 0)
+        return skip('wiring', 'no wiring rules configured');
+    const report = runWiring(cwd, rules, { changedOnly: true, changedFiles });
+    if (report.evaluated === 0) {
+        return skip('wiring', `${report.rules.length} rule(s) configured but none matched the changed scope`);
+    }
+    const errors = report.violations.filter((v) => v.severity === 'error');
+    const warnings = report.violations.filter((v) => v.severity === 'warning');
+    // A misconfigured rule (bad regex / no capture group) yields a diagnostic +
+    // rule-level error but NO violation — it must FAIL the gate, never read as a
+    // silent green ("loud, never silent green").
+    const diag = report.diagnostics;
+    return {
+        name: 'wiring',
+        status: report.verdict === 'errors' || diag.length > 0 ? 'fail' : 'pass',
+        detail: `${report.evaluated}/${report.rules.length} rule(s) evaluated — ${errors.length} error(s), ${warnings.length} warning(s)${diag.length > 0 ? `, ${diag.length} misconfigured` : ''}`,
+        errors: errors.length + diag.length,
+        warnings: warnings.length,
+        items: [
+            ...report.violations.map((v) => ({
+                file: v.file,
+                line: v.line,
+                message: `[${v.severity}] ${v.ruleId}: "${v.token}" ${v.direction === 'registered-missing' ? 'registered but not declared' : 'declared but not registered'}`,
+            })),
+            ...diag.map((d) => ({ message: `misconfigured rule: ${d}` })),
+        ],
+    };
+}
+function policyGate(cwd, rules, changedFiles) {
+    if (rules.length === 0)
+        return skip('policy', 'no policy rules configured');
+    const report = runPolicyLint(cwd, rules, { changedOnly: true, changedFiles });
+    if (report.evaluated === 0) {
+        return skip('policy', `${report.rules.length} rule(s) configured but none matched the changed scope`);
+    }
+    const errors = report.findings.filter((f) => f.severity === 'error');
+    const warnings = report.findings.filter((f) => f.severity === 'warning');
+    const diag = report.diagnostics;
+    return {
+        name: 'policy',
+        status: report.verdict === 'errors' || diag.length > 0 ? 'fail' : 'pass',
+        detail: `${report.evaluated}/${report.rules.length} rule(s) evaluated — ${errors.length} error(s), ${warnings.length} warning(s)${diag.length > 0 ? `, ${diag.length} misconfigured` : ''}`,
+        errors: errors.length + diag.length,
+        warnings: warnings.length,
+        items: [
+            ...report.findings.map((f) => ({
+                file: f.file,
+                line: f.line,
+                message: `[${f.severity}] ${f.ruleId}: ${f.message ?? ''}`.trim(),
+            })),
+            ...diag.map((d) => ({ message: `misconfigured rule: ${d}` })),
+        ],
+    };
+}
+async function orphansGate(input) {
+    const opts = orphanOptsFor(input);
+    if (!opts)
+        return skip('orphans', 'explicit --files scope has no diff to read deletions from');
+    const scan = await computeDeletedOrphans(input.cwd, opts);
+    if (!scan.ok) {
+        return skip('orphans', scan.reason === 'graph-missing'
+            ? 'code-graph index missing — run `shrk graph index` to enable the orphan check'
+            : `diff unavailable: ${scan.error ?? 'unknown'}`);
+    }
+    if (scan.deleted.length === 0)
+        return skip('orphans', `nothing deleted (vs ${scan.ref})`);
+    const orphans = scan.report?.orphans ?? [];
+    return {
+        name: 'orphans',
+        status: orphans.length > 0 ? 'fail' : 'pass',
+        detail: `${scan.deleted.length} deleted file(s) (vs ${scan.ref}) — ${orphans.length} surviving importer(s)`,
+        errors: orphans.length,
+        warnings: 0,
+        items: orphans.map((o) => ({
+            file: o.path ?? o.id,
+            ...(typeof o.line === 'number' ? { line: o.line } : {}),
+            message: o.via === 'reference' && o.symbol
+                ? `references \`${o.symbol}\` from deleted ${o.deletedFile}`
+                : `imports deleted ${o.deletedFile}`,
+        })),
+    };
+}
+async function impactSummary(cwd, changedFiles) {
+    if (changedFiles.length === 0)
+        return { ran: false, note: 'no changed files' };
+    try {
+        const { GraphStore } = await import('@shrkcrft/graph');
+        if (!new GraphStore(cwd).exists()) {
+            return { ran: false, note: 'code-graph index missing — run `shrk graph index`' };
+        }
+        const { analyzeGraphImpact } = await import('@shrkcrft/impact-engine');
+        const analysis = analyzeGraphImpact({ kind: 'files', files: [...changedFiles] }, { projectRoot: cwd, maxDepth: 5, limit: 200 });
+        return {
+            ran: true,
+            risk: analysis.risk,
+            directDependents: analysis.directDependents.length,
+            transitiveDependents: analysis.transitiveDependents.length,
+        };
+    }
+    catch (e) {
+        return { ran: false, note: `impact summary unavailable: ${e instanceof Error ? e.message : String(e)}` };
+    }
+}

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AA0X/B,wBAAgB,aAAa,IAAI,eAAe,CA8X/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAqID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AA4X/B,wBAAgB,aAAa,IAAI,eAAe,CAgY/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAqID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}

package/dist/main.js

@@ -22,6 +22,7 @@ import { presetsListCommand, presetsGetCommand, presetsExplainCommand, presetsRe
 import { taskCommand } from "./commands/task.command.js";
 import { preflightCommand } from "./commands/preflight.command.js";
 import { checkCommand } from "./commands/check.command.js";
+import { finishCommand } from "./commands/finish.command.js";
 import { diffCheckCommand } from "./commands/diff-check.command.js";
 import { driftCommand } from "./commands/drift.command.js";
 import { graphCommand } from "./commands/graph.command.js";
@@ -33,6 +34,7 @@ import { frameworkCommand } from "./commands/framework.command.js";
 import { apiDiffCommand } from "./commands/api-diff.command.js";
 import { gateCommand } from "./commands/gate.command.js";
 import { policyLintCommand } from "./commands/policy-lint.command.js";
+import { wiringCommand } from "./commands/wiring.command.js";
 import { reuseCommand } from "./commands/reuse.command.js";
 import { migrateCommand } from "./commands/migrate.command.js";
 import { coverageCommand } from "./commands/coverage.command.js";
@@ -189,6 +191,7 @@ export function buildRegistry() {
     registry.register(explainCommand);
     registry.register(checkCommand);
     registry.register(diffCheckCommand);
+    registry.register(finishCommand);
     // changed-only preflight orchestrator.
     registry.register(preflightCommand);
     registry.register(driftCommand);
@@ -201,6 +204,7 @@ export function buildRegistry() {
     registry.register(apiDiffCommand);
     registry.register(gateCommand);
     registry.register(policyLintCommand);
+    registry.register(wiringCommand);
     registry.register(reuseCommand);
     registry.register(migrateCommand);
     registry.register(coverageCommand);