@shrkcrft/cli 0.1.0-alpha.2

package/dist/surface/tier.js

@@ -0,0 +1,172 @@
+import { CommandTier, } from "../commands/command-catalog.js";
+/**
+ * Bootstrap commands. Always tier=Core regardless of any other
+ * derivation rule. Listed here (and only here) so the rule is mechanical:
+ * a fresh repo with NO `sharkcraft.config.ts` can always reach these.
+ *
+ * Tokens are catalog `command` strings (the same form as
+ * {@link ICommandCatalogEntry.command}). Multi-token entries (e.g.
+ * `pack author status`) are matched exactly.
+ *
+ * Brutally small set. Discovery verbs (`commands`, `start-here`) live
+ * in extended tier; users find them via `shrk surface list` or `shrk
+ * recommend`.
+ */
+export const BOOTSTRAP_COMMANDS = Object.freeze([
+    'init',
+    'doctor',
+    'recommend',
+    'surface',
+    'help',
+    'version',
+    // Meta verbs that must always work. `--about` is a top-level
+    // meta flag handled in main.ts; included here for documentation
+    // completeness so `surface list` surfaces it.
+    '--about',
+]);
+/**
+ * Source explanations for tier classification. Returned by the
+ * resolver so `shrk surface explain <name>` can describe why a
+ * command's tier is what it is.
+ */
+export var TierSource;
+(function (TierSource) {
+    TierSource["Bootstrap"] = "bootstrap";
+    TierSource["Spine"] = "spine";
+    TierSource["PackContribution"] = "pack-contribution";
+    TierSource["Override"] = "override";
+    TierSource["Hidden"] = "hidden-flag";
+    TierSource["Default"] = "default";
+})(TierSource || (TierSource = {}));
+/**
+ * Mechanically derive a command's tier.
+ *
+ * Resolution order (HIGHEST wins, never demotes Core):
+ *
+ *   1. Bootstrap set → Core.
+ *   2. Spine pipeline reference → Core.
+ *   3. Pack contribution → Experimental (unless in surface.enabled).
+ *   4. Explicit catalog `tier` override → that value (cannot demote Core).
+ *   5. Catalog overlay `hidden` verdict → Experimental.
+ *   6. Otherwise → Extended.
+ *
+ * After derivation, the user's `surface.enabled` / `surface.hidden`
+ * config can flip a single dimension:
+ *
+ *   - `surface.enabled` contains the command → promote Experimental
+ *     to Extended (callable, visible in `surface list` only — `--help`
+ *     visibility is governed by the catalog's own defaultShowInHelp).
+ *   - `surface.hidden` contains the command AND tier is Extended →
+ *     remains Extended-tier but hidden from `--help`. The visibility
+ *     flip is read by the help renderer, not by the tier resolver
+ *     directly.
+ *
+ * Core commands cannot be hidden or disabled. Attempts to do so are
+ * surfaced as warnings by `shrk doctor` and `shrk surface list --json`.
+ */
+export function resolveTier(entry, context) {
+    const name = entry.command;
+    // 1. Bootstrap set always wins.
+    if (BOOTSTRAP_COMMANDS.includes(name)) {
+        return {
+            tier: CommandTier.Core,
+            source: TierSource.Bootstrap,
+            detail: 'bootstrap command (always on)',
+        };
+    }
+    // 2. Spine pipeline reference — also Core.
+    if (context.spineCommands.has(name)) {
+        return {
+            tier: CommandTier.Core,
+            source: TierSource.Spine,
+            detail: 'referenced from a spine pipeline',
+        };
+    }
+    // 3. Pack contributions default to Experimental, unless explicitly enabled.
+    const pack = context.packContributions.get(name);
+    if (pack !== undefined) {
+        const enabled = (context.surfaceConfig?.enabled ?? []).includes(name);
+        return {
+            tier: enabled ? CommandTier.Extended : CommandTier.Experimental,
+            source: TierSource.PackContribution,
+            detail: enabled
+                ? `pack-contributed (${pack}), enabled in surface.enabled`
+                : `pack-contributed (${pack})`,
+            configApplied: enabled,
+        };
+    }
+    // 4. Explicit override on the catalog entry.
+    if (entry.tier !== undefined) {
+        // Cannot demote Core. The override applies for Extended/Experimental only.
+        if (entry.tier === CommandTier.Experimental) {
+            const enabled = (context.surfaceConfig?.enabled ?? []).includes(name);
+            return {
+                tier: enabled ? CommandTier.Extended : CommandTier.Experimental,
+                source: TierSource.Override,
+                detail: 'catalog override (tier=experimental)',
+                configApplied: enabled,
+            };
+        }
+        return {
+            tier: entry.tier,
+            source: TierSource.Override,
+            detail: `catalog override (tier=${entry.tier})`,
+        };
+    }
+    // 5. Catalog overlay `hidden` verdict implies Experimental.
+    // We can't import the overlay here without a circular dep risk; the
+    // caller passes a precomputed view via context. For now, we rely on
+    // the catalog's surface=Internal/Legacy combined with showInDefaultHelp.
+    // If the entry is marked showInDefaultHelp: false explicitly, that's a
+    // weaker signal than the overlay but still pushes toward Experimental.
+    if (entry.showInDefaultHelp === false) {
+        const enabled = (context.surfaceConfig?.enabled ?? []).includes(name);
+        return {
+            tier: enabled ? CommandTier.Extended : CommandTier.Experimental,
+            source: TierSource.Hidden,
+            detail: 'showInDefaultHelp=false in catalog',
+            configApplied: enabled,
+        };
+    }
+    // 6. Default — Extended.
+    return {
+        tier: CommandTier.Extended,
+        source: TierSource.Default,
+        detail: 'default for catalog entries not in spine and not pack-contributed',
+    };
+}
+/**
+ * Is the command callable from the CLI / MCP in the current
+ * surface configuration?
+ *
+ *   - Core: always callable.
+ *   - Extended: always callable.
+ *   - Experimental: callable only if in `surface.enabled`.
+ *
+ * The resolver's promotion of Experimental → Extended already accounts
+ * for `enabled[]`, so this is a simple tier check.
+ */
+export function isCallable(resolution) {
+    return (resolution.tier === CommandTier.Core ||
+        resolution.tier === CommandTier.Extended);
+}
+/**
+ * Should the command be visible in `--help` output?
+ *
+ *   - Core: always visible.
+ *   - Extended: visible unless in `surface.hidden` (the help renderer
+ *     checks the config and consults `defaultShowInHelp(entry)`).
+ *   - Experimental: never visible in `--help`; only in `surface list`.
+ *
+ * The caller still consults `defaultShowInHelp(entry)` for the
+ * underlying surface/lifecycle gating; this function answers "does
+ * the tier permit visibility at all?".
+ */
+export function isVisibleInDefaultHelp(resolution, hiddenByConfig) {
+    if (resolution.tier === CommandTier.Core)
+        return true;
+    if (resolution.tier === CommandTier.Experimental)
+        return false;
+    // Extended: respects hidden[].
+    return !hiddenByConfig;
+}

package/dist/task-next/apply-batch-runner.d.ts

@@ -0,0 +1,42 @@
+export declare const APPLY_BATCH_SCHEMA = "sharkcraft.apply-batch.v1";
+export type BatchStepKind = 'action-hints' | 'knowledge-stale' | 'template-drift';
+export interface IApplyBatchStep {
+    readonly kind: BatchStepKind;
+    readonly args?: Readonly<Record<string, string | number | boolean | readonly string[]>>;
+}
+export interface IApplyBatchPlan {
+    readonly schema: typeof APPLY_BATCH_SCHEMA;
+    readonly steps: readonly IApplyBatchStep[];
+}
+export interface IApplyBatchStepResult {
+    readonly kind: BatchStepKind;
+    readonly stepIndex: number;
+    readonly exitCode: number;
+    readonly outcome: 'applied' | 'refused' | 'no-op' | 'error';
+    readonly stdoutJson?: unknown;
+    readonly stderr?: string;
+}
+export interface IApplyBatchReport {
+    readonly schema: 'sharkcraft.apply-batch-report/v1';
+    readonly batchId: string;
+    readonly allowDivergent: boolean;
+    readonly steps: readonly IApplyBatchStepResult[];
+    readonly stopped: boolean;
+    readonly success: boolean;
+}
+export declare class ApplyBatchPlanError extends Error {
+    constructor(message: string);
+}
+export declare function parseApplyBatchPlan(raw: string): IApplyBatchPlan;
+export declare function computeBatchId(plan: IApplyBatchPlan): string;
+export interface IRunApplyBatchOptions {
+    readonly plan: IApplyBatchPlan;
+    readonly allowDivergent: boolean;
+    readonly dryRun?: boolean;
+    /** Working directory for the spawned shrk processes. */
+    readonly cwd: string;
+    /** Absolute path to the `shrk` executable. */
+    readonly shrkBin: string;
+}
+export declare function runApplyBatch(options: IRunApplyBatchOptions): IApplyBatchReport;
+//# sourceMappingURL=apply-batch-runner.d.ts.map

package/dist/task-next/apply-batch-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-batch-runner.d.ts","sourceRoot":"","sources":["../../src/task-next/apply-batch-runner.ts"],"names":[],"mappings":"AA6BA,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAElF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;CACzF;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,kCAAkC,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAQD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAqDhE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAI5D;AAuBD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,qBAAqB,GAAG,iBAAiB,CAqE/E"}

package/dist/task-next/apply-batch-runner.js

@@ -0,0 +1,192 @@
+/**
+ * `shrk apply --batch <plan.json>` runner.
+ *
+ * Executes a multi-step fix-chain. Each step is a single `shrk` invocation
+ * with a stable kind keyword and forwarded args. The runner:
+ *
+ *   1. Parses the plan JSON, validates the schema and step kinds.
+ *   2. Computes a content-hash `batchId` for provenance grouping.
+ *   3. Runs each step in sequence with `--apply --json`.
+ *   4. Stops on the first refusal unless `--allow-divergent` is set.
+ *   5. Returns an aggregated structured report.
+ *
+ * Each underlying step is itself preview-first (it previews internally
+ * then writes), so a non-atomic batch matches the documented contract: a
+ * refusal in step N stops the batch but step N-1's writes are kept.
+ * With `--allow-divergent`, refused steps are skipped and survivors
+ * apply, identical to per-command semantics today.
+ *
+ * Supported step kinds:
+ *   - `action-hints`
+ *   - `knowledge-stale`
+ *   - `template-drift`
+ *
+ * Each step's `args` is a free-form record forwarded to the underlying
+ * CLI. The runner translates them to `--key value` / `--flag` form.
+ */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+export const APPLY_BATCH_SCHEMA = 'sharkcraft.apply-batch.v1';
+export class ApplyBatchPlanError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ApplyBatchPlanError';
+    }
+}
+const VALID_KINDS = new Set([
+    'action-hints',
+    'knowledge-stale',
+    'template-drift',
+]);
+export function parseApplyBatchPlan(raw) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new ApplyBatchPlanError(`Plan is not valid JSON: ${e.message}`);
+    }
+    if (!json || typeof json !== 'object') {
+        throw new ApplyBatchPlanError('Plan must be a JSON object.');
+    }
+    const o = json;
+    if (o.schema !== APPLY_BATCH_SCHEMA) {
+        throw new ApplyBatchPlanError(`Plan schema must be "${APPLY_BATCH_SCHEMA}".`);
+    }
+    if (!Array.isArray(o.steps)) {
+        throw new ApplyBatchPlanError('Plan.steps must be an array.');
+    }
+    const steps = [];
+    for (let i = 0; i < o.steps.length; i++) {
+        const s = o.steps[i];
+        if (!s || typeof s !== 'object') {
+            throw new ApplyBatchPlanError(`step[${i}] must be an object.`);
+        }
+        const kind = s.kind;
+        if (typeof kind !== 'string' || !VALID_KINDS.has(kind)) {
+            throw new ApplyBatchPlanError(`step[${i}].kind must be one of: ${[...VALID_KINDS].join(', ')}. Got ${JSON.stringify(kind)}.`);
+        }
+        const argsRaw = s.args;
+        if (argsRaw !== undefined && (typeof argsRaw !== 'object' || argsRaw === null || Array.isArray(argsRaw))) {
+            throw new ApplyBatchPlanError(`step[${i}].args must be a flat record if present.`);
+        }
+        const args = {};
+        if (argsRaw) {
+            for (const [k, v] of Object.entries(argsRaw)) {
+                if (typeof v === 'string' ||
+                    typeof v === 'number' ||
+                    typeof v === 'boolean' ||
+                    (Array.isArray(v) && v.every((x) => typeof x === 'string'))) {
+                    args[k] = v;
+                }
+                else {
+                    throw new ApplyBatchPlanError(`step[${i}].args.${k} must be string|number|boolean|string[]. Got ${JSON.stringify(v)}.`);
+                }
+            }
+        }
+        steps.push({ kind: kind, ...(Object.keys(args).length > 0 ? { args } : {}) });
+    }
+    return { schema: APPLY_BATCH_SCHEMA, steps };
+}
+export function computeBatchId(plan) {
+    const h = createHash('sha256');
+    h.update(JSON.stringify(plan));
+    return 'batch_' + h.digest('hex').slice(0, 12);
+}
+function buildCliArgs(step) {
+    // All batch steps target `shrk fix --<kind> --apply --json`.
+    const out = ['fix', `--${step.kind}`, '--apply', '--json'];
+    if (step.args) {
+        for (const [k, v] of Object.entries(step.args)) {
+            if (typeof v === 'boolean') {
+                if (v)
+                    out.push(`--${k}`);
+            }
+            else if (Array.isArray(v)) {
+                for (const item of v) {
+                    out.push(`--${k}`);
+                    out.push(item);
+                }
+            }
+            else {
+                out.push(`--${k}`);
+                out.push(String(v));
+            }
+        }
+    }
+    return out;
+}
+export function runApplyBatch(options) {
+    const { plan, allowDivergent, cwd, shrkBin, dryRun } = options;
+    const batchId = computeBatchId(plan);
+    const results = [];
+    let stopped = false;
+    let success = true;
+    for (let i = 0; i < plan.steps.length; i++) {
+        const step = plan.steps[i];
+        const cliArgs = buildCliArgs(step);
+        if (dryRun) {
+            results.push({
+                kind: step.kind,
+                stepIndex: i,
+                exitCode: 0,
+                outcome: 'no-op',
+                stdoutJson: { dryRun: true, command: `${shrkBin} ${cliArgs.join(' ')}` },
+            });
+            continue;
+        }
+        const proc = spawnSync(shrkBin, cliArgs, {
+            cwd,
+            encoding: 'utf8',
+            env: { ...process.env, SHARKCRAFT_BATCH_ID: batchId, SHARKCRAFT_BATCH_STEP: String(i) },
+        });
+        const exitCode = typeof proc.status === 'number' ? proc.status : 1;
+        let parsed = undefined;
+        try {
+            parsed = JSON.parse(proc.stdout ?? '{}');
+        }
+        catch {
+            // leave undefined
+        }
+        let outcome = 'applied';
+        if (exitCode !== 0) {
+            outcome = 'refused';
+        }
+        else if (parsed && typeof parsed === 'object') {
+            const m = parsed.mode;
+            if (m === 'refused')
+                outcome = 'refused';
+            else if (m === 'applied')
+                outcome = 'applied';
+            else
+                outcome = 'no-op';
+        }
+        else {
+            outcome = 'no-op';
+        }
+        results.push({
+            kind: step.kind,
+            stepIndex: i,
+            exitCode,
+            outcome,
+            ...(parsed !== undefined ? { stdoutJson: parsed } : {}),
+            ...(proc.stderr ? { stderr: proc.stderr } : {}),
+        });
+        if (outcome === 'refused' && !allowDivergent) {
+            stopped = true;
+            success = false;
+            break;
+        }
+        if (outcome === 'refused') {
+            success = false;
+        }
+    }
+    return {
+        schema: 'sharkcraft.apply-batch-report/v1',
+        batchId,
+        allowDivergent,
+        steps: results,
+        stopped,
+        success,
+    };
+}

package/dist/task-next/task-next-ranker.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `shrk task --next` ranker.
+ *
+ * Surveys the workspace, partitions findings by mechanical safety, and
+ * proposes the single highest-leverage next action. Pure ranker over
+ * existing JSON outputs — no new asset kinds, no AI, no domain logic
+ * besides priority order.
+ *
+ * Ranking rules (deterministic, documented in dev-workflow.md):
+ *   1. Doctor blockers (errors that fail-close release).
+ *   2. Stale knowledge with `replaceWith` (mechanically safe --apply).
+ *   3. Template drift `missing-barrel` (mechanically safe --apply).
+ *   4. Action-hint stubs (mechanically safe --apply).
+ *   5. Stale knowledge without `replaceWith` (needs --drop-stale).
+ *   6. Template drift `forbidden-legacy-path` (needs human review).
+ *   7. Everything else (preview-only).
+ */
+import type { IDoctorResult, IKnowledgeStaleReport, ITemplateDriftReport } from '@shrkcrft/inspector';
+export declare const TASK_NEXT_SCHEMA = "sharkcraft.task-next/v1";
+export type NextActionKind = 'fix' | 'apply' | 'investigate';
+export interface INextAction {
+    readonly kind: NextActionKind;
+    readonly command: string;
+    readonly reason: string;
+    /** How many blockers / findings this action resolves. */
+    readonly resolves: number;
+    /** True iff the action's --apply path is mechanically safe (no human review). */
+    readonly autoApplyEligible: boolean;
+}
+export interface ITaskNextReport {
+    readonly schema: typeof TASK_NEXT_SCHEMA;
+    readonly generatedAt: string;
+    readonly nextAction: INextAction | null;
+    /** Up to 3 follow-on actions in descending priority order. */
+    readonly secondary: readonly {
+        command: string;
+        reason: string;
+    }[];
+    /** Quick totals so the agent can sanity-check the ranker. */
+    readonly totals: {
+        readonly doctorBlockers: number;
+        readonly staleWithReplaceWith: number;
+        readonly staleWithoutReplaceWith: number;
+        readonly templateDriftMissingBarrel: number;
+        readonly templateDriftForbiddenLegacyPath: number;
+        readonly templateDriftOther: number;
+        readonly knowledgeActionHintGaps: number;
+    };
+}
+export interface ITaskNextInputs {
+    readonly doctor: IDoctorResult;
+    readonly stale: IKnowledgeStaleReport;
+    readonly drift: ITemplateDriftReport;
+    /**
+     * Knowledge lint summary — used for the action-hint stubs leg. The
+     * shape mirrors the `shrk lint --kind knowledge` JSON.
+     */
+    readonly knowledgeLint?: {
+        readonly categories?: Readonly<Record<string, number>>;
+    };
+    /**
+     * Spec status summary. The ranker picks the highest-leverage
+     * unverified spec as a next action when no doctor blockers exist.
+     * Pass-through `null` (or omit) when the workspace has no specs.
+     */
+    readonly specs?: {
+        readonly implementingUnverified?: readonly {
+            id: string;
+            title: string;
+        }[];
+    };
+}
+/** Pure ranking over the structured inputs. */
+export declare function buildTaskNextReport(inputs: ITaskNextInputs): ITaskNextReport;
+//# sourceMappingURL=task-next-ranker.d.ts.map

package/dist/task-next/task-next-ranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-next-ranker.d.ts","sourceRoot":"","sources":["../../src/task-next/task-next-ranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAE1D,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,OAAO,GAAG,aAAa,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,gBAAgB,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,WAAW,GAAG,IAAI,CAAC;IACxC,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnE,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;QACtC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;QACzC,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;QAC5C,QAAQ,CAAC,gCAAgC,EAAE,MAAM,CAAC;QAClD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;QACpC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;KAC1C,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KACxD,CAAC;IACF;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KAC5E,CAAC;CACH;AAWD,+CAA+C;AAC/C,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAkL5E"}

package/dist/task-next/task-next-ranker.js

@@ -0,0 +1,179 @@
+export const TASK_NEXT_SCHEMA = 'sharkcraft.task-next/v1';
+const BLOCKER_CATEGORIES = new Set([
+    'config-invalid',
+    'pack-signature-invalid',
+    'plan-signature-divergent',
+    'asset-load-failed',
+    'config',
+    'pack-doctor',
+]);
+/** Pure ranking over the structured inputs. */
+export function buildTaskNextReport(inputs) {
+    const { doctor, stale, drift, knowledgeLint, specs } = inputs;
+    // 1. Doctor blockers — errors + warning-categories that gate release.
+    // Mirrors `shrk doctor --blockers` semantics.
+    const doctorBlockers = doctor.checks.filter((c) => c.severity === 'error' ||
+        (c.severity === 'warning' && c.category !== undefined && BLOCKER_CATEGORIES.has(c.category))).length;
+    // 2. Stale knowledge with replaceWith.
+    const staleChecks = stale.referenceChecks.filter((c) => c.outcome === 'stale' || c.outcome === 'missing');
+    const staleWithReplaceWith = staleChecks.filter((c) => c.replaceWith).length;
+    const staleWithoutReplaceWith = staleChecks.length - staleWithReplaceWith;
+    // 3 & 6. Template drift split by code.
+    let templateDriftMissingBarrel = 0;
+    let templateDriftForbiddenLegacyPath = 0;
+    let templateDriftOther = 0;
+    for (const e of drift.entries) {
+        for (const i of e.issues) {
+            if (i.severity !== 'error' && i.severity !== 'warning')
+                continue;
+            if (i.code === 'missing-barrel')
+                templateDriftMissingBarrel += 1;
+            else if (i.code === 'forbidden-legacy-path')
+                templateDriftForbiddenLegacyPath += 1;
+            else
+                templateDriftOther += 1;
+        }
+    }
+    // 4. Action-hint stubs from the knowledge lint.
+    const cats = knowledgeLint?.categories ?? {};
+    const knowledgeActionHintGaps = (cats['missing-action-hints'] ?? 0) + (cats['safe-mechanical-stub'] ?? 0);
+    const totals = {
+        doctorBlockers,
+        staleWithReplaceWith,
+        staleWithoutReplaceWith,
+        templateDriftMissingBarrel,
+        templateDriftForbiddenLegacyPath,
+        templateDriftOther,
+        knowledgeActionHintGaps,
+    };
+    const secondary = [];
+    let nextAction = null;
+    // Priority 1 — doctor blockers.
+    if (doctorBlockers > 0) {
+        nextAction = {
+            kind: 'fix',
+            command: 'shrk doctor --blockers',
+            reason: `${doctorBlockers} blocker(s) — release is gated until these clear.`,
+            resolves: doctorBlockers,
+            autoApplyEligible: false,
+        };
+    }
+    // Priority 1.5: specs in `implementing` status that have NOT
+    // passed `spec verify`. Surfaced after doctor blockers but before
+    // stale-knowledge fixes — closing the spec loop is the highest-
+    // leverage next step once blockers are clear.
+    const implementingUnverified = specs?.implementingUnverified ?? [];
+    if (!nextAction && implementingUnverified.length > 0) {
+        const target = implementingUnverified[0];
+        nextAction = {
+            kind: 'investigate',
+            command: `shrk spec verify ${target.id}`,
+            reason: `Spec "${target.id}" is implementing but has no passing verification yet — close the loop.`,
+            resolves: implementingUnverified.length,
+            autoApplyEligible: false,
+        };
+    }
+    else if (implementingUnverified.length > 0) {
+        secondary.push({
+            command: `shrk spec verify ${implementingUnverified[0].id}`,
+            reason: `${implementingUnverified.length} spec(s) implementing without verification.`,
+        });
+    }
+    // Priority 2 — stale knowledge with replaceWith.
+    if (!nextAction && staleWithReplaceWith > 0) {
+        nextAction = {
+            kind: 'apply',
+            command: 'shrk fix --knowledge-stale --apply',
+            reason: `${staleWithReplaceWith} stale reference(s) have a replaceWith signal — apply renames in place.`,
+            resolves: staleWithReplaceWith,
+            autoApplyEligible: true,
+        };
+    }
+    else if (staleWithReplaceWith > 0) {
+        secondary.push({
+            command: 'shrk fix --knowledge-stale --apply',
+            reason: `${staleWithReplaceWith} stale reference(s) with replaceWith.`,
+        });
+    }
+    // Priority 3 — template drift missing-barrel.
+    if (!nextAction && templateDriftMissingBarrel > 0) {
+        nextAction = {
+            kind: 'apply',
+            command: 'shrk fix --template-drift --apply',
+            reason: `${templateDriftMissingBarrel} missing-barrel finding(s) — creates the file with a placeholder body.`,
+            resolves: templateDriftMissingBarrel,
+            autoApplyEligible: true,
+        };
+    }
+    else if (templateDriftMissingBarrel > 0) {
+        secondary.push({
+            command: 'shrk fix --template-drift --apply',
+            reason: `${templateDriftMissingBarrel} missing-barrel finding(s).`,
+        });
+    }
+    // Priority 4 — action-hint stubs.
+    if (!nextAction && knowledgeActionHintGaps > 0) {
+        nextAction = {
+            kind: 'apply',
+            command: 'shrk fix --action-hints --apply',
+            reason: `${knowledgeActionHintGaps} knowledge entr(y/ies) missing action hints — stubs are mechanically safe.`,
+            resolves: knowledgeActionHintGaps,
+            autoApplyEligible: true,
+        };
+    }
+    else if (knowledgeActionHintGaps > 0) {
+        secondary.push({
+            command: 'shrk fix --action-hints --apply',
+            reason: `${knowledgeActionHintGaps} action-hint stub(s).`,
+        });
+    }
+    // Priority 5 — stale knowledge without replaceWith.
+    if (!nextAction && staleWithoutReplaceWith > 0) {
+        nextAction = {
+            kind: 'investigate',
+            command: 'shrk knowledge stale-check --ci',
+            reason: `${staleWithoutReplaceWith} stale reference(s) without an unambiguous rename — review then re-run with --drop-stale.`,
+            resolves: staleWithoutReplaceWith,
+            autoApplyEligible: false,
+        };
+    }
+    else if (staleWithoutReplaceWith > 0) {
+        secondary.push({
+            command: 'shrk knowledge stale-check --ci',
+            reason: `${staleWithoutReplaceWith} stale reference(s) need human review.`,
+        });
+    }
+    // Priority 6 — template drift forbidden-legacy-path.
+    if (!nextAction && templateDriftForbiddenLegacyPath > 0) {
+        nextAction = {
+            kind: 'investigate',
+            command: 'shrk templates drift --min-severity warning',
+            reason: `${templateDriftForbiddenLegacyPath} forbidden-legacy-path finding(s) — needs human decision on convention.`,
+            resolves: templateDriftForbiddenLegacyPath,
+            autoApplyEligible: false,
+        };
+    }
+    else if (templateDriftForbiddenLegacyPath > 0) {
+        secondary.push({
+            command: 'shrk templates drift --min-severity warning',
+            reason: `${templateDriftForbiddenLegacyPath} forbidden-legacy-path finding(s).`,
+        });
+    }
+    // Priority 7 — everything else.
+    if (!nextAction && templateDriftOther > 0) {
+        nextAction = {
+            kind: 'investigate',
+            command: 'shrk templates drift --min-severity warning',
+            reason: `${templateDriftOther} other template-drift finding(s) — preview-only.`,
+            resolves: templateDriftOther,
+            autoApplyEligible: false,
+        };
+    }
+    return {
+        schema: TASK_NEXT_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        nextAction,
+        secondary: secondary.slice(0, 3),
+        totals,
+    };
+}