snipara-companion 2.2.0 → 2.3.0

package/README.md

@@ -56,6 +56,7 @@ npx -y snipara-companion workflow start --goal "ship auth hardening"
 npx -y snipara-companion workflow phase-start audit
 npx -y snipara-companion lead-plan --task "ship auth hardening" --changed-files src/auth/session.ts --proof "pnpm test auth" --acceptance "auth tests pass"
 npx -y snipara-companion lead-plan --from-plan ./project-health-lead-plan.json --reconcile --changed-files src/auth/session.ts
+npx -y snipara-companion lead-plan --from-plan ./project-health-lead-plan.json --json | jq '.engineeringLeadPlan.executionReceipts'
 npx -y snipara-companion workflow phase-commit audit --summary "mapped auth impact"
 npx -y snipara-companion handoff --summary "auth impact mapped" --next "run auth tests"
 ```

package/dist/index.d.ts

@@ -2159,6 +2159,8 @@ declare const ENGINEERING_LEAD_WORKER_ROLES: readonly ["main_agent", "coding_wor
 declare const ENGINEERING_LEAD_ROUTING_MODES: readonly ["hold", "main_agent_execute", "explicit_handoff_ready", "needs_contract"];
 declare const ENGINEERING_LEAD_WORK_PACKAGE_STATUSES: readonly ["contracting", "ready_for_handoff", "executing", "verifying", "blocked", "closed", "unknown"];
 declare const ENGINEERING_LEAD_SUPERVISION_STATUSES: readonly ["on_track", "needs_review", "needs_replan", "blocked", "cold_start", "unknown"];
+declare const ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES: readonly ["pending_handoff", "handoff_ready", "executing", "verification_required", "blocked", "closed", "unknown"];
+declare const ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES: readonly ["handoff", "claim", "approval", "proof", "outcome", "brain_update"];
 type EngineeringLeadPlanSummary = ProjectIntelligenceEngineeringLeadPlanSummary;
 interface CompanionEngineeringLeadReconciliation {
     status: "on_track" | "needs_review" | "needs_replan" | "blocked";
@@ -3519,4 +3521,4 @@ declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions):
 declare function buildAdaptiveWorkRoutingRecommendation(options: AdaptiveWorkRoutingOptions): AdaptiveWorkRoutingRecommendation;
 declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, agentReadinessAuditCommand, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapQuality, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, evaluateProjectPolicyGates, extractCommandFromToolInput, extractFilesFromToolInput, formatAgentReadinessAuditReport, formatCompanionEngineeringLeadPlanReport, formatOrchestratorRecommendationReason, formatPolicyGateDecision, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES, ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, agentReadinessAuditCommand, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapQuality, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, evaluateProjectPolicyGates, extractCommandFromToolInput, extractFilesFromToolInput, formatAgentReadinessAuditReport, formatCompanionEngineeringLeadPlanReport, formatOrchestratorRecommendationReason, formatPolicyGateDecision, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };

package/dist/index.js

@@ -35,6 +35,8 @@ __export(index_exports, {
   AutomationInstallConflictError: () => AutomationInstallConflictError,
   AutomationUnsupportedHookBundleError: () => AutomationUnsupportedHookBundleError,
   COLLABORATION_STATE_RELATIVE_PATH: () => COLLABORATION_STATE_RELATIVE_PATH,
+  ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES: () => ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES,
+  ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES: () => ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES,
   ENGINEERING_LEAD_POSTURES: () => ENGINEERING_LEAD_POSTURES,
   ENGINEERING_LEAD_ROUTING_MODES: () => ENGINEERING_LEAD_ROUTING_MODES,
   ENGINEERING_LEAD_STATUSES: () => ENGINEERING_LEAD_STATUSES,
@@ -10499,6 +10501,23 @@ var PROJECT_INTELLIGENCE_ENGINEERING_LEAD_SUPERVISION_STATUSES = [
   "cold_start",
   "unknown"
 ];
+var PROJECT_INTELLIGENCE_ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES = [
+  "pending_handoff",
+  "handoff_ready",
+  "executing",
+  "verification_required",
+  "blocked",
+  "closed",
+  "unknown"
+];
+var PROJECT_INTELLIGENCE_ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES = [
+  "handoff",
+  "claim",
+  "approval",
+  "proof",
+  "outcome",
+  "brain_update"
+];
 
 // src/commands/lead-plan.ts
 var ENGINEERING_LEAD_STATUSES = PROJECT_HEALTH_COCKPIT_STATUSES;
@@ -10507,6 +10526,8 @@ var ENGINEERING_LEAD_WORKER_ROLES = PROJECT_INTELLIGENCE_ENGINEERING_LEAD_WORKER
 var ENGINEERING_LEAD_ROUTING_MODES = PROJECT_INTELLIGENCE_ENGINEERING_LEAD_ROUTING_MODES;
 var ENGINEERING_LEAD_WORK_PACKAGE_STATUSES = PROJECT_INTELLIGENCE_ENGINEERING_LEAD_WORK_PACKAGE_STATUSES;
 var ENGINEERING_LEAD_SUPERVISION_STATUSES = PROJECT_INTELLIGENCE_ENGINEERING_LEAD_SUPERVISION_STATUSES;
+var ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES = PROJECT_INTELLIGENCE_ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES;
+var ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES = PROJECT_INTELLIGENCE_ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES;
 var TARGET_LABELS = {
   codex: "Codex",
   "claude-code": "Claude Code",
@@ -10851,6 +10872,133 @@ function buildLocalSupervision(input) {
     ]
   };
 }
+function executionReceiptRequiredStagesForRecommendation(recommendation) {
+  const stages = /* @__PURE__ */ new Set(["handoff", "proof", "outcome"]);
+  if (recommendation && recommendation.role !== "main_agent") {
+    stages.add("claim");
+  }
+  if (recommendation?.contract.approvalRequired) {
+    stages.add("approval");
+  }
+  if ((recommendation?.brainUpdateCandidates.length ?? 0) > 0) {
+    stages.add("brain_update");
+  }
+  return ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES.filter((stage) => stages.has(stage));
+}
+function missingRequirementsForExecutionReceipt(input) {
+  const completed = new Set(input.completedStages);
+  const missing = /* @__PURE__ */ new Set();
+  if (!input.workPackage.owner) missing.add("owner");
+  if (input.workPackage.writeScope.length === 0) missing.add("write_scope");
+  if (input.workPackage.acceptanceCriteria.length === 0) missing.add("acceptance_criteria");
+  if (input.workPackage.proofRequired.length === 0) missing.add("proof_gate");
+  if (input.requiredStages.includes("handoff") && !completed.has("handoff")) {
+    missing.add("handoff_receipt");
+  }
+  if (input.requiredStages.includes("claim") && !completed.has("claim")) {
+    missing.add("claim_id");
+  }
+  if (input.requiredStages.includes("approval") && !completed.has("approval")) {
+    missing.add("approval_receipt");
+  }
+  if (input.requiredStages.includes("proof") && !completed.has("proof")) {
+    missing.add("proof_receipt");
+  }
+  if (input.requiredStages.includes("outcome") && !completed.has("outcome")) {
+    missing.add("outcome_receipt");
+  }
+  if (input.brainUpdateCandidates.length > 0 && input.requiredStages.includes("brain_update") && !completed.has("brain_update")) {
+    missing.add("brain_update_receipt");
+  }
+  return Array.from(missing).sort();
+}
+function executionReceiptStatusFromWorkPackage(input) {
+  if (input.workPackage.status === "blocked") return "blocked";
+  if (input.workPackage.status === "closed" && input.requiredStages.every((stage) => input.completedStages.includes(stage))) {
+    return "closed";
+  }
+  if (input.workPackage.status === "executing") return "executing";
+  if (input.workPackage.status === "verifying") return "verification_required";
+  if (input.workPackage.status === "ready_for_handoff") return "handoff_ready";
+  if (input.missingRequirements.length > 0) return "pending_handoff";
+  return "handoff_ready";
+}
+function executionReceiptNextAction(input) {
+  if (input.status === "blocked") {
+    return "Resolve the blocking receipt or proof issue before delegated execution.";
+  }
+  if (input.missingRequirements.includes("handoff_receipt")) {
+    return "Create or attach the handoff receipt before treating this package as delegated.";
+  }
+  if (input.missingRequirements.includes("approval_receipt")) {
+    return "Capture approval before delegated execution can proceed.";
+  }
+  if (input.missingRequirements.includes("proof_receipt")) {
+    return "Attach proof receipts before closure.";
+  }
+  if (input.missingRequirements.includes("outcome_receipt")) {
+    return "Attach an outcome or closure receipt before Brain promotion.";
+  }
+  if (input.missingRequirements.includes("brain_update_receipt")) {
+    return "Record the reviewed Project Brain update receipt.";
+  }
+  if (input.status === "closed") {
+    return "Keep the closed receipt linked for future routing calibration.";
+  }
+  if (input.status === "executing") {
+    return "Monitor liveness and collect proof, outcome, and Brain-update receipts.";
+  }
+  if (input.status === "verification_required") {
+    return "Verify proof and outcome receipts before closure.";
+  }
+  return "Issue the explicit handoff package and collect the required receipts.";
+}
+function buildExpectedExecutionReceipts(input) {
+  const recommendationsByWorkPackageId = new Map(
+    input.workerRecommendations.filter((recommendation) => recommendation.workPackageId).map((recommendation) => [recommendation.workPackageId, recommendation])
+  );
+  return input.workPackages.map((workPackage) => {
+    const recommendation = recommendationsByWorkPackageId.get(workPackage.id);
+    const requiredStages = executionReceiptRequiredStagesForRecommendation(recommendation);
+    const completedStages = [];
+    const brainUpdateCandidates2 = recommendation?.brainUpdateCandidates ?? [];
+    const missingRequirements = missingRequirementsForExecutionReceipt({
+      workPackage,
+      requiredStages,
+      completedStages,
+      brainUpdateCandidates: brainUpdateCandidates2
+    });
+    const status = executionReceiptStatusFromWorkPackage({
+      workPackage,
+      requiredStages,
+      completedStages,
+      missingRequirements
+    });
+    return {
+      id: `engineering-lead-receipt:${workPackage.id}`,
+      workPackageId: workPackage.id,
+      workPackageTitle: workPackage.title,
+      status,
+      requiredStages,
+      completedStages,
+      handoffReceiptId: null,
+      claimId: null,
+      htaskId: null,
+      approvalReceiptId: null,
+      proofReceiptIds: [],
+      outcomeReceiptId: null,
+      brainUpdateReceiptId: null,
+      proofRequired: workPackage.proofRequired,
+      proofExecuted: [],
+      missingRequirements,
+      nextAction: executionReceiptNextAction({ status, missingRequirements }),
+      replanTriggers: workPackage.replanTriggers,
+      brainUpdateCandidates: brainUpdateCandidates2,
+      evidence: workPackage.evidence,
+      reasonCodes: [`engineering_lead_execution_receipt_${status}`, ...workPackage.reasonCodes]
+    };
+  });
+}
 function buildLocalEngineeringLeadPlan(input) {
   const score = computeScore(input);
   const posture = postureForLocalPlan({ ...input, score });
@@ -10919,6 +11067,10 @@ function buildLocalEngineeringLeadPlan(input) {
     workPackages,
     localSignals: input.localSignals
   });
+  const executionReceipts = buildExpectedExecutionReceipts({
+    workPackages,
+    workerRecommendations: [worker]
+  });
   return {
     version: PROJECT_INTELLIGENCE_ENGINEERING_LEAD_PLAN_VERSION,
     contractVersion: PROJECT_INTELLIGENCE_ENGINEERING_LEAD_CONTRACT_VERSION,
@@ -10932,6 +11084,7 @@ function buildLocalEngineeringLeadPlan(input) {
     failClosedFallback: "main_agent",
     workPackages,
     supervision,
+    executionReceipts,
     workerRecommendations: [worker],
     proofGates: input.proofGates,
     brainUpdateActions: brainCandidates,
@@ -11048,6 +11201,93 @@ function normalizeWorkPackage(value, index) {
     reasonCodes
   };
 }
+function normalizeReceiptStages(field, value) {
+  if (!Array.isArray(value)) {
+    return { stages: [], reasonCodes: [] };
+  }
+  const stages = [];
+  const reasonCodes = /* @__PURE__ */ new Set();
+  for (const item of value) {
+    const stage = cockpitEnumValue(
+      field,
+      ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES,
+      item,
+      "handoff"
+    );
+    if (stage.droppedReasonCode) {
+      reasonCodes.add(stage.droppedReasonCode);
+      continue;
+    }
+    if (!stages.includes(stage.value)) {
+      stages.push(stage.value);
+    }
+  }
+  return { stages, reasonCodes: Array.from(reasonCodes) };
+}
+function normalizeExecutionReceipt(value, index, workPackages, workerRecommendations) {
+  const workPackageId = stringValue3(value.workPackageId) ?? workPackages[index]?.id ?? `work-package:${index + 1}`;
+  const workPackage = workPackages.find((candidate) => candidate.id === workPackageId);
+  const recommendation = workerRecommendations.find(
+    (candidate) => candidate.workPackageId === workPackageId
+  );
+  const fallbackRequiredStages = executionReceiptRequiredStagesForRecommendation(recommendation);
+  const requiredStages = normalizeReceiptStages("execution_receipt_stage", value.requiredStages);
+  const completedStages = normalizeReceiptStages("execution_receipt_stage", value.completedStages);
+  const normalizedRequiredStages = requiredStages.stages.length > 0 ? requiredStages.stages : fallbackRequiredStages;
+  const normalizedCompletedStages = completedStages.stages.filter(
+    (stage) => normalizedRequiredStages.includes(stage)
+  );
+  const brainUpdateCandidates2 = stringList(value.brainUpdateCandidates).length > 0 ? stringList(value.brainUpdateCandidates) : recommendation?.brainUpdateCandidates ?? [];
+  const derivedMissing = workPackage && missingRequirementsForExecutionReceipt({
+    workPackage,
+    requiredStages: normalizedRequiredStages,
+    completedStages: normalizedCompletedStages,
+    brainUpdateCandidates: brainUpdateCandidates2
+  });
+  const missingRequirements = stringList(value.missingRequirements).length > 0 ? stringList(value.missingRequirements) : derivedMissing ?? [];
+  const fallbackStatus = workPackage ? executionReceiptStatusFromWorkPackage({
+    workPackage,
+    requiredStages: normalizedRequiredStages,
+    completedStages: normalizedCompletedStages,
+    missingRequirements
+  }) : "pending_handoff";
+  const status = cockpitEnumValue(
+    "execution_receipt_status",
+    ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES,
+    value.status,
+    fallbackStatus
+  );
+  return {
+    id: stringValue3(value.id) ?? `engineering-lead-receipt:${workPackageId}`,
+    workPackageId,
+    workPackageTitle: stringValue3(value.workPackageTitle) ?? workPackage?.title ?? `Imported work package ${index + 1}`,
+    status: status.value,
+    requiredStages: normalizedRequiredStages,
+    completedStages: normalizedCompletedStages,
+    handoffReceiptId: stringValue3(value.handoffReceiptId) ?? null,
+    claimId: stringValue3(value.claimId) ?? null,
+    htaskId: stringValue3(value.htaskId) ?? null,
+    approvalReceiptId: stringValue3(value.approvalReceiptId) ?? null,
+    proofReceiptIds: stringList(value.proofReceiptIds),
+    outcomeReceiptId: stringValue3(value.outcomeReceiptId) ?? null,
+    brainUpdateReceiptId: stringValue3(value.brainUpdateReceiptId) ?? null,
+    proofRequired: stringList(value.proofRequired).length > 0 ? stringList(value.proofRequired) : workPackage?.proofRequired ?? [],
+    proofExecuted: stringList(value.proofExecuted),
+    missingRequirements,
+    nextAction: stringValue3(value.nextAction) ?? executionReceiptNextAction({ status: status.value, missingRequirements }),
+    replanTriggers: stringList(value.replanTriggers).length > 0 ? stringList(value.replanTriggers) : workPackage?.replanTriggers ?? [],
+    brainUpdateCandidates: brainUpdateCandidates2,
+    evidence: normalizeEvidence(value.evidence).length > 0 ? normalizeEvidence(value.evidence) : workPackage?.evidence ?? [],
+    reasonCodes: [
+      .../* @__PURE__ */ new Set([
+        ...stringList(value.reasonCodes),
+        ...compactReasonCodes([status.droppedReasonCode]),
+        ...requiredStages.reasonCodes,
+        ...completedStages.reasonCodes
+      ])
+    ]
+  };
+}
 function summarizeSupervisionFromWorkPackages(workPackages) {
   const blockedWorkPackages = workPackages.filter(
     (workPackage) => workPackage.status === "blocked"
@@ -11150,6 +11390,10 @@ function normalizeCockpitPlan(cockpit) {
   );
   const workPackages = recordList2(rawPlan.workPackages).map(normalizeWorkPackage);
   const supervision = normalizeSupervision(rawPlan.supervision, workPackages);
+  const rawExecutionReceipts = recordList2(rawPlan.executionReceipts);
+  const executionReceipts = rawExecutionReceipts.length > 0 ? rawExecutionReceipts.map(
+    (receipt, index) => normalizeExecutionReceipt(receipt, index, workPackages, workerRecommendations)
+  ) : buildExpectedExecutionReceipts({ workPackages, workerRecommendations });
   const posture = cockpitEnumValue(
     "posture",
     ENGINEERING_LEAD_POSTURES,
@@ -11171,6 +11415,9 @@ function normalizeCockpitPlan(cockpit) {
   const supervisionDroppedReasonCodes = supervision.reasonCodes.filter(
     (code2) => code2.startsWith("companion_dropped_unknown_")
   );
+  const executionReceiptDroppedReasonCodes = executionReceipts.flatMap(
+    (receipt) => receipt.reasonCodes.filter((code2) => code2.startsWith("companion_dropped_unknown_"))
+  );
   return {
     version: PROJECT_INTELLIGENCE_ENGINEERING_LEAD_PLAN_VERSION,
     contractVersion: PROJECT_INTELLIGENCE_ENGINEERING_LEAD_CONTRACT_VERSION,
@@ -11184,6 +11431,7 @@ function normalizeCockpitPlan(cockpit) {
     failClosedFallback: "main_agent",
     workPackages,
     supervision,
+    executionReceipts,
     workerRecommendations,
     proofGates: stringList(rawPlan.proofGates),
     brainUpdateActions: stringList(rawPlan.brainUpdateActions),
@@ -11206,7 +11454,8 @@ function normalizeCockpitPlan(cockpit) {
         ...stringList(rawPlan.reasonCodes),
         ...workerDroppedReasonCodes,
         ...workPackageDroppedReasonCodes,
-        ...supervisionDroppedReasonCodes
+        ...supervisionDroppedReasonCodes,
+        ...executionReceiptDroppedReasonCodes
       ])
     ]
   };
@@ -11223,6 +11472,7 @@ function reconcileEngineeringLeadPlan(input) {
   const reasonCodes = /* @__PURE__ */ new Set(["companion_lead_plan_reconciled"]);
   const plannedScope = scopeSetForPlan(input.plan);
   const outOfScopeFiles = input.changedFiles.filter((file) => !plannedScope.has(file));
+  const executionReceipts = input.plan.executionReceipts ?? [];
   if (input.plan.workPackages.length === 0) {
     changedSignals.add("no_imported_work_packages");
     recommendedActions.add("Create or import bounded work packages before delegation.");
@@ -11270,9 +11520,25 @@ function reconcileEngineeringLeadPlan(input) {
   for (const trigger of input.plan.supervision.replanTriggers) {
     recommendedActions.add(trigger);
   }
-  const blocked = input.plan.supervision.status === "blocked" || input.plan.workPackages.some((workPackage) => workPackage.status === "blocked");
+  for (const receipt of executionReceipts) {
+    if (receipt.status === "blocked") {
+      changedSignals.add(`blocked_execution_receipt:${receipt.workPackageId}`);
+      recommendedActions.add(receipt.nextAction);
+      reasonCodes.add("companion_reconcile_execution_receipt_blocked");
+    }
+    if (receipt.missingRequirements.length > 0) {
+      changedSignals.add(
+        `execution_receipt_missing:${receipt.workPackageId}:${receipt.missingRequirements.join(",")}`
+      );
+      recommendedActions.add(
+        `Attach missing execution receipt requirement(s) for ${receipt.workPackageTitle}: ${receipt.missingRequirements.join(", ")}.`
+      );
+      reasonCodes.add("companion_reconcile_execution_receipt_missing_requirements");
+    }
+  }
+  const blocked = input.plan.supervision.status === "blocked" || input.plan.workPackages.some((workPackage) => workPackage.status === "blocked") || executionReceipts.some((receipt) => receipt.status === "blocked");
   const replanRequired = blocked || input.plan.supervision.replanRequired || outOfScopeFiles.length > 0 || !input.localSignals.workflow.present || input.localSignals.workflow.status !== "active";
-  const reviewRequired = replanRequired || input.plan.supervision.reviewRequired || !input.localSignals.teamSync.present || input.declaredRisks.length > 0;
+  const reviewRequired = replanRequired || input.plan.supervision.reviewRequired || executionReceipts.some((receipt) => receipt.missingRequirements.length > 0) || !input.localSignals.teamSync.present || input.declaredRisks.length > 0;
   const status = blocked ? "blocked" : replanRequired ? "needs_replan" : reviewRequired ? "needs_review" : "on_track";
   return {
     status,
@@ -11390,6 +11656,7 @@ function formatList2(values, empty = "none") {
 }
 function formatCompanionEngineeringLeadPlanReport(report) {
   const plan = report.engineeringLeadPlan;
+  const executionReceipts = plan.executionReceipts ?? [];
   const lines = [];
   lines.push("Companion Engineering Lead Plan");
   lines.push(`Generated: ${report.generatedAt}`);
@@ -11437,6 +11704,25 @@ function formatCompanionEngineeringLeadPlanReport(report) {
     }
   }
   lines.push("");
+  lines.push("Execution Receipts");
+  if (executionReceipts.length === 0) {
+    lines.push("- none");
+  } else {
+    for (const receipt of executionReceipts) {
+      lines.push(`- [${receipt.status}] ${receipt.workPackageTitle}`);
+      lines.push(`  package: ${receipt.workPackageId}`);
+      lines.push(`  required stages: ${formatList2(receipt.requiredStages)}`);
+      lines.push(`  completed stages: ${formatList2(receipt.completedStages)}`);
+      lines.push(`  handoff receipt: ${receipt.handoffReceiptId ?? "missing"}`);
+      lines.push(`  claim: ${receipt.claimId ?? "missing"}`);
+      lines.push(`  approval receipt: ${receipt.approvalReceiptId ?? "missing"}`);
+      lines.push(`  outcome receipt: ${receipt.outcomeReceiptId ?? "missing"}`);
+      lines.push(`  brain update receipt: ${receipt.brainUpdateReceiptId ?? "missing"}`);
+      lines.push(`  missing: ${formatList2(receipt.missingRequirements)}`);
+      lines.push(`  next: ${receipt.nextAction}`);
+    }
+  }
+  lines.push("");
   lines.push("Worker Recommendations");
   for (const worker of plan.workerRecommendations) {
     lines.push(`- [${worker.status}] ${worker.label} (${worker.role}, ${worker.routingMode})`);
@@ -25326,6 +25612,8 @@ if (require.main === module) {
   AutomationInstallConflictError,
   AutomationUnsupportedHookBundleError,
   COLLABORATION_STATE_RELATIVE_PATH,
+  ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES,
+  ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES,
   ENGINEERING_LEAD_POSTURES,
   ENGINEERING_LEAD_ROUTING_MODES,
   ENGINEERING_LEAD_STATUSES,

package/docs/FULL_REFERENCE.md

@@ -313,6 +313,12 @@ Health: posture, score, routing mode, bounded worker contract, supervised work
 packages, supervision/replan status, proof gates, candidate Project Brain
 updates, `workersSpawned: 0`, and `main_agent` fallback.
 
+Engineering Lead Execution Receipts V1 adds `executionReceipts` to that plan.
+Each receipt records the expected handoff, claim, approval, proof, outcome, and
+Project Brain update stages for a work package, plus missing requirements and
+next actions. Unknown future receipt enum values fail closed with
+`companion_dropped_unknown_execution_receipt_*` reason codes.
+
 Use `--from-cockpit <file>` or `--from-plan <file>` when Project Health has
 exported a cockpit/lead-plan JSON artifact and Companion only needs to normalize
 it into Markdown or JSON for handoff. Add `--reconcile` to compare the imported

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {