@shrkcrft/inspector 0.1.0-alpha.1

package/dist/agent-orchestration.js

@@ -0,0 +1,285 @@
+/**
+ * Agent orchestration planner.
+ *
+ * Given a task, produce a safe, read-only plan describing how an
+ * agent/human should proceed: phases, commands to suggest, MCP tools,
+ * expected artifacts, human-approval points, stop conditions.
+ *
+ * This is not execution. It does not apply, it does not write source.
+ *
+ * Modes:
+ * - conservative: more review/checkpoints; only drafts/plans suggested
+ * - balanced: dev session + plan review + apply hint
+ * - aggressive: still no auto-apply, but suggests bundle/dev flow faster
+ */
+import { classifyChangeIntent, ChangeIntentKind } from "./change-intent.js";
+import { computeRiskSignals, RiskLevel } from "./risk-signals.js";
+import { buildTaskRiskReport, TaskRiskLevel } from "./task-risk.js";
+export const AGENT_ORCHESTRATION_SCHEMA = 'sharkcraft.agent-orchestration/v1';
+export var OrchestrationMode;
+(function (OrchestrationMode) {
+    OrchestrationMode["Conservative"] = "conservative";
+    OrchestrationMode["Balanced"] = "balanced";
+    OrchestrationMode["Aggressive"] = "aggressive";
+})(OrchestrationMode || (OrchestrationMode = {}));
+const FORBIDDEN_ACTIONS = Object.freeze([
+    'Do not run shrk apply without --verify-signature on signed plans.',
+    'Do not auto-execute pack-contributed verification commands without local opt-in.',
+    'Do not call MCP write tools — MCP is read-only.',
+    'Do not publish, tag, or push without explicit human approval.',
+]);
+function discoveryPhase(intent, mode) {
+    return {
+        id: 'discovery',
+        title: 'Discovery',
+        purpose: 'Ground in repository context — rules, paths, templates, constructs relevant to the task.',
+        recommendedCommands: [
+            'shrk doctor',
+            `shrk context --task "${intent.task}"`,
+            `shrk brief "${intent.task}"`,
+        ],
+        mcpTools: ['inspect_workspace', 'get_relevant_context', 'list_templates', 'classify_change_intent'],
+        expectedArtifacts: ['brief markdown'],
+        humanApprovalRequired: false,
+        stopConditions: ['Doctor reports error.', 'Context is empty for this task.'],
+        safetyNotes: mode === OrchestrationMode.Conservative
+            ? ['Read intent + brief carefully before touching any file.']
+            : [],
+    };
+}
+function planPhase(intent, mode) {
+    const cmds = mode === OrchestrationMode.Aggressive
+        ? [
+            `shrk dev start "${intent.task}"`,
+            `shrk gen <templateId> <name> --dry-run --save-plan /tmp/plan.json`,
+            'shrk plan review /tmp/plan.json',
+        ]
+        : [
+            `shrk dev start "${intent.task}"`,
+            `shrk handoff "${intent.task}" --output .sharkcraft/handoff.md`,
+            `shrk gen <templateId> <name> --dry-run --save-plan /tmp/plan.json`,
+        ];
+    return {
+        id: 'plan',
+        title: 'Plan',
+        purpose: 'Produce a dry-run plan (no writes) and review.',
+        recommendedCommands: cmds,
+        mcpTools: ['create_generation_plan', 'review_generation_plan'],
+        expectedArtifacts: ['plan.json (signed, dry-run)'],
+        humanApprovalRequired: false,
+        stopConditions: ['No matching template found.', 'Plan signature missing.'],
+        safetyNotes: mode === OrchestrationMode.Conservative
+            ? ['Plan must be reviewed manually before any apply step.']
+            : [],
+    };
+}
+function reviewPhase(intent, mode) {
+    const cmds = ['shrk plan review /tmp/plan.json', 'shrk impact --since main --format json'];
+    if (mode === OrchestrationMode.Conservative)
+        cmds.push(`shrk simulate "${intent.task}"`);
+    return {
+        id: 'review',
+        title: 'Review',
+        purpose: 'Surface conflicts, divergence, and boundary impact before any write step.',
+        recommendedCommands: cmds,
+        mcpTools: ['review_generation_plan', 'get_impact_analysis', 'simulate_workflow'],
+        expectedArtifacts: ['impact.json', 'plan-review output'],
+        humanApprovalRequired: mode === OrchestrationMode.Conservative,
+        stopConditions: ['Plan has conflicts.', 'Boundary violation introduced.'],
+        safetyNotes: [],
+    };
+}
+function applyPhase(intent, mode) {
+    const writePhase = intent.kind === ChangeIntentKind.Release ? 'release' : 'apply';
+    const cmds = writePhase === 'release'
+        ? ['shrk release readiness --strict', 'shrk release smoke --scenario all', 'shrk release:preflight']
+        : [
+            'shrk apply /tmp/plan.json --verify-signature --validate --verification typecheck --verification unit-tests',
+        ];
+    return {
+        id: writePhase,
+        title: writePhase === 'release' ? 'Release gate' : 'Apply',
+        purpose: writePhase === 'release'
+            ? 'Walk the release gates. Do not publish/tag — those steps are explicit human ones.'
+            : 'Apply the reviewed plan via the CLI (the only write path). Requires `--verify-signature`.',
+        recommendedCommands: cmds,
+        mcpTools: [],
+        expectedArtifacts: writePhase === 'release' ? ['release-readiness report'] : ['written files (logged)'],
+        humanApprovalRequired: true,
+        stopConditions: writePhase === 'release'
+            ? ['preflight gate fails.', 'readiness has blockers.']
+            : ['typecheck or unit-tests fail.', 'divergence detected without --allow-divergent.'],
+        safetyNotes: ['MCP must not run this step. Human approval is required.'],
+    };
+}
+function validationPhase(intent) {
+    return {
+        id: 'validate',
+        title: 'Validate',
+        purpose: 'Run typecheck + tests + readiness sweep.',
+        recommendedCommands: [
+            'bun x tsc -p tsconfig.base.json --noEmit',
+            'bun test',
+            'shrk release readiness',
+            `shrk impact --since main`,
+        ],
+        mcpTools: ['get_release_readiness', 'get_quality_report'],
+        expectedArtifacts: ['test output', 'readiness report'],
+        humanApprovalRequired: false,
+        stopConditions: ['Any of the above fails.'],
+        safetyNotes: [],
+    };
+}
+function riskPhase(risk, taskRisk) {
+    const safetyNotes = [`Risk reasons: ${risk.reasons.join(' · ')}`];
+    if (taskRisk) {
+        safetyNotes.push(`Task risk: ${taskRisk.riskLevel} (score ${taskRisk.score}); ${taskRisk.reasons
+            .slice(0, 3)
+            .map((r) => r.code)
+            .join(', ')}`);
+    }
+    const commands = [
+        'shrk architecture map --risk --signals',
+        'shrk architecture violations',
+        'shrk policy run --explain-overrides',
+        'shrk impact --since main --format json',
+    ];
+    if (taskRisk && taskRisk.task)
+        commands.unshift(`shrk risk "${taskRisk.task}" --explain`);
+    return {
+        id: 'risk-review',
+        title: 'Risk review',
+        purpose: `Risk signals are elevated (${risk.level}${taskRisk ? ` / task ${taskRisk.riskLevel}` : ''}). Surface boundaries, impact, and policy state before generating a plan.`,
+        recommendedCommands: commands,
+        mcpTools: [
+            'get_task_risk_report',
+            'get_architecture_map',
+            'get_architecture_violations',
+            'get_policy_report',
+            'get_impact_analysis',
+        ],
+        expectedArtifacts: ['task risk report', 'architecture map', 'violations report', 'policy report'],
+        humanApprovalRequired: true,
+        stopConditions: ['Boundary violations at error severity unresolved.', 'Policy errors not overridden.'],
+        safetyNotes,
+    };
+}
+export async function buildAgentOrchestrationPlan(task, inspection, options = {}) {
+    const mode = options.mode ?? OrchestrationMode.Balanced;
+    const riskAware = options.riskAware === true;
+    const intent = await classifyChangeIntent(task, inspection);
+    let risk;
+    let taskRisk;
+    if (riskAware) {
+        risk = await computeRiskSignals(inspection, { withSignals: true });
+        try {
+            taskRisk = await buildTaskRiskReport(task, inspection, { includeMemory: true });
+        }
+        catch {
+            taskRisk = undefined;
+        }
+    }
+    const phases = [
+        discoveryPhase(intent, mode),
+        planPhase(intent, mode),
+        reviewPhase(intent, mode),
+        applyPhase(intent, mode),
+        validationPhase(intent),
+    ];
+    // Inject a risk-review phase between discovery and plan when either
+    // global or per-task risk is elevated. The phase is human-approval-gated.
+    const taskRiskElevated = taskRisk &&
+        (taskRisk.riskLevel === TaskRiskLevel.High || taskRisk.riskLevel === TaskRiskLevel.Critical);
+    if (risk && (risk.level === RiskLevel.High || risk.level === RiskLevel.Critical || taskRiskElevated)) {
+        phases.splice(1, 0, riskPhase(risk, taskRisk));
+    }
+    const baseCheckpoints = mode === OrchestrationMode.Conservative
+        ? [
+            'Discovery → human reviews brief.',
+            'Plan → human reviews plan.json before apply.',
+            'Apply → human approves write step.',
+            'Validate → human approves test results.',
+        ]
+        : ['Plan → review plan.', 'Apply → human runs apply (CLI-only).'];
+    const reviewCheckpoints = risk && (risk.level === RiskLevel.High || risk.level === RiskLevel.Critical || taskRiskElevated)
+        ? ['Risk review → human approves before plan.', ...baseCheckpoints]
+        : baseCheckpoints;
+    return {
+        schema: AGENT_ORCHESTRATION_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        task,
+        intent,
+        mode,
+        phases,
+        firstCommand: phases[0]?.recommendedCommands[0] ?? 'shrk start-here',
+        forbiddenActions: FORBIDDEN_ACTIONS,
+        validationCommands: [
+            'bun x tsc -p tsconfig.base.json --noEmit',
+            'bun test',
+            'shrk release readiness',
+        ],
+        reviewCheckpoints,
+        ...(risk ? { risk } : {}),
+        ...(taskRisk ? { taskRisk } : {}),
+        riskAware,
+    };
+}
+export function renderOrchestrationText(plan) {
+    const lines = [];
+    lines.push('=== Agent orchestration plan ===');
+    lines.push(`  task   ${plan.task}`);
+    lines.push(`  mode   ${plan.mode}`);
+    lines.push(`  intent ${plan.intent.kind} (confidence ${plan.intent.confidence})`);
+    lines.push('Phases:');
+    for (const p of plan.phases) {
+        lines.push(`  ${p.id} — ${p.title}${p.humanApprovalRequired ? ' [HUMAN APPROVAL]' : ''}`);
+        for (const c of p.recommendedCommands)
+            lines.push(`    $ ${c}`);
+    }
+    lines.push('First command:');
+    lines.push(`  $ ${plan.firstCommand}`);
+    lines.push('Forbidden actions:');
+    for (const f of plan.forbiddenActions)
+        lines.push(`  • ${f}`);
+    lines.push('Review checkpoints:');
+    for (const c of plan.reviewCheckpoints)
+        lines.push(`  • ${c}`);
+    return lines.join('\n') + '\n';
+}
+export function renderOrchestrationMarkdown(plan) {
+    const lines = [];
+    lines.push(`# Orchestration plan — ${plan.task}`);
+    lines.push('');
+    lines.push(`Mode: **${plan.mode}** · intent: **${plan.intent.kind}** · confidence: ${plan.intent.confidence}`);
+    lines.push('');
+    for (const p of plan.phases) {
+        lines.push(`## ${p.title}${p.humanApprovalRequired ? ' (human approval required)' : ''}`);
+        lines.push(`_${p.purpose}_`);
+        lines.push('');
+        if (p.recommendedCommands.length > 0) {
+            lines.push('Commands:');
+            lines.push('```bash');
+            for (const c of p.recommendedCommands)
+                lines.push(c);
+            lines.push('```');
+        }
+        if (p.mcpTools.length > 0)
+            lines.push(`MCP tools: ${p.mcpTools.map((t) => `\`${t}\``).join(', ')}`);
+        if (p.expectedArtifacts.length > 0)
+            lines.push(`Artifacts: ${p.expectedArtifacts.join(', ')}`);
+        if (p.stopConditions.length > 0) {
+            lines.push('Stop if:');
+            for (const s of p.stopConditions)
+                lines.push(`- ${s}`);
+        }
+        lines.push('');
+    }
+    lines.push('## Forbidden');
+    for (const f of plan.forbiddenActions)
+        lines.push(`- ${f}`);
+    lines.push('');
+    lines.push('## Review checkpoints');
+    for (const c of plan.reviewCheckpoints)
+        lines.push(`- ${c}`);
+    return lines.join('\n') + '\n';
+}

package/dist/agent-task-prep.d.ts

@@ -0,0 +1,31 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const AGENT_TASK_PREP_SCHEMA = "sharkcraft.agent-task-prep/v1";
+export interface IAgentTaskPrepReport {
+    readonly schema: typeof AGENT_TASK_PREP_SCHEMA;
+    readonly generatedAt: string;
+    readonly task: string;
+    readonly intentHints: readonly string[];
+    readonly confidence: 'high' | 'medium' | 'low';
+    readonly missingSignals: readonly string[];
+    readonly primaryCommands: readonly string[];
+    readonly inspectionCommands: readonly string[];
+    readonly generationCommands: readonly string[];
+    readonly validationCommands: readonly string[];
+    readonly relevantProfiles: readonly {
+        id: string;
+        title: string;
+    }[];
+    readonly relevantConventions: readonly {
+        id: string;
+        title: string;
+    }[];
+    readonly routingHints: readonly {
+        id: string;
+        title: string;
+        reasons: readonly string[];
+    }[];
+    readonly safetyNotes: readonly string[];
+    readonly nextSafeAction: string;
+}
+export declare function prepareAgentTask(inspection: ISharkcraftInspection, task: string): Promise<IAgentTaskPrepReport>;
+//# sourceMappingURL=agent-task-prep.d.ts.map

package/dist/agent-task-prep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-task-prep.d.ts","sourceRoot":"","sources":["../src/agent-task-prep.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,sBAAsB,kCAAkC,CAAC;AAEtE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,sBAAsB,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC/C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpE,QAAQ,CAAC,mBAAmB,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvE,QAAQ,CAAC,YAAY,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC5F,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,qBAAqB,EACjC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,oBAAoB,CAAC,CAqD/B"}

package/dist/agent-task-prep.js

@@ -0,0 +1,73 @@
+/**
+ * Canonical agent task entrypoint.
+ *
+ * `prepareAgentTask` is the recommended first call an AI agent (or
+ * MCP client) makes when it picks up a task. It bundles:
+ *   - intent classification
+ *   - relevant rules / paths / templates / playbooks / profiles / conventions
+ *   - recommended CLI commands (inspection / generation / validation)
+ *   - uncertainty signals
+ *   - safety notes
+ *   - next safe action
+ *
+ * Read-only. Never writes; never executes commands.
+ */
+import { buildTaskPacket } from "./task-packet.js";
+import { listPluginLifecycleProfiles } from "./plugin-lifecycle-profile-registry.js";
+import { listConventions } from "./convention-registry.js";
+import { listTaskRoutingHints, explainTaskRouting } from "./task-routing-hint-registry.js";
+import { buildUncertaintySummary } from "./uncertainty.js";
+export const AGENT_TASK_PREP_SCHEMA = 'sharkcraft.agent-task-prep/v1';
+export async function prepareAgentTask(inspection, task) {
+    const packet = buildTaskPacket(inspection, task);
+    const uncertaintyReport = buildUncertaintySummary(packet);
+    const lifecycle = await listPluginLifecycleProfiles(inspection);
+    const conventions = await listConventions(inspection);
+    const routing = await explainTaskRouting(inspection, task);
+    await listTaskRoutingHints(inspection); // warm cache
+    const inspectionCommands = [
+        `shrk context --task "${task}" --commands-first`,
+        `shrk task "${task}"`,
+        `shrk why ${routing[0]?.hint.id ?? '<id>'} --for-task "${task}"`,
+        'shrk packs contributions',
+        'shrk self-config doctor',
+    ];
+    const generationCommands = [
+        `shrk gen <template-id> <name> --dry-run --save-plan /tmp/plan.json`,
+    ];
+    const validationCommands = [
+        'shrk doctor',
+        'shrk check boundaries --changed-only',
+        'shrk test agent',
+        'shrk self-config doctor',
+    ];
+    const primaryCommands = routing.flatMap((m) => m.hint.recommends.commands ?? []).slice(0, 5);
+    const intentHints = [];
+    if (/\brename\b/i.test(task))
+        intentHints.push('refactor');
+    if (/\bremove\b/i.test(task))
+        intentHints.push('removal');
+    if (/\badd\b|\bcreate\b/i.test(task))
+        intentHints.push('generate-code');
+    return {
+        schema: AGENT_TASK_PREP_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        task,
+        intentHints,
+        confidence: uncertaintyReport.confidence,
+        missingSignals: uncertaintyReport.uncertainty.map((s) => s.code),
+        primaryCommands,
+        inspectionCommands,
+        generationCommands,
+        validationCommands,
+        relevantProfiles: lifecycle.slice(0, 5).map((e) => ({ id: e.profile.id, title: e.profile.title })),
+        relevantConventions: conventions.slice(0, 5).map((e) => ({ id: e.convention.id, title: e.convention.title })),
+        routingHints: routing.slice(0, 5).map((m) => ({ id: m.hint.id, title: m.hint.title, reasons: m.reasons })),
+        safetyNotes: [
+            'SharkCraft engine never auto-applies plans. The human runs `shrk apply --verify-signature`.',
+            'MCP tools are read-only; every write happens via the CLI.',
+            'Folder rename/delete plans default to manual checklist; pass `--emit-folder-ops` to opt into structured plan ops with strict safety gates.',
+        ],
+        nextSafeAction: 'Inspect the recommended commands above before writing any code. Start with `shrk task "<task>" --commands-first` for the human-friendly summary.',
+    };
+}

package/dist/ai-readiness.d.ts

@@ -0,0 +1,30 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export interface IReadinessDimension {
+    id: string;
+    title: string;
+    /** 0–10 score. */
+    score: number;
+    /** Weight applied to the score in the final aggregate. */
+    weight: number;
+    /** Free-form note explaining the score. */
+    note: string;
+}
+export type ReadinessGrade = 'excellent' | 'good' | 'partial' | 'poor';
+export interface IReadinessReport {
+    /** 0..100 weighted score. */
+    score: number;
+    grade: ReadinessGrade;
+    dimensions: IReadinessDimension[];
+    /** Up to 5 prioritized actions to improve the score. */
+    topRecommendations: string[];
+}
+/**
+ * Deterministic 0..100 AI-readiness score. Penalties are explicit:
+ *  - Quantity-only "stuff a registry full of entries" is capped via softCap.
+ *  - Duplicate-id warnings reduce data-quality dimension.
+ *  - Placeholder docs (TODO / TBD / "fill in") reduce docs dimension.
+ *  - Critical/high workflow entries missing actionHints reduce safety dim.
+ *  - Doctor health stays a hard gate.
+ */
+export declare function buildAiReadinessReport(inspection: ISharkcraftInspection): IReadinessReport;
+//# sourceMappingURL=ai-readiness.d.ts.map

package/dist/ai-readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-readiness.d.ts","sourceRoot":"","sources":["../src/ai-readiness.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAIvE,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,cAAc,CAAC;IACtB,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,wDAAwD;IACxD,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAmCD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,qBAAqB,GAAG,gBAAgB,CAqQ1F"}