@mcoda/core 0.1.33 → 0.1.35

package/dist/services/planning/TaskSufficiencyService.js

@@ -4,6 +4,8 @@ import { WorkspaceRepository } from "@mcoda/db";
 import { PathHelper } from "@mcoda/shared";
 import { JobService } from "../jobs/JobService.js";
 import { createEpicKeyGenerator, createStoryKeyGenerator, createTaskKeyGenerator } from "./KeyHelpers.js";
+import { collectSdsCoverageSignalsFromDocs, evaluateSdsCoverage, normalizeCoverageAnchor, normalizeCoverageText, } from "./SdsCoverageModel.js";
+import { collectSdsImplementationSignals, isStructuredFilePath, normalizeFolderEntry, normalizeHeadingCandidate, stripManagedSdsPreflightBlock, } from "./SdsStructureSignals.js";
 const DEFAULT_MAX_ITERATIONS = 5;
 const DEFAULT_MAX_TASKS_PER_ITERATION = 24;
 const DEFAULT_MIN_COVERAGE_RATIO = 1;
@@ -16,115 +18,20 @@ const REPORT_FILE_NAME = "task-sufficiency-report.json";
 const ignoredDirs = new Set([".git", "node_modules", "dist", "build", ".mcoda", ".docdex"]);
 const sdsFilenamePattern = /(sds|software[-_ ]design|system[-_ ]design|design[-_ ]spec)/i;
 const sdsContentPattern = /(software design specification|system design specification|^#\s*sds\b)/im;
-const nonImplementationHeadingPattern = /\b(software design specification|system design specification|\bsds\b|revision history|table of contents|purpose|scope|definitions?|abbreviations?|glossary|references?|appendix|document control|authors?)\b/i;
-const likelyImplementationHeadingPattern = /\b(architecture|entity|entities|service|services|module|modules|component|components|pipeline|workflow|api|endpoint|schema|model|feature|store|database|ingestion|training|inference|ui|frontend|backend|ops|observability|security|deployment|solver|integration|testing|validation|contract|index|mapping|registry|cache|queue|event|job|task|migration|controller|router|policy)\b/i;
-const repoRootSegments = new Set([
-    "apps",
-    "api",
-    "backend",
-    "config",
-    "configs",
-    "db",
-    "deployment",
-    "deployments",
-    "docs",
-    "frontend",
-    "implementation",
-    "infra",
-    "internal",
-    "packages",
-    "scripts",
-    "service",
-    "services",
-    "shared",
-    "src",
-    "test",
-    "tests",
-    "ui",
-    "web",
-]);
+const supportRootSegments = new Set(["docs", "fixtures", "policies", "policy", "runbooks", "pdr", "rfp", "sds"]);
 const headingNoiseTokens = new Set(["and", "for", "from", "into", "the", "with"]);
-const coverageStopTokens = new Set([
-    "about",
-    "across",
-    "after",
-    "before",
-    "between",
-    "from",
-    "into",
-    "over",
-    "under",
-    "using",
-    "with",
-    "without",
-    "into",
-    "onto",
-    "the",
-    "and",
-    "for",
-    "of",
-    "to",
-]);
-const normalizeText = (value) => value
-    .toLowerCase()
-    .replace(/[`*_]/g, " ")
-    .replace(/[^a-z0-9/\s.-]+/g, " ")
-    .replace(/\s+/g, " ")
-    .trim();
-const normalizeAnchor = (kind, value) => `${kind}:${normalizeText(value).replace(/\s+/g, " ").trim()}`;
+const normalizeText = (value) => normalizeCoverageText(value);
+const normalizeAnchor = normalizeCoverageAnchor;
 const unique = (items) => Array.from(new Set(items.filter(Boolean)));
+const tokenizeCoverageSignal = (value) => unique(normalizeCoverageText(value)
+    .split(/\s+/)
+    .map((token) => token.replace(/[^a-z0-9._-]+/g, ""))
+    .filter((token) => token.length >= 3));
 const stripDecorators = (value) => value
     .replace(/[`*_]/g, " ")
     .replace(/^[\s>:\-[\]().]+/, "")
     .replace(/\s+/g, " ")
     .trim();
-const normalizeHeadingCandidate = (value) => {
-    const cleaned = stripDecorators(value).replace(/^\d+(?:\.\d+)*\s+/, "").trim();
-    return cleaned.length > 0 ? cleaned : stripDecorators(value);
-};
-const headingLooksImplementationRelevant = (heading) => {
-    const normalized = normalizeHeadingCandidate(heading).toLowerCase();
-    if (!normalized || normalized.length < 3)
-        return false;
-    if (nonImplementationHeadingPattern.test(normalized))
-        return false;
-    if (likelyImplementationHeadingPattern.test(normalized))
-        return true;
-    const sectionMatch = heading.trim().match(/^(\d+)(?:\.\d+)*(?:\s+|$)/);
-    if (sectionMatch) {
-        const major = Number.parseInt(sectionMatch[1] ?? "", 10);
-        if (Number.isFinite(major) && major >= 3)
-            return true;
-    }
-    const tokens = normalized
-        .split(/\s+/)
-        .map((token) => token.replace(/[^a-z0-9.-]+/g, ""))
-        .filter((token) => token.length >= 4 && !headingNoiseTokens.has(token));
-    return tokens.length >= 2;
-};
-const normalizeFolderEntry = (entry) => {
-    const trimmed = stripDecorators(entry)
-        .replace(/^\.?\//, "")
-        .replace(/\/+$/, "")
-        .replace(/\s+/g, "");
-    if (!trimmed.includes("/"))
-        return undefined;
-    if (trimmed.includes("...") || trimmed.includes("*"))
-        return undefined;
-    return trimmed;
-};
-const folderEntryLooksRepoRelevant = (entry) => {
-    const normalized = normalizeFolderEntry(entry);
-    if (!normalized)
-        return false;
-    if (normalized.startsWith("/") || /^[A-Za-z]:\//.test(normalized))
-        return false;
-    const segments = normalized.split("/").filter(Boolean);
-    if (segments.length < 2)
-        return false;
-    const root = segments[0].toLowerCase();
-    return repoRootSegments.has(root);
-};
 const deriveSectionDomain = (heading) => {
     const normalized = normalizeHeadingCandidate(heading).toLowerCase();
     const tokens = normalized
@@ -142,130 +49,125 @@ const deriveFolderDomain = (entry) => {
         return "structure";
     return segments.length === 1 ? segments[0] : `${segments[0]}-${segments[1]}`;
 };
-const extractMarkdownHeadings = (content, limit) => {
-    if (!content)
-        return [];
-    const lines = content.split(/\r?\n/);
-    const headings = [];
-    for (let index = 0; index < lines.length; index += 1) {
-        const line = lines[index]?.trim() ?? "";
-        if (!line)
-            continue;
-        const hashHeading = line.match(/^#{1,6}\s+(.+)$/);
-        if (hashHeading) {
-            const heading = hashHeading[1]?.replace(/#+$/, "").trim();
-            if (heading)
-                headings.push(heading);
-        }
-        else if (index + 1 < lines.length &&
-            /^[=-]{3,}\s*$/.test((lines[index + 1] ?? "").trim()) &&
-            !line.startsWith("-") &&
-            !line.startsWith("*")) {
-            headings.push(line);
-        }
-        else {
-            const numberedHeading = line.match(/^(\d+(?:\.\d+)+)\s+(.+)$/);
-            if (numberedHeading) {
-                const heading = `${numberedHeading[1]} ${numberedHeading[2]}`.trim();
-                if (/[a-z]/i.test(heading))
-                    headings.push(heading);
-            }
-        }
-        if (headings.length >= limit)
-            break;
+const implementationRootWeight = (target) => {
+    const normalized = normalizeFolderEntry(target)?.toLowerCase() ?? normalizeText(target);
+    const segments = normalized.split("/").filter(Boolean);
+    const root = segments[0] ?? normalized;
+    let score = 55 + Math.min(segments.length, 4) * 6 + (isStructuredFilePath(normalized) ? 10 : 0);
+    if (supportRootSegments.has(root))
+        score -= 30;
+    if (segments.some((segment) => ["src", "app", "apps", "lib", "libs", "server", "api", "worker", "workers"].includes(segment))) {
+        score += 20;
+    }
+    if (segments.some((segment) => ["test", "tests", "spec", "specs", "integration", "acceptance", "e2e"].includes(segment))) {
+        score += 10;
+    }
+    if (segments.some((segment) => ["db", "data", "schema", "schemas", "migration", "migrations"].includes(segment))) {
+        score += 12;
     }
-    return unique(headings).slice(0, limit);
+    if (segments.some((segment) => ["ops", "infra", "deploy", "deployment", "deployments", "script", "scripts"].includes(segment))) {
+        score += 12;
+    }
+    return score;
 };
-const extractFolderEntries = (content, limit) => {
-    if (!content)
-        return [];
-    const candidates = [];
-    const lines = content.split(/\r?\n/);
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        const matches = [...trimmed.matchAll(/[`'"]?([a-zA-Z0-9._-]+(?:\/[a-zA-Z0-9._-]+)+(?:\/[a-zA-Z0-9._-]+)*)[`'"]?/g)];
-        for (const match of matches) {
-            const raw = (match[1] ?? "").replace(/^\.?\//, "").replace(/\/+$/, "").trim();
-            if (!raw || !raw.includes("/"))
-                continue;
-            candidates.push(raw);
-            if (candidates.length >= limit)
-                break;
-        }
-        if (candidates.length >= limit)
-            break;
+const inferImplementationTargets = (bundle, availablePaths, limit = 3) => {
+    const explicitTargets = bundle.values
+        .map((value) => normalizeFolderEntry(value))
+        .filter((value) => Boolean(value));
+    if (explicitTargets.length > 0) {
+        return unique(explicitTargets).slice(0, limit);
     }
-    return unique(candidates).slice(0, limit);
+    const anchorTokens = tokenizeCoverageSignal(normalizeText([bundle.domain, ...bundle.values].join(" ")).replace(/[-/]+/g, " "));
+    const domainNeedle = bundle.domain.replace(/[-_]+/g, " ").trim();
+    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 overlap = anchorTokens.filter((token) => normalizedCandidate.includes(token)).length;
+        const hasDomainMatch = domainNeedle.length > 0 && normalizedCandidate.includes(domainNeedle);
+        const hasEvidence = overlap > 0 || hasDomainMatch;
+        const score = implementationRootWeight(candidate) +
+            overlap * 20 +
+            (hasDomainMatch ? 15 : 0) -
+            (candidate.startsWith("docs/") ? 25 : 0);
+        return { candidate, 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 tokenizeCoverageSignal = (value) => unique(value
-    .split(/\s+/)
-    .map((token) => token.replace(/[^a-z0-9._-]+/g, ""))
-    .filter((token) => token.length >= 3 && !coverageStopTokens.has(token)));
-const buildBigrams = (tokens) => {
-    const bigrams = [];
-    for (let index = 0; index < tokens.length - 1; index += 1) {
-        const left = tokens[index];
-        const right = tokens[index + 1];
-        if (!left || !right)
-            continue;
-        bigrams.push(`${left} ${right}`);
+const summarizeImplementationTargets = (targets) => {
+    if (targets.length === 0)
+        return "target implementation surfaces";
+    if (targets.length === 1)
+        return targets[0];
+    if (targets.length === 2)
+        return `${targets[0]}, ${targets[1]}`;
+    return `${targets[0]} (+${targets.length - 1} more)`;
+};
+const summarizeBundleScope = (bundle) => {
+    const normalizedValues = unique(bundle.values
+        .map((value) => bundle.kind === "folder" ? normalizeFolderEntry(value) ?? stripDecorators(value) : normalizeHeadingCandidate(value))
+        .filter(Boolean));
+    if (normalizedValues.length === 0)
+        return bundle.domain.replace(/[-_]+/g, " ").trim() || "coverage";
+    if (normalizedValues.length === 1)
+        return normalizedValues[0];
+    return `${normalizedValues[0]} (+${normalizedValues.length - 1} more)`;
+};
+const buildRemediationTitle = (bundle, implementationTargets) => {
+    const domainLabel = bundle.domain.replace(/[-_]+/g, " ").trim() || "coverage";
+    const scopeLabel = summarizeBundleScope(bundle);
+    if (implementationTargets.length === 0) {
+        return `Implement ${scopeLabel || domainLabel}`.slice(0, 180);
     }
-    return unique(bigrams);
+    if (bundle.kind === "folder") {
+        return `Implement ${summarizeImplementationTargets(implementationTargets)}`.slice(0, 180);
+    }
+    return `Implement ${scopeLabel} in ${summarizeImplementationTargets(implementationTargets)}`.slice(0, 180);
 };
-const headingCovered = (corpus, heading) => {
-    const normalized = normalizeText(normalizeHeadingCandidate(heading));
-    if (!normalized)
-        return true;
-    if (corpus.includes(normalized))
-        return true;
-    const tokens = tokenizeCoverageSignal(normalized).slice(0, 10);
-    if (tokens.length === 0)
-        return true;
-    const hitCount = tokens.filter((token) => corpus.includes(token)).length;
-    const requiredHits = tokens.length <= 2
-        ? tokens.length
-        : tokens.length <= 4
-            ? 2
-            : Math.min(4, Math.ceil(tokens.length * 0.6));
-    if (hitCount < requiredHits)
-        return false;
-    if (tokens.length >= 3) {
-        const longestToken = tokens.reduce((longest, token) => (token.length > longest.length ? token : longest), "");
-        if (longestToken.length >= 6 && !corpus.includes(longestToken))
-            return false;
+const summarizeAnchorBundle = (bundle) => {
+    if (bundle.normalizedAnchors.length === 0) {
+        return `${bundle.kind}:${summarizeBundleScope(bundle)}`;
     }
-    const bigrams = buildBigrams(tokens);
-    if (tokens.length >= 3 && bigrams.length > 0 && !bigrams.some((bigram) => corpus.includes(bigram))) {
-        return false;
+    if (bundle.normalizedAnchors.length === 1) {
+        return bundle.normalizedAnchors[0];
     }
-    return true;
+    return `${bundle.normalizedAnchors[0]} (+${bundle.normalizedAnchors.length - 1} more)`;
 };
-const folderEntryCovered = (corpus, entry) => {
-    const normalizedEntry = normalizeFolderEntry(entry)?.toLowerCase().replace(/\/+/g, "/");
-    if (!normalizedEntry)
-        return true;
-    const corpusTight = corpus.replace(/\s+/g, "");
-    if (corpusTight.includes(normalizedEntry.replace(/\s+/g, "")))
-        return true;
-    const segments = normalizedEntry
-        .split("/")
-        .map((segment) => segment.trim().replace(/[^a-z0-9._-]+/g, ""))
-        .filter(Boolean);
-    if (segments.length === 0)
-        return true;
-    const tailSegments = unique(segments.slice(Math.max(0, segments.length - 3)));
-    const hitCount = tailSegments.filter((segment) => corpus.includes(segment)).length;
-    const requiredHits = tailSegments.length <= 1 ? 1 : Math.min(2, tailSegments.length);
-    if (hitCount < requiredHits)
-        return false;
-    if (tailSegments.length >= 2) {
-        const hasStrongTokenMatch = tailSegments.some((segment) => segment.length >= 5 && corpus.includes(segment));
-        if (!hasStrongTokenMatch)
-            return false;
+const buildTargetedTestGuidance = (implementationTargets) => {
+    const guidance = new Set();
+    for (const target of implementationTargets) {
+        const segments = target
+            .toLowerCase()
+            .split("/")
+            .map((segment) => segment.trim())
+            .filter(Boolean);
+        if (segments.some((segment) => ["ui", "web", "frontend", "page", "pages", "screen", "screens", "component", "components"].includes(segment))) {
+            guidance.add("- Add/update unit, component, and flow coverage for the affected user-facing path.");
+        }
+        else if (segments.some((segment) => ["api", "server", "backend", "route", "routes", "controller", "controllers", "handler", "handlers"].includes(segment))) {
+            guidance.add("- Add/update unit and integration coverage for the affected service/API surface.");
+        }
+        else if (segments.some((segment) => ["cli", "cmd", "bin", "command", "commands"].includes(segment))) {
+            guidance.add("- Add/update command-level tests and end-to-end invocation coverage for the affected runtime flow.");
+        }
+        else if (segments.some((segment) => ["ops", "infra", "deploy", "deployment", "deployments", "script", "scripts"].includes(segment))) {
+            guidance.add("- Add/update operational smoke coverage or script validation for the affected deployment/runbook path.");
+        }
+        else if (segments.some((segment) => ["db", "data", "schema", "schemas", "migration", "migrations", "model", "models"].includes(segment))) {
+            guidance.add("- Add/update persistence, schema, and integration coverage for the affected implementation path.");
+        }
+        else if (segments.some((segment) => ["worker", "workers", "job", "jobs", "queue", "task", "tasks", "service", "services", "module", "modules"].includes(segment))) {
+            guidance.add("- Add/update unit and integration coverage for the affected implementation path.");
+        }
     }
-    return true;
+    if (guidance.size === 0) {
+        guidance.add("- Add/update the smallest deterministic test scope that proves the affected implementation targets.");
+    }
+    return Array.from(guidance);
 };
 const readJsonSafe = (raw, fallback) => {
     if (typeof raw !== "string" || raw.trim().length === 0)
@@ -371,7 +273,10 @@ export class TaskSufficiencyService {
         const docs = [];
         for (const filePath of paths) {
             try {
-                const content = await fs.readFile(filePath, "utf8");
+                const rawContent = await fs.readFile(filePath, "utf8");
+                const content = stripManagedSdsPreflightBlock(rawContent) ?? "";
+                if (!content)
+                    continue;
                 if (!sdsContentPattern.test(content) && !sdsFilenamePattern.test(path.basename(filePath)))
                     continue;
                 docs.push({ path: filePath, content });
@@ -433,33 +338,13 @@ export class TaskSufficiencyService {
             epicCount: epics.length,
             storyCount: stories.length,
             taskCount: tasks.length,
-            corpus: normalizeText(corpusChunks.join("\n")).replace(/\s+/g, " ").trim(),
+            corpus: normalizeCoverageText(corpusChunks.join("\n")),
             existingAnchors,
             maxPriority: Number(maxPriorityRow?.max_priority ?? 0),
         };
     }
     evaluateCoverage(corpus, sectionHeadings, folderEntries, existingAnchors) {
-        const missingSectionHeadings = sectionHeadings.filter((heading) => {
-            const anchor = normalizeAnchor("section", heading);
-            if (existingAnchors.has(anchor))
-                return false;
-            return !headingCovered(corpus, heading);
-        });
-        const missingFolderEntries = folderEntries.filter((entry) => {
-            const anchor = normalizeAnchor("folder", entry);
-            if (existingAnchors.has(anchor))
-                return false;
-            return !folderEntryCovered(corpus, entry);
-        });
-        const totalSignals = sectionHeadings.length + folderEntries.length;
-        const coveredSignals = totalSignals - missingSectionHeadings.length - missingFolderEntries.length;
-        const coverageRatio = totalSignals === 0 ? 1 : coveredSignals / totalSignals;
-        return {
-            coverageRatio: Number(coverageRatio.toFixed(4)),
-            totalSignals,
-            missingSectionHeadings,
-            missingFolderEntries,
-        };
+        return evaluateSdsCoverage(corpus, { sectionHeadings, folderEntries }, existingAnchors);
     }
     buildGapItems(coverage, existingAnchors, limit) {
         const items = [];
@@ -604,29 +489,26 @@ export class TaskSufficiencyService {
         const existingTaskKeys = await this.workspaceRepo.listTaskKeys(params.storyId);
         const taskKeyGen = createTaskKeyGenerator(params.storyKey, existingTaskKeys);
         const now = new Date().toISOString();
-        const taskInserts = params.gapBundles.map((bundle, index) => {
-            const target = bundle.values[0] ?? "SDS coverage gap";
+        const taskInserts = params.gapBundles.map(({ bundle, implementationTargets }, index) => {
+            if (implementationTargets.length === 0) {
+                throw new Error(`task-sufficiency-audit attempted to insert a remediation task without implementation targets (${summarizeAnchorBundle(bundle)}).`);
+            }
             const scopeCount = bundle.values.length;
             const domainLabel = bundle.domain.replace(/[-_]+/g, " ").trim() || "coverage";
-            const titlePrefix = bundle.kind === "folder"
-                ? "Implement SDS path"
-                : bundle.kind === "mixed"
-                    ? "Implement SDS bundle"
-                    : "Implement SDS section";
-            const title = scopeCount <= 1
-                ? `${titlePrefix}: ${target}`.slice(0, 180)
-                : `Implement SDS ${domainLabel} coverage bundle (${scopeCount} anchors)`.slice(0, 180);
+            const title = buildRemediationTitle(bundle, implementationTargets);
             const objective = bundle.kind === "folder"
                 ? scopeCount <= 1
-                    ? `Create or update production code under the SDS folder-tree path \`${target}\`.`
+                    ? `Create or update production code under the SDS path \`${bundle.values[0] ?? implementationTargets[0] ?? domainLabel}\`.`
                     : `Create or update production code for ${scopeCount} related SDS folder-tree paths in the ${domainLabel} domain.`
                 : bundle.kind === "mixed"
                     ? `Implement a cohesive capability slice covering both SDS sections and folder targets in the ${domainLabel} domain.`
                     : scopeCount <= 1
-                        ? `Implement the missing production functionality described by SDS section \`${target}\`.`
+                        ? `Implement the missing production functionality described by SDS section \`${bundle.values[0] ?? domainLabel}\`.`
                         : `Implement ${scopeCount} related SDS section requirements in the ${domainLabel} domain.`;
             const scopeLines = bundle.values.map((value) => `- ${value}`);
             const anchorLines = bundle.normalizedAnchors.map((anchor) => `- ${anchor}`);
+            const targetLines = implementationTargets.map((target) => `- ${target}`);
+            const testingLines = buildTargetedTestGuidance(implementationTargets);
             const description = [
                 "## Objective",
                 objective,
@@ -639,21 +521,25 @@ export class TaskSufficiencyService {
                 "## Anchor Scope",
                 ...scopeLines,
                 "",
+                "## Concrete Implementation Targets",
+                ...targetLines,
+                "",
                 "## Anchor Keys",
                 ...anchorLines,
                 "",
                 "## Implementation Plan",
-                "- Phase 1: add or update contracts/interfaces used by this scope.",
-                "- Phase 2: implement production logic for each anchor item (no docs-only closure).",
-                "- Phase 3: wire dependencies and startup/runtime integration points affected by this scope.",
+                "- Phase 1: update the listed implementation targets first; add missing files/scripts/tests only where the SDS requires them.",
+                "- Phase 2: implement production logic for each anchor item and keep the work mapped to the concrete targets above.",
+                "- Phase 3: wire dependencies, startup/runtime sequencing, and artifact generation affected by this scope.",
                 "- Keep implementation traceable to anchor keys in commit and test evidence.",
                 "",
                 "## Testing",
-                "- Add or update targeted unit/component/integration/API coverage for all listed anchors.",
-                "- Execute the smallest deterministic test scope that proves the behavior.",
+                ...testingLines,
+                "- Execute the smallest deterministic test scope that proves the behavior for the listed targets.",
                 "",
                 "## Definition of Done",
                 "- All anchor scope items in this bundle are represented in working code.",
+                "- All concrete implementation targets above are updated or explicitly confirmed unchanged with evidence.",
                 "- Validation evidence exists and maps back to each anchor key.",
             ].join("\n");
             const storyPointsBase = bundle.kind === "folder" ? 1 : 2;
@@ -676,6 +562,7 @@ export class TaskSufficiencyService {
                         domain: bundle.domain,
                         scopeCount,
                         values: bundle.values,
+                        implementationTargets,
                         anchor: bundle.normalizedAnchors[0],
                         anchors: bundle.normalizedAnchors,
                         iteration: params.iteration,
@@ -746,17 +633,11 @@ export class TaskSufficiencyService {
                 throw new Error("task-sufficiency-audit requires an SDS document but none was found. Add docs/sds.md (or a fuzzy-match SDS doc) and retry.");
             }
             const warnings = [];
-            const rawSectionHeadings = unique(sdsDocs.flatMap((doc) => extractMarkdownHeadings(doc.content, SDS_HEADING_LIMIT))).slice(0, SDS_HEADING_LIMIT);
-            const rawFolderEntries = unique(sdsDocs.flatMap((doc) => extractFolderEntries(doc.content, SDS_FOLDER_LIMIT))).slice(0, SDS_FOLDER_LIMIT);
-            const sectionHeadings = unique(rawSectionHeadings
-                .map((heading) => normalizeHeadingCandidate(heading))
-                .filter((heading) => headingLooksImplementationRelevant(heading))).slice(0, SDS_HEADING_LIMIT);
-            const folderEntries = unique(rawFolderEntries
-                .map((entry) => normalizeFolderEntry(entry))
-                .filter((entry) => Boolean(entry))
-                .filter((entry) => folderEntryLooksRepoRelevant(entry))).slice(0, SDS_FOLDER_LIMIT);
-            const skippedHeadingSignals = Math.max(0, rawSectionHeadings.length - sectionHeadings.length);
-            const skippedFolderSignals = Math.max(0, rawFolderEntries.length - folderEntries.length);
+            const coverageSignals = collectSdsCoverageSignalsFromDocs(sdsDocs, {
+                headingLimit: SDS_HEADING_LIMIT,
+                folderLimit: SDS_FOLDER_LIMIT,
+            });
+            const { rawSectionHeadings, rawFolderEntries, sectionHeadings, folderEntries, skippedHeadingSignals, skippedFolderSignals, } = coverageSignals;
             if (skippedHeadingSignals > 0 || skippedFolderSignals > 0) {
                 warnings.push(`Filtered non-actionable SDS signals (headings=${skippedHeadingSignals}, folders=${skippedFolderSignals}) before remediation.`);
             }
@@ -828,6 +709,47 @@ export class TaskSufficiencyService {
                     });
                     break;
                 }
+                const plannedGapBundles = gapBundles.map((bundle) => ({
+                    bundle,
+                    implementationTargets: inferImplementationTargets(bundle, folderEntries, 3),
+                }));
+                const actionableGapBundles = plannedGapBundles.filter((entry) => entry.implementationTargets.length > 0);
+                const unresolvedGapBundles = plannedGapBundles.filter((entry) => entry.implementationTargets.length === 0);
+                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))
+                        .join("; ")}).`);
+                }
+                if (actionableGapBundles.length === 0) {
+                    warnings.push(`Iteration ${iteration}: unresolved SDS gaps remain but no executable remediation tasks could be generated.`);
+                    iterations.push({
+                        iteration,
+                        coverageRatio: coverage.coverageRatio,
+                        totalSignals: coverage.totalSignals,
+                        missingSectionCount: coverage.missingSectionHeadings.length,
+                        missingFolderCount: coverage.missingFolderEntries.length,
+                        createdTaskKeys: [],
+                    });
+                    await this.jobService.writeCheckpoint(job.id, {
+                        stage: "iteration",
+                        timestamp: new Date().toISOString(),
+                        details: {
+                            iteration,
+                            coverageRatio: coverage.coverageRatio,
+                            totalSignals: coverage.totalSignals,
+                            missingSectionCount: coverage.missingSectionHeadings.length,
+                            missingFolderCount: coverage.missingFolderEntries.length,
+                            action: "unresolved",
+                            unresolvedGapItems: unresolvedGapBundles.map((entry) => ({
+                                kind: entry.bundle.kind,
+                                domain: entry.bundle.domain,
+                                values: entry.bundle.values,
+                                anchors: entry.bundle.normalizedAnchors,
+                            })),
+                        },
+                    });
+                    break;
+                }
                 if (dryRun) {
                     iterations.push({
                         iteration,
@@ -847,10 +769,17 @@ export class TaskSufficiencyService {
                             missingSectionCount: coverage.missingSectionHeadings.length,
                             missingFolderCount: coverage.missingFolderEntries.length,
                             action: "dry_run",
-                            proposedGapItems: gapBundles.map((bundle) => ({
-                                kind: bundle.kind,
-                                domain: bundle.domain,
-                                values: bundle.values,
+                            proposedGapItems: actionableGapBundles.map((entry) => ({
+                                kind: entry.bundle.kind,
+                                domain: entry.bundle.domain,
+                                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,
                             })),
                         },
                     });
@@ -863,7 +792,7 @@ export class TaskSufficiencyService {
                     storyKey: target.storyKey,
                     epicId: target.epicId,
                     maxPriority: snapshot.maxPriority,
-                    gapBundles,
+                    gapBundles: actionableGapBundles,
                     iteration,
                     jobId: job.id,
                     commandRunId: commandRun.id,
@@ -891,7 +820,7 @@ export class TaskSufficiencyService {
                         addedCount: createdTaskKeys.length,
                     },
                 });
-                await this.jobService.appendLog(job.id, `Iteration ${iteration}: added ${createdTaskKeys.length} remediation task(s) from ${gapBundles.length} gap bundle(s): ${createdTaskKeys.join(", ")}\n`);
+                await this.jobService.appendLog(job.id, `Iteration ${iteration}: added ${createdTaskKeys.length} remediation task(s) from ${actionableGapBundles.length} actionable gap bundle(s): ${createdTaskKeys.join(", ")}\n`);
             }
             const finalSnapshot = await this.loadProjectSnapshot(request.projectKey);
             const finalCoverage = this.evaluateCoverage(finalSnapshot.corpus, sectionHeadings, folderEntries, finalSnapshot.existingAnchors);
@@ -914,18 +843,19 @@ export class TaskSufficiencyService {
                 satisfied,
                 totalTasksAdded,
                 totalTasksUpdated,
-                docs: sdsDocs.map((doc) => ({
-                    path: path.relative(request.workspace.workspaceRoot, doc.path),
-                    headingSignals: extractMarkdownHeadings(doc.content, SDS_HEADING_LIMIT)
-                        .map((heading) => normalizeHeadingCandidate(heading))
-                        .filter((heading) => headingLooksImplementationRelevant(heading)).length,
-                    folderSignals: extractFolderEntries(doc.content, SDS_FOLDER_LIMIT)
-                        .map((entry) => normalizeFolderEntry(entry))
-                        .filter((entry) => Boolean(entry))
-                        .filter((entry) => folderEntryLooksRepoRelevant(entry)).length,
-                    rawHeadingSignals: extractMarkdownHeadings(doc.content, SDS_HEADING_LIMIT).length,
-                    rawFolderSignals: extractFolderEntries(doc.content, SDS_FOLDER_LIMIT).length,
-                })),
+                docs: sdsDocs.map((doc) => {
+                    const signals = collectSdsImplementationSignals(doc.content, {
+                        headingLimit: SDS_HEADING_LIMIT,
+                        folderLimit: SDS_FOLDER_LIMIT,
+                    });
+                    return {
+                        path: path.relative(request.workspace.workspaceRoot, doc.path),
+                        headingSignals: signals.sectionHeadings.length,
+                        folderSignals: signals.folderEntries.length,
+                        rawHeadingSignals: signals.rawSectionHeadings.length,
+                        rawFolderSignals: signals.rawFolderEntries.length,
+                    };
+                }),
                 finalCoverage: {
                     coverageRatio: finalCoverage.coverageRatio,
                     totalSignals: finalCoverage.totalSignals,
@@ -945,6 +875,7 @@ export class TaskSufficiencyService {
                     satisfied,
                     totalTasksAdded,
                     totalTasksUpdated,
+                    finalTotalSignals: finalCoverage.totalSignals,
                     finalCoverageRatio: finalCoverage.coverageRatio,
                 },
             });
@@ -959,6 +890,7 @@ export class TaskSufficiencyService {
                 totalTasksUpdated,
                 maxIterations,
                 minCoverageRatio,
+                finalTotalSignals: finalCoverage.totalSignals,
                 finalCoverageRatio: finalCoverage.coverageRatio,
                 remainingSectionHeadings: finalCoverage.missingSectionHeadings,
                 remainingFolderEntries: finalCoverage.missingFolderEntries,
@@ -981,6 +913,7 @@ export class TaskSufficiencyService {
                     totalTasksUpdated,
                     maxIterations,
                     minCoverageRatio,
+                    finalTotalSignals: finalCoverage.totalSignals,
                     finalCoverageRatio: finalCoverage.coverageRatio,
                     remainingSectionCount: finalCoverage.missingSectionHeadings.length,
                     remainingFolderCount: finalCoverage.missingFolderEntries.length,