@devflow-tools/delivery-line 0.18.34 → 0.18.36

package/dist/facade/delivery-line-facade.js

@@ -43,15 +43,23 @@ function normalizeDecisionOptions(options) {
             return false;
         seen.add(id);
         return true;
-    }).map(option => ({ id: option.id.trim(), label: option.label.trim(), ...(option.recommended ? { recommended: true } : {}) }));
+    }).map(option => ({
+        id: option.id.trim(),
+        label: option.label.trim(),
+        ...(option.description?.trim() ? { description: option.description.trim() } : {}),
+        ...(option.recommended ? { recommended: true } : {}),
+    }));
+}
+function normalizeDecisionText(value) {
+    return value.replace(/[\u0000-\u001f\u007f\ufffd]+/gu, ' ').replace(/\s+/gu, ' ').trim();
 }
 function optionsForExistingImplementations(paths) {
     return [
-        { id: 'create-new', label: 'Create a new implementation' },
+        { id: 'create-new', label: 'Create a new implementation', description: 'Add a separate implementation and leave every discovered candidate unchanged.' },
         ...paths.flatMap((path, index) => [
-            { id: `extend-${index + 1}`, label: `Extend existing implementation: ${path}` },
-            { id: `replace-${index + 1}`, label: `Replace existing implementation: ${path}` },
-            { id: `retain-${index + 1}`, label: `Retain existing implementation unchanged: ${path}` },
+            { id: `extend-${index + 1}`, label: `Extend existing implementation: ${path}`, description: `Reuse ${path} and preserve its existing public behavior while adding the requested capability.` },
+            { id: `replace-${index + 1}`, label: `Replace existing implementation: ${path}`, description: `Replace ${path}; the plan must preserve or explicitly revise every current behavior and caller.` },
+            { id: `retain-${index + 1}`, label: `Retain existing implementation unchanged: ${path}`, description: `Keep ${path} unchanged and constrain the new work to a separate integration point.` },
         ]),
     ];
 }
@@ -68,8 +76,10 @@ function nextActionsFor(record) {
         && record.interaction.blockingUnknowns.length === 0
         && record.artifacts.some(artifact => artifact.type === 'intent'))
         || (record.stage === 'spec_ready' && record.artifacts.some(artifact => artifact.type === 'spec'))
-        || record.stage === 'plan_ready'
+        || (record.stage === 'plan_ready' && record.artifacts.some(artifact => artifact.type === 'plan'))
         || record.stage === 'reviewed';
+    if (record.stage === 'plan_ready' && !record.artifacts.some(artifact => artifact.type === 'plan'))
+        nextActions.push('prepare_plan');
     if (approvalReady)
         nextActions.push('approve');
     if (record.blockers?.some(blocker => blocker.code === 'WORKTREE_ADMISSION_REQUIRED'))
@@ -157,7 +167,15 @@ function artifactApprovalDecision(record) {
         caseVersion: record.version,
         turn: record.interaction.turn,
         targetDecisionHash: hash({ caseId: record.id, caseVersion: record.version, turn: record.interaction.turn, approval }),
-        options: [],
+        options: stage === 'release'
+            ? [
+                { id: 'approve', label: 'Approve release', description: 'Accept the reviewed integration revision and continue to package export.' },
+                { id: 'reject', label: 'Reject release', description: 'Stop this delivery because the reviewed revision is not acceptable.' },
+            ]
+            : [
+                { id: 'approve', label: `Approve ${stage} and continue`, description: `Accept the current ${stage} artifact and continue to the next delivery stage.` },
+                { id: 'reject', label: `Reject ${stage} and stop`, description: `Reject the current ${stage} artifact and stop this delivery case.` },
+            ],
         approval,
         status: 'pending',
         createdAt: Date.now(),
@@ -348,12 +366,21 @@ export class DeliveryLineFacade {
         requireIdentity(input);
         if (input.actor.kind !== 'agent')
             throw new DeliveryLineError('UNAUTHORIZED_ROLE', 'only an agent may propose clarification; a trusted user must resolve it');
+        const current = await this.ports.store.get(caseId);
+        const pending = await this.ports.store.getPendingDecision?.(caseId);
+        const options = normalizeDecisionOptions(input.options);
+        if (pending?.status === 'pending') {
+            const sameQuestion = normalizeDecisionText(current.interaction.openQuestions[0] ?? '') === normalizeDecisionText(input.question);
+            const sameOptions = JSON.stringify(pending.options) === JSON.stringify(options);
+            if (sameQuestion && sameOptions)
+                return this.view(current);
+            throw new DeliveryLineError('INVALID_TRANSITION', 'a user decision is already pending', { pendingDecisionId: pending.id, currentTurn: pending.turn, recoveryAction: 'Render and resolve the current pending decision before proposing another question.' });
+        }
         return this.mutate(caseId, input, 'proposal.clarification', async (record) => {
             if (!input.question.trim())
                 throw new DeliveryLineError('MISSING_PREREQUISITE', 'clarification question is required');
             const nextTurn = record.interaction.turn + 1;
             record.interaction = { ...record.interaction, status: 'awaiting_user', turn: nextTurn, openQuestions: [input.question], blockingUnknowns: [input.question] };
-            const options = normalizeDecisionOptions(input.options);
             await this.ports.store.createPendingDecision?.({ id: `${record.id}:decision:${nextTurn}`, caseId: record.id, kind: 'clarification', caseVersion: record.version + 1, turn: nextTurn, targetDecisionHash: hash({ caseId: record.id, question: input.question, options }), options, status: 'pending', createdAt: Date.now() });
             return record;
         });
@@ -368,6 +395,13 @@ export class DeliveryLineFacade {
         const options = normalizeDecisionOptions(input.options);
         if (!input.question.trim() || options.length < 2)
             throw new DeliveryLineError('MISSING_PREREQUISITE', 'at least two materially different options are required');
+        if (pending?.status === 'pending' && !enrichesInitialDecision) {
+            const sameQuestion = normalizeDecisionText(current.interaction.openQuestions[0] ?? '') === normalizeDecisionText(input.question);
+            const sameOptions = JSON.stringify(pending.options) === JSON.stringify(options);
+            if (sameQuestion && sameOptions)
+                return this.view(current);
+            throw new DeliveryLineError('INVALID_TRANSITION', 'a user decision is already pending', { pendingDecisionId: pending.id, currentTurn: pending.turn, recoveryAction: 'Render and resolve the current pending decision before proposing another option set.' });
+        }
         return this.mutate(caseId, input, 'proposal.options', async (record) => {
             const nextTurn = enrichesInitialDecision ? record.interaction.turn : record.interaction.turn + 1;
             record.interaction = { ...record.interaction, status: 'awaiting_user', turn: nextTurn, openQuestions: [input.question], blockingUnknowns: [input.question] };
@@ -424,8 +458,10 @@ export class DeliveryLineFacade {
             if (acceptanceCriteria.length === 0)
                 acceptanceCriteria.push(rawAnswer);
             record.interaction = answerInteraction(record.interaction, input.turn);
-            if (record.unknownRegistry)
-                record.unknownRegistry = record.unknownRegistry.map(item => ({ ...item, blocking: false }));
+            if (record.unknownRegistry) {
+                const answeredQuestion = normalizeDecisionText(question);
+                record.unknownRegistry = record.unknownRegistry.map(item => normalizeDecisionText(item.question) === answeredQuestion ? { ...item, blocking: false } : item);
+            }
             if (input.trustedDecision) {
                 const authority = { id: input.actor.id, kind: 'human' };
                 record.authorities = { ...record.authorities, decisionAuthority: record.authorities?.decisionAuthority ?? authority, approvalAuthority: record.authorities?.approvalAuthority ?? authority };
@@ -434,7 +470,7 @@ export class DeliveryLineFacade {
             const decisionHash = hash({ questionId, optionId: input.optionId, selectedLabel, rawAnswer, acceptanceCriteria, optionsSnapshot });
             record.decisions.push({ id: randomUUID(), kind: 'product', questionId, question, options: optionsSnapshot.map(option => option.label), optionsSnapshot, optionId: input.optionId, selectedLabel, rawAnswer, acceptanceCriteria, decisionHash, sessionId: input.sessionId, toolUseId: input.toolUseId, decision: selectedLabel, decidedBy: input.actor, artifactHash: decisionHash });
             if (record.interaction.phase === 'clarification')
-                record.artifacts.push(await this.createArtifact(record, 'intent', renderIntentMarkdown({ title: record.title, originalRequest: record.originalRequest, problem: selectedLabel, outcome: selectedLabel, answer: rawAnswer, contextQuality: record.contextQuality, affectedSystems: [record.projectRoot], constraints: ['Respect the approved Delivery Line gates.'], successCriteria: [selectedLabel, ...acceptanceCriteria], openQuestions: record.taskSemantics && record.taskSemantics.confidence > 0 ? (record.unknownRegistry?.filter(item => item.blocking).map(item => item.question) ?? []) : record.interaction.blockingUnknowns, unknownRegistry: record.taskSemantics && record.taskSemantics.confidence > 0 ? record.unknownRegistry : undefined, actor: input.actor }), input.actor));
+                record.artifacts.push(await this.createArtifact(record, 'intent', renderIntentMarkdown({ title: record.title, originalRequest: record.originalRequest, problem: record.originalRequest ?? record.title, outcome: selectedLabel, answer: rawAnswer, contextQuality: record.contextQuality, affectedSystems: [record.projectRoot], constraints: ['Preserve existing behavior outside the confirmed scope.'], successCriteria: acceptanceCriteria, openQuestions: record.taskSemantics && record.taskSemantics.confidence > 0 ? (record.unknownRegistry?.filter(item => item.blocking).map(item => item.question) ?? []) : record.interaction.blockingUnknowns, unknownRegistry: record.taskSemantics && record.taskSemantics.confidence > 0 ? record.unknownRegistry : undefined, actor: input.actor }), input.actor));
             await this.createProjectionArtifact(record, 'stack-facts.md', 'Stack facts', 'Project stack evidence bound at case creation.', { baseRef: record.baseRef, targetRef: record.targetRef, projectRoot: record.projectRoot }, input.actor);
             await this.createProjectionArtifact(record, 'decisions.md', 'Decisions', 'Current-turn decision ledger projection.', { decisionHash, questionId, optionId: input.optionId, selectedLabel }, input.actor);
             record.interaction = appendInteractionSummary(record.interaction, { id: randomUUID(), phase: record.interaction.phase, turn: input.turn, question, answer: rawAnswer, rawAnswer, acceptanceCriteria, decision: selectedLabel, options: optionsSnapshot.map(option => option.label), contextReceipt: input.contextReceipt, artifactHashes: [decisionHash], actor: input.actor });
@@ -511,10 +547,118 @@ export class DeliveryLineFacade {
             const requiredContextChannels = [...new Set(Object.values(selectedCapabilities?.selected ?? {}).flatMap(manifest => manifest.requiredContextChannels))]
                 .filter((channel) => ['code', 'memory', 'knowledge'].includes(channel));
             record.pluginSelection = { selectedManifestHash: pluginSelectionHash, stackFactsHash, decisionRefs: [decisionHash], selectionReason: selectedCapabilities?.selectionReason ?? 'selected by current user decision', rejectedAlternatives: [...new Set([...(selectedCapabilities?.rejectedAlternatives ?? []), ...optionsSnapshot.filter(option => option.id !== optionId).map(option => option.id)])], ...(requiredContextChannels.length ? { requiredContextChannels } : {}), ...(selectedCapabilities ? { selectedByRole: Object.fromEntries(Object.entries(selectedCapabilities.selected).map(([role, manifest]) => [role, { pluginName: manifest.name, version: manifest.version, manifestHash: hash(manifest) }])), ...(selectedCapabilities.hostWorkerFallback ? { hostWorkerFallback: true } : {}) } : {}), selectedAt: Date.now() };
+            if (selectedCapabilities && this.ports.capabilities) {
+                const stackFactsFingerprint = record.stackFacts?.fingerprint ?? record.stackFactsHash ?? hash({ projectRoot: record.projectRoot, baseRef: record.baseRef, targetRef: record.targetRef });
+                for (const role of ['analyzer', 'designer']) {
+                    const selected = selectedCapabilities.selected[role];
+                    if (!selected || selected.kind !== 'runner')
+                        continue;
+                    const runtimeManifest = await this.ports.capabilities.manifest(selected.name, role);
+                    const receipt = await this.ports.capabilities.run({
+                        caseId: record.id,
+                        taskId: `${record.id}:${role}:${record.interaction.turn}`,
+                        role,
+                        pluginName: runtimeManifest.pluginName,
+                        capability: runtimeManifest.capability,
+                        manifestHash: runtimeManifest.manifestHash,
+                        stackFactsFingerprint,
+                        allowedFiles: [],
+                        payload: {
+                            changedFiles: [],
+                            role,
+                            request: record.originalRequest ?? record.title,
+                            componentName: record.taskSemantics?.entities[0] ?? selectedLabel,
+                            contextReceiptHash: record.contextReceipt ?? input.contextReceipt,
+                            decisionHash,
+                            optionsSnapshot,
+                        },
+                    });
+                    if (receipt.manifestHash !== runtimeManifest.manifestHash || receipt.verified !== true)
+                        throw new DeliveryLineError('ARTIFACT_HASH_MISMATCH', `plugin ${role} receipt is not verified`);
+                    record.evidence.push({
+                        id: randomUUID(),
+                        kind: 'tool',
+                        hash: hash({ role, pluginName: runtimeManifest.pluginName, pluginVersion: receipt.pluginVersion, manifestHash: receipt.manifestHash, outputHash: receipt.outputHash, contextReceiptHash: record.contextReceipt ?? input.contextReceipt, decisionHash }),
+                        createdAt: Date.now(),
+                        metadata: { role, pluginName: runtimeManifest.pluginName, pluginVersion: receipt.pluginVersion, manifestHash: receipt.manifestHash, outputHash: receipt.outputHash, stackFactsFingerprint, contextReceiptHash: record.contextReceipt ?? input.contextReceipt, decisionHash, verified: receipt.verified },
+                    });
+                }
+            }
             await this.createProjectionArtifact(record, 'plugin-selection.md', 'Plugin selection', 'Capability providers selected by Delivery from stack facts and the current decision.', record.pluginSelection, input.actor);
             record.stage = 'spec_ready';
             record.interaction = { ...record.interaction, phase: 'design', status: 'awaiting_approval', openQuestions: [], blockingUnknowns: [] };
-            record.artifacts.push(await this.createArtifact(record, 'spec', renderSpecMarkdown({ title: record.title, option: selectedLabel, contextReceipt: input.contextReceipt, actor: input.actor }), input.actor));
+            const selectedOption = optionsSnapshot.find(option => option.id === optionId);
+            const acceptanceCriteria = record.decisions
+                .filter(decision => decision.kind === 'product')
+                .flatMap(decision => decision.acceptanceCriteria ?? [decision.selectedLabel ?? decision.decision]);
+            record.artifacts.push(await this.createArtifact(record, 'spec', renderSpecMarkdown({
+                title: record.title,
+                request: record.originalRequest ?? record.title,
+                selectedOption,
+                alternatives: optionsSnapshot.filter(option => option.id !== optionId),
+                acceptanceCriteria,
+                constraints: ['Preserve existing behavior outside the approved scope.', 'Use only dependencies and project conventions verified from the current repository.'],
+                existingImplementations: record.existingImplementations,
+                detectedStacks: record.stackFacts?.detectedStacks,
+                contextReceipt: record.contextReceipt ?? input.contextReceipt,
+                contextGaps: record.contextQuality?.gaps,
+                actor: input.actor,
+            }), input.actor));
+            return record;
+        });
+    }
+    /**
+     * Compile and persist a plan proposal before asking the user to approve it.
+     * Approval must consume this immutable draft by hash; it must never depend on
+     * the model being able to submit a plan object through a trusted command.
+     */
+    async preparePlan(caseId, input) {
+        requireIdentity(input);
+        if (input.actor.kind !== 'agent')
+            throw new DeliveryLineError('UNAUTHORIZED_ROLE', 'only an agent may propose an executable plan; a trusted user must approve it');
+        return this.mutate(caseId, input, 'plan.prepared', async (record) => {
+            if (input.turn !== record.interaction.turn)
+                throw staleTurnError(record, input.turn);
+            if (record.stage !== 'plan_ready')
+                throw new DeliveryLineError('INVALID_TRANSITION', 'plan preparation requires a ready plan stage', { currentStage: record.stage, recoveryAction: 'Refresh delivery_status and follow its nextActions.' });
+            if (record.artifacts.some(artifact => artifact.type === 'plan'))
+                throw new DeliveryLineError('IDEMPOTENCY_CONFLICT', 'a plan draft is already prepared; refresh delivery_status and approve the pending plan decision');
+            if (this.ports.context) {
+                const plannerReceipt = await this.ports.context.build({
+                    role: 'planner',
+                    ...(record.pluginSelection?.requiredContextChannels?.length ? { requiredChannels: record.pluginSelection.requiredContextChannels } : {}),
+                    retrieval: {
+                        taskRevision: record.version + 1,
+                        projectRoot: record.projectRoot,
+                        query: `${record.originalRequest ?? record.title} implementation plan`,
+                        sessionId: input.sessionId,
+                        executionId: input.executionId,
+                        requestId: `delivery:plan:${record.id}:${record.version}`,
+                        turnId: `delivery:plan:${record.id}:${record.interaction.turn}`,
+                    },
+                });
+                record.contextReceipt = plannerReceipt.receiptHash;
+                if (plannerReceipt.channelStatus && plannerReceipt.gaps && plannerReceipt.attribution)
+                    record.contextQuality = { blocking: plannerReceipt.blocking ?? false, ...(plannerReceipt.channelAvailability ? { channelAvailability: plannerReceipt.channelAvailability } : {}), channelStatus: plannerReceipt.channelStatus, gaps: plannerReceipt.gaps, attribution: plannerReceipt.attribution, ...('quality' in plannerReceipt && plannerReceipt.quality ? { quality: plannerReceipt.quality } : {}) };
+            }
+            const planContent = renderPlanMarkdown(input.plan);
+            const planHash = contentHash(planContent);
+            new PlanCompiler().compile({
+                caseId: record.id,
+                projectRoot: record.projectRoot,
+                baseRevision: record.baseRef,
+                planHash,
+                contextReceiptHash: record.contextReceipt ?? input.contextReceipt,
+                hostSelectionSnapshotHash: hash({ mode: 'manual-plan', actor: input.actor, sessionId: input.sessionId, executionId: input.executionId }),
+                executionAuthority: hash({ caseId: record.id, stage: 'plan', planHash }),
+                plan: input.plan,
+            });
+            const artifact = await this.createArtifact(record, 'plan', planContent, input.actor, { path: 'plan.json', content: renderPlanJson(input.plan) });
+            if (artifact.contentHash !== planHash)
+                throw new DeliveryLineError('ARTIFACT_HASH_MISMATCH', 'plan artifact hash changed while persisting the proposal');
+            record.planDraft = structuredClone(input.plan);
+            record.artifacts.push(artifact);
+            record.interaction = { ...record.interaction, status: 'awaiting_approval' };
             return record;
         });
     }
@@ -530,31 +674,17 @@ export class DeliveryLineFacade {
             let planContent;
             let proposedArtifactHash;
             if (input.stage === 'plan') {
-                if (!input.plan)
-                    throw new DeliveryLineError('PLAN_NOT_EXECUTABLE', 'plan approval requires an executable plan');
-                if (this.ports.context) {
-                    const plannerReceipt = await this.ports.context.build({
-                        role: 'planner',
-                        ...(record.pluginSelection?.requiredContextChannels?.length ? { requiredChannels: record.pluginSelection.requiredContextChannels } : {}),
-                        retrieval: {
-                            taskRevision: record.version + 1,
-                            projectRoot: record.projectRoot,
-                            query: `${record.title} implementation plan`,
-                            sessionId: input.sessionId,
-                            executionId: input.executionId,
-                            requestId: `delivery:plan:${record.id}:${record.version}`,
-                            turnId: `delivery:plan:${record.id}:${record.interaction.turn}`,
-                        },
-                    });
-                    record.contextReceipt = plannerReceipt.receiptHash;
-                    if (plannerReceipt.channelStatus && plannerReceipt.gaps && plannerReceipt.attribution)
-                        record.contextQuality = { blocking: plannerReceipt.blocking ?? false, ...(plannerReceipt.channelAvailability ? { channelAvailability: plannerReceipt.channelAvailability } : {}), channelStatus: plannerReceipt.channelStatus, gaps: plannerReceipt.gaps, attribution: plannerReceipt.attribution, ...('quality' in plannerReceipt && plannerReceipt.quality ? { quality: plannerReceipt.quality } : {}) };
-                }
-                planContent = renderPlanMarkdown(input.plan);
+                const proposedPlan = record.planDraft;
+                if (!proposedPlan)
+                    throw new DeliveryLineError('PLAN_NOT_EXECUTABLE', 'plan approval requires a prepared executable plan');
+                planContent = renderPlanMarkdown(proposedPlan);
                 proposedArtifactHash = contentHash(planContent);
+                const preparedArtifact = [...record.artifacts].reverse().find(item => item.type === 'plan');
+                if (preparedArtifact && preparedArtifact.contentHash !== proposedArtifactHash)
+                    throw new DeliveryLineError('ARTIFACT_HASH_MISMATCH', 'prepared plan does not match the approval artifact');
             }
             let artifact = [...record.artifacts].reverse().find(item => item.type === artifactType);
-            if (input.stage !== 'plan') {
+            if (input.stage !== 'release') {
                 if (input.artifactId && artifact?.id !== input.artifactId)
                     throw new DeliveryLineError('ARTIFACT_VERSION_CONFLICT', 'approval artifact id is stale');
                 if (input.expectedVersion !== undefined && artifact?.version !== input.expectedVersion)
@@ -596,6 +726,9 @@ export class DeliveryLineFacade {
             if (input.stage === 'spec')
                 record.stage = 'plan_ready';
             if (input.stage === 'plan') {
+                const proposedPlan = record.planDraft;
+                if (!proposedPlan)
+                    throw new DeliveryLineError('PLAN_NOT_EXECUTABLE', 'plan approval requires a prepared executable plan');
                 const envelopes = new PlanCompiler().compile({
                     caseId: record.id,
                     projectRoot: record.projectRoot,
@@ -604,13 +737,8 @@ export class DeliveryLineFacade {
                     contextReceiptHash: record.contextReceipt ?? input.contextReceipt,
                     hostSelectionSnapshotHash: hash({ mode: 'manual-plan', actor: input.actor, sessionId: input.sessionId, executionId: input.executionId }),
                     executionAuthority: hash({ actor: input.actor, stage: input.stage, planHash: proposedArtifactHash }),
-                    plan: input.plan,
+                    plan: proposedPlan,
                 });
-                record.artifacts = record.artifacts.filter(item => item.type !== 'plan');
-                artifact = await this.createArtifact(record, 'plan', planContent, input.actor, { path: 'plan.json', content: renderPlanJson(input.plan) });
-                if (artifact.contentHash !== proposedArtifactHash)
-                    throw new DeliveryLineError('ARTIFACT_HASH_MISMATCH', 'plan artifact hash changed while persisting the approval artifact');
-                record.artifacts.push(artifact);
                 record.stage = 'plan_approved';
                 const decision = [...record.decisions].reverse().find(item => item.decisionHash);
                 if (decision && record.pluginSelection && record.stackFactsHash) {
@@ -1036,7 +1164,7 @@ export class DeliveryLineFacade {
                 id: pending.id,
                 kind: pending.kind,
                 question: `Approve the current ${pending.approval.stage} artifact?`,
-                options: [],
+                options: pending.options,
                 blocking: true,
                 turn: pending.turn,
                 command: `/devflow:approve ${pending.id}`,