@devtrack-solution/codesdd 1.2.2 → 1.2.4-rc3

package/dist/core/sdd/services/context.service.js

@@ -1,10 +1,48 @@
 import path from "node:path";
 import { existsSync, promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
 import { parse } from "yaml";
+import { createProjectFingerprint, ensureGlobalCacheLayout } from "../../global-config.js";
 import { CLI_NAME } from "../../branding.js";
-import { loadStateSnapshot } from "../state.js";
+import { loadStateSnapshot, nowIso } from "../state.js";
 import { bundlesForSkills, getRuntime, relProjectPath, coreDocRef, planningDocRef, featureActiveDir, activeDocNamesForLayout, unresolvedDependencies, lockConflictWithActive, featureReadiness, gateSatisfied, detectContextType, pathExists, listAdrRefs } from "../legacy-operations.js";
+import { normalizeSddEntityRef } from "../entity-reference.js";
 import { workspacePlanSchema, workspaceSpecSchema } from "../workspace-schemas.js";
+export const CONTEXT_PACK_BUDGET_MODES = ['compact', 'standard', 'full'];
+const UNLIMITED = Number.POSITIVE_INFINITY;
+const CONTEXT_PACK_CACHE_SCHEMA_VERSION = 2;
+const CONTEXT_PACK_BUDGET_PROFILES = {
+    compact: {
+        maxReadOrder: 8,
+        maxCoreDocs: 6,
+        maxRelevantContracts: 40,
+        maxRelevantServices: 5,
+        maxServiceContracts: 12,
+        maxPredecessorOutputs: 5,
+        maxRelatedFeatures: 50,
+        maxRelatedDebates: 20,
+    },
+    standard: {
+        maxReadOrder: UNLIMITED,
+        maxCoreDocs: UNLIMITED,
+        maxRelevantContracts: UNLIMITED,
+        maxRelevantServices: UNLIMITED,
+        maxServiceContracts: UNLIMITED,
+        maxPredecessorOutputs: UNLIMITED,
+        maxRelatedFeatures: UNLIMITED,
+        maxRelatedDebates: UNLIMITED,
+    },
+    full: {
+        maxReadOrder: UNLIMITED,
+        maxCoreDocs: UNLIMITED,
+        maxRelevantContracts: UNLIMITED,
+        maxRelevantServices: UNLIMITED,
+        maxServiceContracts: UNLIMITED,
+        maxPredecessorOutputs: UNLIMITED,
+        maxRelatedFeatures: UNLIMITED,
+        maxRelatedDebates: UNLIMITED,
+    },
+};
 async function readYamlWorkspaceDoc(filePath, schema) {
     const content = await fs.readFile(filePath, 'utf-8').catch(() => '');
     if (!content.trim())
@@ -59,13 +97,25 @@ export class ContextService {
     constructor(stores) {
         this.stores = stores;
     }
-    async execute(projectRoot, ref) {
+    async execute(projectRoot, ref, options = {}) {
+        const budgetMode = options.budgetMode ?? 'standard';
         const { config, paths } = await getRuntime(projectRoot);
         const snapshot = await loadStateSnapshot(paths, config);
-        const type = detectContextType(ref);
+        const normalizedRef = normalizeSddEntityRef(ref);
+        const type = detectContextType(normalizedRef);
         if (!type) {
             throw new Error(`Referencia ${ref} invalida. Use FEAT/EPIC/RAD/FGAP/TD.`);
         }
+        const cacheRef = await buildContextPackCacheRef(paths, normalizedRef, type, budgetMode);
+        const cached = await readContextPackCache(cacheRef);
+        if (cached) {
+            return attachContextPackCacheMetadata(cached, cacheRef, true);
+        }
+        const finishContextPack = async (context) => {
+            const budgeted = applyContextPackBudget(context, budgetMode);
+            await writeContextPackCache(cacheRef, budgeted);
+            return attachContextPackCacheMetadata(budgeted, cacheRef, false);
+        };
         const coreDocs = [
             coreDocRef(paths, 'index.md'),
             coreDocRef(paths, 'arquitetura.md'),
@@ -80,9 +130,9 @@ export class ContextService {
             coreDocs.push(planningDocRef(paths, 'frontend-auditoria.md'));
         }
         if (type === 'FEAT') {
-            const item = snapshot.backlog.items.find((entry) => entry.id === ref);
+            const item = snapshot.backlog.items.find((entry) => entry.id === normalizedRef);
             if (!item)
-                throw new Error(`Feature ${ref} nao encontrada.`);
+                throw new Error(`Feature ${normalizedRef} nao encontrada.`);
             const unresolved = unresolvedDependencies(item, snapshot.backlog.items);
             const lockConflicts = lockConflictWithActive(item, snapshot.backlog.items);
             const predecessorOutputs = item.blocked_by
@@ -145,9 +195,9 @@ export class ContextService {
                 ? relProjectPath(paths, path.join(paths.projectRoot, workspace.workspace_path, docNames.quality))
                 : '';
             const requiredSkillEvidence = item.recommended_skills.filter(Boolean);
-            return {
+            return finishContextPack({
                 sdd_pack_version: 1,
-                target_id: ref,
+                target_id: normalizedRef,
                 target_type: type,
                 summary: `${item.title} [${item.status}]`,
                 objective: workspace.spec?.objective || item.summary || '',
@@ -166,7 +216,7 @@ export class ContextService {
                 origin: { type: item.origin_type, ref: item.origin_ref || '' },
                 related_discovery: item.origin_ref
                     ? snapshot.discoveryIndex.records
-                        .filter((record) => record.id === item.origin_ref || record.related_ids.includes(ref))
+                        .filter((record) => record.id === item.origin_ref || record.related_ids.includes(normalizedRef))
                         .map((record) => record.id)
                     : [],
                 related_gaps: item.frontend_gap_refs,
@@ -210,22 +260,22 @@ export class ContextService {
                 lock_conflicts_with: lockConflicts,
                 readiness: featureReadiness(item, snapshot.backlog.items),
                 core_docs: coreDocs,
-            };
+            });
         }
         if (type === 'RAD' || type === 'EPIC') {
-            const radar = snapshot.discoveryIndex.records.find((record) => record.id === ref && (record.type === 'RAD' || record.type === 'EPIC'));
+            const radar = snapshot.discoveryIndex.records.find((record) => record.id === normalizedRef && (record.type === 'RAD' || record.type === 'EPIC'));
             if (!radar)
-                throw new Error(`Epic/Radar ${ref} nao encontrado.`);
-            const relatedFeatures = snapshot.backlog.items.filter((item) => (item.origin_type === 'radar' || item.origin_type === 'epic') && item.origin_ref === ref);
-            return {
+                throw new Error(`Epic/Radar ${normalizedRef} nao encontrado.`);
+            const relatedFeatures = snapshot.backlog.items.filter((item) => (item.origin_type === 'radar' || item.origin_type === 'epic') && item.origin_ref === normalizedRef);
+            return finishContextPack({
                 sdd_pack_version: 1,
-                target_id: ref,
+                target_id: normalizedRef,
                 target_type: type,
                 summary: `${radar.title} [${radar.status}]`,
                 quality_contract: radar.quality_contract || null,
                 related_features: relatedFeatures.map((item) => item.id),
                 related_debates: snapshot.discoveryIndex.records
-                    .filter((record) => record.type === 'DEB' && record.related_ids.includes(ref))
+                    .filter((record) => record.type === 'DEB' && record.related_ids.includes(normalizedRef))
                     .map((record) => record.id),
                 read_order: [
                     'README.md',
@@ -234,15 +284,15 @@ export class ContextService {
                     planningDocRef(paths, 'backlog-graph.md'),
                 ],
                 core_docs: coreDocs,
-            };
+            });
         }
         if (type === 'FGAP') {
-            const gap = snapshot.frontendGaps?.items.find((item) => item.id === ref);
+            const gap = snapshot.frontendGaps?.items.find((item) => item.id === normalizedRef);
             if (!gap)
-                throw new Error(`Gap de frontend ${ref} nao encontrado.`);
-            return {
+                throw new Error(`Gap de frontend ${normalizedRef} nao encontrado.`);
+            return finishContextPack({
                 sdd_pack_version: 1,
-                target_id: ref,
+                target_id: normalizedRef,
                 target_type: type,
                 summary: `${gap.title} [${gap.status}]`,
                 source_feature: gap.origin_feature || '',
@@ -255,14 +305,14 @@ export class ContextService {
                     planningDocRef(paths, 'frontend-gaps.md'),
                 ],
                 core_docs: coreDocs,
-            };
+            });
         }
-        const debt = snapshot.techDebt.items.find((item) => item.id === ref);
+        const debt = snapshot.techDebt.items.find((item) => item.id === normalizedRef);
         if (!debt)
-            throw new Error(`Divida tecnica ${ref} nao encontrada.`);
-        return {
+            throw new Error(`Divida tecnica ${normalizedRef} nao encontrada.`);
+        return finishContextPack({
             sdd_pack_version: 1,
-            target_id: ref,
+            target_id: normalizedRef,
             target_type: type,
             summary: `${debt.title} [${debt.status}]`,
             related_refs: debt.related_refs,
@@ -272,7 +322,273 @@ export class ContextService {
                 planningDocRef(paths, 'tech-debt.md'),
             ],
             core_docs: coreDocs,
+        });
+    }
+}
+async function buildContextPackCacheRef(paths, ref, type, mode) {
+    const projectFingerprint = createProjectFingerprint(paths.projectRoot);
+    const sourceFingerprint = await buildContextSourceFingerprint(paths, ref);
+    const key = createHash('sha256')
+        .update(JSON.stringify([CONTEXT_PACK_CACHE_SCHEMA_VERSION, projectFingerprint, ref, type, mode, sourceFingerprint]))
+        .digest('hex')
+        .slice(0, 32);
+    const cacheRoot = path.join(ensureGlobalCacheLayout().projects, projectFingerprint, 'context-summary');
+    const cacheFilePath = path.join(cacheRoot, `${key}.json`);
+    return {
+        schema_version: CONTEXT_PACK_CACHE_SCHEMA_VERSION,
+        enabled: true,
+        key,
+        project_fingerprint: projectFingerprint,
+        source_fingerprint: sourceFingerprint,
+        cache_path: displayCachePath(cacheFilePath),
+        cache_file_path: cacheFilePath,
+    };
+}
+async function buildContextSourceFingerprint(paths, ref) {
+    const hash = createHash('sha256');
+    const stateFiles = Object.values(paths.stateFiles);
+    for (const filePath of stateFiles.sort()) {
+        await hashFileIfPresent(hash, filePath);
+    }
+    const workspaceFiles = await listContextWorkspaceFiles(paths, ref);
+    for (const filePath of workspaceFiles.sort()) {
+        await hashFileIfPresent(hash, filePath);
+    }
+    return hash.digest('hex').slice(0, 32);
+}
+async function listContextWorkspaceFiles(paths, ref) {
+    const workspaceRoots = [paths.activeDir, paths.plannedDir, paths.archivedDir].map((root) => path.join(root, ref));
+    const files = [];
+    for (const workspaceRoot of workspaceRoots) {
+        const names = await fs.readdir(workspaceRoot).catch(() => []);
+        for (const name of names) {
+            if (name.endsWith('.yaml') || name.endsWith('.yml') || name.endsWith('.md')) {
+                files.push(path.join(workspaceRoot, name));
+            }
+        }
+    }
+    return files;
+}
+async function hashFileIfPresent(hash, filePath) {
+    const content = await fs.readFile(filePath).catch(() => null);
+    if (!content)
+        return;
+    hash.update(filePath);
+    hash.update('\0');
+    hash.update(content);
+    hash.update('\0');
+}
+async function readContextPackCache(cacheRef) {
+    const content = await fs.readFile(cacheRef.cache_file_path, 'utf-8').catch(() => '');
+    if (!content.trim())
+        return null;
+    try {
+        const entry = JSON.parse(content);
+        if (entry.schema_version !== CONTEXT_PACK_CACHE_SCHEMA_VERSION ||
+            entry.key !== cacheRef.key ||
+            entry.project_fingerprint !== cacheRef.project_fingerprint ||
+            entry.source_fingerprint !== cacheRef.source_fingerprint ||
+            !isRecord(entry.context)) {
+            return null;
+        }
+        return entry.context;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeContextPackCache(cacheRef, context) {
+    const entry = {
+        schema_version: CONTEXT_PACK_CACHE_SCHEMA_VERSION,
+        key: cacheRef.key,
+        project_fingerprint: cacheRef.project_fingerprint,
+        source_fingerprint: cacheRef.source_fingerprint,
+        created_at: nowIso(),
+        context,
+    };
+    await fs.mkdir(path.dirname(cacheRef.cache_file_path), { recursive: true });
+    await fs.writeFile(cacheRef.cache_file_path, JSON.stringify(entry), 'utf-8').catch(() => undefined);
+}
+function attachContextPackCacheMetadata(context, cacheRef, hit) {
+    const { cache_file_path: _cacheFilePath, ...publicCacheRef } = cacheRef;
+    const result = {
+        ...context,
+        context_cache: {
+            ...publicCacheRef,
+            hit,
+            refreshed_at: nowIso(),
+        },
+    };
+    result.context_budget = {
+        ...result.context_budget,
+        estimated_chars_after_budget: estimatePayloadChars(result),
+    };
+    return result;
+}
+function displayCachePath(filePath) {
+    const homeDir = process.env.HOME ? path.resolve(process.env.HOME) : '';
+    const resolved = path.resolve(filePath);
+    if (!homeDir || !resolved.startsWith(`${homeDir}${path.sep}`)) {
+        return resolved;
+    }
+    return path.join('~', path.relative(homeDir, resolved));
+}
+function applyContextPackBudget(context, mode) {
+    const profile = CONTEXT_PACK_BUDGET_PROFILES[mode];
+    const estimatedBefore = estimatePayloadChars(context);
+    const dedupedFields = [];
+    const truncatedFields = [];
+    const budgeted = { ...context };
+    const targetRef = typeof context.target_id === 'string' ? context.target_id : '<REF>';
+    const omittedFields = [];
+    budgeted.read_order = dedupeArrayField(budgeted.read_order, 'read_order', dedupedFields);
+    budgeted.core_docs = dedupeArrayField(budgeted.core_docs, 'core_docs', dedupedFields);
+    budgeted.relevant_contracts = dedupeArrayField(budgeted.relevant_contracts, 'relevant_contracts', dedupedFields);
+    budgeted.predecessor_outputs = dedupeArrayField(budgeted.predecessor_outputs, 'predecessor_outputs', dedupedFields);
+    budgeted.related_features = dedupeArrayField(budgeted.related_features, 'related_features', dedupedFields);
+    budgeted.related_debates = dedupeArrayField(budgeted.related_debates, 'related_debates', dedupedFields);
+    budgeted.relevant_services = dedupeRelevantServices(budgeted.relevant_services, dedupedFields);
+    budgeted.read_order = trimArrayField(budgeted.read_order, profile.maxReadOrder, 'read_order', truncatedFields, omittedFields);
+    budgeted.core_docs = trimArrayField(budgeted.core_docs, profile.maxCoreDocs, 'core_docs', truncatedFields, omittedFields);
+    budgeted.relevant_contracts = trimArrayField(budgeted.relevant_contracts, profile.maxRelevantContracts, 'relevant_contracts', truncatedFields, omittedFields);
+    budgeted.relevant_services = trimRelevantServices(trimArrayField(budgeted.relevant_services, profile.maxRelevantServices, 'relevant_services', truncatedFields, omittedFields), profile.maxServiceContracts, truncatedFields, omittedFields);
+    budgeted.predecessor_outputs = trimArrayField(budgeted.predecessor_outputs, profile.maxPredecessorOutputs, 'predecessor_outputs', truncatedFields, omittedFields);
+    budgeted.related_features = trimArrayField(budgeted.related_features, profile.maxRelatedFeatures, 'related_features', truncatedFields, omittedFields);
+    budgeted.related_debates = trimArrayField(budgeted.related_debates, profile.maxRelatedDebates, 'related_debates', truncatedFields, omittedFields);
+    const result = {
+        ...budgeted,
+        context_budget: {
+            mode,
+            estimated_chars_before_budget: estimatedBefore,
+            estimated_chars_after_budget: 0,
+            deduped_fields: dedupedFields,
+            truncated_fields: Array.from(new Set(truncatedFields)),
+        },
+    };
+    if (omittedFields.length > 0) {
+        result.progressive_disclosure = {
+            mode,
+            reveal_command: `${CLI_NAME} sdd context ${targetRef} --full --json`,
+            omitted_fields: mergeDisclosureHints(omittedFields),
         };
     }
+    result.context_budget.estimated_chars_after_budget = estimatePayloadChars(result);
+    return result;
+}
+function dedupeArrayField(value, fieldName, dedupedFields) {
+    if (!Array.isArray(value) || value.length <= 1) {
+        return value;
+    }
+    const seen = new Set();
+    const deduped = [];
+    for (const entry of value) {
+        const key = stableContextKey(entry);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(entry);
+    }
+    if (deduped.length < value.length) {
+        dedupedFields.push({
+            field: fieldName,
+            before: value.length,
+            after: deduped.length,
+            removed: value.length - deduped.length,
+        });
+    }
+    return deduped;
+}
+function dedupeRelevantServices(value, dedupedFields) {
+    const services = dedupeArrayField(value, 'relevant_services', dedupedFields);
+    if (!Array.isArray(services)) {
+        return services;
+    }
+    return services.map((service, index) => {
+        if (!isRecord(service) || !Array.isArray(service.contracts)) {
+            return service;
+        }
+        const field = `relevant_services[${index}].contracts`;
+        return {
+            ...service,
+            contracts: dedupeArrayField(service.contracts, field, dedupedFields),
+        };
+    });
+}
+function trimArrayField(value, maxItems, fieldName, truncatedFields, omittedFields) {
+    if (!Array.isArray(value) || !Number.isFinite(maxItems) || value.length <= maxItems) {
+        return value;
+    }
+    truncatedFields.push(fieldName);
+    omittedFields.push({
+        field: fieldName,
+        omitted_count: value.length - maxItems,
+        reason: 'budget',
+    });
+    return value.slice(0, maxItems);
+}
+function trimRelevantServices(value, maxServiceContracts, truncatedFields, omittedFields) {
+    if (!Array.isArray(value) || !Number.isFinite(maxServiceContracts)) {
+        return value;
+    }
+    let truncated = false;
+    const services = value.map((service) => {
+        if (!isRecord(service) || !Array.isArray(service.contracts)) {
+            return service;
+        }
+        if (service.contracts.length <= maxServiceContracts) {
+            return service;
+        }
+        truncated = true;
+        omittedFields.push({
+            field: 'relevant_services.contracts',
+            omitted_count: service.contracts.length - maxServiceContracts,
+            reason: 'budget',
+        });
+        return {
+            ...service,
+            contracts: service.contracts.slice(0, maxServiceContracts),
+        };
+    });
+    if (truncated) {
+        truncatedFields.push('relevant_services.contracts');
+    }
+    return services;
+}
+function mergeDisclosureHints(hints) {
+    const byField = new Map();
+    for (const hint of hints) {
+        const existing = byField.get(hint.field);
+        if (!existing) {
+            byField.set(hint.field, { ...hint });
+            continue;
+        }
+        existing.omitted_count += hint.omitted_count;
+    }
+    return Array.from(byField.values());
+}
+function stableContextKey(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
+        return JSON.stringify(value);
+    }
+    return JSON.stringify(sortContextValue(value));
+}
+function sortContextValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortContextValue);
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, sortContextValue(value[key])]));
+}
+function estimatePayloadChars(value) {
+    return JSON.stringify(value).length;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 //# sourceMappingURL=context.service.js.map

package/dist/core/sdd/services/debate.service.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { promises as fs } from "node:fs";
 import { TransitionEngine } from "../domain/transition-engine.js";
 import { allocateEntityId, loadStateSnapshot, nowIso, saveStateTransaction } from "../state.js";
-import { slugify, computeCanonicalTitle, findDiscoveryRecord, markdownDebateTemplate, buildDefaultQualityContract, syncCounterFromId, getRuntime, persistAndRender, applyLoggedTransition } from "../legacy-operations.js";
+import { slugify, computeCanonicalTitle, findDiscoveryRecord, markdownDebateTemplate, buildDefaultQualityContract, findDebateFile, syncCounterFromId, getRuntime, persistAndRender, applyLoggedTransition } from "../legacy-operations.js";
 import { withStateLock } from "../state-lock.js";
 export class DebateService {
     stores;
@@ -19,10 +19,23 @@ export class DebateService {
             }
             const existingDebate = snapshot.discoveryIndex.records.find((record) => record.type === 'DEB' && record.related_ids.includes(insight.id));
             if (existingDebate) {
+                const existingFile = await findDebateFile(paths, existingDebate.id);
+                if (existingFile) {
+                    return {
+                        id: existingDebate.id,
+                        title: existingDebate.title,
+                        filePath: existingFile,
+                        reused: true,
+                    };
+                }
+                const repairedFilePath = path.join(paths.discoveryDebatesDir, `${existingDebate.id}-${slugify(existingDebate.title)}.md`);
+                await fs.mkdir(paths.discoveryDebatesDir, { recursive: true });
+                await fs.writeFile(repairedFilePath, markdownDebateTemplate(insight, existingDebate.id), 'utf-8');
+                await persistAndRender(paths, config, options?.render);
                 return {
                     id: existingDebate.id,
                     title: existingDebate.title,
-                    filePath: path.join(paths.discoveryDebatesDir, `${existingDebate.id}-${slugify(existingDebate.title)}.md`),
+                    filePath: repairedFilePath,
                     reused: true,
                 };
             }

package/dist/core/sdd/services/feature-lint.service.d.ts

@@ -1,3 +1,6 @@
+import { type SddPaths, type SddRuntimeConfig } from '../state.js';
+import type { BacklogItem } from '../types.js';
+import { type WorkspaceQualityDocument, type WorkspaceTasksDocument } from '../workspace-schemas.js';
 export interface FeatureLintOptions {
     strict?: boolean;
 }
@@ -22,6 +25,25 @@ export interface FeatureLintReport {
     };
     findings: FeatureLintFinding[];
 }
+export declare function isFoundationPrescriptiveFeature(feature: Pick<BacklogItem, 'title' | 'summary'>): boolean;
+export declare function loadTasksDocument(paths: SddPaths, config: SddRuntimeConfig, featureId: string): Promise<{
+    workspacePath: string;
+    tasks?: WorkspaceTasksDocument;
+    error?: string;
+}>;
+export declare function loadQualityDocument(paths: SddPaths, config: SddRuntimeConfig, featureId: string): Promise<{
+    workspacePath: string;
+    quality?: WorkspaceQualityDocument;
+    error?: string;
+}>;
+export declare function hasTemplatePlaceholder(content: string): boolean;
+export declare function collectTaskCommands(tasks: WorkspaceTasksDocument | undefined): string[];
+export declare function addFinding(findings: FeatureLintFinding[], severity: FeatureLintFinding['severity'], code: string, message: string, evidence: Record<string, unknown>): void;
+export declare function lintFeatureShape(feature: BacklogItem, taskCount: number, workspaceError: string | undefined, qualityDocument: WorkspaceQualityDocument | undefined, qualityError: string | undefined, commands: string[], adr: {
+    exists: boolean;
+    isTemplate: boolean;
+    path: string;
+}): FeatureLintFinding[];
 export declare class FeatureLintService {
     execute(projectRoot: string, featureId: string, options?: FeatureLintOptions): Promise<FeatureLintReport>;
 }

package/dist/core/sdd/services/feature-lint.service.js

@@ -2,8 +2,20 @@ import path from 'node:path';
 import { existsSync, promises as fs } from 'node:fs';
 import { loadProjectSddConfig, loadStateSnapshot, resolveSddPaths, } from '../state.js';
 import { activeDocNamesForLayout, ensureMemoryInitialized, relProjectPath } from '../legacy-operations.js';
-import { parseWorkspaceYamlDocument } from '../workspace-schemas.js';
-async function loadTasksDocument(paths, config, featureId) {
+import { parseWorkspaceYamlDocument, } from '../workspace-schemas.js';
+const FOUNDATION_PROFILE_TOKENS = ['foundation api', 'devtrack foundation api'];
+const FOUNDATION_ENFORCEMENT_TOKENS = ['prescriptive', 'enforcement', 'lint', 'scaffold'];
+const ADR_TEMPLATE_PLACEHOLDERS = [
+    'Describe the context that motivated this architecture decision',
+    'Document the decision, the change scope, and the alternatives rejected.',
+    'List positive impacts, residual risks, and mitigation actions.',
+];
+export function isFoundationPrescriptiveFeature(feature) {
+    const source = `${feature.title} ${feature.summary || ''}`.toLowerCase();
+    return (FOUNDATION_PROFILE_TOKENS.some((token) => source.includes(token)) &&
+        FOUNDATION_ENFORCEMENT_TOKENS.some((token) => source.includes(token)));
+}
+export async function loadTasksDocument(paths, config, featureId) {
     const names = activeDocNamesForLayout(config);
     const roots = [paths.activeDir, paths.plannedDir, paths.archivedDir];
     for (const root of roots) {
@@ -30,10 +42,47 @@ async function loadTasksDocument(paths, config, featureId) {
     }
     return { workspacePath: '', error: 'Feature workspace not found.' };
 }
-function addFinding(findings, severity, code, message, evidence) {
+export async function loadQualityDocument(paths, config, featureId) {
+    const names = activeDocNamesForLayout(config);
+    const roots = [paths.activeDir, paths.plannedDir, paths.archivedDir];
+    for (const root of roots) {
+        const workspacePath = path.join(root, featureId);
+        if (!existsSync(workspacePath))
+            continue;
+        const qualityPath = path.join(workspacePath, names.quality);
+        if (!existsSync(qualityPath)) {
+            return { workspacePath: relProjectPath(paths, workspacePath), error: `${names.quality} not found.` };
+        }
+        const content = await fs.readFile(qualityPath, 'utf-8');
+        try {
+            return {
+                workspacePath: relProjectPath(paths, workspacePath),
+                quality: parseWorkspaceYamlDocument('5-quality.yaml', content),
+            };
+        }
+        catch (error) {
+            return {
+                workspacePath: relProjectPath(paths, workspacePath),
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    return { workspacePath: '', error: 'Feature workspace not found.' };
+}
+export function hasTemplatePlaceholder(content) {
+    return ADR_TEMPLATE_PLACEHOLDERS.some((placeholder) => content.includes(placeholder));
+}
+export function collectTaskCommands(tasks) {
+    if (!tasks)
+        return [];
+    return tasks.tasks
+        .flatMap((task) => task.test_scripts.map((script) => script.command.toLowerCase().trim()))
+        .filter(Boolean);
+}
+export function addFinding(findings, severity, code, message, evidence) {
     findings.push({ severity, code, message, evidence });
 }
-function lintFeatureShape(feature, taskCount, workspaceError) {
+export function lintFeatureShape(feature, taskCount, workspaceError, qualityDocument, qualityError, commands, adr) {
     const findings = [];
     if (workspaceError) {
         addFinding(findings, 'error', 'workspace_tasks_unreadable', 'Feature tasks could not be read from the workspace.', {
@@ -87,6 +136,49 @@ function lintFeatureShape(feature, taskCount, workspaceError) {
             touches: feature.touches,
         });
     }
+    if (isFoundationPrescriptiveFeature(feature)) {
+        if ((feature.quality_contract?.enforcement || 'blocking') !== 'blocking') {
+            addFinding(findings, 'error', 'foundation_enforcement_not_blocking', 'Foundation API prescriptive features must use blocking quality enforcement.', {
+                feature_id: feature.id,
+                enforcement: feature.quality_contract?.enforcement || 'undefined',
+            });
+        }
+        if (qualityError) {
+            addFinding(findings, 'error', 'foundation_quality_unreadable', 'Foundation API prescriptive features require a readable 5-quality.yaml workspace document.', {
+                feature_id: feature.id,
+                error: qualityError,
+            });
+        }
+        if (!commands.some((command) => command.includes('sdd lint feature'))) {
+            addFinding(findings, 'error', 'foundation_lint_blocker_missing', 'Foundation API prescriptive features must include a feature-lint blocker command in tasks.', {
+                feature_id: feature.id,
+            });
+        }
+        if (!commands.some((command) => command.includes('sdd plugin devtrack-api scaffold-dry-run'))) {
+            addFinding(findings, 'error', 'foundation_scaffold_blocker_missing', 'Foundation API prescriptive features must include a devtrack-api scaffold dry-run blocker command in tasks.', {
+                feature_id: feature.id,
+            });
+        }
+        const exceptionCount = qualityDocument?.exceptions.length || feature.quality_contract?.exceptions.length || 0;
+        if (exceptionCount > 0 && !feature.requires_adr) {
+            addFinding(findings, 'error', 'foundation_exception_requires_adr_flag', 'Foundation API exceptions require requires_adr=true in backlog state.', {
+                feature_id: feature.id,
+                exceptions: exceptionCount,
+            });
+        }
+        if (exceptionCount > 0 && !adr.exists) {
+            addFinding(findings, 'error', 'foundation_exception_missing_adr', 'Foundation API exceptions require ADR documentation before execution can proceed.', {
+                feature_id: feature.id,
+                expected_adr: adr.path,
+            });
+        }
+        if (exceptionCount > 0 && adr.isTemplate) {
+            addFinding(findings, 'error', 'foundation_exception_adr_template', 'Foundation API exception ADR must be completed with concrete context, decision, and consequences.', {
+                feature_id: feature.id,
+                adr_path: adr.path,
+            });
+        }
+    }
     return findings;
 }
 export class FeatureLintService {
@@ -103,8 +195,16 @@ export class FeatureLintService {
             throw new Error(`Feature ${featureId} not found in backlog.`);
         }
         const workspace = await loadTasksDocument(paths, config, featureId);
+        const qualityWorkspace = await loadQualityDocument(paths, config, featureId);
         const taskCount = workspace.tasks?.tasks.length ?? 0;
-        const findings = lintFeatureShape(feature, taskCount, workspace.error);
+        const commandList = collectTaskCommands(workspace.tasks);
+        const adrPath = path.join(paths.coreDir, 'adrs', `ADR-${feature.id}.md`);
+        const adrContent = await fs.readFile(adrPath, 'utf-8').catch(() => '');
+        const findings = lintFeatureShape(feature, taskCount, workspace.error, qualityWorkspace.quality, qualityWorkspace.error, commandList, {
+            exists: !!adrContent.trim(),
+            isTemplate: hasTemplatePlaceholder(adrContent),
+            path: relProjectPath(paths, adrPath),
+        });
         const hasErrors = findings.some((finding) => finding.severity === 'error');
         const hasWarnings = findings.some((finding) => finding.severity === 'warning');
         const ok = !hasErrors && !(options.strict && hasWarnings);