@mcoda/core 0.1.35 → 0.1.37

package/dist/services/planning/SdsPreflightService.js

@@ -566,17 +566,17 @@ export class SdsPreflightService {
         if (technologies.length > 0) {
             return [
                 "## Technology Stack",
-                `- Chosen stack baseline: ${technologies.join(", ")}.`,
-                "- Alternatives considered must be recorded with trade-offs for runtime, complexity, and verification impact.",
-                "- Keep one explicit baseline per layer so create-tasks can generate deterministic implementation work.",
+                `- Observed source-backed technology signals: ${technologies.join(", ")}.`,
+                "- Keep the chosen stack explicit in the source docs for runtime, language, persistence, interface, and tooling layers.",
+                "- Record alternatives only when the source docs name them; do not invent default stack choices during preflight.",
                 "",
             ];
         }
         return [
             "## Technology Stack",
-            "- Chosen stack baseline must be explicit for runtime, language, persistence, and tooling layers.",
-            "- Alternatives considered should be named with rationale and trade-offs.",
-            "- Use one baseline per layer to avoid ambiguous backlog generation.",
+            "- Source docs do not yet make the technology stack explicit.",
+            "- Record runtime, language, persistence, interface, and tooling decisions explicitly in the source docs without assuming defaults.",
+            "- Preflight must not invent a chosen stack baseline when the source is silent.",
             "",
         ];
     }

package/dist/services/planning/TaskSufficiencyService.d.ts

@@ -1,6 +1,19 @@
 import { WorkspaceRepository } from "@mcoda/db";
 import { WorkspaceResolution } from "../../workspace/WorkspaceManager.js";
 import { JobService } from "../jobs/JobService.js";
+export interface TaskSufficiencyPlannedGapBundle {
+    kind: "section" | "folder" | "mixed";
+    domain: string;
+    values: string[];
+    anchors: string[];
+    implementationTargets: string[];
+}
+export interface TaskSufficiencyUnresolvedBundle {
+    kind: "section" | "folder" | "mixed";
+    domain: string;
+    values: string[];
+    anchors: string[];
+}
 export interface TaskSufficiencyAuditRequest {
     workspace: WorkspaceResolution;
     projectKey: string;
@@ -16,6 +29,7 @@ export interface TaskSufficiencyAuditIteration {
     totalSignals: number;
     missingSectionCount: number;
     missingFolderCount: number;
+    unresolvedBundleCount: number;
     createdTaskKeys: string[];
 }
 export interface TaskSufficiencyAuditResult {
@@ -38,6 +52,8 @@ export interface TaskSufficiencyAuditResult {
         folders: number;
         total: number;
     };
+    plannedGapBundles: TaskSufficiencyPlannedGapBundle[];
+    unresolvedBundles: TaskSufficiencyUnresolvedBundle[];
     iterations: TaskSufficiencyAuditIteration[];
     reportPath: string;
     reportHistoryPath?: string;

package/dist/services/planning/TaskSufficiencyService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TaskSufficiencyService.d.ts","sourceRoot":"","sources":["../../../src/services/planning/TaskSufficiencyService.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAiC,MAAM,WAAW,CAAC;AAE/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAoEnD,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,mBAAmB,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,aAAa,EAAE;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,UAAU,EAAE,6BAA6B,EAAE,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,KAAK,mBAAmB,GAAG;IACzB,aAAa,EAAE,mBAAmB,CAAC;IACnC,UAAU,EAAE,UAAU,CAAC;CACxB,CAAC;AA+KF,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAU;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;gBAG9C,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE,mBAAmB,EACzB,SAAS,GAAE;QAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAO;WAS9D,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAU9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YASd,gBAAgB;YA4BhB,iBAAiB;YAmCjB,cAAc;YAgBd,mBAAmB;IAwEjC,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,aAAa;IA+BrB,OAAO,CAAC,cAAc;YA2BR,iBAAiB;YAyGjB,cAAc;YAoId,oBAAoB;IAkB5B,QAAQ,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,0BAA0B,CAAC;CA6X1F"}
+{"version":3,"file":"TaskSufficiencyService.d.ts","sourceRoot":"","sources":["../../../src/services/planning/TaskSufficiencyService.ts"],"names":[],"mappings":"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"}

package/dist/services/planning/TaskSufficiencyService.js

@@ -20,8 +20,170 @@ const sdsFilenamePattern = /(sds|software[-_ ]design|system[-_ ]design|design[-_
 const sdsContentPattern = /(software design specification|system design specification|^#\s*sds\b)/im;
 const supportRootSegments = new Set(["docs", "fixtures", "policies", "policy", "runbooks", "pdr", "rfp", "sds"]);
 const headingNoiseTokens = new Set(["and", "for", "from", "into", "the", "with"]);
+const runtimePathSegments = new Set([
+    "api",
+    "app",
+    "apps",
+    "bin",
+    "cli",
+    "client",
+    "clients",
+    "cmd",
+    "command",
+    "commands",
+    "engine",
+    "engines",
+    "feature",
+    "features",
+    "gateway",
+    "gateways",
+    "handler",
+    "handlers",
+    "module",
+    "modules",
+    "pipeline",
+    "pipelines",
+    "processor",
+    "processors",
+    "route",
+    "routes",
+    "server",
+    "servers",
+    "service",
+    "services",
+    "src",
+    "ui",
+    "web",
+    "worker",
+    "workers",
+]);
+const interfacePathSegments = new Set([
+    "contract",
+    "contracts",
+    "dto",
+    "dtos",
+    "interface",
+    "interfaces",
+    "policy",
+    "policies",
+    "proto",
+    "protocol",
+    "protocols",
+    "schema",
+    "schemas",
+    "spec",
+    "specs",
+    "type",
+    "types",
+]);
+const dataPathSegments = new Set([
+    "cache",
+    "caches",
+    "data",
+    "db",
+    "ledger",
+    "migration",
+    "migrations",
+    "model",
+    "models",
+    "persistence",
+    "repository",
+    "repositories",
+    "storage",
+]);
+const testPathSegments = new Set(["acceptance", "e2e", "integration", "spec", "specs", "test", "tests"]);
+const opsPathSegments = new Set([
+    "automation",
+    "deploy",
+    "deployment",
+    "deployments",
+    "infra",
+    "ops",
+    "operation",
+    "operations",
+    "orchestration",
+    "orchestrations",
+    "provision",
+    "provisioning",
+    "runbook",
+    "runbooks",
+    "script",
+    "scripts",
+]);
+const manifestSignalTokens = new Set([
+    "build",
+    "config",
+    "configuration",
+    "dependency",
+    "dependencies",
+    "environment",
+    "lock",
+    "lockfile",
+    "manifest",
+    "package",
+    "project",
+    "settings",
+    "tooling",
+    "workspace",
+    "worktree",
+]);
+const manifestMachineFilePattern = /\.(?:cfg|cnf|conf|gradle|ini|json|kts|lock|mod|properties|sum|toml|txt|xml|ya?ml)$/i;
+const nonManifestTokens = new Set([
+    "acceptance",
+    "archive",
+    "changelog",
+    "contract",
+    "contracts",
+    "example",
+    "examples",
+    "fixture",
+    "fixtures",
+    "guide",
+    "guides",
+    "license",
+    "manual",
+    "manuals",
+    "notice",
+    "readme",
+    "reference",
+    "references",
+    "sample",
+    "samples",
+    "schema",
+    "schemas",
+    "spec",
+    "specs",
+    "test",
+    "tests",
+]);
+const serviceArtifactSignalPattern = /(?:^|[._-])(compose|daemon|orchestrator|scheduler|service|socket|timer|worker)(?:[._-]|$)|\.(?:service|socket|timer)$/i;
+const tokenizeBasename = (value) => value
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .map((segment) => segment.trim())
+    .filter(Boolean);
+const isManifestLikeBasename = (basename, segments = []) => {
+    const normalized = basename.toLowerCase();
+    const tokens = tokenizeBasename(normalized);
+    if (tokens.some((token) => manifestSignalTokens.has(token)))
+        return true;
+    if (!manifestMachineFilePattern.test(normalized))
+        return false;
+    if (segments.length <= 2 && tokens.length <= 3 && !tokens.some((token) => nonManifestTokens.has(token))) {
+        return true;
+    }
+    return false;
+};
+const isServiceArtifactBasename = (basename) => serviceArtifactSignalPattern.test(basename.toLowerCase());
 const normalizeText = (value) => normalizeCoverageText(value);
 const normalizeAnchor = normalizeCoverageAnchor;
+const toPlannedGapBundle = (entry) => ({
+    kind: entry.bundle.kind,
+    domain: entry.bundle.domain,
+    values: entry.bundle.values,
+    anchors: entry.bundle.normalizedAnchors,
+    implementationTargets: entry.implementationTargets,
+});
 const unique = (items) => Array.from(new Set(items.filter(Boolean)));
 const tokenizeCoverageSignal = (value) => unique(normalizeCoverageText(value)
     .split(/\s+/)
@@ -70,6 +232,44 @@ const implementationRootWeight = (target) => {
     }
     return score;
 };
+const classifyImplementationTarget = (target) => {
+    const normalized = normalizeFolderEntry(target)?.toLowerCase() ?? normalizeText(target);
+    const segments = normalized.split("/").filter(Boolean);
+    const basename = segments[segments.length - 1] ?? normalized;
+    const isServiceArtifact = isServiceArtifactBasename(basename);
+    if (segments.some((segment) => supportRootSegments.has(segment))) {
+        return { normalized, basename, segments, kind: "doc", isServiceArtifact };
+    }
+    if (isManifestLikeBasename(basename, segments) || isServiceArtifact) {
+        return { normalized, basename, segments, kind: "manifest", isServiceArtifact };
+    }
+    if (segments.some((segment) => testPathSegments.has(segment))) {
+        return { normalized, basename, segments, kind: "test", isServiceArtifact };
+    }
+    if (segments.some((segment) => opsPathSegments.has(segment))) {
+        return { normalized, basename, segments, kind: "ops", isServiceArtifact };
+    }
+    if (segments.some((segment) => interfacePathSegments.has(segment))) {
+        return { normalized, basename, segments, kind: "interface", isServiceArtifact };
+    }
+    if (segments.some((segment) => dataPathSegments.has(segment))) {
+        return { normalized, basename, segments, kind: "data", isServiceArtifact };
+    }
+    if (segments.some((segment) => runtimePathSegments.has(segment))) {
+        return { normalized, basename, segments, kind: "runtime", isServiceArtifact };
+    }
+    return { normalized, basename, segments, kind: "unknown", isServiceArtifact };
+};
+const deriveSemanticTargetNeeds = (bundle) => {
+    const corpus = normalizeText([bundle.domain, ...bundle.values].join(" "));
+    return {
+        wantsVerification: /\b(verify|verification|acceptance|scenario|suite|test|tests|quality|gate|matrix)\b/.test(corpus),
+        wantsOps: /\b(rollback|recovery|replay|restart|rotation|drill|runbook|failover|release|startup|deploy|deployment|operations?|incident|compromise)\b/.test(corpus),
+        wantsInterface: /\b(contract|interface|schema|policy|policies|oracle|gateway|api|protocol)\b/.test(corpus),
+        wantsData: /\b(data|storage|cache|db|database|ledger|pipeline|metering|pricing)\b/.test(corpus),
+        wantsProvider: /\b(provider|providers|gateway|gateways|rpc|adapter|adapters|sanctions|moderation|kyt)\b/.test(corpus),
+    };
+};
 const inferImplementationTargets = (bundle, availablePaths, limit = 3) => {
     const explicitTargets = bundle.values
         .map((value) => normalizeFolderEntry(value))
@@ -79,24 +279,135 @@ const inferImplementationTargets = (bundle, availablePaths, limit = 3) => {
     }
     const anchorTokens = tokenizeCoverageSignal(normalizeText([bundle.domain, ...bundle.values].join(" ")).replace(/[-/]+/g, " "));
     const domainNeedle = bundle.domain.replace(/[-_]+/g, " ").trim();
+    const targetNeeds = deriveSemanticTargetNeeds(bundle);
     const scored = availablePaths
         .map((candidate) => normalizeFolderEntry(candidate))
         .filter((candidate) => Boolean(candidate))
         .filter((candidate) => bundle.kind === "folder" || !candidate.startsWith("docs/"))
         .map((candidate) => {
-        const normalizedCandidate = normalizeText(candidate.replace(/\//g, " "));
+        const classification = classifyImplementationTarget(candidate);
+        const normalizedCandidate = classification.normalized.replace(/\//g, " ");
         const overlap = anchorTokens.filter((token) => normalizedCandidate.includes(token)).length;
         const hasDomainMatch = domainNeedle.length > 0 && normalizedCandidate.includes(domainNeedle);
-        const hasEvidence = overlap > 0 || hasDomainMatch;
+        const semanticEvidence = (targetNeeds.wantsVerification && classification.kind === "test") ||
+            (targetNeeds.wantsOps && classification.kind === "ops") ||
+            (targetNeeds.wantsInterface && classification.kind === "interface") ||
+            (targetNeeds.wantsData && classification.kind === "data") ||
+            (targetNeeds.wantsProvider &&
+                (classification.kind === "interface" ||
+                    classification.kind === "runtime" ||
+                    classification.kind === "ops"));
+        const hasEvidence = overlap > 0 || hasDomainMatch || semanticEvidence;
         const score = implementationRootWeight(candidate) +
             overlap * 20 +
             (hasDomainMatch ? 15 : 0) -
-            (candidate.startsWith("docs/") ? 25 : 0);
-        return { candidate, score, hasEvidence };
+            (candidate.startsWith("docs/") ? 25 : 0) +
+            (targetNeeds.wantsVerification && classification.kind === "test" ? 45 : 0) +
+            (targetNeeds.wantsOps && classification.kind === "ops" ? 60 : 0) +
+            (targetNeeds.wantsInterface && classification.kind === "interface" ? 55 : 0) +
+            (targetNeeds.wantsData && classification.kind === "data" ? 55 : 0) +
+            (targetNeeds.wantsProvider &&
+                (classification.kind === "interface" || classification.kind === "runtime")
+                ? 35
+                : 0) -
+            (classification.kind === "manifest" ? 120 : 0) -
+            (classification.kind === "doc" ? 120 : 0);
+        return { candidate, classification, score, hasEvidence };
     })
         .filter((entry) => entry.hasEvidence)
         .sort((left, right) => right.score - left.score || left.candidate.localeCompare(right.candidate));
-    return unique(scored.filter((entry) => entry.score > 0).map((entry) => entry.candidate)).slice(0, limit);
+    const hasStrongCandidates = scored.some((entry) => entry.score > 0 &&
+        (entry.classification.kind === "runtime" ||
+            entry.classification.kind === "interface" ||
+            entry.classification.kind === "data" ||
+            entry.classification.kind === "test" ||
+            entry.classification.kind === "ops"));
+    const filtered = scored.filter((entry) => {
+        if (entry.score <= 0)
+            return false;
+        if (!hasStrongCandidates)
+            return true;
+        if (entry.classification.kind === "manifest")
+            return false;
+        if (entry.classification.kind === "doc")
+            return false;
+        return true;
+    });
+    const prioritized = (filtered.length > 0 ? filtered : scored.filter((entry) => entry.score > 0)).filter((entry, _, entries) => {
+        if (isStructuredFilePath(entry.classification.basename))
+            return true;
+        return !entries.some((other) => {
+            if (other === entry)
+                return false;
+            if (other.score + 5 < entry.score)
+                return false;
+            if (!other.candidate.startsWith(`${entry.candidate}/`))
+                return false;
+            return (other.classification.kind === entry.classification.kind ||
+                isStructuredFilePath(other.classification.basename));
+        });
+    });
+    const prioritizedFiles = prioritized.filter((entry) => isStructuredFilePath(entry.classification.basename));
+    const fileLifted = prioritized.map((entry) => {
+        if (isStructuredFilePath(entry.classification.basename))
+            return entry;
+        const replacement = prioritizedFiles.find((other) => {
+            if (!other.candidate.startsWith(`${entry.candidate}/`))
+                return false;
+            if (other.score + 10 < entry.score)
+                return false;
+            return (other.classification.kind === entry.classification.kind ||
+                other.classification.kind === "runtime" ||
+                entry.classification.kind === "unknown");
+        });
+        return replacement ?? entry;
+    });
+    const collapsed = fileLifted.filter((entry, _, entries) => {
+        if (isStructuredFilePath(entry.classification.basename))
+            return true;
+        return !entries.some((other) => {
+            if (other === entry)
+                return false;
+            if (!isStructuredFilePath(other.classification.basename))
+                return false;
+            return other.candidate.startsWith(`${entry.candidate}/`);
+        });
+    });
+    const descendantFiles = unique(availablePaths
+        .map((candidate) => normalizeFolderEntry(candidate))
+        .filter((candidate) => Boolean(candidate))
+        .filter((candidate) => isStructuredFilePath(path.basename(candidate)))
+        .map((candidate) => {
+        const classification = classifyImplementationTarget(candidate);
+        const normalizedCandidate = classification.normalized.replace(/\//g, " ");
+        const overlap = anchorTokens.filter((token) => normalizedCandidate.includes(token)).length;
+        const hasDomainMatch = domainNeedle.length > 0 && normalizedCandidate.includes(domainNeedle);
+        const semanticBonus = (targetNeeds.wantsVerification && classification.kind === "test" ? 40 : 0) +
+            (targetNeeds.wantsOps && classification.kind === "ops" ? 50 : 0) +
+            (targetNeeds.wantsInterface && classification.kind === "interface" ? 45 : 0) +
+            (targetNeeds.wantsData && classification.kind === "data" ? 45 : 0) +
+            (targetNeeds.wantsProvider &&
+                (classification.kind === "runtime" || classification.kind === "interface")
+                ? 25
+                : 0);
+        return {
+            candidate,
+            score: implementationRootWeight(candidate) + overlap * 20 + (hasDomainMatch ? 20 : 0) + semanticBonus,
+        };
+    })
+        .sort((left, right) => right.score - left.score || left.candidate.localeCompare(right.candidate))
+        .map((entry) => entry.candidate));
+    const promoted = unique(collapsed.map((entry) => {
+        if (isStructuredFilePath(entry.classification.basename))
+            return entry.candidate;
+        const replacement = descendantFiles.find((candidate) => candidate.startsWith(`${entry.candidate}/`) || candidate.startsWith(`${entry.candidate.replace(/\/+$/g, "")}/`));
+        return replacement ?? entry.candidate;
+    })).filter((candidate, _, entries) => {
+        if (isStructuredFilePath(path.basename(candidate)))
+            return true;
+        return !entries.some((other) => other !== candidate && isStructuredFilePath(path.basename(other)) && other.startsWith(`${candidate}/`));
+    });
+    return promoted.slice(0, limit);
 };
 const summarizeImplementationTargets = (targets) => {
     if (targets.length === 0)
@@ -137,6 +448,12 @@ const summarizeAnchorBundle = (bundle) => {
     }
     return `${bundle.normalizedAnchors[0]} (+${bundle.normalizedAnchors.length - 1} more)`;
 };
+const toUnresolvedBundle = (bundle) => ({
+    kind: bundle.kind,
+    domain: bundle.domain,
+    values: [...bundle.values],
+    anchors: [...bundle.normalizedAnchors],
+});
 const buildTargetedTestGuidance = (implementationTargets) => {
     const guidance = new Set();
     for (const target of implementationTargets) {
@@ -666,6 +983,7 @@ export class TaskSufficiencyService {
             let totalTasksAdded = 0;
             const totalTasksUpdated = 0;
             let satisfied = false;
+            let latestUnresolvedBundles = [];
             for (let iteration = 1; iteration <= maxIterations; iteration += 1) {
                 const snapshot = await this.loadProjectSnapshot(request.projectKey);
                 const coverage = this.evaluateCoverage(snapshot.corpus, sectionHeadings, folderEntries, snapshot.existingAnchors);
@@ -679,6 +997,7 @@ export class TaskSufficiencyService {
                         totalSignals: coverage.totalSignals,
                         missingSectionCount: coverage.missingSectionHeadings.length,
                         missingFolderCount: coverage.missingFolderEntries.length,
+                        unresolvedBundleCount: 0,
                         createdTaskKeys: [],
                     });
                     await this.jobService.writeCheckpoint(job.id, {
@@ -690,6 +1009,7 @@ export class TaskSufficiencyService {
                             totalSignals: coverage.totalSignals,
                             missingSectionCount: coverage.missingSectionHeadings.length,
                             missingFolderCount: coverage.missingFolderEntries.length,
+                            unresolvedBundleCount: 0,
                             action: "complete",
                         },
                     });
@@ -698,6 +1018,7 @@ export class TaskSufficiencyService {
                 const gapItems = this.buildGapItems(coverage, snapshot.existingAnchors, maxTasksPerIteration);
                 const gapBundles = this.bundleGapItems(gapItems, maxTasksPerIteration);
                 if (gapBundles.length === 0) {
+                    latestUnresolvedBundles = [];
                     warnings.push(`Iteration ${iteration}: unresolved SDS gaps remain but no insertable gap items were identified.`);
                     iterations.push({
                         iteration,
@@ -705,6 +1026,7 @@ export class TaskSufficiencyService {
                         totalSignals: coverage.totalSignals,
                         missingSectionCount: coverage.missingSectionHeadings.length,
                         missingFolderCount: coverage.missingFolderEntries.length,
+                        unresolvedBundleCount: 0,
                         createdTaskKeys: [],
                     });
                     break;
@@ -715,6 +1037,7 @@ export class TaskSufficiencyService {
                 }));
                 const actionableGapBundles = plannedGapBundles.filter((entry) => entry.implementationTargets.length > 0);
                 const unresolvedGapBundles = plannedGapBundles.filter((entry) => entry.implementationTargets.length === 0);
+                latestUnresolvedBundles = unresolvedGapBundles.map((entry) => toUnresolvedBundle(entry.bundle));
                 if (unresolvedGapBundles.length > 0) {
                     warnings.push(`Iteration ${iteration}: ${unresolvedGapBundles.length} SDS gap bundle(s) remain unresolved because no concrete implementation targets were inferred (${unresolvedGapBundles
                         .map((entry) => summarizeAnchorBundle(entry.bundle))
@@ -728,6 +1051,7 @@ export class TaskSufficiencyService {
                         totalSignals: coverage.totalSignals,
                         missingSectionCount: coverage.missingSectionHeadings.length,
                         missingFolderCount: coverage.missingFolderEntries.length,
+                        unresolvedBundleCount: latestUnresolvedBundles.length,
                         createdTaskKeys: [],
                     });
                     await this.jobService.writeCheckpoint(job.id, {
@@ -739,13 +1063,9 @@ export class TaskSufficiencyService {
                             totalSignals: coverage.totalSignals,
                             missingSectionCount: coverage.missingSectionHeadings.length,
                             missingFolderCount: coverage.missingFolderEntries.length,
+                            unresolvedBundleCount: latestUnresolvedBundles.length,
                             action: "unresolved",
-                            unresolvedGapItems: unresolvedGapBundles.map((entry) => ({
-                                kind: entry.bundle.kind,
-                                domain: entry.bundle.domain,
-                                values: entry.bundle.values,
-                                anchors: entry.bundle.normalizedAnchors,
-                            })),
+                            unresolvedGapItems: latestUnresolvedBundles,
                         },
                     });
                     break;
@@ -757,6 +1077,7 @@ export class TaskSufficiencyService {
                         totalSignals: coverage.totalSignals,
                         missingSectionCount: coverage.missingSectionHeadings.length,
                         missingFolderCount: coverage.missingFolderEntries.length,
+                        unresolvedBundleCount: latestUnresolvedBundles.length,
                         createdTaskKeys: [],
                     });
                     await this.jobService.writeCheckpoint(job.id, {
@@ -768,6 +1089,7 @@ export class TaskSufficiencyService {
                             totalSignals: coverage.totalSignals,
                             missingSectionCount: coverage.missingSectionHeadings.length,
                             missingFolderCount: coverage.missingFolderEntries.length,
+                            unresolvedBundleCount: latestUnresolvedBundles.length,
                             action: "dry_run",
                             proposedGapItems: actionableGapBundles.map((entry) => ({
                                 kind: entry.bundle.kind,
@@ -775,12 +1097,7 @@ export class TaskSufficiencyService {
                                 values: entry.bundle.values,
                                 implementationTargets: entry.implementationTargets,
                             })),
-                            unresolvedGapItems: unresolvedGapBundles.map((entry) => ({
-                                kind: entry.bundle.kind,
-                                domain: entry.bundle.domain,
-                                values: entry.bundle.values,
-                                anchors: entry.bundle.normalizedAnchors,
-                            })),
+                            unresolvedGapItems: latestUnresolvedBundles,
                         },
                     });
                     break;
@@ -805,6 +1122,7 @@ export class TaskSufficiencyService {
                     totalSignals: coverage.totalSignals,
                     missingSectionCount: coverage.missingSectionHeadings.length,
                     missingFolderCount: coverage.missingFolderEntries.length,
+                    unresolvedBundleCount: latestUnresolvedBundles.length,
                     createdTaskKeys,
                 });
                 await this.jobService.writeCheckpoint(job.id, {
@@ -816,6 +1134,7 @@ export class TaskSufficiencyService {
                         totalSignals: coverage.totalSignals,
                         missingSectionCount: coverage.missingSectionHeadings.length,
                         missingFolderCount: coverage.missingFolderEntries.length,
+                        unresolvedBundleCount: latestUnresolvedBundles.length,
                         createdTaskKeys,
                         addedCount: createdTaskKeys.length,
                     },
@@ -831,6 +1150,17 @@ export class TaskSufficiencyService {
             if (!satisfied) {
                 warnings.push(`Sufficiency target not reached (coverage=${finalCoverage.coverageRatio}, threshold=${minCoverageRatio}) after ${iterations.length} iteration(s).`);
             }
+            const finalGapItemLimit = Math.max(1, finalCoverage.missingSectionHeadings.length + finalCoverage.missingFolderEntries.length);
+            const finalGapItems = this.buildGapItems(finalCoverage, finalSnapshot.existingAnchors, finalGapItemLimit);
+            const finalGapBundles = this.bundleGapItems(finalGapItems, finalGapItemLimit);
+            const finalPlannedGapBundles = finalGapBundles.map((bundle) => ({
+                bundle,
+                implementationTargets: inferImplementationTargets(bundle, folderEntries, 3),
+            }));
+            const plannedGapBundles = finalPlannedGapBundles.map(toPlannedGapBundle);
+            const unresolvedBundles = finalPlannedGapBundles
+                .filter((entry) => entry.implementationTargets.length === 0)
+                .map((entry) => toUnresolvedBundle(entry.bundle));
             const report = {
                 projectKey: request.projectKey,
                 sourceCommand,
@@ -862,6 +1192,8 @@ export class TaskSufficiencyService {
                     missingSectionHeadings: finalCoverage.missingSectionHeadings,
                     missingFolderEntries: finalCoverage.missingFolderEntries,
                 },
+                plannedGapBundles,
+                unresolvedBundles,
                 iterations,
                 warnings,
             };
@@ -877,6 +1209,7 @@ export class TaskSufficiencyService {
                     totalTasksUpdated,
                     finalTotalSignals: finalCoverage.totalSignals,
                     finalCoverageRatio: finalCoverage.coverageRatio,
+                    unresolvedBundleCount: unresolvedBundles.length,
                 },
             });
             const result = {
@@ -899,6 +1232,8 @@ export class TaskSufficiencyService {
                     folders: finalCoverage.missingFolderEntries.length,
                     total: finalCoverage.missingSectionHeadings.length + finalCoverage.missingFolderEntries.length,
                 },
+                plannedGapBundles,
+                unresolvedBundles,
                 iterations,
                 reportPath,
                 reportHistoryPath: historyPath,
@@ -917,6 +1252,7 @@ export class TaskSufficiencyService {
                     finalCoverageRatio: finalCoverage.coverageRatio,
                     remainingSectionCount: finalCoverage.missingSectionHeadings.length,
                     remainingFolderCount: finalCoverage.missingFolderEntries.length,
+                    unresolvedBundleCount: unresolvedBundles.length,
                     reportPath,
                     reportHistoryPath: historyPath,
                     warnings,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcoda/core",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "Core services and APIs for the mcoda CLI.",
   "type": "module",
   "main": "dist/index.js",
@@ -32,11 +32,11 @@
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.0",
     "yaml": "^2.4.2",
-    "@mcoda/shared": "0.1.35",
-    "@mcoda/db": "0.1.35",
-    "@mcoda/agents": "0.1.35",
-    "@mcoda/generators": "0.1.35",
-    "@mcoda/integrations": "0.1.35"
+    "@mcoda/db": "0.1.37",
+    "@mcoda/shared": "0.1.37",
+    "@mcoda/generators": "0.1.37",
+    "@mcoda/agents": "0.1.37",
+    "@mcoda/integrations": "0.1.37"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",