@shrkcrft/inspector 0.1.0-alpha.1

package/dist/agent-contract.js

@@ -0,0 +1,555 @@
+/**
+ * Agent contract.
+ *
+ * Given a task, role, and mode, compose a deterministic safety contract
+ * combining existing systems (intent, task risk, impact, ownership,
+ * boundaries, policies, playbooks, constructs, templates, role views).
+ *
+ * Read-only. No model calls, no telemetry, no embeddings.
+ */
+import { classifyChangeIntent, ChangeIntentKind, } from "./change-intent.js";
+import { buildTaskRiskReport, TaskRiskLevel, } from "./task-risk.js";
+import { analyzeImpact, ImpactInputKind } from "./impact-analysis.js";
+import { loadOwnershipRules, impactFor as ownershipImpactFor } from "./ownership.js";
+import { listPlaybooks, recommendPlaybooks } from "./playbook-registry.js";
+import { listConstructs, loadConstructs } from "./construct-registry.js";
+import { RoleId } from "./role-views.js";
+import { ContractFileRuleKind, ContractFileRuleSeverity, } from "./contract-file-rule.js";
+export const AGENT_CONTRACT_SCHEMA = 'sharkcraft.agent-contract/v1';
+export var AgentContractMode;
+(function (AgentContractMode) {
+    AgentContractMode["Conservative"] = "conservative";
+    AgentContractMode["Balanced"] = "balanced";
+    AgentContractMode["Aggressive"] = "aggressive";
+})(AgentContractMode || (AgentContractMode = {}));
+const ROLE_FROM_STRING = new Map([
+    ['developer', RoleId.Developer],
+    ['reviewer', RoleId.Reviewer],
+    ['architect', RoleId.Architect],
+    ['release-manager', RoleId.ReleaseManager],
+    ['release', RoleId.ReleaseManager],
+    ['security', RoleId.Security],
+    ['ai-agent', RoleId.AiAgent],
+    ['ai', RoleId.AiAgent],
+]);
+function resolveRole(input) {
+    if (!input)
+        return RoleId.Developer;
+    const key = String(input).toLowerCase();
+    return ROLE_FROM_STRING.get(key) ?? RoleId.Developer;
+}
+function resolveMode(input) {
+    const v = String(input ?? '').toLowerCase();
+    if (v === 'conservative')
+        return AgentContractMode.Conservative;
+    if (v === 'aggressive')
+        return AgentContractMode.Aggressive;
+    return AgentContractMode.Balanced;
+}
+function uniq(xs) {
+    return [...new Set(xs)];
+}
+function isPublicApiPath(file) {
+    return (file.endsWith('/index.ts') ||
+        file.includes('plugin-api/') ||
+        file.includes('public-api/'));
+}
+function isAdapterPath(file) {
+    return file.includes('/adapters/') || file.includes('adapter');
+}
+function isReleaseTask(intent) {
+    return intent.kind === ChangeIntentKind.Release;
+}
+function isMigrationTask(intent) {
+    return intent.kind === ChangeIntentKind.Migration;
+}
+function buildBoundaryHints(impact, files) {
+    const out = [];
+    if (impact) {
+        for (const b of impact.potentialBoundaryRisks) {
+            out.push(`${b.ruleId} — ${b.reason}`);
+        }
+    }
+    for (const f of files) {
+        if (isAdapterPath(f))
+            out.push(`adapter boundary likely touched (${f})`);
+    }
+    return uniq(out).slice(0, 10);
+}
+function buildPolicyHints(impact) {
+    if (!impact)
+        return [];
+    return uniq(impact.affectedPolicies.map((p) => `${p.policyId} — ${p.reason}`)).slice(0, 10);
+}
+function buildLikelyTests(impact) {
+    if (!impact)
+        return [];
+    return uniq(impact.likelyTests).slice(0, 10);
+}
+function buildImpactedAreas(impact) {
+    if (!impact)
+        return [];
+    const set = new Set();
+    for (const a of impact.affectedAreas ?? [])
+        set.add(a.id);
+    return [...set].slice(0, 10);
+}
+function buildPublicApiRisks(intent, files, impact) {
+    const out = [];
+    const apiFiles = files.filter(isPublicApiPath);
+    for (const f of apiFiles)
+        out.push(`public API file touched: ${f}`);
+    if (intent.domains.includes('plugin') &&
+        (intent.kind === ChangeIntentKind.Architecture ||
+            intent.kind === ChangeIntentKind.Feature ||
+            intent.kind === ChangeIntentKind.Migration)) {
+        out.push('Plugin-api / public API may change — require API review.');
+    }
+    return uniq(out).slice(0, 10);
+}
+function buildOwnershipReview(impact) {
+    if (!impact)
+        return [];
+    const own = impact.affectedOwnership;
+    const out = [];
+    if (own && own.requiredReviewFiles.length > 0) {
+        for (const f of own.requiredReviewFiles)
+            out.push(f);
+    }
+    return uniq(out).slice(0, 10);
+}
+function buildForbiddenFiles(role, intent) {
+    const out = [];
+    // Releases and migrations: never auto-edit packaging or signature material.
+    if (isReleaseTask(intent)) {
+        out.push('package.json (do not bump version without explicit approval)');
+        out.push('CHANGELOG.md (release manager approval required)');
+    }
+    // AI agent must never write to git internals or release-affecting files.
+    if (role === RoleId.AiAgent) {
+        out.push('.git/**');
+        out.push('.npmrc');
+        out.push('package.json (do not modify without explicit human approval)');
+    }
+    return uniq(out);
+}
+function buildForbiddenFilesDetailed(role, intent) {
+    const out = [];
+    if (isReleaseTask(intent)) {
+        out.push({
+            pattern: 'package.json',
+            kind: ContractFileRuleKind.Exact,
+            reason: 'Release task: do not bump version without explicit approval.',
+            severity: ContractFileRuleSeverity.Error,
+        });
+        out.push({
+            pattern: 'CHANGELOG.md',
+            kind: ContractFileRuleKind.Exact,
+            reason: 'Release manager approval required.',
+            severity: ContractFileRuleSeverity.Error,
+        });
+    }
+    if (role === RoleId.AiAgent) {
+        out.push({
+            pattern: '.git/**',
+            kind: ContractFileRuleKind.Glob,
+            reason: 'Never write to git internals.',
+            severity: ContractFileRuleSeverity.Error,
+        });
+        out.push({
+            pattern: '.npmrc',
+            kind: ContractFileRuleKind.Exact,
+            reason: 'Registry credentials surface.',
+            severity: ContractFileRuleSeverity.Error,
+        });
+        out.push({
+            pattern: 'package.json',
+            kind: ContractFileRuleKind.Exact,
+            reason: 'AI agent must not modify without explicit human approval.',
+            severity: ContractFileRuleSeverity.Error,
+        });
+    }
+    return out;
+}
+function buildAllowedFilesDetailed(files, intent) {
+    const out = [];
+    for (const f of files) {
+        if (isPublicApiPath(f))
+            continue;
+        out.push({ pattern: f, kind: ContractFileRuleKind.Exact });
+    }
+    if (out.length === 0 && intent.likelyTemplates.length > 0) {
+        // Allow generated files under common template targets.
+        out.push({ pattern: 'packages/**', kind: ContractFileRuleKind.Glob });
+    }
+    return out;
+}
+function buildForbiddenCommands(role, intent) {
+    const out = [
+        'shrk apply <plan.json> --allow-divergent  (without explicit human approval)',
+    ];
+    if (isReleaseTask(intent) || isMigrationTask(intent)) {
+        out.push('git push --tags');
+        out.push('npm publish');
+        out.push('bun publish');
+    }
+    if (role === RoleId.AiAgent) {
+        out.push('Any MCP tool that writes (none exist; MCP is read-only).');
+        out.push('shrk apply (auto-apply without human in the loop)');
+        out.push('Pack-contributed verification commands (run via local CLI only).');
+    }
+    return uniq(out);
+}
+function buildAllowedCommands(role, intent) {
+    const t = JSON.stringify(intent.task || '<task>');
+    const out = [
+        `shrk brief ${t}`,
+        `shrk intent ${t}`,
+        `shrk risk ${t} --include-memory`,
+        `shrk impact --since main`,
+        'shrk check boundaries',
+    ];
+    if (role === RoleId.AiAgent) {
+        out.push(`shrk handoff ${t}`);
+        out.push(`shrk orchestrate ${t} --mode conservative`);
+        out.push(`shrk agent graph ${t} --role ai-agent`);
+    }
+    if (role === RoleId.Reviewer || role === RoleId.Architect) {
+        out.push('shrk review packet --v3 --since main');
+        out.push('shrk owners impact --since main');
+        out.push('shrk policy run --explain-overrides');
+    }
+    if (role === RoleId.ReleaseManager) {
+        out.push('shrk release readiness --strict');
+        out.push('shrk release smoke --scenario all');
+    }
+    return uniq(out);
+}
+function buildRequiredValidations(intent, risk) {
+    const out = new Set();
+    out.add('bun x tsc -p tsconfig.base.json --noEmit');
+    out.add('bun test');
+    out.add('shrk doctor');
+    out.add('shrk check boundaries');
+    if (intent.kind === ChangeIntentKind.Architecture ||
+        intent.domains.includes('boundaries')) {
+        out.add('shrk architecture violations');
+    }
+    if (risk.riskLevel === TaskRiskLevel.High || risk.riskLevel === TaskRiskLevel.Critical) {
+        out.add('shrk policy run --explain-overrides');
+        out.add('shrk safety audit --deep');
+    }
+    if (isReleaseTask(intent)) {
+        out.add('bun run release:preflight');
+        out.add('shrk release readiness --strict');
+    }
+    if (isMigrationTask(intent)) {
+        out.add('shrk migration readiness');
+    }
+    return [...out];
+}
+function buildRequiredReviews(role, intent, risk, hasPublicApi, hasAdapter) {
+    const out = new Set();
+    if (risk.riskLevel === TaskRiskLevel.High ||
+        risk.riskLevel === TaskRiskLevel.Critical ||
+        intent.requiredHumanReview) {
+        out.add('human review (risk-driven)');
+    }
+    if (hasPublicApi)
+        out.add('API review (plugin-api / public-api change)');
+    if (hasAdapter)
+        out.add('adapter-boundary review');
+    if (role === RoleId.AiAgent) {
+        out.add('human in the loop — agent must NOT auto-apply');
+    }
+    return [...out];
+}
+function buildRequiredPlanReviews(intent) {
+    const lower = intent.task.toLowerCase();
+    const out = [];
+    if (lower.includes('plan') ||
+        lower.includes('update operation') ||
+        lower.includes('saved plan') ||
+        intent.kind === ChangeIntentKind.Migration) {
+        out.push('shrk plan review <plan.json>');
+        out.push('shrk plan simulate <plan.json> --include-boundaries --include-impact');
+    }
+    return out;
+}
+function buildHumanApprovalGates(role, intent, risk, hasPublicApi) {
+    const out = new Set();
+    if (risk.riskLevel === TaskRiskLevel.High ||
+        risk.riskLevel === TaskRiskLevel.Critical ||
+        intent.requiredHumanReview) {
+        out.add('Approve before apply (risk-driven).');
+    }
+    if (isReleaseTask(intent)) {
+        out.add('Approve before any publish / tag step.');
+        out.add('Approve preflight result before tagging.');
+    }
+    if (isMigrationTask(intent)) {
+        out.add('Approve migration readiness before applying.');
+    }
+    if (hasPublicApi)
+        out.add('Approve any public-API change explicitly.');
+    if (role === RoleId.AiAgent)
+        out.add('Human runs the apply step; agent never auto-applies.');
+    return [...out];
+}
+function buildRollbackPlan(intent) {
+    const out = [
+        'git restore -SW <changed files>  (before commit)',
+        'git revert <commit-sha>          (after commit)',
+    ];
+    if (isReleaseTask(intent)) {
+        out.push('npm unpublish (within 72h) only with explicit authorization.');
+        out.push('Tag rollback: do not force-push; cut a follow-up release instead.');
+    }
+    return out;
+}
+function buildDefinitionOfDone(intent, validations) {
+    const out = [
+        'All listed validations pass.',
+        'No new boundary violations.',
+        'Plan was reviewed and applied via CLI (not MCP).',
+    ];
+    if (intent.kind !== ChangeIntentKind.Docs) {
+        out.push('Tests cover new public surfaces.');
+    }
+    if (isReleaseTask(intent)) {
+        out.push('CHANGELOG entry exists; preflight is green.');
+    }
+    if (validations.includes('shrk migration readiness')) {
+        out.push('Migration readiness verdict is "ready".');
+    }
+    return out;
+}
+function buildAllowedFiles(files, intent) {
+    const out = [];
+    for (const f of files) {
+        if (isPublicApiPath(f))
+            continue;
+        out.push(f);
+    }
+    if (out.length === 0 && intent.likelyTemplates.length > 0) {
+        out.push('(target files derived from chosen template at gen time)');
+    }
+    return uniq(out);
+}
+function buildSafetyNotes(role, intent, risk) {
+    const out = [
+        'MCP is read-only — never call write-style MCP tools (none exist).',
+        'CLI is the only write path. Apply requires --verify-signature for signed plans.',
+    ];
+    if (role === RoleId.AiAgent) {
+        out.push('Agent contract requires explicit human approval before apply.');
+        out.push('Always run shrk handoff / shrk brief before first action.');
+    }
+    if (risk.riskLevel === TaskRiskLevel.High || risk.riskLevel === TaskRiskLevel.Critical) {
+        out.push(`Risk level is ${risk.riskLevel} — extra approval required.`);
+    }
+    if (isReleaseTask(intent)) {
+        out.push('Release work must not auto-publish; preflight + readiness required.');
+    }
+    return out;
+}
+function buildRecommendedNextCommand(role, intent) {
+    const t = JSON.stringify(intent.task || '<task>');
+    if (role === RoleId.AiAgent)
+        return `shrk handoff ${t}`;
+    if (role === RoleId.ReleaseManager)
+        return 'shrk release readiness --strict';
+    if (role === RoleId.Security)
+        return 'shrk safety audit --deep';
+    if (role === RoleId.Architect)
+        return 'shrk architecture map --risk --signals';
+    if (role === RoleId.Reviewer)
+        return 'shrk review packet --v3 --since main';
+    return `shrk brief ${t}`;
+}
+export async function buildAgentContract(task, inspection, options = {}) {
+    const trimmed = (task || '').trim();
+    const role = resolveRole(options.role);
+    const mode = resolveMode(options.mode);
+    const intent = await classifyChangeIntent(trimmed, inspection);
+    const risk = await buildTaskRiskReport(trimmed, inspection, {
+        ...(options.files ? { files: options.files } : {}),
+        ...(options.since ? { since: options.since } : {}),
+        ...(options.staged ? { staged: true } : {}),
+        includeMemory: true,
+    });
+    let impact = null;
+    try {
+        const impactInput = {
+            task: trimmed,
+            inputKind: (options.files && options.files.length > 0) ? ImpactInputKind.Files : ImpactInputKind.Task,
+        };
+        if (options.files && options.files.length > 0)
+            impactInput.files = options.files;
+        impact = await analyzeImpact(inspection, impactInput);
+    }
+    catch {
+        impact = null;
+    }
+    // Make sure ownership rules are loaded so risk.ownershipGaps has context.
+    try {
+        await loadOwnershipRules(inspection.projectRoot);
+    }
+    catch {
+        /* best-effort */
+    }
+    void ownershipImpactFor; // referenced for future direct calls
+    await loadConstructs(inspection);
+    const constructList = listConstructs(inspection) ?? [];
+    const playbooks = await listPlaybooks(inspection);
+    const recommended = recommendPlaybooks(playbooks, trimmed);
+    const files = options.files ?? risk.affectedFiles;
+    const hasAdapter = files.some(isAdapterPath);
+    const hasPublicApi = files.some(isPublicApiPath);
+    const allowedCommands = buildAllowedCommands(role, intent);
+    const forbiddenCommands = buildForbiddenCommands(role, intent);
+    const allowedFiles = buildAllowedFiles(files, intent);
+    const forbiddenFiles = buildForbiddenFiles(role, intent);
+    const allowedFilesDetailed = buildAllowedFilesDetailed(files, intent);
+    const forbiddenFilesDetailed = buildForbiddenFilesDetailed(role, intent);
+    const requiredValidations = buildRequiredValidations(intent, risk);
+    const requiredReviews = buildRequiredReviews(role, intent, risk, hasPublicApi, hasAdapter);
+    const requiredPlanReviews = buildRequiredPlanReviews(intent);
+    const humanApprovalGates = buildHumanApprovalGates(role, intent, risk, hasPublicApi);
+    const rollbackPlan = buildRollbackPlan(intent);
+    const definitionOfDone = buildDefinitionOfDone(intent, requiredValidations);
+    const safetyNotes = buildSafetyNotes(role, intent, risk);
+    const recommendedNextCommand = buildRecommendedNextCommand(role, intent);
+    const relevantConstructs = uniq([
+        ...intent.likelyConstructs,
+        ...risk.affectedConstructs,
+        ...constructList
+            .filter((c) => trimmed.toLowerCase().includes(c.id.toLowerCase()))
+            .map((c) => c.id),
+    ]).slice(0, 12);
+    const relevantPlaybooks = recommended.slice(0, 5).map((r) => r.playbook.id);
+    const relevantTemplates = intent.likelyTemplates.slice(0, 10);
+    const relevantPolicies = buildPolicyHints(impact);
+    const relevantBoundaries = buildBoundaryHints(impact, files);
+    const likelyTests = buildLikelyTests(impact);
+    const impactedAreas = buildImpactedAreas(impact);
+    const publicApiRisks = buildPublicApiRisks(intent, files, impact);
+    const ownershipReview = buildOwnershipReview(impact);
+    return {
+        schema: AGENT_CONTRACT_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        task: trimmed,
+        intent,
+        taskRisk: risk,
+        role,
+        mode,
+        allowedFiles,
+        forbiddenFiles,
+        allowedFilesDetailed,
+        forbiddenFilesDetailed,
+        allowedCommands,
+        forbiddenCommands,
+        requiredValidations,
+        requiredReviews,
+        requiredPlanReviews,
+        humanApprovalGates,
+        rollbackPlan,
+        definitionOfDone,
+        relevantConstructs,
+        relevantPolicies,
+        relevantBoundaries,
+        relevantPlaybooks,
+        relevantTemplates,
+        likelyTests,
+        impactedAreas,
+        publicApiRisks,
+        ownershipReview,
+        recommendedNextCommand,
+        safetyNotes,
+    };
+}
+function listLines(title, items) {
+    if (items.length === 0)
+        return '';
+    return `${title}:\n${items.map((i) => `  • ${i}`).join('\n')}\n\n`;
+}
+export function renderAgentContractText(c) {
+    let out = `=== Agent contract ===\n`;
+    out += `  task     ${c.task || '(empty)'}\n`;
+    out += `  intent   ${c.intent.kind} / ${c.intent.confidence}\n`;
+    out += `  role     ${c.role}\n`;
+    out += `  mode     ${c.mode}\n`;
+    out += `  risk     ${c.taskRisk.riskLevel} (score ${c.taskRisk.score})\n`;
+    out += `  approval ${c.taskRisk.humanApprovalRequired ? 'REQUIRED' : 'not required by risk gate'}\n\n`;
+    out += listLines('Allowed files', c.allowedFiles);
+    out += listLines('Forbidden files', c.forbiddenFiles);
+    out += listLines('Allowed commands', c.allowedCommands);
+    out += listLines('Forbidden commands', c.forbiddenCommands);
+    out += listLines('Required validations', c.requiredValidations);
+    out += listLines('Required reviews', c.requiredReviews);
+    out += listLines('Required plan reviews', c.requiredPlanReviews);
+    out += listLines('Human approval gates', c.humanApprovalGates);
+    out += listLines('Rollback plan', c.rollbackPlan);
+    out += listLines('Definition of done', c.definitionOfDone);
+    out += listLines('Relevant constructs', c.relevantConstructs);
+    out += listLines('Relevant policies', c.relevantPolicies);
+    out += listLines('Relevant boundaries', c.relevantBoundaries);
+    out += listLines('Relevant playbooks', c.relevantPlaybooks);
+    out += listLines('Relevant templates', c.relevantTemplates);
+    out += listLines('Likely tests', c.likelyTests);
+    out += listLines('Impacted areas', c.impactedAreas);
+    out += listLines('Public API risks', c.publicApiRisks);
+    out += listLines('Ownership review', c.ownershipReview);
+    out += listLines('Safety notes', c.safetyNotes);
+    out += `Recommended next command:\n  $ ${c.recommendedNextCommand}\n`;
+    return out;
+}
+function mdList(title, items) {
+    if (items.length === 0)
+        return '';
+    return `## ${title}\n${items.map((i) => `- ${i}`).join('\n')}\n\n`;
+}
+export function renderAgentContractMarkdown(c) {
+    let out = `# Agent contract\n\n`;
+    out += `- **task**: ${c.task || '(empty)'}\n`;
+    out += `- **intent**: ${c.intent.kind} (${c.intent.confidence})\n`;
+    out += `- **role**: ${c.role}\n`;
+    out += `- **mode**: ${c.mode}\n`;
+    out += `- **risk**: ${c.taskRisk.riskLevel} (score ${c.taskRisk.score})\n`;
+    out += `- **approval**: ${c.taskRisk.humanApprovalRequired ? 'REQUIRED' : 'not required by risk gate'}\n`;
+    out += `- **generated**: ${c.generatedAt}\n\n`;
+    out += mdList('Allowed files', c.allowedFiles);
+    out += mdList('Forbidden files', c.forbiddenFiles);
+    out += mdList('Allowed commands', c.allowedCommands);
+    out += mdList('Forbidden commands', c.forbiddenCommands);
+    out += mdList('Required validations', c.requiredValidations);
+    out += mdList('Required reviews', c.requiredReviews);
+    out += mdList('Required plan reviews', c.requiredPlanReviews);
+    out += mdList('Human approval gates', c.humanApprovalGates);
+    out += mdList('Rollback plan', c.rollbackPlan);
+    out += mdList('Definition of done', c.definitionOfDone);
+    out += mdList('Relevant constructs', c.relevantConstructs);
+    out += mdList('Relevant policies', c.relevantPolicies);
+    out += mdList('Relevant boundaries', c.relevantBoundaries);
+    out += mdList('Relevant playbooks', c.relevantPlaybooks);
+    out += mdList('Relevant templates', c.relevantTemplates);
+    out += mdList('Likely tests', c.likelyTests);
+    out += mdList('Impacted areas', c.impactedAreas);
+    out += mdList('Public API risks', c.publicApiRisks);
+    out += mdList('Ownership review', c.ownershipReview);
+    out += mdList('Safety notes', c.safetyNotes);
+    out += `**Recommended next command**: \`${c.recommendedNextCommand}\`\n`;
+    return out;
+}
+function htmlEscape(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+export function renderAgentContractHtml(c) {
+    const md = renderAgentContractMarkdown(c);
+    return `<!doctype html><html><head><meta charset="utf-8"><title>Agent contract</title></head><body><pre>${htmlEscape(md)}</pre></body></html>\n`;
+}

package/dist/agent-handoff.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Agent handoff packet.
+ *
+ * `brief` is the *pre-work* context for an agent. `handoff` is the
+ * *continue-from-here* context: it captures current task status, what was
+ * already done, what remains, and the single next safe command — so a
+ * different agent (or the same agent after a context reset) can pick up
+ * without redoing discovery.
+ *
+ * Read-only. Sources state from:
+ *  - a passed-in task string + inspection
+ *  - an existing dev session (sessionId)
+ *  - an existing feature bundle (bundleId)
+ *  - optionally a git ref (`since`) for changed-files surfacing
+ *
+ * Never writes (the CLI write step is the caller's responsibility).
+ */
+import { type ITaskRiskReport } from './task-risk.js';
+import { type IAgentContract } from './agent-contract.js';
+import { type ITaskExecutionGraph } from './execution-graph.js';
+import { type IPlanSimulationReport } from './plan-simulation.js';
+import { type IMemoryRiskReport } from './repo-memory.js';
+import { type IUncertaintyReport } from './uncertainty-report.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const AGENT_HANDOFF_SCHEMA = "sharkcraft.agent-handoff/v1";
+export interface IAgentHandoffInput {
+    task?: string;
+    /** Existing dev session to continue. */
+    sessionId?: string;
+    /** Existing feature bundle to continue. */
+    bundleId?: string;
+    /** Git ref to surface "since this point" changed files. */
+    since?: string;
+    /** Generate chunked output. */
+    chunked?: boolean;
+    /** Output destination filename (chunks live in the same dir if chunked). */
+    output?: string;
+    /** Fold an agent contract summary into the handoff. */
+    includeContract?: boolean;
+    /** Include the same pre-work brief content (matches `shrk brief`). */
+    includeBrief?: boolean;
+    /** Include a summary of the task execution graph. */
+    includeExecutionGraph?: boolean;
+    /** Include memory-driven warnings. */
+    includeMemory?: boolean;
+    /** Include plan simulation summary when a plan path is supplied. */
+    includePlanSimulation?: string;
+    /** Role for contract/handoff personalisation. */
+    role?: string;
+    /** Mode for contract personalisation. */
+    mode?: string;
+}
+export interface IAgentHandoffChunk {
+    file: string;
+    sectionId: string;
+    title: string;
+    body: string;
+    tokenEstimate: number;
+}
+export interface IAgentHandoffReport {
+    schema: typeof AGENT_HANDOFF_SCHEMA;
+    generatedAt: string;
+    projectRoot: string;
+    task: string;
+    knownContext: readonly string[];
+    doNotTouch: readonly string[];
+    relevantFiles: readonly string[];
+    relevantRules: readonly string[];
+    currentStatus: string;
+    nextSafeCommand: string;
+    validationExpectations: readonly string[];
+    humanApprovalPoints: readonly string[];
+    availableArtifacts: readonly {
+        kind: string;
+        path: string;
+    }[];
+    safetyNote: string;
+    markdown: string;
+    chunks?: readonly IAgentHandoffChunk[];
+    /** Per-task risk summary (best-effort; only when a task is provided). */
+    taskRiskSummary?: {
+        level: string;
+        score: number;
+        reasons: readonly string[];
+    };
+    /** Full task-risk report (when --include-memory/--include-contract drove memory-weighted risk). */
+    taskRisk?: ITaskRiskReport;
+    /** Full agent contract when --include-contract was set. */
+    contract?: IAgentContract;
+    /** Short contract summary text. */
+    contractSummary?: {
+        role: string;
+        mode: string;
+        forbiddenCommands: readonly string[];
+        requiredValidations: readonly string[];
+        requiredReviews: readonly string[];
+        humanApprovalGates: readonly string[];
+        recommendedNextCommand: string;
+        contractHash: string;
+    };
+    /** Execution graph (full) when --include-execution-graph. */
+    executionGraph?: ITaskExecutionGraph;
+    /** Short execution graph summary. */
+    executionGraphSummary?: {
+        nodes: number;
+        edges: number;
+        humanApprovalNodes: readonly string[];
+    };
+    /** Plan simulation when --include-plan-simulation <plan.json>. */
+    planSimulation?: IPlanSimulationReport;
+    /** Memory-derived risk (when --include-memory and an index exists). */
+    memoryRisk?: IMemoryRiskReport;
+    source: {
+        kind: 'task-only' | 'session' | 'bundle' | 'session+bundle';
+        sessionId?: string;
+        bundleId?: string;
+    };
+    /** Uncertainty report (confidence + signals + safe fallback). */
+    uncertainty?: IUncertaintyReport;
+}
+export declare function buildAgentHandoff(inspection: ISharkcraftInspection, input: IAgentHandoffInput): Promise<IAgentHandoffReport>;
+export declare function defaultHandoffOutputPath(projectRoot: string, task: string): string;
+//# sourceMappingURL=agent-handoff.d.ts.map

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

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