snipara-companion 2.1.1 → 2.2.0

package/README.md

@@ -55,6 +55,7 @@ After the first impact check, keep the work resumable:
 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 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

@@ -2157,7 +2157,18 @@ declare const ENGINEERING_LEAD_STATUSES: readonly ["healthy", "watch", "risk", "
 declare const ENGINEERING_LEAD_POSTURES: readonly ["lead_ready", "lead_watch", "lead_blocked", "lead_cold_start"];
 declare const ENGINEERING_LEAD_WORKER_ROLES: readonly ["main_agent", "coding_worker", "test_worker", "reviewer", "documentation_worker", "human_approver"];
 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"];
 type EngineeringLeadPlanSummary = ProjectIntelligenceEngineeringLeadPlanSummary;
+interface CompanionEngineeringLeadReconciliation {
+    status: "on_track" | "needs_review" | "needs_replan" | "blocked";
+    summary: string;
+    replanRequired: boolean;
+    reviewRequired: boolean;
+    changedSignals: string[];
+    recommendedActions: string[];
+    reasonCodes: string[];
+}
 interface CompanionEngineeringLeadPlanReport {
     version: "snipara.companion_engineering_lead_plan.v1";
     generatedAt: string;
@@ -2176,6 +2187,7 @@ interface CompanionEngineeringLeadPlanReport {
         declaredRisks: string[];
     };
     localSignals: AgentReadinessLocalSignals;
+    reconciliation?: CompanionEngineeringLeadReconciliation;
     suggestedCommands: string[];
     caveats: string[];
 }
@@ -2188,6 +2200,8 @@ interface LeadPlanCommandOptions {
     acceptance?: string[];
     risk?: string[];
     fromCockpit?: string;
+    fromPlan?: string;
+    reconcile?: boolean;
     dir?: string;
     output?: string;
     json?: boolean;
@@ -3505,4 +3519,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_WORKER_ROLES, 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_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

@@ -38,7 +38,9 @@ __export(index_exports, {
   ENGINEERING_LEAD_POSTURES: () => ENGINEERING_LEAD_POSTURES,
   ENGINEERING_LEAD_ROUTING_MODES: () => ENGINEERING_LEAD_ROUTING_MODES,
   ENGINEERING_LEAD_STATUSES: () => ENGINEERING_LEAD_STATUSES,
+  ENGINEERING_LEAD_SUPERVISION_STATUSES: () => ENGINEERING_LEAD_SUPERVISION_STATUSES,
   ENGINEERING_LEAD_WORKER_ROLES: () => ENGINEERING_LEAD_WORKER_ROLES,
+  ENGINEERING_LEAD_WORK_PACKAGE_STATUSES: () => ENGINEERING_LEAD_WORK_PACKAGE_STATUSES,
   ORCHESTRATOR_HANDOFF_RELATIVE_PATH: () => ORCHESTRATOR_HANDOFF_RELATIVE_PATH,
   TEAM_SYNC_STATE_RELATIVE_PATH: () => TEAM_SYNC_STATE_RELATIVE_PATH,
   WORKFLOW_PLANS_RELATIVE_DIR: () => WORKFLOW_PLANS_RELATIVE_DIR,
@@ -10459,6 +10461,7 @@ var path15 = __toESM(require("path"));
 // ../project-intelligence-contracts/src/index.ts
 var PROJECT_HEALTH_COCKPIT_STATUSES = ["healthy", "watch", "risk", "unknown"];
 var PROJECT_INTELLIGENCE_ENGINEERING_LEAD_PLAN_VERSION = "project-intelligence-engineering-lead-plan-v0";
+var PROJECT_INTELLIGENCE_ENGINEERING_LEAD_CONTRACT_VERSION = "engineering-lead-contract-v1";
 var PROJECT_INTELLIGENCE_ENGINEERING_LEAD_POSTURES = [
   "lead_ready",
   "lead_watch",
@@ -10479,12 +10482,31 @@ var PROJECT_INTELLIGENCE_ENGINEERING_LEAD_ROUTING_MODES = [
   "explicit_handoff_ready",
   "needs_contract"
 ];
+var PROJECT_INTELLIGENCE_ENGINEERING_LEAD_WORK_PACKAGE_STATUSES = [
+  "contracting",
+  "ready_for_handoff",
+  "executing",
+  "verifying",
+  "blocked",
+  "closed",
+  "unknown"
+];
+var PROJECT_INTELLIGENCE_ENGINEERING_LEAD_SUPERVISION_STATUSES = [
+  "on_track",
+  "needs_review",
+  "needs_replan",
+  "blocked",
+  "cold_start",
+  "unknown"
+];
 
 // src/commands/lead-plan.ts
 var ENGINEERING_LEAD_STATUSES = PROJECT_HEALTH_COCKPIT_STATUSES;
 var ENGINEERING_LEAD_POSTURES = PROJECT_INTELLIGENCE_ENGINEERING_LEAD_POSTURES;
 var ENGINEERING_LEAD_WORKER_ROLES = PROJECT_INTELLIGENCE_ENGINEERING_LEAD_WORKER_ROLES;
 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 TARGET_LABELS = {
   codex: "Codex",
   "claude-code": "Claude Code",
@@ -10724,6 +10746,111 @@ function suggestedCommands2(input) {
   }
   return commands;
 }
+function localWorkPackageStatus(input) {
+  if (input.posture === "lead_cold_start") return "unknown";
+  if (input.posture === "lead_blocked") return "blocked";
+  if (input.routingMode === "explicit_handoff_ready") return "ready_for_handoff";
+  return "contracting";
+}
+function localWorkPackageReplanTriggers(input) {
+  const triggers = /* @__PURE__ */ new Set();
+  if (!input.task) {
+    triggers.add("Define the task before treating this as a work package.");
+  }
+  if (input.changedFiles.length === 0) {
+    triggers.add("Declare the write scope before delegation.");
+  }
+  if (input.acceptanceCriteria.length === 0) {
+    triggers.add("Add acceptance criteria before worker handoff.");
+  }
+  if (input.proofGates.length === 0) {
+    triggers.add("Add proof gates before worker handoff.");
+  }
+  if (!input.localSignals.workflow.present || input.localSignals.workflow.status !== "active") {
+    triggers.add("Start or resume a Companion workflow before delegated execution.");
+  }
+  if (!input.localSignals.teamSync.present) {
+    triggers.add("Record a Team Sync breadcrumb before handing work to another agent.");
+  }
+  if (input.declaredRisks.length > 0) {
+    triggers.add("Review declared risks before promoting Brain update candidates.");
+  }
+  return Array.from(triggers);
+}
+function buildLocalWorkPackages(input) {
+  if (!input.workPackageId) {
+    return [];
+  }
+  const workPackageStatus = localWorkPackageStatus({
+    posture: input.posture,
+    routingMode: input.routingMode
+  });
+  const replanTriggers = localWorkPackageReplanTriggers(input);
+  return [
+    {
+      id: input.workPackageId,
+      title: input.workPackageTitle,
+      status: workPackageStatus,
+      health: input.status,
+      owner: input.owner,
+      dependencies: [],
+      writeScope: input.changedFiles,
+      acceptanceCriteria: input.acceptanceCriteria,
+      proofRequired: input.proofGates,
+      resultExpectation: input.routingMode === "explicit_handoff_ready" ? "Return changed files, proof receipts, residual risks, and candidate Project Brain updates." : "Return a bounded implementation summary only after the contract is complete.",
+      nextAction: workPackageStatus === "ready_for_handoff" ? "Generate a handoff or adapter pack, then collect proof receipts before closure." : replanTriggers[0] ?? "Tighten the work package contract before handoff.",
+      replanTriggers,
+      evidence: input.evidence,
+      reasonCodes: [
+        `engineering_lead_work_package_${workPackageStatus}`,
+        `engineering_lead_${input.posture}`,
+        `routing_${input.routingMode}`
+      ]
+    }
+  ];
+}
+function buildLocalSupervision(input) {
+  const replanTriggers = Array.from(
+    new Set(input.workPackages.flatMap((workPackage) => workPackage.replanTriggers))
+  );
+  const reviewRequired = input.posture === "lead_watch" || input.routingMode === "main_agent_execute" || input.workPackages.some((workPackage) => workPackage.replanTriggers.length > 0);
+  const replanRequired = input.posture === "lead_blocked" || input.workPackages.some((workPackage) => workPackage.status === "blocked");
+  const status = input.workPackages.length === 0 ? "cold_start" : replanRequired ? "blocked" : reviewRequired ? "needs_review" : "on_track";
+  const readyWorkPackages = input.workPackages.filter(
+    (workPackage) => workPackage.status === "ready_for_handoff"
+  ).length;
+  const blockedWorkPackages = input.workPackages.filter(
+    (workPackage) => workPackage.status === "blocked"
+  ).length;
+  const receiptsRequired = /* @__PURE__ */ new Set();
+  if (input.routingMode === "explicit_handoff_ready") {
+    receiptsRequired.add("handoff_receipt");
+    receiptsRequired.add("proof_receipt");
+  }
+  if (!input.localSignals.teamSync.present) {
+    receiptsRequired.add("team_sync_handoff");
+  }
+  return {
+    status,
+    summary: status === "cold_start" ? "No local work package is available for supervision yet." : status === "blocked" ? "Local delegation is blocked until the worker contract has scope, acceptance, and proof." : status === "needs_review" ? "Local work is scoped, but workflow continuity or handoff readiness still needs review." : "Local work package is ready for advisory handoff supervision.",
+    openWorkPackages: input.workPackages.length,
+    blockedWorkPackages,
+    readyWorkPackages,
+    executingWorkPackages: 0,
+    verifyingWorkPackages: 0,
+    closedWorkPackages: 0,
+    reviewRequired,
+    replanRequired,
+    nextCheck: status === "cold_start" ? "Define task scope, files, context refs, and proof gates." : status === "blocked" ? "Close contract gaps before delegated execution." : status === "needs_review" ? "Review workflow, Team Sync, risks, and proof gates before handoff." : "Collect proof and outcome receipts after handoff.",
+    replanTriggers,
+    receiptsRequired: Array.from(receiptsRequired),
+    reasonCodes: [
+      "engineering_lead_contract_v1_supervision",
+      `engineering_lead_supervision_${status}`,
+      `routing_${input.routingMode}`
+    ]
+  };
+}
 function buildLocalEngineeringLeadPlan(input) {
   const score = computeScore(input);
   const posture = postureForLocalPlan({ ...input, score });
@@ -10743,6 +10870,7 @@ function buildLocalEngineeringLeadPlan(input) {
   ].slice(0, 10);
   const brainCandidates = brainUpdateCandidates(input);
   const workPackageId = posture === "lead_cold_start" ? null : `lead-plan:${slug(workPackageTitle, "work-package")}`;
+  const owner = posture === "lead_cold_start" ? "main_agent" : TARGET_LABELS[input.target];
   const worker = {
     id: workPackageId ?? "engineering-lead:cold-start",
     role,
@@ -10751,7 +10879,7 @@ function buildLocalEngineeringLeadPlan(input) {
     routingMode,
     workPackageId,
     workPackageTitle: posture === "lead_cold_start" ? null : workPackageTitle,
-    owner: posture === "lead_cold_start" ? "main_agent" : TARGET_LABELS[input.target],
+    owner,
     rationale: routingMode === "explicit_handoff_ready" ? "Local scope, workflow continuity, acceptance, and proof gates are present for an explicit handoff." : routingMode === "main_agent_execute" ? "The contract is usable, but no active Companion workflow is present; keep execution with the main agent." : routingMode === "needs_contract" ? "Proof gates or acceptance criteria are incomplete; hold worker launch until the contract is explicit." : "No bounded work package exists yet; the main agent must define scope before delegation.",
     contract: {
       writeScope: input.changedFiles,
@@ -10770,8 +10898,30 @@ function buildLocalEngineeringLeadPlan(input) {
       `routing_${routingMode}`
     ]
   };
+  const workPackages = buildLocalWorkPackages({
+    workPackageId,
+    workPackageTitle,
+    status,
+    posture,
+    routingMode,
+    owner,
+    changedFiles: input.changedFiles,
+    acceptanceCriteria: input.acceptanceCriteria,
+    proofGates: input.proofGates,
+    evidence,
+    declaredRisks: input.declaredRisks,
+    localSignals: input.localSignals,
+    task: input.task
+  });
+  const supervision = buildLocalSupervision({
+    posture,
+    routingMode,
+    workPackages,
+    localSignals: input.localSignals
+  });
   return {
     version: PROJECT_INTELLIGENCE_ENGINEERING_LEAD_PLAN_VERSION,
+    contractVersion: PROJECT_INTELLIGENCE_ENGINEERING_LEAD_CONTRACT_VERSION,
     posture,
     status,
     score,
@@ -10780,6 +10930,8 @@ function buildLocalEngineeringLeadPlan(input) {
     nextAction: routingMode === "explicit_handoff_ready" ? "Generate a handoff or adapter pack, then require proof receipts before closure." : routingMode === "main_agent_execute" ? "Start or resume a Companion workflow before assigning this to another worker." : routingMode === "needs_contract" ? "Define proof gates and acceptance criteria before worker handoff." : "Define task scope, files, context refs, and proof gates.",
     workersSpawned: 0,
     failClosedFallback: "main_agent",
+    workPackages,
+    supervision,
     workerRecommendations: [worker],
     proofGates: input.proofGates,
     brainUpdateActions: brainCandidates,
@@ -10787,6 +10939,7 @@ function buildLocalEngineeringLeadPlan(input) {
       { label: "Work packages", value: workPackageId ? 1 : 0 },
       { label: "Ready packages", value: routingMode === "explicit_handoff_ready" ? 1 : 0 },
       { label: "Blocked packages", value: posture === "lead_blocked" ? 1 : 0 },
+      { label: "Supervision", value: supervision.status },
       { label: "Context refs", value: input.contextRefs.length },
       { label: "Proof gates", value: input.proofGates.length },
       { label: "Acceptance criteria", value: input.acceptanceCriteria.length },
@@ -10859,12 +11012,144 @@ function normalizeWorkerRecommendation(value, index) {
     ]
   };
 }
+function normalizeWorkPackage(value, index) {
+  const status = cockpitEnumValue(
+    "work_package_status",
+    ENGINEERING_LEAD_WORK_PACKAGE_STATUSES,
+    value.status,
+    "unknown"
+  );
+  const health = cockpitEnumValue(
+    "work_package_health",
+    ENGINEERING_LEAD_STATUSES,
+    value.health,
+    "unknown"
+  );
+  const reasonCodes = [
+    .../* @__PURE__ */ new Set([
+      ...stringList(value.reasonCodes),
+      ...compactReasonCodes([status.droppedReasonCode, health.droppedReasonCode])
+    ])
+  ];
+  return {
+    id: stringValue3(value.id) ?? `work-package:${index + 1}`,
+    title: stringValue3(value.title) ?? `Imported work package ${index + 1}`,
+    status: status.value,
+    health: health.value,
+    owner: stringValue3(value.owner) ?? null,
+    dependencies: stringList(value.dependencies),
+    writeScope: stringList(value.writeScope),
+    acceptanceCriteria: stringList(value.acceptanceCriteria),
+    proofRequired: stringList(value.proofRequired),
+    resultExpectation: stringValue3(value.resultExpectation) ?? "Return proof receipts, residual risks, and candidate Project Brain updates.",
+    nextAction: stringValue3(value.nextAction) ?? "Review imported work package before creating handoffs.",
+    replanTriggers: stringList(value.replanTriggers),
+    evidence: normalizeEvidence(value.evidence),
+    reasonCodes
+  };
+}
+function summarizeSupervisionFromWorkPackages(workPackages) {
+  const blockedWorkPackages = workPackages.filter(
+    (workPackage) => workPackage.status === "blocked"
+  ).length;
+  const readyWorkPackages = workPackages.filter(
+    (workPackage) => workPackage.status === "ready_for_handoff"
+  ).length;
+  const executingWorkPackages = workPackages.filter(
+    (workPackage) => workPackage.status === "executing"
+  ).length;
+  const verifyingWorkPackages = workPackages.filter(
+    (workPackage) => workPackage.status === "verifying"
+  ).length;
+  const closedWorkPackages = workPackages.filter(
+    (workPackage) => workPackage.status === "closed"
+  ).length;
+  const replanTriggers = Array.from(
+    new Set(workPackages.flatMap((workPackage) => workPackage.replanTriggers))
+  );
+  const reviewRequired = workPackages.some((workPackage) => workPackage.health === "watch") || workPackages.some((workPackage) => workPackage.replanTriggers.length > 0);
+  const replanRequired = blockedWorkPackages > 0;
+  const status = workPackages.length === 0 ? "cold_start" : replanRequired ? "needs_replan" : reviewRequired ? "needs_review" : "on_track";
+  return {
+    status,
+    summary: workPackages.length === 0 ? "No imported work packages are available for supervision." : replanRequired ? `${blockedWorkPackages} imported work package(s) require replan.` : reviewRequired ? "Imported work packages need review before delegated execution." : "Imported work packages are on track for advisory supervision.",
+    openWorkPackages: Math.max(0, workPackages.length - closedWorkPackages),
+    blockedWorkPackages,
+    readyWorkPackages,
+    executingWorkPackages,
+    verifyingWorkPackages,
+    closedWorkPackages,
+    reviewRequired,
+    replanRequired,
+    nextCheck: status === "cold_start" ? "Import or create bounded work packages." : status === "needs_replan" ? "Replan blocked imported packages before handoff." : status === "needs_review" ? "Review imported package contracts and receipts." : "Collect proof and outcome receipts after handoff.",
+    replanTriggers,
+    receiptsRequired: [],
+    reasonCodes: [
+      "engineering_lead_contract_v1_supervision",
+      `engineering_lead_supervision_${status}`
+    ]
+  };
+}
+function normalizeSupervision(value, workPackages) {
+  if (!isRecord5(value)) {
+    return summarizeSupervisionFromWorkPackages(workPackages);
+  }
+  const fallback = summarizeSupervisionFromWorkPackages(workPackages);
+  const fallbackStatus = fallback.status === "on_track" ? "needs_review" : fallback.status;
+  const status = cockpitEnumValue(
+    "supervision_status",
+    ENGINEERING_LEAD_SUPERVISION_STATUSES,
+    value.status,
+    fallbackStatus
+  );
+  return {
+    status: status.value,
+    summary: stringValue3(value.summary) ?? fallback.summary,
+    openWorkPackages: Math.max(
+      0,
+      Math.round(numberValue2(value.openWorkPackages, fallback.openWorkPackages))
+    ),
+    blockedWorkPackages: Math.max(
+      0,
+      Math.round(numberValue2(value.blockedWorkPackages, fallback.blockedWorkPackages))
+    ),
+    readyWorkPackages: Math.max(
+      0,
+      Math.round(numberValue2(value.readyWorkPackages, fallback.readyWorkPackages))
+    ),
+    executingWorkPackages: Math.max(
+      0,
+      Math.round(numberValue2(value.executingWorkPackages, fallback.executingWorkPackages))
+    ),
+    verifyingWorkPackages: Math.max(
+      0,
+      Math.round(numberValue2(value.verifyingWorkPackages, fallback.verifyingWorkPackages))
+    ),
+    closedWorkPackages: Math.max(
+      0,
+      Math.round(numberValue2(value.closedWorkPackages, fallback.closedWorkPackages))
+    ),
+    reviewRequired: booleanValue(value.reviewRequired, fallback.reviewRequired),
+    replanRequired: booleanValue(value.replanRequired, fallback.replanRequired),
+    nextCheck: stringValue3(value.nextCheck) ?? fallback.nextCheck,
+    replanTriggers: stringList(value.replanTriggers),
+    receiptsRequired: stringList(value.receiptsRequired),
+    reasonCodes: [
+      .../* @__PURE__ */ new Set([
+        ...stringList(value.reasonCodes),
+        ...compactReasonCodes([status.droppedReasonCode])
+      ])
+    ]
+  };
+}
 function normalizeCockpitPlan(cockpit) {
   const rawPlan = isRecord5(cockpit.engineeringLeadPlan) ? cockpit.engineeringLeadPlan : cockpit;
   const score = Math.round(numberValue2(rawPlan.score, 0));
   const workerRecommendations = recordList2(rawPlan.workerRecommendations).map(
     normalizeWorkerRecommendation
   );
+  const workPackages = recordList2(rawPlan.workPackages).map(normalizeWorkPackage);
+  const supervision = normalizeSupervision(rawPlan.supervision, workPackages);
   const posture = cockpitEnumValue(
     "posture",
     ENGINEERING_LEAD_POSTURES,
@@ -10880,8 +11165,15 @@ function normalizeCockpitPlan(cockpit) {
   const workerDroppedReasonCodes = workerRecommendations.flatMap(
     (worker) => worker.reasonCodes.filter((code2) => code2.startsWith("companion_dropped_unknown_"))
   );
+  const workPackageDroppedReasonCodes = workPackages.flatMap(
+    (workPackage) => workPackage.reasonCodes.filter((code2) => code2.startsWith("companion_dropped_unknown_"))
+  );
+  const supervisionDroppedReasonCodes = supervision.reasonCodes.filter(
+    (code2) => code2.startsWith("companion_dropped_unknown_")
+  );
   return {
     version: PROJECT_INTELLIGENCE_ENGINEERING_LEAD_PLAN_VERSION,
+    contractVersion: PROJECT_INTELLIGENCE_ENGINEERING_LEAD_CONTRACT_VERSION,
     posture: posture.value,
     status: status.value,
     score,
@@ -10890,6 +11182,8 @@ function normalizeCockpitPlan(cockpit) {
     nextAction: stringValue3(rawPlan.nextAction) ?? "Review the imported cockpit plan before creating worker handoffs.",
     workersSpawned: 0,
     failClosedFallback: "main_agent",
+    workPackages,
+    supervision,
     workerRecommendations,
     proofGates: stringList(rawPlan.proofGates),
     brainUpdateActions: stringList(rawPlan.brainUpdateActions),
@@ -10910,11 +11204,117 @@ function normalizeCockpitPlan(cockpit) {
         "companion_imported_project_health_lead_plan",
         ...compactReasonCodes([posture.droppedReasonCode, status.droppedReasonCode]),
         ...stringList(rawPlan.reasonCodes),
-        ...workerDroppedReasonCodes
+        ...workerDroppedReasonCodes,
+        ...workPackageDroppedReasonCodes,
+        ...supervisionDroppedReasonCodes
       ])
     ]
   };
 }
+function scopeSetForPlan(plan) {
+  return /* @__PURE__ */ new Set([
+    ...plan.workPackages.flatMap((workPackage) => workPackage.writeScope),
+    ...plan.workerRecommendations.flatMap((worker) => worker.contract.writeScope)
+  ]);
+}
+function reconcileEngineeringLeadPlan(input) {
+  const changedSignals = /* @__PURE__ */ new Set();
+  const recommendedActions = /* @__PURE__ */ new Set();
+  const reasonCodes = /* @__PURE__ */ new Set(["companion_lead_plan_reconciled"]);
+  const plannedScope = scopeSetForPlan(input.plan);
+  const outOfScopeFiles = input.changedFiles.filter((file) => !plannedScope.has(file));
+  if (input.plan.workPackages.length === 0) {
+    changedSignals.add("no_imported_work_packages");
+    recommendedActions.add("Create or import bounded work packages before delegation.");
+    reasonCodes.add("companion_reconcile_no_work_packages");
+  }
+  if (outOfScopeFiles.length > 0) {
+    changedSignals.add(`out_of_scope_files:${outOfScopeFiles.join(",")}`);
+    recommendedActions.add(
+      "Replan because current changed files are outside the imported write scope."
+    );
+    reasonCodes.add("companion_reconcile_scope_changed");
+  }
+  if (!input.localSignals.workflow.present || input.localSignals.workflow.status !== "active") {
+    changedSignals.add("workflow_not_active");
+    recommendedActions.add("Start or resume a Companion workflow before delegated execution.");
+    reasonCodes.add("companion_reconcile_workflow_not_active");
+  }
+  if (!input.localSignals.teamSync.present) {
+    changedSignals.add("team_sync_missing");
+    recommendedActions.add(
+      "Record Team Sync start-work or handoff before assigning work to another agent."
+    );
+    reasonCodes.add("companion_reconcile_team_sync_missing");
+  }
+  if (input.proofGates.length === 0 && input.plan.proofGates.length === 0) {
+    changedSignals.add("proof_gates_missing");
+    recommendedActions.add("Define proof gates before worker handoff.");
+    reasonCodes.add("companion_reconcile_missing_proof");
+  }
+  if (input.acceptanceCriteria.length === 0) {
+    const importedAcceptance = input.plan.workPackages.some(
+      (workPackage) => workPackage.acceptanceCriteria.length > 0
+    );
+    if (!importedAcceptance) {
+      changedSignals.add("acceptance_criteria_missing");
+      recommendedActions.add("Define acceptance criteria before worker handoff.");
+      reasonCodes.add("companion_reconcile_missing_acceptance");
+    }
+  }
+  if (input.declaredRisks.length > 0) {
+    changedSignals.add("declared_risks_present");
+    recommendedActions.add("Review declared risks before promoting Brain update candidates.");
+    reasonCodes.add("companion_reconcile_declared_risks");
+  }
+  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");
+  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 status = blocked ? "blocked" : replanRequired ? "needs_replan" : reviewRequired ? "needs_review" : "on_track";
+  return {
+    status,
+    summary: status === "blocked" ? "Imported lead plan has blocked work or blocked supervision signals." : status === "needs_replan" ? "Imported lead plan no longer matches current local execution signals." : status === "needs_review" ? "Imported lead plan is usable, but local continuity or risk review is required." : "Imported lead plan matches current local execution signals.",
+    replanRequired,
+    reviewRequired,
+    changedSignals: Array.from(changedSignals),
+    recommendedActions: Array.from(recommendedActions),
+    reasonCodes: Array.from(reasonCodes)
+  };
+}
+function applyReconciliationToPlan(plan, reconciliation) {
+  if (!reconciliation.replanRequired && !reconciliation.reviewRequired) {
+    return {
+      ...plan,
+      reasonCodes: [.../* @__PURE__ */ new Set([...plan.reasonCodes, ...reconciliation.reasonCodes])]
+    };
+  }
+  const supervisionStatus = reconciliation.status === "blocked" ? "blocked" : reconciliation.status === "needs_replan" ? "needs_replan" : "needs_review";
+  return {
+    ...plan,
+    nextAction: reconciliation.recommendedActions[0] ?? plan.nextAction,
+    supervision: {
+      ...plan.supervision,
+      status: supervisionStatus,
+      summary: reconciliation.summary,
+      reviewRequired: reconciliation.reviewRequired,
+      replanRequired: reconciliation.replanRequired,
+      replanTriggers: [
+        .../* @__PURE__ */ new Set([...plan.supervision.replanTriggers, ...reconciliation.recommendedActions])
+      ],
+      reasonCodes: [.../* @__PURE__ */ new Set([...plan.supervision.reasonCodes, ...reconciliation.reasonCodes])]
+    },
+    caveats: [
+      .../* @__PURE__ */ new Set([
+        ...plan.caveats,
+        "This plan was reconciled against current local Companion signals; replan signals are advisory and fail-closed."
+      ])
+    ],
+    reasonCodes: [.../* @__PURE__ */ new Set([...plan.reasonCodes, ...reconciliation.reasonCodes])]
+  };
+}
 function readJsonFile3(filePath) {
   const parsed = JSON.parse(fs16.readFileSync(path15.resolve(filePath), "utf8"));
   if (!isRecord5(parsed)) {
@@ -10932,8 +11332,8 @@ function buildCompanionEngineeringLeadPlanReport(options = {}) {
   const proofGates = unique3(options.proof);
   const acceptanceCriteria = unique3(options.acceptance);
   const declaredRisks = unique3(options.risk);
-  const cockpit = options.cockpit ?? (options.fromCockpit ? readJsonFile3(options.fromCockpit) : void 0);
-  const engineeringLeadPlan = cockpit ? normalizeCockpitPlan(cockpit) : buildLocalEngineeringLeadPlan({
+  const cockpit = options.cockpit ?? (options.fromCockpit || options.fromPlan ? readJsonFile3(options.fromCockpit ?? options.fromPlan ?? "") : void 0);
+  const importedPlan = cockpit ? normalizeCockpitPlan(cockpit) : buildLocalEngineeringLeadPlan({
     target,
     task,
     changedFiles,
@@ -10943,6 +11343,15 @@ function buildCompanionEngineeringLeadPlanReport(options = {}) {
     declaredRisks,
     localSignals
   });
+  const reconciliation = options.reconcile && cockpit ? reconcileEngineeringLeadPlan({
+    plan: importedPlan,
+    changedFiles,
+    proofGates,
+    acceptanceCriteria,
+    declaredRisks,
+    localSignals
+  }) : void 0;
+  const engineeringLeadPlan = reconciliation ? applyReconciliationToPlan(importedPlan, reconciliation) : importedPlan;
   return {
     version: "snipara.companion_engineering_lead_plan.v1",
     generatedAt: (options.now ?? /* @__PURE__ */ new Date()).toISOString(),
@@ -10961,6 +11370,7 @@ function buildCompanionEngineeringLeadPlanReport(options = {}) {
       declaredRisks
     },
     localSignals,
+    ...reconciliation ? { reconciliation } : {},
     suggestedCommands: suggestedCommands2({
       target,
       task,
@@ -10996,6 +11406,37 @@ function formatCompanionEngineeringLeadPlanReport(report) {
   lines.push(`Headline: ${plan.headline}`);
   lines.push(`Next action: ${plan.nextAction}`);
   lines.push("");
+  lines.push("Supervision");
+  lines.push(`Status: ${plan.supervision.status}`);
+  lines.push(`Summary: ${plan.supervision.summary}`);
+  lines.push(`Review required: ${plan.supervision.reviewRequired}`);
+  lines.push(`Replan required: ${plan.supervision.replanRequired}`);
+  lines.push(`Next check: ${plan.supervision.nextCheck}`);
+  lines.push(`Replan triggers: ${formatList2(plan.supervision.replanTriggers)}`);
+  lines.push("");
+  if (report.reconciliation) {
+    lines.push("Reconciliation");
+    lines.push(`Status: ${report.reconciliation.status}`);
+    lines.push(`Summary: ${report.reconciliation.summary}`);
+    lines.push(`Changed signals: ${formatList2(report.reconciliation.changedSignals)}`);
+    lines.push(`Recommended actions: ${formatList2(report.reconciliation.recommendedActions)}`);
+    lines.push("");
+  }
+  lines.push("Work Packages");
+  if (plan.workPackages.length === 0) {
+    lines.push("- none");
+  } else {
+    for (const workPackage of plan.workPackages) {
+      lines.push(`- [${workPackage.health}] ${workPackage.title} (${workPackage.status})`);
+      if (workPackage.owner) {
+        lines.push(`  owner: ${workPackage.owner}`);
+      }
+      lines.push(`  next: ${workPackage.nextAction}`);
+      lines.push(`  scope: ${formatList2(workPackage.writeScope)}`);
+      lines.push(`  proof: ${formatList2(workPackage.proofRequired)}`);
+    }
+  }
+  lines.push("");
   lines.push("Worker Recommendations");
   for (const worker of plan.workerRecommendations) {
     lines.push(`- [${worker.status}] ${worker.label} (${worker.role}, ${worker.routingMode})`);
@@ -23365,7 +23806,7 @@ program.command("agent-readiness").description("Audit whether a repo/task is rea
 program.command("lead-plan").description("Create a fail-closed Companion Engineering Lead Plan").option("--task <task>", "Current task or work package summary").option(
   "--target <target>",
   "Target agent or ADE (codex|claude-code|cursor|orca|windsurf|custom)"
-).option("--changed-files <files...>", "Changed or relevant files").option("--context <refs...>", "Context references, decisions, docs, or source facts").option("--proof <proof...>", "Required proof gates or verification evidence").option("--acceptance <criteria...>", "Acceptance criteria for the delegated work").option("--risk <risks...>", "Known risks or caveats").option("--from-cockpit <file>", "Read a Project Health cockpit JSON export").option("-d, --dir <directory>", "Project directory (default: current)").option("-o, --output <file>", "Write Markdown or JSON report").option("--json", "Print raw JSON").action(async (options) => {
+).option("--changed-files <files...>", "Changed or relevant files").option("--context <refs...>", "Context references, decisions, docs, or source facts").option("--proof <proof...>", "Required proof gates or verification evidence").option("--acceptance <criteria...>", "Acceptance criteria for the delegated work").option("--risk <risks...>", "Known risks or caveats").option("--from-cockpit <file>", "Read a Project Health cockpit JSON export").option("--from-plan <file>", "Read a Companion or Project Health Engineering Lead Plan JSON").option("--reconcile", "Reconcile an imported lead plan against current local Companion signals").option("-d, --dir <directory>", "Project directory (default: current)").option("-o, --output <file>", "Write Markdown or JSON report").option("--json", "Print raw JSON").action(async (options) => {
   await leadPlanCommand({
     task: options.task,
     target: options.target,
@@ -23375,6 +23816,8 @@ program.command("lead-plan").description("Create a fail-closed Companion Enginee
     acceptance: options.acceptance,
     risk: options.risk,
     fromCockpit: options.fromCockpit,
+    fromPlan: options.fromPlan,
+    reconcile: Boolean(options.reconcile),
     dir: options.dir,
     output: options.output,
     json: Boolean(options.json)
@@ -24886,7 +25329,9 @@ if (require.main === module) {
   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,

package/docs/FULL_REFERENCE.md

@@ -309,13 +309,16 @@ snipara-companion lead-plan \
 
 The command reads local workflow state, Team Sync, project instructions, and
 explicit inputs. The output uses the same lead-plan vocabulary as Project
-Health: posture, score, routing mode, bounded worker contract, proof gates,
-candidate Project Brain updates, `workersSpawned: 0`, and `main_agent` fallback.
-
-Use `--from-cockpit <file>` when Project Health has exported a cockpit JSON
-artifact and Companion only needs to normalize it into Markdown or JSON for
-handoff. This is still advisory and fail-closed: the command does not approve
-work, execute proof gates, or spawn workers.
+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.
+
+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
+plan against current local workflow, Team Sync, proof, acceptance, and file
+scope signals. This is still advisory and fail-closed: the command does not
+approve work, execute proof gates, or spawn workers.
 
 ## Verification Plans
 

package/package.json

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