@shrkcrft/inspector 0.1.0-alpha.2

package/dist/adoption-state.js

@@ -0,0 +1,296 @@
+/**
+ * sharkcraft.adoption-state/v1
+ *
+ * Persistent state for the onboarding adoption workflow. Written under
+ * `sharkcraft/onboarding/adoption/adoption-state.json` whenever a patch is
+ * generated. Captures source draft + target file hashes so freshness can be
+ * computed deterministically without re-running inference.
+ *
+ * Writes are confined to `sharkcraft/onboarding/adoption/` — never live config.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import * as nodePath from 'node:path';
+import { AdoptionCategory } from "./onboarding-adoption.js";
+export const ADOPTION_STATE_SCHEMA = 'sharkcraft.adoption-state/v1';
+export var AdoptionFreshnessStatus;
+(function (AdoptionFreshnessStatus) {
+    AdoptionFreshnessStatus["Fresh"] = "fresh";
+    AdoptionFreshnessStatus["Stale"] = "stale";
+    AdoptionFreshnessStatus["Unknown"] = "unknown";
+})(AdoptionFreshnessStatus || (AdoptionFreshnessStatus = {}));
+const ADOPTION_DIR_RELATIVE = nodePath.join('sharkcraft', 'onboarding', 'adoption');
+const ADOPTION_DRAFT_DIR_RELATIVE = nodePath.join('sharkcraft', 'onboarding');
+const STATE_FILENAME = 'adoption-state.json';
+export function adoptionDir(projectRoot) {
+    return nodePath.resolve(projectRoot, ADOPTION_DIR_RELATIVE);
+}
+export function adoptionStatePath(projectRoot) {
+    return nodePath.join(adoptionDir(projectRoot), STATE_FILENAME);
+}
+export function adoptionHistoryDir(projectRoot) {
+    return nodePath.join(adoptionDir(projectRoot), 'history');
+}
+function readSafe(absolute) {
+    try {
+        return readFileSync(absolute, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function sha256(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+export function hashFile(absolute) {
+    const body = readSafe(absolute);
+    if (body === null)
+        return null;
+    return sha256(body);
+}
+function buildCategoryIds(plan) {
+    const out = {
+        [AdoptionCategory.SafeToAdopt]: [],
+        [AdoptionCategory.ManualReview]: [],
+        [AdoptionCategory.LowConfidence]: [],
+        [AdoptionCategory.Conflict]: [],
+        [AdoptionCategory.AlreadyCovered]: [],
+        [AdoptionCategory.Skipped]: [],
+    };
+    for (const it of plan.items) {
+        out[it.category].push(`${it.kind}:${it.id}`);
+    }
+    return {
+        [AdoptionCategory.SafeToAdopt]: out[AdoptionCategory.SafeToAdopt],
+        [AdoptionCategory.ManualReview]: out[AdoptionCategory.ManualReview],
+        [AdoptionCategory.LowConfidence]: out[AdoptionCategory.LowConfidence],
+        [AdoptionCategory.Conflict]: out[AdoptionCategory.Conflict],
+        [AdoptionCategory.AlreadyCovered]: out[AdoptionCategory.AlreadyCovered],
+        [AdoptionCategory.Skipped]: out[AdoptionCategory.Skipped],
+    };
+}
+/** Collect every draft file under sharkcraft/onboarding/ that the adoption
+ *  plan derived items from. We always include the directory listing for
+ *  robustness — a draft can affect the plan without being explicitly named. */
+function collectDraftFileHashes(projectRoot) {
+    const dir = nodePath.resolve(projectRoot, ADOPTION_DRAFT_DIR_RELATIVE);
+    if (!existsSync(dir))
+        return [];
+    const files = [];
+    const visit = (d) => {
+        let entries;
+        try {
+            entries = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e === 'adoption')
+                continue; // never include adoption outputs as drafts
+            const full = nodePath.join(d, e);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                visit(full);
+            }
+            else if (st.isFile() && /\.(draft\.ts|draft\.md|md|ts)$/.test(e)) {
+                const body = readSafe(full);
+                if (body !== null) {
+                    files.push({
+                        relativePath: nodePath.relative(projectRoot, full).split(nodePath.sep).join('/'),
+                        hash: sha256(body),
+                    });
+                }
+            }
+        }
+    };
+    visit(dir);
+    return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+function collectTargetHashes(projectRoot, targets) {
+    const out = [];
+    for (const t of targets) {
+        if (t.beforeHash) {
+            out.push({ relativePath: t.relativePath, hash: t.beforeHash });
+            continue;
+        }
+        const full = nodePath.resolve(projectRoot, t.relativePath);
+        const h = hashFile(full);
+        out.push({ relativePath: t.relativePath, hash: h ?? '(missing)' });
+    }
+    return out;
+}
+export function buildAdoptionState(input) {
+    const now = new Date().toISOString();
+    const state = {
+        schema: ADOPTION_STATE_SCHEMA,
+        projectRoot: input.projectRoot,
+        createdAt: input.previousCreatedAt ?? now,
+        updatedAt: now,
+        sharkcraftVersion: input.sharkcraftVersion ?? '0.1.0-alpha.2',
+        command: input.command,
+        sourceDraftFiles: collectDraftFileHashes(input.projectRoot),
+        targetFiles: collectTargetHashes(input.projectRoot, input.targets),
+        generatedFiles: input.generatedFiles,
+        patchPath: input.patchPath,
+        summaryPath: input.summaryPath,
+        ...(input.reportPath ? { reportPath: input.reportPath } : {}),
+        diffFormat: input.diffFormat,
+        confidenceThreshold: input.plan.confidence,
+        includedKinds: input.plan.included,
+        excludedKinds: input.plan.excluded,
+        categories: buildCategoryIds(input.plan),
+        freshness: { status: AdoptionFreshnessStatus.Fresh, staleReasons: [] },
+        warnings: input.warnings ?? [],
+        nextCommands: input.nextCommands ??
+            [
+                'shrk onboard adopt status',
+                'shrk onboard adopt review',
+                'git apply sharkcraft/onboarding/adoption/adopt.patch',
+            ],
+    };
+    return state;
+}
+export function writeAdoptionState(projectRoot, state) {
+    const target = adoptionStatePath(projectRoot);
+    const dir = nodePath.dirname(target);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    if (!target.startsWith(adoptionDir(projectRoot))) {
+        throw new Error(`adoption state path escapes adoption dir: ${target}`);
+    }
+    writeFileSync(target, JSON.stringify(state, null, 2) + '\n', 'utf8');
+    return target;
+}
+export function readAdoptionState(projectRoot) {
+    const target = adoptionStatePath(projectRoot);
+    const body = readSafe(target);
+    if (body === null)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed.schema !== ADOPTION_STATE_SCHEMA)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Recompute freshness from disk. Compares stored hashes against current file
+ * content. A patch is stale when any target or draft file changed since the
+ * state was written (or when state files are missing).
+ */
+export function computeAdoptionFreshness(projectRoot, state) {
+    if (!state) {
+        return {
+            status: AdoptionFreshnessStatus.Unknown,
+            staleReasons: ['no adoption state on disk'],
+            changedTargets: [],
+            changedDrafts: [],
+            missingTargets: [],
+            missingDrafts: [],
+        };
+    }
+    const reasons = [];
+    const changedTargets = [];
+    const changedDrafts = [];
+    const missingTargets = [];
+    const missingDrafts = [];
+    for (const t of state.targetFiles) {
+        const full = nodePath.resolve(projectRoot, t.relativePath);
+        if (!existsSync(full)) {
+            // The "(missing)" placeholder means "the target didn't exist when we
+            // wrote the patch" — that's a create-file hunk. If it still doesn't
+            // exist, that's fresh. If it now exists, that's a stale-target change.
+            if (t.hash === '(missing)')
+                continue;
+            missingTargets.push(t.relativePath);
+            reasons.push(`target file vanished: ${t.relativePath}`);
+            continue;
+        }
+        const current = hashFile(full);
+        if (t.hash === '(missing)') {
+            // Target was created since plan-time.
+            changedTargets.push(t);
+            reasons.push(`target file created after patch: ${t.relativePath}`);
+            continue;
+        }
+        if (current && current !== t.hash) {
+            changedTargets.push(t);
+            reasons.push(`target file changed: ${t.relativePath}`);
+        }
+    }
+    // Drafts: compare against the directory now. Any added/removed/edited file
+    // is a stale signal.
+    const currentDrafts = collectDraftFileHashes(projectRoot);
+    const currentByPath = new Map(currentDrafts.map((f) => [f.relativePath, f.hash]));
+    const previousByPath = new Map(state.sourceDraftFiles.map((f) => [f.relativePath, f.hash]));
+    for (const [path, hash] of previousByPath) {
+        if (!currentByPath.has(path)) {
+            missingDrafts.push(path);
+            reasons.push(`draft file removed: ${path}`);
+            continue;
+        }
+        if (currentByPath.get(path) !== hash) {
+            changedDrafts.push({ relativePath: path, hash });
+            reasons.push(`draft file changed: ${path}`);
+        }
+    }
+    for (const [path, hash] of currentByPath) {
+        if (!previousByPath.has(path)) {
+            changedDrafts.push({ relativePath: path, hash });
+            reasons.push(`new draft file appeared: ${path}`);
+        }
+    }
+    const status = reasons.length === 0 ? AdoptionFreshnessStatus.Fresh : AdoptionFreshnessStatus.Stale;
+    return {
+        status,
+        staleReasons: reasons,
+        changedTargets,
+        changedDrafts,
+        missingTargets,
+        missingDrafts,
+    };
+}
+export function archivePreviousAdoptionOutputs(projectRoot, timestamp = new Date().toISOString().replace(/[:.]/g, '-')) {
+    const dir = adoptionDir(projectRoot);
+    if (!existsSync(dir))
+        return { archived: [], historyDir: adoptionHistoryDir(projectRoot) };
+    const history = adoptionHistoryDir(projectRoot);
+    if (!existsSync(history))
+        mkdirSync(history, { recursive: true });
+    const archived = [];
+    for (const name of ['adoption-state.json', 'adopt.patch', 'adoption-plan.md', 'adopt-summary.json']) {
+        const src = nodePath.join(dir, name);
+        if (!existsSync(src))
+            continue;
+        const dest = nodePath.join(history, `${timestamp}-${name}`);
+        if (existsSync(dest)) {
+            // Never overwrite history.
+            continue;
+        }
+        renameSync(src, dest);
+        archived.push(dest);
+    }
+    return { archived, historyDir: history };
+}
+export function updateAdoptionStateAfterRegenerate(input) {
+    const previous = readAdoptionState(input.projectRoot);
+    const archived = input.archivePrevious
+        ? archivePreviousAdoptionOutputs(input.projectRoot)
+        : null;
+    const state = buildAdoptionState({
+        ...input,
+        ...(previous ? { previousCreatedAt: previous.createdAt } : {}),
+    });
+    const statePath = writeAdoptionState(input.projectRoot, state);
+    return { state, archived, statePath };
+}

package/dist/adoption-three-way.d.ts

@@ -0,0 +1,46 @@
+import type { IAdoptionStateFile } from './adoption-state.js';
+export declare enum ThreeWayVerdict {
+    Safe = "safe",
+    ProbablySafe = "probably-safe",
+    StaleTarget = "stale-target",
+    StaleDraft = "stale-draft",
+    ManualReview = "manual-review",
+    CreateFileSafe = "create-file-safe",
+    Conflict = "conflict"
+}
+export interface IThreeWayPreviewInput {
+    /** Project root. Used to read the current file content. */
+    projectRoot: string;
+    /** Target relative to projectRoot. */
+    relativePath: string;
+    /** The base hash recorded in adoption-state (the hash captured when the
+     *  patch was rendered). For create-file hunks this is "(missing)". */
+    baseHash: string;
+    /** Optional append-block body. When provided, we can check whether the
+     *  append-block contents already exist in the file (the patch would be a
+     *  no-op) or whether they conflict with existing content. */
+    appendBlock?: string;
+    /** If the draft for this target changed since the state was written, the
+     *  patch is also stale. Caller computes this from the draft-file diff. */
+    draftChangedSinceState?: boolean;
+}
+export interface IThreeWayPreviewResult {
+    relativePath: string;
+    verdict: ThreeWayVerdict;
+    reasons: readonly string[];
+    /** Whether the file is currently present on disk. */
+    targetExists: boolean;
+    /** Whether the current file hash equals the recorded base hash. */
+    targetUnchanged: boolean;
+    /** When appendBlock is provided: whether the file already contains it. */
+    alreadyApplied: boolean;
+}
+export declare function previewThreeWay(input: IThreeWayPreviewInput): IThreeWayPreviewResult;
+export interface IThreeWayPreviewBatchResult {
+    perTarget: readonly IThreeWayPreviewResult[];
+    summary: Record<ThreeWayVerdict, number>;
+}
+export declare function previewThreeWayBatch(projectRoot: string, targets: readonly IAdoptionStateFile[], options?: {
+    draftsChanged?: boolean;
+}): IThreeWayPreviewBatchResult;
+//# sourceMappingURL=adoption-three-way.d.ts.map

package/dist/adoption-three-way.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adoption-three-way.d.ts","sourceRoot":"","sources":["../src/adoption-three-way.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,oBAAY,eAAe;IACzB,IAAI,SAAS;IACb,YAAY,kBAAkB;IAC9B,WAAW,iBAAiB;IAC5B,UAAU,gBAAgB;IAC1B,YAAY,kBAAkB;IAC9B,cAAc,qBAAqB;IACnC,QAAQ,aAAa;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB;0EACsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB;;iEAE6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;8EAC0E;IAC1E,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,qDAAqD;IACrD,YAAY,EAAE,OAAO,CAAC;IACtB,mEAAmE;IACnE,eAAe,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,cAAc,EAAE,OAAO,CAAC;CACzB;AA6BD,wBAAgB,eAAe,CAAC,KAAK,EAAE,qBAAqB,GAAG,sBAAsB,CAoHpF;AAED,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,SAAS,kBAAkB,EAAE,EACtC,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,2BAA2B,CAoB7B"}

package/dist/adoption-three-way.js

@@ -0,0 +1,181 @@
+/**
+ * Three-way merge preview for adoption patches.
+ *
+ * Inputs (the three "sides"):
+ *   - base: the file hash recorded in adoption-state.json
+ *   - current: the file content on disk right now
+ *   - proposed: the append block from the adoption patch
+ *
+ * Output: a verdict per target — safe | probably-safe | stale-target |
+ * stale-draft | manual-review | create-file-safe | conflict.
+ *
+ * This is read-only. It never writes or mutates the target.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export var ThreeWayVerdict;
+(function (ThreeWayVerdict) {
+    ThreeWayVerdict["Safe"] = "safe";
+    ThreeWayVerdict["ProbablySafe"] = "probably-safe";
+    ThreeWayVerdict["StaleTarget"] = "stale-target";
+    ThreeWayVerdict["StaleDraft"] = "stale-draft";
+    ThreeWayVerdict["ManualReview"] = "manual-review";
+    ThreeWayVerdict["CreateFileSafe"] = "create-file-safe";
+    ThreeWayVerdict["Conflict"] = "conflict";
+})(ThreeWayVerdict || (ThreeWayVerdict = {}));
+function sha256(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+/** Detect whether the file already ends with (a non-trivial chunk of) the
+ *  append block. Used to flag "patch already applied" rather than "conflict". */
+function endsWith(content, fragment) {
+    // The fragment may have leading/trailing whitespace that's not in the file.
+    // Compare on trimmed content vs trimmed fragment, and also check raw EOF.
+    if (fragment.length === 0)
+        return false;
+    if (content.endsWith(fragment))
+        return true;
+    const t = content.trimEnd();
+    const f = fragment.trimEnd();
+    return t.endsWith(f);
+}
+/** Whether the file already contains *every* line of the fragment (probably
+ *  applied in a different order or with reformatting). */
+function containsAllLines(content, fragment) {
+    const lines = fragment.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (lines.length === 0)
+        return false;
+    for (const l of lines) {
+        if (!content.includes(l))
+            return false;
+    }
+    return true;
+}
+export function previewThreeWay(input) {
+    const full = nodePath.resolve(input.projectRoot, input.relativePath);
+    const exists = existsSync(full);
+    const reasons = [];
+    // Case A: the patch was a "create file" — base hash is the sentinel.
+    if (input.baseHash === '(missing)') {
+        if (!exists) {
+            return {
+                relativePath: input.relativePath,
+                verdict: ThreeWayVerdict.CreateFileSafe,
+                reasons: ['target file does not exist; create-file hunk is safe'],
+                targetExists: false,
+                targetUnchanged: true,
+                alreadyApplied: false,
+            };
+        }
+        // The file now exists where it didn't at plan-time. That's a stale-target.
+        return {
+            relativePath: input.relativePath,
+            verdict: ThreeWayVerdict.StaleTarget,
+            reasons: ['target file was created after the patch was generated'],
+            targetExists: true,
+            targetUnchanged: false,
+            alreadyApplied: false,
+        };
+    }
+    if (!exists) {
+        return {
+            relativePath: input.relativePath,
+            verdict: ThreeWayVerdict.StaleTarget,
+            reasons: ['target file was deleted after the patch was generated'],
+            targetExists: false,
+            targetUnchanged: false,
+            alreadyApplied: false,
+        };
+    }
+    const body = readFileSync(full, 'utf8');
+    const currentHash = sha256(body);
+    const targetUnchanged = currentHash === input.baseHash;
+    let alreadyApplied = false;
+    if (input.appendBlock) {
+        alreadyApplied = endsWith(body, input.appendBlock) || containsAllLines(body, input.appendBlock);
+    }
+    if (alreadyApplied) {
+        reasons.push('the append block already appears in the target — patch is a no-op');
+    }
+    if (input.draftChangedSinceState) {
+        reasons.push('source draft changed after the patch was generated');
+    }
+    // Case B: target hash unchanged → safe.
+    if (targetUnchanged) {
+        if (input.draftChangedSinceState) {
+            return {
+                relativePath: input.relativePath,
+                verdict: ThreeWayVerdict.StaleDraft,
+                reasons,
+                targetExists: true,
+                targetUnchanged: true,
+                alreadyApplied,
+            };
+        }
+        return {
+            relativePath: input.relativePath,
+            verdict: alreadyApplied ? ThreeWayVerdict.ManualReview : ThreeWayVerdict.Safe,
+            reasons: reasons.length === 0
+                ? ['target file unchanged since the patch was generated']
+                : reasons,
+            targetExists: true,
+            targetUnchanged: true,
+            alreadyApplied,
+        };
+    }
+    // Case C: target changed. If the append block is present, the patch was
+    // already applied — manual review (or no-op).
+    if (alreadyApplied) {
+        return {
+            relativePath: input.relativePath,
+            verdict: ThreeWayVerdict.ManualReview,
+            reasons: ['target changed since the patch was generated, but the append block is present'],
+            targetExists: true,
+            targetUnchanged: false,
+            alreadyApplied: true,
+        };
+    }
+    // Case D: target changed but the file still ends with content (i.e. the
+    // file wasn't truncated to empty). For an append-only patch with a small
+    // context window, git apply may still work — call it "probably-safe".
+    if (body.trimEnd().length > 0) {
+        return {
+            relativePath: input.relativePath,
+            verdict: ThreeWayVerdict.ProbablySafe,
+            reasons: ['target changed since the patch was generated; review before applying'],
+            targetExists: true,
+            targetUnchanged: false,
+            alreadyApplied: false,
+        };
+    }
+    // Case E: target became empty or unrecognisable.
+    return {
+        relativePath: input.relativePath,
+        verdict: ThreeWayVerdict.ManualReview,
+        reasons: ['target file is empty or unrecognisable — re-render patch'],
+        targetExists: true,
+        targetUnchanged: false,
+        alreadyApplied: false,
+    };
+}
+export function previewThreeWayBatch(projectRoot, targets, options = {}) {
+    const perTarget = targets.map((t) => previewThreeWay({
+        projectRoot,
+        relativePath: t.relativePath,
+        baseHash: t.hash,
+        ...(options.draftsChanged ? { draftChangedSinceState: true } : {}),
+    }));
+    const summary = {
+        [ThreeWayVerdict.Safe]: 0,
+        [ThreeWayVerdict.ProbablySafe]: 0,
+        [ThreeWayVerdict.StaleTarget]: 0,
+        [ThreeWayVerdict.StaleDraft]: 0,
+        [ThreeWayVerdict.ManualReview]: 0,
+        [ThreeWayVerdict.CreateFileSafe]: 0,
+        [ThreeWayVerdict.Conflict]: 0,
+    };
+    for (const r of perTarget)
+        summary[r.verdict] += 1;
+    return { perTarget, summary };
+}

package/dist/agent-brief.d.ts

@@ -0,0 +1,77 @@
+import { type IImpactAnalysis } from './impact-analysis.js';
+import { type ITaskRiskReport } from './task-risk.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const AGENT_BRIEF_SCHEMA = "sharkcraft.agent-brief/v1";
+export declare enum BriefMode {
+    Compact = "compact",
+    Full = "full",
+    Review = "review",
+    Implementation = "implementation",
+    Handoff = "handoff"
+}
+export interface IAgentBriefInput {
+    task?: string;
+    mode?: BriefMode;
+    files?: readonly string[];
+    since?: string;
+    staged?: boolean;
+    bundleId?: string;
+    sessionId?: string;
+    /** Optional path to a quality baseline JSON, for comparison. */
+    qualityBaselineFile?: string;
+    /** Cap on token-equivalent budget for the body. Default: 6000. */
+    maxTokens?: number;
+    /** When true, also produce chunked output via `chunks`. */
+    chunked?: boolean;
+    /**
+     * Per-section budget (token-equivalent). Keys match section ids; values are
+     * max tokens. Unknown keys are ignored.
+     */
+    sectionBudgets?: Record<string, number>;
+}
+export interface IAgentBriefSection {
+    id: string;
+    title: string;
+    body: string;
+}
+export interface IAgentBriefChunk {
+    /** Filename for the chunk (e.g. `01-task.md`). */
+    file: string;
+    /** Section id (matches IAgentBriefSection.id, or "index"). */
+    sectionId: string;
+    title: string;
+    body: string;
+    /** Token-equivalent estimate (chars/4). */
+    tokenEstimate: number;
+}
+export interface IAgentBrief {
+    schema: typeof AGENT_BRIEF_SCHEMA;
+    task: string;
+    mode: BriefMode;
+    generatedAt: string;
+    projectRoot: string;
+    sections: readonly IAgentBriefSection[];
+    /** Markdown serialization of the brief. */
+    markdown: string;
+    /** Top suggested next commands. */
+    suggestedCommands: readonly string[];
+    /** Optional impact summary if files/bundle/since produced one. */
+    impact?: IImpactAnalysis;
+    /** Per-task risk report when a task is provided. */
+    taskRisk?: ITaskRiskReport;
+    /** Source flags used to compute the brief. */
+    inputs: {
+        files: readonly string[];
+        since: string | null;
+        staged: boolean;
+        bundleId: string | null;
+        sessionId: string | null;
+    };
+    warnings: readonly string[];
+    /** Token-equivalent estimate (chars/4) for the full markdown body. */
+    totalTokenEstimate: number;
+    /** Chunked output when input.chunked is true. */
+    chunks?: readonly IAgentBriefChunk[];
+}
+export declare function buildAgentBrief(inspection: ISharkcraftInspection, input: IAgentBriefInput): Promise<IAgentBrief>;
+//# sourceMappingURL=agent-brief.d.ts.map

package/dist/agent-brief.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-brief.d.ts","sourceRoot":"","sources":["../src/agent-brief.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAS3E,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,oBAAY,SAAS;IACnB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,cAAc,mBAAmB;IACjC,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACxC,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kEAAkE;IAClE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,EAAE;QACN,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,CAAC;IACF,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,sEAAsE;IACtE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,MAAM,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACtC;AAmVD,wBAAsB,eAAe,CACnC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,WAAW,CAAC,CAqItB"}