snipara-companion 2.0.10 → 2.1.0

package/README.md

@@ -44,7 +44,7 @@ These commands are useful without hosted Snipara:
 | `code callers` / `imports` / `neighbors` / `shortest-path`   | Structural repo questions from local files                   |
 | `workflow start` / `phase-start` / `phase-commit` / `resume` | Agent continuity that survives compaction                    |
 | `context-pack`                                               | Reversible local packs for long logs, diffs, and tool output |
-| `judgment-card`, `verify`, `agent-readiness`, `references`   | Local review artifacts, readiness audits, and references     |
+| `judgment-card`, `verify`, `lead-plan`, `agent-readiness`    | Local review artifacts and delegation contracts              |
 | `stuck-guard`, `memory-guard`, `pre-tool`, `post-tool`       | Fail-soft local guards and hook helpers                      |
 
 ## Agent Continuity
@@ -54,6 +54,7 @@ After the first impact check, keep the work resumable:
 ```bash
 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 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

@@ -2151,6 +2151,109 @@ declare function buildAgentReadinessAuditReport(options?: BuildAgentReadinessAud
 declare function formatAgentReadinessAuditReport(report: AgentReadinessAuditReport): string;
 declare function agentReadinessAuditCommand(options: AgentReadinessAuditCommandOptions): Promise<void>;
 
+type EngineeringLeadPosture = "lead_ready" | "lead_watch" | "lead_blocked" | "lead_cold_start";
+type EngineeringLeadStatus = "healthy" | "watch" | "risk" | "unknown";
+type EngineeringLeadWorkerRole = "main_agent" | "coding_worker" | "test_worker" | "reviewer" | "documentation_worker" | "human_approver";
+type EngineeringLeadRoutingMode = "hold" | "main_agent_execute" | "explicit_handoff_ready" | "needs_contract";
+interface EngineeringLeadEvidenceRef {
+    id: string;
+    kind: "memory" | "project_decision" | "shadow_signal" | "context_graph" | "outcome_signal" | "retrieval_event" | "workflow" | "repository" | "manual";
+    label: string;
+    sourceRef?: string | null;
+    strength?: number | null;
+    reviewStatus?: string | null;
+    authorityStatus?: string | null;
+    freshness?: string | null;
+}
+interface EngineeringLeadWorkerContract {
+    writeScope: string[];
+    contextRefs: EngineeringLeadEvidenceRef[];
+    acceptanceCriteria: string[];
+    proofRequired: string[];
+    approvalRequired: boolean;
+    fallback: "main_agent";
+}
+interface EngineeringLeadWorkerRecommendation {
+    id: string;
+    role: EngineeringLeadWorkerRole;
+    label: string;
+    status: EngineeringLeadStatus;
+    routingMode: EngineeringLeadRoutingMode;
+    workPackageId: string | null;
+    workPackageTitle: string | null;
+    owner: string | null;
+    rationale: string;
+    contract: EngineeringLeadWorkerContract;
+    proofGates: string[];
+    brainUpdateCandidates: string[];
+    evidence: EngineeringLeadEvidenceRef[];
+    reasonCodes: string[];
+}
+interface EngineeringLeadPlanSummary {
+    version: "project-intelligence-engineering-lead-plan-v0";
+    posture: EngineeringLeadPosture;
+    status: EngineeringLeadStatus;
+    score: number;
+    headline: string;
+    operatingMode: "advisory_fail_closed";
+    nextAction: string;
+    workersSpawned: 0;
+    failClosedFallback: "main_agent";
+    workerRecommendations: EngineeringLeadWorkerRecommendation[];
+    proofGates: string[];
+    brainUpdateActions: string[];
+    metrics: Array<{
+        label: string;
+        value: string | number;
+    }>;
+    evidence: EngineeringLeadEvidenceRef[];
+    caveats: string[];
+    reasonCodes: string[];
+}
+interface CompanionEngineeringLeadPlanReport {
+    version: "snipara.companion_engineering_lead_plan.v1";
+    generatedAt: string;
+    source: "local_companion_inputs" | "project_health_cockpit";
+    target: {
+        id: AgentReadinessTarget;
+        label: string;
+    };
+    task?: string;
+    engineeringLeadPlan: EngineeringLeadPlanSummary;
+    explicitInputs: {
+        changedFiles: string[];
+        contextRefs: string[];
+        proofGates: string[];
+        acceptanceCriteria: string[];
+        declaredRisks: string[];
+    };
+    localSignals: AgentReadinessLocalSignals;
+    suggestedCommands: string[];
+    caveats: string[];
+}
+interface LeadPlanCommandOptions {
+    task?: string;
+    target?: string;
+    changedFiles?: string[];
+    context?: string[];
+    proof?: string[];
+    acceptance?: string[];
+    risk?: string[];
+    fromCockpit?: string;
+    dir?: string;
+    output?: string;
+    json?: boolean;
+}
+interface BuildCompanionEngineeringLeadPlanOptions extends LeadPlanCommandOptions {
+    cwd?: string;
+    now?: Date;
+    localSignals?: AgentReadinessLocalSignals;
+    cockpit?: Record<string, unknown>;
+}
+declare function buildCompanionEngineeringLeadPlanReport(options?: BuildCompanionEngineeringLeadPlanOptions): CompanionEngineeringLeadPlanReport;
+declare function formatCompanionEngineeringLeadPlanReport(report: CompanionEngineeringLeadPlanReport): string;
+declare function leadPlanCommand(options: LeadPlanCommandOptions): Promise<void>;
+
 type ProjectPolicyGateSeverity = "advisory" | "required_action" | "block";
 type ProjectPolicyGateSurface = "release" | "schema" | "auth" | "billing" | "deploy" | "package_surface";
 type ProjectPolicyGateSampleMode = "not_applicable" | "structural" | "explicit_contract" | "sample_gated";
@@ -3454,4 +3557,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, 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, 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, formatOrchestratorRecommendationReason, formatPolicyGateDecision, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, 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, 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 };