@shrkcrft/inspector 0.1.0-alpha.2

package/dist/policy-test.d.ts

@@ -0,0 +1,83 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import { PolicySeverity, type IPolicyCheck, type IPolicyCheckRegistration } from './policy-engine.js';
+export declare const POLICY_TEST_SCHEMA = "sharkcraft.policy-test/v1";
+export declare const POLICY_SNAPSHOT_SCHEMA = "sharkcraft.policy-snapshot/v1";
+export interface IPolicyTestExpectation {
+    /** When provided, fail unless the test result.passed matches. */
+    passed?: boolean;
+    /** Substring that must appear in any emitted check.message. */
+    messageContains?: string;
+    /** Minimum severity that must appear. */
+    minSeverity?: PolicySeverity;
+}
+export interface IPolicyTestInput {
+    policyId?: string;
+    /** Optional pre-built input object — overrides the loader. */
+    policyInput?: {
+        projectRoot?: string;
+        planTargets?: readonly string[];
+        bundleAffectedFiles?: readonly string[];
+    };
+    fixtureDir?: string;
+    expected?: IPolicyTestExpectation;
+}
+export interface IPolicyTestResult {
+    policyId: string;
+    passed: boolean;
+    inputSource: string;
+    evidence: readonly string[];
+    checks: readonly IPolicyCheck[];
+    registration: IPolicyCheckRegistration | null;
+    expectation?: IPolicyTestExpectation;
+    expectationOutcome?: {
+        matched: boolean;
+        mismatches: readonly string[];
+    };
+}
+export interface IPolicyTestBatch {
+    schema: typeof POLICY_TEST_SCHEMA;
+    results: readonly IPolicyTestResult[];
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+    };
+}
+export declare function runPolicyTest(inspection: ISharkcraftInspection, input: IPolicyTestInput): Promise<IPolicyTestResult>;
+export interface IPolicySnapshot {
+    schema: typeof POLICY_SNAPSHOT_SCHEMA;
+    policyId: string;
+    inputHash: string;
+    capturedAt: string;
+    passed: boolean;
+    severityHighest: PolicySeverity | null;
+    /** First message of the first emitted check. */
+    message: string | null;
+    /** Concise evidence summary. */
+    evidence: readonly string[];
+}
+export interface IPolicySnapshotInput {
+    /** Where the snapshot file lives. */
+    snapshotFile: string;
+    /** When true, write a new snapshot regardless of current state. */
+    updateSnapshot?: boolean;
+}
+export interface IPolicySnapshotOutcome {
+    schema: typeof POLICY_SNAPSHOT_SCHEMA;
+    policyId: string;
+    inputSource: string;
+    snapshotFile: string;
+    /** Current run result (re-uses the policy-test machinery). */
+    result: IPolicyTestResult;
+    snapshot: IPolicySnapshot;
+    /** When false, the current run differs from the saved snapshot. */
+    matchesSnapshot: boolean;
+    /** When updateSnapshot was set and a new snapshot was written. */
+    updated: boolean;
+    diffs: readonly string[];
+}
+export declare function runPolicySnapshot(inspection: ISharkcraftInspection, testInput: IPolicyTestInput, snapshot: IPolicySnapshotInput): Promise<IPolicySnapshotOutcome>;
+export declare function runPolicyTestsForAll(inspection: ISharkcraftInspection, options?: {
+    fixtureDir?: string;
+}): Promise<IPolicyTestBatch>;
+//# sourceMappingURL=policy-test.d.ts.map

package/dist/policy-test.d.ts.map

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

package/dist/policy-test.js

@@ -0,0 +1,342 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { evaluatePolicy, PolicySeverity, } from "./policy-engine.js";
+export const POLICY_TEST_SCHEMA = 'sharkcraft.policy-test/v1';
+export const POLICY_SNAPSHOT_SCHEMA = 'sharkcraft.policy-snapshot/v1';
+function readJsonOptional(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function readFixtureInput(fixtureDir) {
+    const inputFile = nodePath.join(fixtureDir, 'policy-input.json');
+    const expectedFile = nodePath.join(fixtureDir, 'expected.json');
+    const expected = readJsonOptional(expectedFile) ?? undefined;
+    const direct = readJsonOptional(inputFile);
+    if (direct) {
+        return {
+            source: nodePath.relative(fixtureDir, inputFile) || 'policy-input.json',
+            input: direct,
+            ...(expected ? { expected } : {}),
+        };
+    }
+    // Synthesize input from planTargets.json + bundleAffectedFiles.json.
+    const planTargets = readJsonOptional(nodePath.join(fixtureDir, 'planTargets.json'));
+    const bundleAffectedFiles = readJsonOptional(nodePath.join(fixtureDir, 'bundleAffectedFiles.json'));
+    const input = {
+        projectRoot: fixtureDir,
+        planTargets: planTargets ?? [],
+        bundleAffectedFiles: bundleAffectedFiles ?? [],
+    };
+    return {
+        source: 'planTargets+bundleAffectedFiles',
+        input,
+        ...(expected ? { expected } : {}),
+    };
+}
+async function loadLocalPolicyChecks(inspection, localFiles) {
+    const out = [];
+    const sharkcraftDir = inspection.sharkcraftDir;
+    const localCandidates = localFiles ?? [
+        sharkcraftDir ? nodePath.join(sharkcraftDir, 'policies.ts') : null,
+        sharkcraftDir ? nodePath.join(sharkcraftDir, 'policies.js') : null,
+    ].filter((x) => Boolean(x));
+    for (const file of localCandidates) {
+        if (!existsSync(file))
+            continue;
+        try {
+            const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+            const decls = mod.default ?? mod.policyChecks ?? [];
+            for (const d of decls)
+                out.push({ check: d, sourceFile: file, isLocal: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // Pack-contributed policies — read directly so we can test individual ids.
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const contributions = (pack.manifest?.contributions ?? {});
+        for (const rel of contributions.policyCheckFiles ?? []) {
+            const file = nodePath.resolve(pack.packageRoot, rel);
+            if (!existsSync(file))
+                continue;
+            try {
+                const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+                const decls = mod.default ?? mod.policyChecks ?? [];
+                for (const d of decls)
+                    out.push({ check: d, sourceFile: file, isLocal: false });
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    return { decls: out };
+}
+function severityRank(s) {
+    switch (s) {
+        case PolicySeverity.Critical:
+            return 4;
+        case PolicySeverity.Error:
+            return 3;
+        case PolicySeverity.Warning:
+            return 2;
+        case PolicySeverity.Info:
+            return 1;
+    }
+    return 0;
+}
+function evaluateExpectation(result, expected) {
+    if (!expected)
+        return undefined;
+    const mismatches = [];
+    if (typeof expected.passed === 'boolean' && expected.passed !== result.passed) {
+        mismatches.push(`expected passed=${expected.passed}, got passed=${result.passed}`);
+    }
+    if (expected.messageContains) {
+        const found = result.checks.some((c) => c.message.includes(expected.messageContains));
+        if (!found)
+            mismatches.push(`no check message contained "${expected.messageContains}"`);
+    }
+    if (expected.minSeverity) {
+        const max = result.checks.reduce((acc, c) => Math.max(acc, severityRank(c.severity)), 0);
+        if (max < severityRank(expected.minSeverity)) {
+            mismatches.push(`min severity ${expected.minSeverity} not reached`);
+        }
+    }
+    return { matched: mismatches.length === 0, mismatches };
+}
+export async function runPolicyTest(inspection, input) {
+    let source = 'live';
+    let evidence = [];
+    let expected = input.expected;
+    // Resolve fixture if requested.
+    let policyInput = input.policyInput;
+    if (input.fixtureDir && existsSync(input.fixtureDir)) {
+        const fx = readFixtureInput(input.fixtureDir);
+        policyInput = policyInput ?? fx.input;
+        source = `fixture:${nodePath.basename(input.fixtureDir)}`;
+        if (!expected && fx.expected)
+            expected = fx.expected;
+        evidence.push(`fixture: ${fx.source}`);
+    }
+    // If no specific id is provided, we run the live engine and surface
+    // everything.
+    const id = input.policyId;
+    const policyEvalInput = {};
+    if (id)
+        policyEvalInput.onlyId = id;
+    const report = await evaluatePolicy(inspection, policyEvalInput);
+    // Filter checks/registrations to the requested id when provided.
+    const checks = id
+        ? report.checks.filter((c) => c.id === id || c.id.startsWith(id + ':'))
+        : report.checks;
+    const registration = id
+        ? report.registrations.find((r) => r.id === id || r.id === `local:${id}` || r.id === `pack:${id}`) ?? null
+        : null;
+    // Optionally override with a synthetic evaluation when an explicit policyInput was passed.
+    let extraChecks = [];
+    if (policyInput && id) {
+        const { decls } = await loadLocalPolicyChecks(inspection);
+        const match = decls.find((d) => d.check.id === id);
+        if (match) {
+            try {
+                const evalResult = match.check.evaluate({
+                    projectRoot: policyInput.projectRoot ?? inspection.projectRoot,
+                    planTargets: policyInput.planTargets ?? [],
+                    bundleAffectedFiles: policyInput.bundleAffectedFiles ?? [],
+                });
+                if (evalResult !== true) {
+                    const detail = typeof evalResult === 'object'
+                        ? evalResult
+                        : { message: 'Policy check failed (synthetic fixture)' };
+                    extraChecks.push({
+                        id: match.check.id,
+                        title: match.check.title,
+                        severity: match.check.severity ?? PolicySeverity.Warning,
+                        checkType: match.check.checkType ?? 'path',
+                        message: detail.message,
+                        ...(detail.suggestedFix ? { suggestedFix: detail.suggestedFix } : {}),
+                        ...(detail.context ? { context: detail.context } : {}),
+                    });
+                }
+                evidence.push(`evaluated ${match.check.id} against fixture input`);
+            }
+            catch (e) {
+                extraChecks.push({
+                    id: `${match.check.id}:error`,
+                    title: match.check.title,
+                    severity: PolicySeverity.Warning,
+                    checkType: match.check.checkType ?? 'path',
+                    message: `Policy check threw: ${e.message}`,
+                });
+            }
+        }
+    }
+    const allChecks = [...checks, ...extraChecks];
+    const passed = allChecks.length === 0;
+    const result = {
+        policyId: id ?? '<all>',
+        passed,
+        inputSource: source,
+        evidence,
+        checks: allChecks,
+        registration,
+    };
+    const outcome = evaluateExpectation(result, expected);
+    return {
+        ...result,
+        ...(expected ? { expectation: expected } : {}),
+        ...(outcome ? { expectationOutcome: outcome } : {}),
+    };
+}
+function hashInput(input) {
+    const canon = JSON.stringify({
+        projectRoot: input.projectRoot ?? '',
+        planTargets: [...(input.planTargets ?? [])].sort(),
+        bundleAffectedFiles: [...(input.bundleAffectedFiles ?? [])].sort(),
+    });
+    return createHash('sha256').update(canon).digest('hex').slice(0, 16);
+}
+function summarizeChecks(checks) {
+    if (checks.length === 0)
+        return { severityHighest: null, message: null, evidence: [] };
+    let max = PolicySeverity.Info;
+    for (const c of checks) {
+        if (severityRank(c.severity) > severityRank(max))
+            max = c.severity;
+    }
+    return {
+        severityHighest: max,
+        message: checks[0].message,
+        evidence: checks.slice(0, 5).map((c) => `[${c.severity}] ${c.id}`),
+    };
+}
+function snapshotsEqual(a, b) {
+    const diffs = [];
+    if (a.passed !== b.passed)
+        diffs.push(`passed: ${a.passed} → ${b.passed}`);
+    if (a.severityHighest !== b.severityHighest)
+        diffs.push(`severityHighest: ${a.severityHighest ?? 'null'} → ${b.severityHighest ?? 'null'}`);
+    if ((a.message ?? '') !== (b.message ?? ''))
+        diffs.push(`message: "${a.message ?? ''}" → "${b.message ?? ''}"`);
+    if (JSON.stringify(a.evidence) !== JSON.stringify(b.evidence))
+        diffs.push('evidence: changed');
+    if (a.inputHash !== b.inputHash)
+        diffs.push(`inputHash: ${a.inputHash} → ${b.inputHash}`);
+    return diffs;
+}
+export async function runPolicySnapshot(inspection, testInput, snapshot) {
+    const result = await runPolicyTest(inspection, testInput);
+    const policyInput = testInput.policyInput ?? {
+        projectRoot: inspection.projectRoot,
+        planTargets: [],
+        bundleAffectedFiles: [],
+    };
+    const summary = summarizeChecks(result.checks);
+    const next = {
+        schema: POLICY_SNAPSHOT_SCHEMA,
+        policyId: result.policyId,
+        inputHash: hashInput(policyInput),
+        capturedAt: new Date().toISOString(),
+        passed: result.passed,
+        severityHighest: summary.severityHighest,
+        message: summary.message,
+        evidence: summary.evidence,
+    };
+    let saved = null;
+    if (existsSync(snapshot.snapshotFile)) {
+        try {
+            saved = JSON.parse(readFileSync(snapshot.snapshotFile, 'utf8'));
+        }
+        catch {
+            saved = null;
+        }
+    }
+    let matchesSnapshot = true;
+    let diffs = [];
+    if (saved) {
+        diffs = snapshotsEqual(saved, next);
+        matchesSnapshot = diffs.length === 0;
+    }
+    else {
+        matchesSnapshot = false;
+        diffs = ['no snapshot found'];
+    }
+    let updated = false;
+    if (snapshot.updateSnapshot || !saved) {
+        // Snapshot writes always live under fixture dir / caller-specified location;
+        // never under project source. Create parent dirs but only mkdir, never resolve outside.
+        mkdirSync(nodePath.dirname(snapshot.snapshotFile), { recursive: true });
+        writeFileSync(snapshot.snapshotFile, JSON.stringify(next, null, 2) + '\n', 'utf8');
+        updated = true;
+        if (snapshot.updateSnapshot)
+            matchesSnapshot = true;
+    }
+    return {
+        schema: POLICY_SNAPSHOT_SCHEMA,
+        policyId: result.policyId,
+        inputSource: result.inputSource,
+        snapshotFile: snapshot.snapshotFile,
+        result,
+        snapshot: next,
+        matchesSnapshot,
+        updated,
+        diffs,
+    };
+}
+export async function runPolicyTestsForAll(inspection, options = {}) {
+    const dir = options.fixtureDir;
+    const results = [];
+    if (!dir) {
+        // Run every registered policy with no fixture.
+        const report = await evaluatePolicy(inspection);
+        for (const reg of report.registrations) {
+            const checks = report.checks.filter((c) => c.id === reg.id || c.id.startsWith(reg.id + ':'));
+            results.push({
+                policyId: reg.id,
+                passed: checks.length === 0,
+                inputSource: 'live',
+                evidence: [],
+                checks,
+                registration: reg,
+            });
+        }
+    }
+    else {
+        // Iterate over <dir>/<policyId>/ subfolders.
+        const subdirs = existsSync(dir)
+            ? readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory())
+            : [];
+        for (const sub of subdirs) {
+            const fixturePath = nodePath.join(dir, sub.name);
+            results.push(await runPolicyTest(inspection, { policyId: sub.name, fixtureDir: fixturePath }));
+        }
+    }
+    const passed = results.filter((r) => r.passed).length;
+    return {
+        schema: POLICY_TEST_SCHEMA,
+        results,
+        summary: {
+            total: results.length,
+            passed,
+            failed: results.length - passed,
+        },
+    };
+}

package/dist/pr-summary.d.ts

@@ -0,0 +1,34 @@
+import { type IUncertaintyReport } from './uncertainty-report.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const PR_SUMMARY_SCHEMA = "sharkcraft.pr-summary/v1";
+export interface IPrSummarySection {
+    title: string;
+    body: string;
+}
+export interface IPrSummaryReport {
+    schema: typeof PR_SUMMARY_SCHEMA;
+    generatedAt: string;
+    sections: readonly IPrSummarySection[];
+    /** Final rendered Markdown body. */
+    markdown: string;
+    /** Uncertainty report (confidence + signals + safe fallback). */
+    uncertainty?: IUncertaintyReport;
+}
+export interface IPrSummaryOptions {
+    /** Diff input — same shape as IChangesSummaryOptions. */
+    since?: string;
+    staged?: boolean;
+    files?: readonly string[];
+    /** Cap items per list. Default 12. */
+    maxItems?: number;
+    /** Include raw links to reports (kept off by default). */
+    includeRawLinks?: boolean;
+    /** Reports directory. Default `.sharkcraft/reports`. */
+    reportsDir?: string;
+    /** Build the summary from a dev session's applied-plan files. */
+    fromSession?: string;
+    /** Build the summary from a bundle's plan files. */
+    fromBundle?: string;
+}
+export declare function buildPrSummary(inspection: ISharkcraftInspection, options?: IPrSummaryOptions): Promise<IPrSummaryReport>;
+//# sourceMappingURL=pr-summary.d.ts.map

package/dist/pr-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-summary.d.ts","sourceRoot":"","sources":["../src/pr-summary.ts"],"names":[],"mappings":"AAWA,OAAO,EAA0B,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE1F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAwBD,wBAAsB,cAAc,CAClC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CA2K3B"}

package/dist/pr-summary.js

@@ -0,0 +1,220 @@
+/**
+ * PR summary / description generator.
+ *
+ * Builds a single PR-description blob from the changes summary + review
+ * packet + CI report (if present) + release-readiness + safety audit.
+ *
+ * Read-only; deterministic; no AI. Schema: sharkcraft.pr-summary/v1.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildChangesSummary } from "./changes-summary.js";
+import { buildUncertaintyReport } from "./uncertainty-report.js";
+import { readDevSessionState } from "./dev-session.js";
+export const PR_SUMMARY_SCHEMA = 'sharkcraft.pr-summary/v1';
+function loadJson(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function readMaybe(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function cap(arr, limit) {
+    return arr.slice(0, limit);
+}
+export async function buildPrSummary(inspection, options = {}) {
+    const maxItems = options.maxItems ?? 12;
+    const cwd = inspection.projectRoot;
+    const reportsDir = nodePath.isAbsolute(options.reportsDir ?? '.sharkcraft/reports')
+        ? (options.reportsDir ?? '.sharkcraft/reports')
+        : nodePath.join(cwd, options.reportsDir ?? '.sharkcraft/reports');
+    const changesOpts = {};
+    if (options.since)
+        changesOpts.since = options.since;
+    if (options.staged)
+        changesOpts.staged = true;
+    if (options.files && options.files.length > 0)
+        changesOpts.files = options.files;
+    // Derive `files` from a session or bundle if requested.
+    if (options.fromSession && !changesOpts.files) {
+        try {
+            const state = readDevSessionState(cwd, options.fromSession);
+            if (state) {
+                const sessionFiles = state.appliedPlans.flatMap((p) => p.changedFiles ?? []);
+                if (sessionFiles.length > 0)
+                    changesOpts.files = Array.from(new Set(sessionFiles));
+            }
+        }
+        catch {
+            // ignore — empty files leaves the standard `working-tree` mode.
+        }
+    }
+    if (options.fromBundle && !changesOpts.files) {
+        // Bundle resolution: read the bundle's plan-list JSON if present under
+        // `.sharkcraft/bundles/<id>/manifest.json`.
+        const bundleManifest = nodePath.join(cwd, '.sharkcraft', 'bundles', options.fromBundle, 'manifest.json');
+        if (existsSync(bundleManifest)) {
+            try {
+                const json = JSON.parse(readFileSync(bundleManifest, 'utf8'));
+                const bundleFiles = (json.plans ?? []).flatMap((p) => p.changedFiles ?? []);
+                if (bundleFiles.length > 0)
+                    changesOpts.files = Array.from(new Set(bundleFiles));
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    const changes = await buildChangesSummary(inspection, changesOpts);
+    const sections = [];
+    // Summary
+    sections.push({
+        title: 'Summary',
+        body: changes.likelyPrSummary,
+    });
+    // Why
+    sections.push({
+        title: 'Why',
+        body: 'Edit this section to describe the motivation. The PR generator surfaces what changed; the human writes why.',
+    });
+    // What changed
+    const whatChanged = [];
+    for (const [area, files] of Object.entries(changes.filesByArea)) {
+        whatChanged.push(`- **${area}** (${files.length}):`);
+        for (const f of cap(files, maxItems))
+            whatChanged.push(`  - \`${f}\``);
+        if (files.length > maxItems)
+            whatChanged.push(`  - … ${files.length - maxItems} more`);
+    }
+    sections.push({
+        title: 'What changed',
+        body: whatChanged.join('\n'),
+    });
+    // Safety
+    const safetyBody = [];
+    if (changes.touchedMcpTools.length > 0) {
+        safetyBody.push(`- MCP tool files touched (${changes.touchedMcpTools.length}). Read-only invariant must be re-verified.`);
+        for (const m of cap(changes.touchedMcpTools, maxItems))
+            safetyBody.push(`  - \`${m}\``);
+    }
+    if (changes.safetyRelevantFiles.length > 0) {
+        safetyBody.push(`- Safety-relevant files: ${changes.safetyRelevantFiles.length}`);
+        for (const m of cap(changes.safetyRelevantFiles, maxItems))
+            safetyBody.push(`  - \`${m}\``);
+    }
+    if (safetyBody.length === 0)
+        safetyBody.push('No safety-relevant files touched.');
+    sections.push({ title: 'Safety', body: safetyBody.join('\n') });
+    // Validation
+    sections.push({
+        title: 'Validation',
+        body: changes.suggestedValidationCommands.map((c) => `- \`${c}\``).join('\n'),
+    });
+    // Risk / review notes
+    const risk = [`Risk: **${changes.risk}**`];
+    for (const r of changes.riskReasons)
+        risk.push(`- ${r}`);
+    sections.push({ title: 'Risk / review notes', body: risk.join('\n') });
+    // Breaking changes
+    sections.push({
+        title: 'Breaking changes',
+        body: 'None known. Edit if this PR removes/renames public exports or changes write-path defaults.',
+    });
+    // Migration notes
+    sections.push({
+        title: 'Migration notes',
+        body: 'None. Edit if downstream consumers need an upgrade path.',
+    });
+    // Known limitations
+    sections.push({
+        title: 'Known limitations',
+        body: 'None. Edit if any TODO / partial implementation remains.',
+    });
+    // Follow-ups
+    sections.push({
+        title: 'Follow-ups',
+        body: 'Edit to list deferred items.',
+    });
+    // Commands run
+    sections.push({
+        title: 'Commands run',
+        body: changes.suggestedValidationCommands.map((c) => `- \`${c}\``).join('\n'),
+    });
+    // Reports / artifacts
+    const reports = collectReports(reportsDir);
+    const reportLines = [];
+    if (reports.length === 0)
+        reportLines.push('_(no reports under `.sharkcraft/reports/`)_');
+    for (const r of cap(reports, maxItems))
+        reportLines.push(`- \`${r}\``);
+    sections.push({ title: 'Reports / artifacts', body: reportLines.join('\n') });
+    const markdown = sections
+        .map((s) => `## ${s.title}\n\n${s.body}\n`)
+        .join('\n');
+    // Uncertainty.
+    let confidence = 'high';
+    const reasons = [];
+    const missing = [];
+    if (!changesOpts.files && !options.since && !options.staged) {
+        confidence = 'medium';
+        reasons.push('Diff scope was inferred from working tree — explicit --since or --files is more reliable.');
+        missing.push({
+            id: 'no-explicit-scope',
+            message: 'No --since / --from-session / --from-bundle scope provided.',
+        });
+    }
+    if ((options.fromSession || options.fromBundle) && !changesOpts.files) {
+        confidence = 'low';
+        reasons.push('Session/bundle scope was requested but no files were resolved.');
+        missing.push({
+            id: 'session-or-bundle-empty',
+            message: 'Session/bundle had no applied-plan files.',
+        });
+    }
+    const uncertainty = buildUncertaintyReport({
+        confidence,
+        reasons,
+        missingSignals: missing,
+        suggestedCommands: [
+            'shrk pr summary --since main',
+            'shrk pr summary --from-session <id>',
+        ],
+        safeFallbackCommand: 'shrk impact --since main',
+    });
+    return {
+        schema: PR_SUMMARY_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        sections,
+        markdown,
+        uncertainty,
+    };
+}
+function collectReports(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        const full = nodePath.join(dir, name);
+        try {
+            if (statSync(full).isFile())
+                out.push(nodePath.relative(process.cwd(), full));
+        }
+        catch {
+            // ignore
+        }
+    }
+    return out.sort();
+}