@neuraloom/contracts 0.0.0-stage → 0.1.23

package/dist/workflow/workflow-assurance-manifest.js

@@ -0,0 +1,309 @@
+"use strict";
+/**
+ * Workflow Assurance Manifest — registry-derived SSOT for browser harness selectors.
+ *
+ * Pure derivation from channel registry, WORKFLOW_STEPS (software foundation),
+ * step-id-canonical, film nav aliases, and wiring-tier overrides.
+ * No runtime workflow behavior changes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKFLOW_ASSURANCE_MANIFEST = exports.WORKFLOW_ASSURANCE_LEGACY_ROUTE_PATTERNS = exports.WORKFLOW_ASSURANCE_MANIFEST_VERSION = void 0;
+exports.buildWorkflowAssuranceManifest = buildWorkflowAssuranceManifest;
+exports.getAssuranceActiveVariants = getAssuranceActiveVariants;
+exports.getAssuranceVariantSummaries = getAssuranceVariantSummaries;
+const workflow_registry_1 = require("../constants/workflow-registry");
+const channel_registry_1 = require("./channel-registry");
+const film_spine_nav_aliases_1 = require("./film-spine-nav-aliases");
+const step_id_canonical_1 = require("./step-id-canonical");
+const workflow_assurance_wiring_tiers_1 = require("./workflow-assurance-wiring-tiers");
+exports.WORKFLOW_ASSURANCE_MANIFEST_VERSION = '1.0.0';
+/** Routes the harness must never treat as canonical operator paths. */
+exports.WORKFLOW_ASSURANCE_LEGACY_ROUTE_PATTERNS = [
+    '/film/**',
+    '/quality',
+    '/scan',
+];
+const SOFTWARE_FOUNDATION_STEP_IDS = [
+    'integrations',
+    'repo',
+    'ingest',
+    'team',
+];
+const FOUNDATION_ORCHESTRATOR_KEYS = {
+    integrations: 'foundationIntegrations',
+    repo: 'foundationRepo',
+    ingest: 'foundationIngest',
+    team: 'foundationTeam',
+};
+const FOUNDATION_DISPLAY_KEYS = {
+    integrations: 'IntegrationsPanel',
+    repo: 'RepositoryPanel',
+    ingest: 'IngestDashboard',
+    team: 'TeamPanel',
+};
+function collectNavAliases(stepId, routePath) {
+    const aliases = new Set();
+    for (const [navKey, canonicalId] of Object.entries(step_id_canonical_1.REGISTRY_WORKFLOW_STEP_ID_BY_NAV_KEY)) {
+        if (canonicalId === stepId && navKey !== stepId) {
+            aliases.add(navKey);
+        }
+    }
+    for (const [aliasPath, canonicalPath] of Object.entries(step_id_canonical_1.WORKFLOW_STEP_ROUTE_PATH_ALIASES)) {
+        if (canonicalPath === routePath && aliasPath !== routePath) {
+            aliases.add(aliasPath);
+        }
+    }
+    for (const [from, to] of step_id_canonical_1.WORKFLOW_STEP_ID_ALIAS_PAIRS) {
+        if (to === stepId && from !== stepId) {
+            aliases.add(from);
+        }
+    }
+    return [...aliases];
+}
+function resolveCompletionProbe(variant, stepId, channelCompletion) {
+    if (variant === 'film_production') {
+        return 'film_domain';
+    }
+    if (stepId === 'ingest') {
+        return 'ingest_gate';
+    }
+    if (stepId === 'ci' || stepId === 'deploy' || stepId === 'deployments') {
+        return 'cicd_ready';
+    }
+    if (channelCompletion !== undefined) {
+        return 'workflow_artifacts';
+    }
+    return 'none';
+}
+function buildCompletionFromChannel(step) {
+    return {
+        mode: step.completion.mode,
+        requiredStageIds: [...step.completion.requiredStageIds],
+        ...(step.completion.finalStageId !== undefined
+            ? { finalStageId: step.completion.finalStageId }
+            : {}),
+        probe: 'workflow_artifacts',
+    };
+}
+function buildFoundationCompletion(stepId) {
+    if (stepId === 'ingest') {
+        return { mode: 'external_gate', requiredStageIds: [], probe: 'ingest_gate' };
+    }
+    return { mode: 'external_gate', requiredStageIds: [], probe: 'none' };
+}
+function resolveStepStatus(variant, step, channelExperimental) {
+    if (step.deprecated === true) {
+        return 'deprecated';
+    }
+    if (step.experimental === true || channelExperimental === true) {
+        return 'experimental';
+    }
+    if ((0, workflow_assurance_wiring_tiers_1.isAssurancePlannedStep)(variant, step.stepId)) {
+        return 'planned';
+    }
+    return 'active';
+}
+function resolveFoundationStatus(_stepId) {
+    return 'active';
+}
+function legacyRoutesForStep(stepId, routePath) {
+    const legacy = [];
+    if (stepId === 'scan' || routePath === '/scan') {
+        legacy.push('/scan');
+    }
+    if (legacy.length === 0) {
+        return undefined;
+    }
+    return legacy;
+}
+/**
+ * Derive the data-action values the browser harness must trigger to advance this step.
+ * Foundation/config steps (producesArtifacts=false) require no automated actions.
+ */
+function inferRequiredActions(stepId, producesArtifacts) {
+    if (!producesArtifacts)
+        return [];
+    if (stepId === 'review' || stepId === 'patch-review')
+        return ['generate', 'approve'];
+    if (stepId === 'ci' || stepId === 'deploy' || stepId === 'deployments')
+        return ['ship'];
+    return ['generate'];
+}
+/**
+ * Infer which AI/media provider kinds are needed to produce artifacts for this step.
+ * film_production adds Runway because video generation is part of its pipeline.
+ */
+function inferRequiredProviderKinds(variant, producesArtifacts) {
+    if (!producesArtifacts)
+        return [];
+    if (variant === 'film_production')
+        return ['openai', 'runway'];
+    return ['openai'];
+}
+/**
+ * Collect the artifact stage IDs this step must produce.
+ * Deduplicates finalStageId against requiredStageIds.
+ */
+function collectRequiredArtifacts(completion) {
+    const ids = new Set(completion.requiredStageIds);
+    if (completion.finalStageId)
+        ids.add(completion.finalStageId);
+    return [...ids];
+}
+function computeAssuranceBlockers(status, pageExists) {
+    const blockers = [];
+    if (status === 'deprecated')
+        blockers.push('step-deprecated');
+    if (status === 'planned')
+        blockers.push('no-gp-scenario');
+    if (status === 'experimental')
+        blockers.push('step-experimental');
+    if (!pageExists)
+        blockers.push('page-missing');
+    return blockers;
+}
+function computeCoverageTier(status, pageExists) {
+    if (status === 'deprecated' || !pageExists)
+        return 'blocked';
+    if (status === 'planned')
+        return 'planned';
+    if (status === 'experimental')
+        return 'experimental';
+    return 'active';
+}
+function channelStepToAssurance(variant, step, channelExperimental) {
+    const stepId = (0, step_id_canonical_1.resolveCanonicalWorkflowStepId)(step.stepId);
+    const routePath = (0, step_id_canonical_1.resolveWorkflowStepRoutePath)(step.routePath);
+    const navAliases = [
+        ...collectNavAliases(stepId, routePath),
+        ...(variant === 'film_production' ? (0, film_spine_nav_aliases_1.getFilmNavAliasesForStep)(stepId) : []),
+    ];
+    const legacy = legacyRoutesForStep(stepId, routePath);
+    const status = resolveStepStatus(variant, step, channelExperimental);
+    const wiringTier = (0, workflow_assurance_wiring_tiers_1.resolveAssuranceWiringTier)(variant, stepId);
+    const producesArtifacts = step.producedArtifacts.length > 0;
+    const completion = {
+        ...buildCompletionFromChannel(step),
+        probe: resolveCompletionProbe(variant, stepId, step.completion),
+    };
+    const blockers = computeAssuranceBlockers(status, true);
+    const coverageTier = computeCoverageTier(status, true);
+    return {
+        variant,
+        stepId,
+        navAliases,
+        route: routePath,
+        pageExists: true,
+        orchestratorKey: step.orchestratorKey,
+        displayComponentKey: step.displayComponentKey,
+        apiRouteKey: step.apiRouteKey,
+        completion,
+        gates: step.gates.map((g) => g.gateId),
+        status,
+        producesArtifacts,
+        ...(legacy !== undefined ? { legacyRoutes: legacy } : {}),
+        wiringTier,
+        requiredActions: inferRequiredActions(stepId, producesArtifacts),
+        requiredArtifacts: collectRequiredArtifacts(completion),
+        requiredProviderKinds: inferRequiredProviderKinds(variant, producesArtifacts),
+        requiredComponents: [step.displayComponentKey],
+        isBrowserAssurable: status === 'active',
+        assuranceBlockers: blockers,
+        coverageTier,
+    };
+}
+function foundationStepToAssurance(stepId) {
+    const registryStep = workflow_registry_1.WORKFLOW_STEPS.find((s) => s.id === stepId);
+    const routePath = registryStep?.path ?? `/${stepId}`;
+    const canonicalId = (0, step_id_canonical_1.resolveCanonicalWorkflowStepId)(stepId);
+    const resolvedRoute = (0, step_id_canonical_1.resolveWorkflowStepRoutePath)(routePath);
+    const pageExists = registryStep !== undefined;
+    const status = resolveFoundationStatus(stepId);
+    const completion = buildFoundationCompletion(stepId);
+    return {
+        variant: 'software_app',
+        stepId: canonicalId,
+        navAliases: collectNavAliases(canonicalId, resolvedRoute),
+        route: resolvedRoute,
+        pageExists,
+        orchestratorKey: FOUNDATION_ORCHESTRATOR_KEYS[stepId] ?? `foundation.${stepId}`,
+        displayComponentKey: FOUNDATION_DISPLAY_KEYS[stepId] ?? `Foundation.${stepId}Display`,
+        completion,
+        gates: [],
+        status,
+        producesArtifacts: false,
+        wiringTier: (0, workflow_assurance_wiring_tiers_1.resolveAssuranceWiringTier)('software_app', canonicalId),
+        requiredActions: [],
+        requiredArtifacts: [],
+        requiredProviderKinds: [],
+        requiredComponents: [FOUNDATION_DISPLAY_KEYS[stepId] ?? `Foundation.${stepId}Display`],
+        isBrowserAssurable: status === 'active' && pageExists,
+        assuranceBlockers: computeAssuranceBlockers(status, pageExists),
+        coverageTier: computeCoverageTier(status, pageExists),
+    };
+}
+function buildSoftwareAppSteps() {
+    const channel = channel_registry_1.WORKFLOW_CHANNEL_REGISTRY.software_app;
+    const channelStepIds = new Set(channel.steps.map((s) => (0, step_id_canonical_1.resolveCanonicalWorkflowStepId)(s.stepId)));
+    const foundationSteps = SOFTWARE_FOUNDATION_STEP_IDS.filter((id) => !channelStepIds.has((0, step_id_canonical_1.resolveCanonicalWorkflowStepId)(id))).map((id) => foundationStepToAssurance(id));
+    const channelSteps = channel.steps.map((step) => channelStepToAssurance('software_app', step, channel.experimental));
+    return [...foundationSteps, ...channelSteps];
+}
+function buildVariantSteps(variant) {
+    if (variant === 'software_app') {
+        return buildSoftwareAppSteps();
+    }
+    const channel = channel_registry_1.WORKFLOW_CHANNEL_REGISTRY[variant];
+    return channel.steps.map((step) => channelStepToAssurance(variant, step, channel.experimental));
+}
+function buildVariantSummary(variant, steps) {
+    const nonDeprecated = steps.filter((s) => s.status !== 'deprecated');
+    const activeSteps = steps.filter((s) => s.status === 'active');
+    const browserAssurableSteps = steps.filter((s) => s.isBrowserAssurable);
+    const allBlockers = new Set();
+    for (const step of nonDeprecated) {
+        for (const b of step.assuranceBlockers)
+            allBlockers.add(b);
+    }
+    let coverageTier = 'blocked';
+    if (nonDeprecated.some((s) => s.coverageTier === 'active'))
+        coverageTier = 'active';
+    else if (nonDeprecated.some((s) => s.coverageTier === 'planned'))
+        coverageTier = 'planned';
+    else if (nonDeprecated.some((s) => s.coverageTier === 'experimental'))
+        coverageTier = 'experimental';
+    return {
+        variant,
+        isBrowserAssurable: browserAssurableSteps.length > 0,
+        coverageTier,
+        assuranceBlockers: [...allBlockers],
+        activeStepCount: activeSteps.length,
+        browserAssurableStepCount: browserAssurableSteps.length,
+    };
+}
+/** Build the full assurance manifest from registry SSOT (pure, deterministic). */
+function buildWorkflowAssuranceManifest() {
+    const variants = {};
+    const summaries = {};
+    for (const variant of channel_registry_1.WORKFLOW_VARIANTS) {
+        const steps = buildVariantSteps(variant);
+        variants[variant] = steps;
+        summaries[variant] = buildVariantSummary(variant, steps);
+    }
+    return {
+        version: exports.WORKFLOW_ASSURANCE_MANIFEST_VERSION,
+        legacyRoutePatterns: exports.WORKFLOW_ASSURANCE_LEGACY_ROUTE_PATTERNS,
+        variants,
+        summaries,
+    };
+}
+/** Pre-built manifest singleton for importers that need a stable reference. */
+exports.WORKFLOW_ASSURANCE_MANIFEST = buildWorkflowAssuranceManifest();
+/** Active channel variants that must appear in the manifest with at least one step. */
+function getAssuranceActiveVariants() {
+    return (0, channel_registry_1.getActiveVariants)();
+}
+/** Variant-level coverage summaries — ready for management dashboards and CI reports. */
+function getAssuranceVariantSummaries() {
+    return channel_registry_1.WORKFLOW_VARIANTS.map((v) => exports.WORKFLOW_ASSURANCE_MANIFEST.summaries[v]);
+}

package/dist/workflow/workflow-assurance-wiring-tiers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wiring-tier overrides for workflow assurance status.
+ *
+ * Mirrors `canonical_planned` entries in
+ * `packages/frontend/src/lib/workflow/__tests__/workflow-full-wiring-audit.test.ts`.
+ * Step lists are NOT duplicated here — only variant×stepId status overrides.
+ */
+import type { WorkflowVariant } from './channel-registry';
+export type WorkflowAssuranceWiringTier = 'canonical_active' | 'canonical_planned';
+/** variant:stepId keys with canonical_planned wiring (harness may warn, not hard-fail). */
+export declare const WORKFLOW_ASSURANCE_PLANNED_STEP_KEYS: ReadonlySet<string>;
+export declare function isAssurancePlannedStep(variant: WorkflowVariant, stepId: string): boolean;
+export declare function resolveAssuranceWiringTier(variant: WorkflowVariant, stepId: string): WorkflowAssuranceWiringTier;

package/dist/workflow/workflow-assurance-wiring-tiers.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Wiring-tier overrides for workflow assurance status.
+ *
+ * Mirrors `canonical_planned` entries in
+ * `packages/frontend/src/lib/workflow/__tests__/workflow-full-wiring-audit.test.ts`.
+ * Step lists are NOT duplicated here — only variant×stepId status overrides.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKFLOW_ASSURANCE_PLANNED_STEP_KEYS = void 0;
+exports.isAssurancePlannedStep = isAssurancePlannedStep;
+exports.resolveAssuranceWiringTier = resolveAssuranceWiringTier;
+/** variant:stepId keys with canonical_planned wiring (harness may warn, not hard-fail). */
+exports.WORKFLOW_ASSURANCE_PLANNED_STEP_KEYS = new Set([
+    // software_app — schema step is active in the app but not yet in any GP scenario
+    'software_app:schema',
+    'research_report:specify',
+    'research_report:tasks',
+    'screenplay:specify',
+    'screenplay:review',
+    'film_production:development',
+    'film_production:script',
+    'film_production:preproduction',
+    'film_production:postproduction',
+    'film_production:release',
+]);
+function isAssurancePlannedStep(variant, stepId) {
+    return exports.WORKFLOW_ASSURANCE_PLANNED_STEP_KEYS.has(`${variant}:${stepId}`);
+}
+function resolveAssuranceWiringTier(variant, stepId) {
+    return isAssurancePlannedStep(variant, stepId) ? 'canonical_planned' : 'canonical_active';
+}

package/dist/workflow/workflow-doctor-closure.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pure helpers for Workflow Doctor closure visibility (#943).
+ * No I/O — safe for unit tests and SSR compute wiring.
+ */
+import type { WorkflowDoctorChannelSummary, WorkflowDoctorClosure, WorkflowDoctorCompletionBlocker, WorkflowDoctorMappingHint, WorkflowDoctorStepArtifactCoverage, WorkflowDoctorStepReport } from '../schemas/workflow/workflow-doctor.schema';
+import type { WorkflowChannelDefinition, WorkflowVariant } from './channel-registry';
+import type { ProjectForVariantResolution } from './resolve-workflow-variant';
+/** Max blockers returned so the Doctor UI stays scannable. */
+export declare const WORKFLOW_DOCTOR_CLOSURE_BLOCKER_CAP = 24;
+export declare function deriveWorkflowDoctorMappingHints(row: ProjectForVariantResolution, resolvedVariant: WorkflowVariant): WorkflowDoctorMappingHint[];
+export declare function isSoftwareChannelDeprecatedStep(stepId: string): boolean;
+export declare function filterSoftwareDoctorActiveChannelSteps(channel: WorkflowChannelDefinition): WorkflowChannelDefinition['steps'];
+export declare function buildWorkflowDoctorChannelSummary(channel: WorkflowChannelDefinition): WorkflowDoctorChannelSummary;
+export declare function buildWorkflowDoctorStepArtifactCoverage(channel: WorkflowChannelDefinition, stepReports: WorkflowDoctorStepReport[]): WorkflowDoctorStepArtifactCoverage[];
+export declare function deriveWorkflowDoctorCompletionBlockers(channel: WorkflowChannelDefinition, stepReports: WorkflowDoctorStepReport[], acceptedArtifactTypes: ReadonlySet<string>): WorkflowDoctorCompletionBlocker[];
+export declare function buildWorkflowDoctorClosure(channel: WorkflowChannelDefinition, row: ProjectForVariantResolution, resolvedVariant: WorkflowVariant, stepReports: WorkflowDoctorStepReport[], acceptedArtifactTypes: ReadonlySet<string>): WorkflowDoctorClosure;

package/dist/workflow/workflow-doctor-closure.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * Pure helpers for Workflow Doctor closure visibility (#943).
+ * No I/O — safe for unit tests and SSR compute wiring.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKFLOW_DOCTOR_CLOSURE_BLOCKER_CAP = void 0;
+exports.deriveWorkflowDoctorMappingHints = deriveWorkflowDoctorMappingHints;
+exports.isSoftwareChannelDeprecatedStep = isSoftwareChannelDeprecatedStep;
+exports.filterSoftwareDoctorActiveChannelSteps = filterSoftwareDoctorActiveChannelSteps;
+exports.buildWorkflowDoctorChannelSummary = buildWorkflowDoctorChannelSummary;
+exports.buildWorkflowDoctorStepArtifactCoverage = buildWorkflowDoctorStepArtifactCoverage;
+exports.deriveWorkflowDoctorCompletionBlockers = deriveWorkflowDoctorCompletionBlockers;
+exports.buildWorkflowDoctorClosure = buildWorkflowDoctorClosure;
+const workflow_registry_1 = require("../constants/workflow-registry");
+const resolve_workflow_variant_1 = require("./resolve-workflow-variant");
+const DEFAULT_VARIANT = 'software_app';
+/** Max blockers returned so the Doctor UI stays scannable. */
+exports.WORKFLOW_DOCTOR_CLOSURE_BLOCKER_CAP = 24;
+function deriveWorkflowDoctorMappingHints(row, resolvedVariant) {
+    const hints = [];
+    const explicitRaw = row.workflow_variant?.trim();
+    if (explicitRaw && !(0, resolve_workflow_variant_1.isValidWorkflowVariant)(explicitRaw)) {
+        hints.push({
+            kind: 'invalid_explicit_variant_coerced',
+            message: `Stored workflow_variant "${explicitRaw}" is not a canonical variant key; resolution used legacy kind fields or the default spine.`,
+        });
+    }
+    if (explicitRaw && (0, resolve_workflow_variant_1.isValidWorkflowVariant)(explicitRaw)) {
+        hints.push({
+            kind: 'explicit_variant_resolved',
+            message: `Using explicit workflow_variant: ${explicitRaw}.`,
+        });
+        return hints;
+    }
+    const legacyKind = row.project_kind ?? row.kind;
+    const mapped = legacyKind !== undefined && legacyKind !== null && legacyKind !== ''
+        ? resolve_workflow_variant_1.LEGACY_KIND_TO_WORKFLOW_VARIANT[legacyKind]
+        : undefined;
+    if (legacyKind && mapped !== undefined) {
+        const kindLabel = row.project_kind !== undefined && row.project_kind !== null && row.project_kind !== ''
+            ? 'legacy_project_kind_mapped'
+            : 'legacy_kind_field_mapped';
+        hints.push({
+            kind: kindLabel,
+            message: `Mapped legacy kind "${legacyKind}" → ${mapped} (resolved spine: ${resolvedVariant}).`,
+        });
+        return hints;
+    }
+    if (legacyKind) {
+        hints.push({
+            kind: 'unknown_legacy_kind_defaulted',
+            message: `Legacy kind "${legacyKind}" has no registry mapping; defaulted to ${resolvedVariant}.`,
+        });
+        return hints;
+    }
+    hints.push({
+        kind: 'fallback_default_variant',
+        message: `No workflow_variant or legacy kind present; defaulted to ${DEFAULT_VARIANT} (resolved: ${resolvedVariant}).`,
+    });
+    return hints;
+}
+const deprecatedChannelStepIdSet = new Set(workflow_registry_1.SOFTWARE_CHANNEL_DEPRECATED_STEP_IDS);
+function isSoftwareChannelDeprecatedStep(stepId) {
+    return deprecatedChannelStepIdSet.has(stepId);
+}
+function filterSoftwareDoctorActiveChannelSteps(channel) {
+    if (channel.variant !== 'software_app') {
+        return channel.steps.filter((step) => step.deprecated !== true);
+    }
+    return channel.steps.filter((step) => step.deprecated !== true && !isSoftwareChannelDeprecatedStep(step.stepId));
+}
+function buildWorkflowDoctorChannelSummary(channel) {
+    const experimentalStepIds = channel.steps.filter(s => s.experimental === true).map(s => s.stepId);
+    const deprecatedChannelStepIds = channel.variant === 'software_app'
+        ? channel.steps
+            .filter((step) => step.deprecated === true || isSoftwareChannelDeprecatedStep(step.stepId))
+            .map((step) => step.stepId)
+        : channel.steps.filter((step) => step.deprecated === true).map((step) => step.stepId);
+    const activeChannelSteps = filterSoftwareDoctorActiveChannelSteps(channel);
+    const stepCount = channel.variant === 'software_app'
+        ? workflow_registry_1.SOFTWARE_OPERATOR_NAV_STEP_IDS.length
+        : activeChannelSteps.length;
+    return {
+        variant: channel.variant,
+        family: channel.family,
+        channelLabel: channel.label,
+        channelDescription: channel.description,
+        workflowVersion: channel.workflowVersion,
+        projectKind: channel.projectKind,
+        stepCount,
+        experimentalStepIds,
+        ...(channel.variant === 'software_app'
+            ? {
+                operatorNavStepCount: workflow_registry_1.SOFTWARE_OPERATOR_NAV_STEP_IDS.length,
+                deprecatedChannelStepIds,
+            }
+            : deprecatedChannelStepIds.length > 0
+                ? { deprecatedChannelStepIds }
+                : {}),
+    };
+}
+function buildWorkflowDoctorStepArtifactCoverage(channel, stepReports) {
+    const byStep = new Map(stepReports.map(r => [r.stepId, r]));
+    return channel.steps.map(stepDef => {
+        const report = byStep.get(stepDef.stepId);
+        const stages = report?.stages ?? [];
+        let presentAccepted = 0;
+        let presentPending = 0;
+        let presentRejected = 0;
+        let missing = 0;
+        let wrongVariant = 0;
+        let stale = 0;
+        let extraInDb = 0;
+        for (const s of stages) {
+            if (s.extra) {
+                extraInDb += 1;
+                continue;
+            }
+            switch (s.status) {
+                case 'present_accepted':
+                    presentAccepted += 1;
+                    break;
+                case 'present_pending':
+                    presentPending += 1;
+                    break;
+                case 'present_rejected':
+                    presentRejected += 1;
+                    break;
+                case 'missing':
+                    missing += 1;
+                    break;
+                case 'wrong_variant':
+                    wrongVariant += 1;
+                    break;
+                case 'stale':
+                    stale += 1;
+                    break;
+                case 'extra':
+                    extraInDb += 1;
+                    break;
+                default:
+                    break;
+            }
+        }
+        return {
+            stepId: stepDef.stepId,
+            label: stepDef.label,
+            expectedStages: stepDef.stages.length,
+            presentAccepted,
+            presentPending,
+            presentRejected,
+            missing,
+            wrongVariant,
+            stale,
+            extraInDb,
+            completionSatisfied: report?.completionSatisfied ?? false,
+            completionMode: report?.completionMode ?? stepDef.completion.mode,
+        };
+    });
+}
+function deriveWorkflowDoctorCompletionBlockers(channel, stepReports, acceptedArtifactTypes) {
+    const blockers = [];
+    const byStep = new Map(stepReports.map(r => [r.stepId, r]));
+    for (const stepDef of channel.steps) {
+        const report = byStep.get(stepDef.stepId);
+        if (!report) {
+            continue;
+        }
+        for (const req of stepDef.requiredInputs) {
+            if (!req.required) {
+                continue;
+            }
+            if (!acceptedArtifactTypes.has(req.stageId)) {
+                const upstream = channel.steps.find(s => s.stepId === req.stepId);
+                blockers.push({
+                    blockerKind: 'missing_upstream_input',
+                    stepId: stepDef.stepId,
+                    stepLabel: stepDef.label,
+                    message: `Step "${stepDef.label}" is gated on accepted artifact type "${req.stageId}" from "${req.stepId}".`,
+                    remediationHint: upstream
+                        ? `Complete "${upstream.label}" (${req.stepId}) until "${req.stageId}" exists as an accepted, current artifact.`
+                        : `Produce an accepted current artifact of type "${req.stageId}" before advancing.`,
+                });
+            }
+        }
+        if (!report.completionSatisfied) {
+            const pendingLabels = report.stages
+                .filter(s => s.expected && (s.status === 'present_pending' || s.status === 'present_rejected'))
+                .map(s => s.label);
+            const missingLabels = report.stages.filter(s => s.expected && s.status === 'missing').map(s => s.label);
+            const detailParts = [];
+            if (missingLabels.length > 0) {
+                detailParts.push(`missing: ${missingLabels.join(', ')}`);
+            }
+            if (pendingLabels.length > 0) {
+                detailParts.push(`not accepted: ${pendingLabels.join(', ')}`);
+            }
+            blockers.push({
+                blockerKind: 'incomplete_step_outputs',
+                stepId: stepDef.stepId,
+                stepLabel: stepDef.label,
+                message: `Step "${stepDef.label}" completion rule (${report.completionMode}) is not satisfied.`,
+                remediationHint: detailParts.length > 0
+                    ? `Finish required artifacts — ${detailParts.join('; ')}.`
+                    : `Accept required artifacts for this step per registry completion mode "${report.completionMode}".`,
+            });
+        }
+        if (report.wrongVariantCount > 0) {
+            blockers.push({
+                blockerKind: 'wrong_variant_artifact',
+                stepId: stepDef.stepId,
+                stepLabel: stepDef.label,
+                message: `${report.wrongVariantCount} artifact(s) on this step carry a different workflow_variant than the resolved project spine.`,
+                remediationHint: 'Regenerate or replace artifacts after aligning workflow_variant, or purge superseded rows so current artifacts match the active variant.',
+            });
+        }
+        if (report.staleCount > 0) {
+            blockers.push({
+                blockerKind: 'stale_artifact',
+                stepId: stepDef.stepId,
+                stepLabel: stepDef.label,
+                message: `${report.staleCount} stale artifact(s): upstream inputs changed after these outputs were accepted.`,
+                remediationHint: 'Re-run downstream generation for stale stages using the Doctor stale rules as a guide.',
+            });
+        }
+        if (blockers.length >= exports.WORKFLOW_DOCTOR_CLOSURE_BLOCKER_CAP) {
+            break;
+        }
+    }
+    return blockers.slice(0, exports.WORKFLOW_DOCTOR_CLOSURE_BLOCKER_CAP);
+}
+function buildWorkflowDoctorClosure(channel, row, resolvedVariant, stepReports, acceptedArtifactTypes) {
+    const channelSummary = buildWorkflowDoctorChannelSummary(channel);
+    const mappingHints = deriveWorkflowDoctorMappingHints(row, resolvedVariant);
+    const stepArtifactCoverage = buildWorkflowDoctorStepArtifactCoverage(channel, stepReports);
+    const completionBlockers = deriveWorkflowDoctorCompletionBlockers(channel, stepReports, acceptedArtifactTypes);
+    return {
+        channelSummary,
+        mappingHints,
+        stepArtifactCoverage,
+        completionBlockers,
+        closureReady: completionBlockers.length === 0,
+    };
+}