sdd-mcp-server 3.5.1 → 5.0.0

package/dist/application/services/ContextCompactionService.js

@@ -10,9 +10,64 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+import { createHash } from 'node:crypto';
+import path from 'node:path';
 import { injectable, inject } from 'inversify';
-import { v4 as uuidv4 } from 'uuid';
 import { TYPES } from '../../infrastructure/di/types.js';
+import { SpecPathResolver } from './SpecPathResolver.js';
+export class ContextBudgetTooSmallError extends Error {
+    requested;
+    minimumRequired;
+    code = 'ContextBudgetTooSmall';
+    constructor(requested, minimumRequired) {
+        super(`Context budget ${requested} is below the mandatory minimum ${minimumRequired}`);
+        this.requested = requested;
+        this.minimumRequired = minimumRequired;
+        this.name = 'ContextBudgetTooSmallError';
+    }
+}
+export class ContextBudgetExceededError extends Error {
+    requested;
+    required;
+    code = 'ContextBudgetExceeded';
+    constructor(requested, required) {
+        super(`Full context requires ${required} estimated tokens; requested ${requested}`);
+        this.requested = requested;
+        this.required = required;
+        this.name = 'ContextBudgetExceededError';
+    }
+}
+export class PhaseNotApprovedError extends Error {
+    phase;
+    code = 'PhaseNotApproved';
+    constructor(phase) {
+        super(`Phase is not approved: ${phase}`);
+        this.phase = phase;
+        this.name = 'PhaseNotApprovedError';
+    }
+}
+export class ContextArtifactDriftError extends Error {
+    phase;
+    code = 'ArtifactDrift';
+    constructor(phase) {
+        super(`Approved artifact has drifted: ${phase}`);
+        this.phase = phase;
+        this.name = 'ContextArtifactDriftError';
+    }
+}
+export class ContextSourceError extends Error {
+    sourcePath;
+    code = 'ContextSourceError';
+    constructor(sourcePath, message) {
+        super(`${message}: ${sourcePath}`);
+        this.sourcePath = sourcePath;
+        this.name = 'ContextSourceError';
+    }
+}
+const MODE_BUDGETS = { compact: 2048, standard: 4096, full: 16384 };
+const PHASES = ['requirements', 'design', 'tasks'];
+const HANDOFF_SCHEMA = 2;
+const SELECTION_VERSION = 2;
 let ContextCompactionService = class ContextCompactionService {
     fileSystem;
     logger;
@@ -20,227 +75,459 @@ let ContextCompactionService = class ContextCompactionService {
         this.fileSystem = fileSystem;
         this.logger = logger;
     }
+    async loadContext(requestOrProject, legacyMode = 'compact') {
+        if (!('projectRoot' in requestOrProject)) {
+            const result = await this.loadContextRequest({ projectRoot: requestOrProject.path, featureName: requestOrProject.name, mode: legacyMode });
+            return result.content ?? '';
+        }
+        return this.loadContextRequest(requestOrProject);
+    }
     async generatePhaseHandoff(project, approvedPhase) {
-        const correlationId = uuidv4();
-        const contextDir = this.getContextDir(project);
-        const handoffPath = `${contextDir}/handoff.md`;
-        const phaseHandoffPath = `${contextDir}/${approvedPhase}-handoff.md`;
-        this.logger.info('Generating compact workflow handoff', {
-            correlationId,
-            projectId: project.id,
-            approvedPhase
-        });
-        await this.fileSystem.mkdir(contextDir);
-        const documents = await this.loadAvailableDocuments(project);
-        const sourceCharacters = documents.reduce((sum, doc) => sum + doc.content.length, 0);
-        const content = this.buildHandoff(project, approvedPhase, documents, sourceCharacters);
-        await this.fileSystem.writeFile(handoffPath, content);
-        await this.fileSystem.writeFile(phaseHandoffPath, content);
-        const estimate = this.estimateContextSize(sourceCharacters, content.length);
-        this.logger.info('Compact workflow handoff generated', {
-            correlationId,
-            projectId: project.id,
-            approvedPhase,
-            sourceTokens: estimate.sourceTokens,
-            compactTokens: estimate.compactTokens,
-            reductionPercentage: estimate.reductionPercentage
-        });
+        const result = await this.loadContextRequest({ projectRoot: project.path, featureName: project.name, phase: approvedPhase, mode: 'compact' });
+        const content = result.content ?? '';
         return {
-            path: handoffPath,
+            path: path.join(project.path, '.spec', 'specs', project.name, 'context', 'handoff.md'),
             content,
-            estimate
+            fingerprint: result.fingerprint,
+            estimate: this.estimateContextSize(result.sourceCharacters, result.payloadCharacters),
         };
     }
-    async loadContext(project, mode = 'compact') {
-        if (mode === 'full') {
-            return this.loadFullContext(project);
-        }
-        const handoffPath = `${this.getContextDir(project)}/handoff.md`;
+    async invalidateCanonicalHandoff(request) {
+        const resolved = await new SpecPathResolver(this.fileSystem).resolve(request.projectRoot, request.featureName);
+        const handoffPath = path.join(resolved.featureRoot, 'context', 'handoff.md');
+        const contextRoot = path.dirname(handoffPath);
+        const resolver = new SpecPathResolver(this.fileSystem);
+        await resolver.assertContained(resolved.featureRoot, contextRoot);
+        await resolver.assertContained(resolved.featureRoot, handoffPath);
         if (await this.fileSystem.exists(handoffPath)) {
-            const handoff = await this.fileSystem.readFile(handoffPath);
-            if (mode === 'standard') {
-                const spec = await this.readOptionalFile(`${this.getSpecDir(project)}/spec.json`);
-                return [
-                    handoff,
-                    spec ? '\n## Current Spec Metadata\n\n```json\n' + spec + '\n```' : ''
-                ].filter(Boolean).join('\n');
-            }
-            return handoff;
+            if (!this.fileSystem.unlink)
+                throw new Error('FileSystemPort.unlink is required to invalidate context');
+            await this.fileSystem.unlink(handoffPath);
         }
-        const documents = await this.loadAvailableDocuments(project);
-        const sourceCharacters = documents.reduce((sum, doc) => sum + doc.content.length, 0);
-        return this.buildHandoff(project, 'requirements', documents, sourceCharacters);
     }
     estimateContextSize(sourceCharacters, compactCharacters) {
-        const sourceTokens = this.estimateTokens(sourceCharacters);
-        const compactTokens = this.estimateTokens(compactCharacters);
-        const reductionPercentage = sourceTokens === 0
-            ? 0
-            : Math.max(0, Math.round((1 - compactTokens / sourceTokens) * 100));
+        const sourceTokens = Math.ceil(sourceCharacters / 4);
+        const compactTokens = Math.ceil(compactCharacters / 4);
         return {
             sourceCharacters,
             sourceTokens,
             compactCharacters,
             compactTokens,
-            reductionPercentage
+            reductionPercentage: sourceTokens === 0 || compactTokens >= sourceTokens ? 0 : Math.round((1 - compactTokens / sourceTokens) * 100),
+        };
+    }
+    async loadContextRequest(request) {
+        const { mode, budget } = this.resolveLoadOptions(request);
+        const resolver = new SpecPathResolver(this.fileSystem);
+        const resolved = await resolver.resolve(request.projectRoot, request.featureName);
+        const specPath = path.join(resolved.featureRoot, 'spec.json');
+        await resolver.assertContained(resolved.featureRoot, specPath);
+        const spec = await this.readSpec(specPath, request.featureName);
+        const selected = await this.selectState(resolved.featureRoot, spec, request, resolver);
+        const sourceCharacters = selected.documents.reduce((total, document) => total + document.content.length, 0);
+        const sourceFingerprint = this.hash(JSON.stringify({
+            schema: HANDOFF_SCHEMA,
+            phase: selected.phase,
+            status: selected.status,
+            approvals: spec.approvals,
+            reviewRequired: spec.reviewRequired,
+            reviewCompleted: spec.reviewCompleted,
+            implementation: spec.implementation,
+            sources: selected.documents.map(({ relativePath, content }) => [relativePath, content]),
+        }));
+        const fingerprint = this.hash(JSON.stringify({
+            sourceFingerprint,
+            mode,
+            budget,
+            includeUnapproved: request.includeUnapproved === true,
+            selection: SELECTION_VERSION,
+        }));
+        const canonical = mode === 'compact'
+            && request.maxEstimatedTokens === undefined
+            && request.includeUnapproved !== true;
+        const handoffPath = path.join(resolved.featureRoot, 'context', 'handoff.md');
+        const built = mode === 'full'
+            ? this.buildFull(spec, selected, budget)
+            : this.buildBounded(spec, selected, budget, mode, sourceFingerprint, fingerprint, canonical);
+        const cached = await this.readCanonicalCache(canonical, handoffPath, resolved.featureRoot, resolver, built.content);
+        if (cached !== undefined) {
+            const result = this.resultFor(cached, mode, selected, sourceFingerprint, fingerprint, sourceCharacters, [], 'hit');
+            return this.applyEtag(result, request.ifNoneMatch);
+        }
+        await this.persistCanonical(canonical, handoffPath, built.content, resolved.featureRoot, resolver);
+        const result = this.resultFor(built.content, mode, selected, sourceFingerprint, fingerprint, sourceCharacters, built.omittedSources, 'regenerated');
+        this.logger.debug('Context payload prepared', {
+            featureName: request.featureName,
+            mode,
+            phase: selected.phase,
+            payloadEstimatedTokens: result.payloadEstimatedTokens,
+        });
+        return this.applyEtag(result, request.ifNoneMatch);
+    }
+    resolveLoadOptions(request) {
+        const mode = request.mode ?? 'compact';
+        const budget = request.maxEstimatedTokens ?? MODE_BUDGETS[mode];
+        if (!Number.isInteger(budget) || budget <= 0)
+            throw new ContextBudgetTooSmallError(budget, 1);
+        if (request.includeUnapproved && mode !== 'full') {
+            throw new Error('includeUnapproved is supported only in full mode');
+        }
+        return { mode, budget };
+    }
+    async readCanonicalCache(canonical, handoffPath, featureRoot, resolver, expectedContent) {
+        if (!canonical || !(await this.fileSystem.exists(handoffPath)))
+            return undefined;
+        await resolver.assertContained(featureRoot, handoffPath);
+        const cached = await this.fileSystem.readFile(handoffPath);
+        return cached === expectedContent ? cached : undefined;
+    }
+    async persistCanonical(canonical, handoffPath, content, featureRoot, resolver) {
+        if (!canonical)
+            return;
+        const contextRoot = path.dirname(handoffPath);
+        await resolver.assertContained(featureRoot, contextRoot);
+        await this.fileSystem.mkdir(contextRoot);
+        await resolver.assertContained(featureRoot, contextRoot);
+        await resolver.assertContained(featureRoot, handoffPath);
+        if (!this.fileSystem.writeFileAtomic) {
+            throw new Error('FileSystemPort.writeFileAtomic is required for context persistence');
+        }
+        await this.fileSystem.writeFileAtomic(handoffPath, content);
+    }
+    applyEtag(result, ifNoneMatch) {
+        if (ifNoneMatch !== result.fingerprint)
+            return result;
+        return {
+            ...result,
+            content: undefined,
+            cacheStatus: 'not-modified',
+            payloadCharacters: 0,
+            payloadEstimatedTokens: 0,
+        };
+    }
+    async readSpec(specPath, expectedFeature) {
+        if (!(await this.fileSystem.exists(specPath))) {
+            throw new ContextSourceError(specPath, 'Missing required workflow metadata');
+        }
+        const record = await this.readJsonRecord(specPath);
+        const approvalsRecord = this.requiredRecord(record.approvals, specPath, 'Missing approvals');
+        const options = this.optionalRecord(record.workflow_options ?? record.workflowOptions);
+        const checkpoints = this.optionalRecord(record.checkpoints);
+        const test = this.optionalRecord(checkpoints.test_cases ?? checkpoints.testCases);
+        const implementationRecord = this.optionalRecord(record.implementation);
+        const implementationTasks = this.optionalRecord(implementationRecord.tasks);
+        return {
+            featureName: this.specFeatureName(record, expectedFeature, specPath),
+            phase: typeof record.phase === 'string' ? record.phase : 'init',
+            approvals: this.parseApprovals(approvalsRecord),
+            reviewRequired: test.required === true
+                || options.review_test_cases === true
+                || options.reviewTestCases === true,
+            reviewCompleted: test.reviewed === true,
+            implementation: Object.keys(implementationTasks).length > 0
+                ? {
+                    revision: typeof implementationRecord.revision === 'number' ? implementationRecord.revision : 0,
+                    tasks: Object.fromEntries(Object.entries(implementationTasks).map(([taskNumber, value]) => {
+                        const task = this.optionalRecord(value);
+                        const dependencies = Array.isArray(task.dependencies)
+                            ? task.dependencies.filter((dependency) => typeof dependency === 'string')
+                            : [];
+                        return [taskNumber, {
+                                status: typeof task.status === 'string' ? task.status : 'pending',
+                                blocker: typeof task.blocker === 'string' ? task.blocker : undefined,
+                                dependencies,
+                            }];
+                    })),
+                }
+                : undefined,
         };
     }
-    async loadFullContext(project) {
-        const documents = await this.loadAvailableDocuments(project);
-        const sections = documents.map((doc) => `## ${doc.name}\n\n${doc.content}`);
-        return [`# Full SDD Context: ${project.name}`, ...sections].join('\n\n');
-    }
-    buildHandoff(project, approvedPhase, documents, sourceCharacters) {
-        const sourceTokens = this.estimateTokens(sourceCharacters);
-        const sections = documents.map((doc) => this.summarizeDocument(doc));
-        const approvals = project.metadata.approvals;
-        const checkpoint = project.metadata.checkpoints?.testCases;
-        const nextSteps = this.getNextSteps(approvedPhase, checkpoint?.required === true && !checkpoint.reviewed);
-        const draft = [
-            `# SDD Context Handoff: ${project.name}`,
-            '',
-            `Generated: ${new Date().toISOString()}`,
-            `Approved phase: ${approvedPhase}`,
-            '',
-            '## Workflow State',
-            '',
-            `- Requirements: ${this.formatApproval(approvals.requirements)}`,
-            `- Design: ${this.formatApproval(approvals.design)}`,
-            `- Tasks: ${this.formatApproval(approvals.tasks)}`,
-            checkpoint?.required
-                ? `- TDD test-case review: ${checkpoint.reviewed ? 'reviewed' : 'pending'}`
-                : '- TDD test-case review: not required',
-            '',
-            '## Compact Phase Summaries',
-            '',
-            sections.join('\n\n'),
-            '',
-            '## Next Actions',
-            '',
-            ...nextSteps.map((step) => `- ${step}`),
-            '',
-            '## Source References',
-            '',
-            ...documents.map((doc) => `- ${doc.path}`),
-            '',
-            '## Context Budget Estimate',
-            '',
-            `- Full source context: ~${sourceTokens} tokens`,
-            `- Handoff context: ~${this.estimateTokens(sourceCharacters > 0 ? Math.min(sourceCharacters, 1) : 0)} tokens before final write estimate`,
-            '- Use `sdd-context-load` default compact mode for routine continuation.',
-            '- Use `sdd-context-load` with `mode: "full"` only for audits or ambiguous decisions.'
-        ].join('\n');
-        const estimate = this.estimateContextSize(sourceCharacters, draft.length);
-        return draft.replace(/- Handoff context: ~\d+ tokens before final write estimate/, `- Handoff context: ~${estimate.compactTokens} tokens`);
-    }
-    summarizeDocument(doc) {
-        const lines = this.normalizeLines(doc.content);
-        const headings = this.extractHeadings(lines);
-        const bullets = this.extractBullets(lines);
-        const requirements = this.extractRequirementLikeLines(lines);
-        return [
-            `### ${doc.name}`,
-            '',
-            headings.length > 0 ? '**Key sections:**' : '',
-            ...headings.slice(0, 8).map((line) => `- ${line}`),
-            bullets.length > 0 ? '\n**Important points:**' : '',
-            ...bullets.slice(0, 8).map((line) => `- ${line}`),
-            requirements.length > 0 ? '\n**Constraints and acceptance signals:**' : '',
-            ...requirements.slice(0, 8).map((line) => `- ${line}`),
-            headings.length === 0 && bullets.length === 0 && requirements.length === 0
-                ? '- No structured summary points found; open source document if this phase is active.'
-                : ''
-        ].filter(Boolean).join('\n');
-    }
-    async loadAvailableDocuments(project) {
-        const specDir = this.getSpecDir(project);
-        const names = ['requirements.md', 'design.md', 'tasks.md', 'spec.json'];
+    async readJsonRecord(specPath) {
+        let value;
+        try {
+            value = JSON.parse(await this.fileSystem.readFile(specPath));
+        }
+        catch {
+            throw new ContextSourceError(specPath, 'Malformed workflow metadata');
+        }
+        if (!value || typeof value !== 'object') {
+            throw new ContextSourceError(specPath, 'Invalid workflow metadata');
+        }
+        return value;
+    }
+    requiredRecord(value, specPath, message) {
+        if (!value || typeof value !== 'object')
+            throw new ContextSourceError(specPath, message);
+        return value;
+    }
+    optionalRecord(value) {
+        return value && typeof value === 'object' ? value : {};
+    }
+    parseApprovals(record) {
+        return Object.fromEntries(PHASES.map(phase => {
+            const state = this.optionalRecord(record[phase]);
+            return [phase, {
+                    generated: state.generated === true,
+                    approved: state.approved === true,
+                    artifactSha256: typeof state.artifact_sha256 === 'string'
+                        ? state.artifact_sha256
+                        : typeof state.artifactSha256 === 'string'
+                            ? state.artifactSha256
+                            : undefined,
+                }];
+        }));
+    }
+    specFeatureName(record, expectedFeature, specPath) {
+        const persisted = typeof record.feature_name === 'string'
+            ? record.feature_name
+            : typeof record.name === 'string'
+                ? record.name
+                : undefined;
+        if (persisted !== undefined && persisted !== expectedFeature) {
+            throw new ContextSourceError(specPath, 'Feature metadata name does not match directory');
+        }
+        return expectedFeature;
+    }
+    async selectState(featureRoot, spec, request, resolver) {
+        const selection = this.resolveEffectivePhase(spec, request);
+        const documents = await this.readSelectedDocuments(featureRoot, spec, selection.phase, resolver);
+        return { ...selection, documents };
+    }
+    resolveEffectivePhase(spec, request) {
+        if (spec.implementation && !request.phase)
+            return { phase: 'implementation', status: 'approved' };
+        if (request.phase)
+            return this.resolveExplicitPhase(spec, request);
+        if (request.mode === 'full' && request.includeUnapproved) {
+            const latestGenerated = [...PHASES].reverse()
+                .find(candidate => spec.approvals[candidate].generated);
+            if (!latestGenerated)
+                return { phase: 'init', status: 'init' };
+            return {
+                phase: latestGenerated,
+                status: spec.approvals[latestGenerated].approved ? 'approved' : 'unapproved',
+            };
+        }
+        const latestApproved = [...PHASES].reverse()
+            .find(candidate => spec.approvals[candidate].approved);
+        return latestApproved
+            ? { phase: latestApproved, status: 'approved' }
+            : { phase: 'init', status: 'init' };
+    }
+    resolveExplicitPhase(spec, request) {
+        const phase = request.phase;
+        if (!phase)
+            return { phase: 'init', status: 'init' };
+        if (phase === 'implementation') {
+            if (!spec.approvals.tasks.approved || !spec.implementation)
+                throw new PhaseNotApprovedError('tasks');
+            return { phase, status: 'approved' };
+        }
+        const state = spec.approvals[phase];
+        const draftAllowed = request.mode === 'full' && request.includeUnapproved && state.generated;
+        if (!state.approved && !draftAllowed)
+            throw new PhaseNotApprovedError(phase);
+        return { phase, status: state.approved ? 'approved' : 'unapproved' };
+    }
+    async readSelectedDocuments(featureRoot, spec, phase, resolver) {
+        if (phase === 'init')
+            return [];
         const documents = [];
-        for (const name of names) {
-            const path = `${specDir}/${name}`;
-            const content = await this.readOptionalFile(path);
-            if (content) {
-                documents.push({ name, path, content });
+        const last = phase === 'implementation' ? PHASES.length - 1 : PHASES.indexOf(phase);
+        for (const selectedPhase of PHASES.slice(0, last + 1)) {
+            if (!spec.approvals[selectedPhase].generated) {
+                throw new ContextSourceError(`${selectedPhase}.md`, 'Selected phase metadata is inconsistent');
             }
+            documents.push(await this.readPhaseDocument(featureRoot, selectedPhase, spec.approvals[selectedPhase], resolver));
         }
         return documents;
     }
-    async readOptionalFile(path) {
+    async readPhaseDocument(featureRoot, selectedPhase, approval, resolver) {
+        const name = `${selectedPhase}.md`;
+        const absolutePath = path.join(featureRoot, name);
+        await resolver.assertContained(featureRoot, absolutePath);
+        if (!(await this.fileSystem.exists(absolutePath))) {
+            throw new ContextSourceError(absolutePath, 'Missing required selected-phase document');
+        }
+        let content;
         try {
-            if (!(await this.fileSystem.exists(path))) {
-                return null;
-            }
-            return await this.fileSystem.readFile(path);
+            content = await this.fileSystem.readFile(absolutePath);
         }
         catch {
-            return null;
-        }
-    }
-    normalizeLines(content) {
-        return content
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .filter((line) => line.length > 0 && !line.startsWith('```'));
-    }
-    extractHeadings(lines) {
-        return this.unique(lines
-            .filter((line) => /^#{1,4}\s+/.test(line))
-            .map((line) => line.replace(/^#{1,4}\s+/, '').trim()));
-    }
-    extractBullets(lines) {
-        return this.unique(lines
-            .filter((line) => /^[-*]\s+/.test(line) || /^\d+\.\s+/.test(line))
-            .map((line) => line.replace(/^[-*]\s+/, '').replace(/^\d+\.\s+/, '').trim())
-            .filter((line) => line.length > 0 && line.length <= 220));
-    }
-    extractRequirementLikeLines(lines) {
-        const keywords = /\b(SHALL|MUST|WHEN|IF|THEN|WHERE|constraint|risk|security|performance|error|edge case)\b/i;
-        return this.unique(lines
-            .filter((line) => keywords.test(line))
-            .map((line) => line.replace(/^[-*]\s+/, '').replace(/^\d+\.\s+/, '').trim())
-            .filter((line) => line.length <= 240));
-    }
-    unique(lines) {
-        const seen = new Set();
-        const result = [];
-        for (const line of lines) {
-            const key = line.toLowerCase();
-            if (!seen.has(key)) {
-                seen.add(key);
-                result.push(line);
-            }
+            throw new ContextSourceError(absolutePath, 'Unable to read selected-phase document');
+        }
+        if (approval.approved && approval.artifactSha256 && this.hash(content) !== approval.artifactSha256) {
+            throw new ContextArtifactDriftError(selectedPhase);
+        }
+        return {
+            name,
+            relativePath: name,
+            absolutePath,
+            content,
+        };
+    }
+    buildBounded(spec, selected, budget, mode, sourceFingerprint, fingerprint, canonical) {
+        const envelope = this.buildEnvelope(spec, selected, sourceFingerprint, fingerprint, canonical);
+        const maximumCharacters = budget * 4;
+        if (envelope.length > maximumCharacters) {
+            throw new ContextBudgetTooSmallError(budget, Math.ceil(envelope.length / 4));
+        }
+        if (!selected.documents.length) {
+            return { content: this.embedEstimate(envelope), omittedSources: [] };
         }
-        return result;
+        const direct = this.buildDirectPayload(envelope, selected, maximumCharacters);
+        if (direct)
+            return { content: direct, omittedSources: [] };
+        return this.selectCandidates(envelope, this.collectCandidates(selected.documents, mode), selected.documents, maximumCharacters);
+    }
+    buildEnvelope(spec, selected, sourceFingerprint, fingerprint, canonical) {
+        const metadata = canonical
+            ? `<!-- sdd-context schema=${HANDOFF_SCHEMA} phase=${selected.phase} source=${sourceFingerprint} payload=${fingerprint} -->\n`
+            : '';
+        const sourceReferences = selected.documents.length
+            ? selected.documents.map(document => `- ${document.relativePath}`).join('\n')
+            : '- spec.json';
+        const review = spec.reviewRequired
+            ? spec.reviewCompleted ? 'reviewed' : 'pending'
+            : 'not required';
+        const implementationProgress = spec.implementation
+            ? `\n\n## Implementation Progress\n${this.implementationProgress(spec)}`
+            : '';
+        return `${metadata}# SDD Context: ${spec.featureName}\n\n## Workflow State\n- Effective phase: ${selected.phase}\n- Phase status: ${selected.status}\n- Requirements: ${this.approvalLabel(spec.approvals.requirements)}\n- Design: ${this.approvalLabel(spec.approvals.design)}\n- Tasks: ${this.approvalLabel(spec.approvals.tasks)}\n- Test-case review: ${review}${implementationProgress}\n\n## Next Action\n${this.nextAction(spec, selected)}\n\n## Source References\n${sourceReferences}\n\n## Payload Estimate\n- Payload estimated tokens: 00000`;
     }
-    getNextSteps(approvedPhase, testReviewPending) {
-        if (approvedPhase === 'requirements') {
-            return ['Generate or review design using the approved requirements handoff.'];
+    nextAction(spec, selected) {
+        const phase = selected.phase;
+        if (selected.status === 'unapproved') {
+            return `Continue the ${phase} Skill to revise, validate, and request approval for this draft.`;
         }
-        if (approvedPhase === 'design') {
-            return ['Generate TDD task breakdown from the approved design handoff.'];
+        if (phase === 'init')
+            return 'Generate requirements through the requirements Skill.';
+        if (phase === 'requirements')
+            return 'Continue with the design Skill.';
+        if (phase === 'design')
+            return 'Continue with the tasks Skill.';
+        if (phase === 'implementation' && spec.implementation) {
+            const tasks = Object.entries(spec.implementation.tasks);
+            const active = tasks.filter(([, task]) => ['in-progress', 'red-observed', 'green-observed', 'blocked'].includes(task.status));
+            if (active.length === 1)
+                return `Continue task ${active[0][0]} from ${active[0][1].status}.`;
+            if (active.length > 1) {
+                return `Select a resumable task: ${this.taskCandidateSummary(active, true)}.`;
+            }
+            const ready = tasks.filter(([, task]) => task.status === 'pending'
+                && task.dependencies.every((dependency) => spec.implementation.tasks[dependency]?.status === 'completed'));
+            if (ready.length === 1)
+                return `Start task ${ready[0][0]}.`;
+            if (ready.length > 1)
+                return `Select a ready task: ${this.taskCandidateSummary(ready, false)}.`;
+            return tasks.every(([, task]) => task.status === 'completed')
+                ? 'Implementation is complete.'
+                : 'No dependency-ready task is available; inspect persisted task blockers.';
         }
-        if (testReviewPending) {
-            return ['Review TDD test cases, then run sdd-review-test-cases before approving tasks.'];
+        if (spec.reviewRequired && !spec.reviewCompleted)
+            return 'Review test cases before approving tasks.';
+        return 'Start governed implementation.';
+    }
+    taskCandidateSummary(candidates, includeStatus) {
+        const visible = candidates.slice(0, 20).map(([id, task]) => includeStatus ? `${id} (${task.status})` : id);
+        const omitted = candidates.length - visible.length;
+        return `${visible.join(', ')}${omitted > 0 ? `, and ${omitted} more` : ''}`;
+    }
+    implementationProgress(spec) {
+        if (!spec.implementation)
+            return '';
+        const tasks = Object.entries(spec.implementation.tasks);
+        const completed = tasks.filter(([, task]) => task.status === 'completed').length;
+        const active = tasks.filter(([, task]) => ['in-progress', 'red-observed', 'green-observed'].includes(task.status));
+        const blocked = tasks.filter(([, task]) => task.status === 'blocked');
+        const details = [...active, ...blocked].slice(0, 20)
+            .map(([taskNumber, task]) => `- ${taskNumber}: ${task.status}${this.blockerSummary(task.blocker)}`)
+            .join('\n');
+        return `- Revision: ${spec.implementation.revision}\n- Completed: ${completed}/${tasks.length}\n- Active: ${active.length}\n- Blocked: ${blocked.length}${details ? `\n${details}` : ''}`;
+    }
+    blockerSummary(blocker) {
+        if (!blocker)
+            return '';
+        const normalized = blocker.replace(/\s+/g, ' ').trim();
+        const summary = normalized.length > 160 ? `${normalized.slice(0, 159)}…` : normalized;
+        return ` — ${summary}`;
+    }
+    buildDirectPayload(envelope, selected, maximumCharacters) {
+        if (selected.documents.length !== 1 || selected.documents[0].content.length > 600) {
+            return undefined;
         }
-        return ['Begin implementation with compact context loaded; open full docs only for ambiguous details.'];
+        const direct = `${envelope}\n\n## Approved Source\n${selected.documents[0].content.trim()}`;
+        return direct.length <= maximumCharacters ? this.embedEstimate(direct) : undefined;
     }
-    formatApproval(status) {
-        if (status.generated && status.approved) {
-            return 'generated, approved';
+    collectCandidates(documents, mode) {
+        const seen = new Set();
+        const candidates = [];
+        const perLineCap = mode === 'compact' ? 320 : 640;
+        for (const document of documents) {
+            this.collectDocumentCandidates(document, perLineCap, seen, candidates);
         }
-        if (status.generated) {
-            return 'generated, pending approval';
+        return candidates;
+    }
+    collectDocumentCandidates(document, perLineCap, seen, candidates) {
+        for (const rawLine of document.content.split(/\r?\n/)) {
+            const normalized = rawLine.trim().replace(/^[-*]\s+/, '').replace(/^\d+\.\s+/, '');
+            if (!normalized || normalized.startsWith('```'))
+                continue;
+            const capped = normalized.slice(0, perLineCap);
+            const key = capped.toLocaleLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            candidates.push({ source: document.relativePath, text: capped });
+        }
+    }
+    selectCandidates(envelope, candidates, documents, maximumCharacters) {
+        let content = envelope;
+        const usedSources = new Set();
+        for (const candidate of candidates) {
+            const line = `\n- ${candidate.text}`;
+            if (content.length + '\n\n## Selected Context'.length + line.length > maximumCharacters) {
+                continue;
+            }
+            if (!content.includes('\n\n## Selected Context'))
+                content += '\n\n## Selected Context';
+            content += line;
+            usedSources.add(candidate.source);
         }
-        return 'not generated';
+        return {
+            content: this.embedEstimate(content),
+            omittedSources: documents
+                .filter(document => !usedSources.has(document.relativePath))
+                .map(document => document.relativePath),
+        };
+    }
+    buildFull(spec, selected, budget) {
+        let content = [
+            `# Full SDD Context: ${spec.featureName}`,
+            `Effective phase: ${selected.phase} (${selected.status})`,
+            `Next action: ${this.nextAction(spec, selected)}`,
+            ...selected.documents.map((document) => `## ${document.name}\n\n${document.content}`),
+            '## Payload Estimate\n- Payload estimated tokens: 00000',
+        ].join('\n\n');
+        content = this.embedEstimate(content);
+        const required = Math.ceil(content.length / 4);
+        if (required > budget)
+            throw new ContextBudgetExceededError(budget, required);
+        return { content, omittedSources: [] };
+    }
+    embedEstimate(content) {
+        return content.replace('Payload estimated tokens: 00000', `Payload estimated tokens: ${String(Math.ceil(content.length / 4)).padStart(5, '0')}`);
     }
-    estimateTokens(characters) {
-        return Math.max(1, Math.ceil(characters / 4));
+    resultFor(content, mode, selected, sourceFingerprint, fingerprint, sourceCharacters, omittedSources, cacheStatus) {
+        const payloadEstimatedTokens = Math.ceil(content.length / 4);
+        const sourceEstimatedTokens = Math.ceil(sourceCharacters / 4);
+        return { content, mode, effectivePhase: selected.phase, phaseStatus: selected.status, sourceFingerprint, fingerprint, cacheStatus, sourceCharacters, sourceEstimatedTokens, payloadCharacters: content.length, payloadEstimatedTokens, reductionPercentage: sourceEstimatedTokens === 0 || payloadEstimatedTokens >= sourceEstimatedTokens ? 0 : Math.round((1 - payloadEstimatedTokens / sourceEstimatedTokens) * 100), omittedSources };
     }
-    getSpecDir(project) {
-        return `${project.path}/.spec/specs/${project.name}`;
+    approvalLabel(state) {
+        return state.approved ? 'approved' : state.generated ? 'generated, unapproved' : 'not generated';
     }
-    getContextDir(project) {
-        return `${this.getSpecDir(project)}/context`;
+    hash(content) {
+        return createHash('sha256').update(content).digest('hex');
     }
 };
 ContextCompactionService = __decorate([