snipara-companion 2.0.9 → 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`, `references`                      | Local review artifacts and source-backed 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

@@ -2045,6 +2045,215 @@ declare function memoryLocalCommand(options: LocalMemoryCommandOptions): Promise
 declare function evalExportCommand(options: EvalExportOptions): Promise<void>;
 declare function evalRunCommand(options: EvalRunOptions): Promise<void>;
 
+type AgentReadinessTarget = "codex" | "claude-code" | "cursor" | "orca" | "windsurf" | "custom";
+type AgentReadinessCheckStatus = "pass" | "warning" | "fail" | "manual";
+type AgentReadinessGapSeverity = "low" | "medium" | "high" | "blocker";
+type AgentReadinessScoreBand = "ready" | "mostly_ready" | "needs_hardening" | "blocked";
+type AgentReadinessServiceTier = "launch_review" | "enablement_pack" | "hardening_sprint";
+interface AgentReadinessAuditCommandOptions {
+    target?: string;
+    task?: string;
+    changedFiles?: string[];
+    context?: string[];
+    proof?: string[];
+    acceptance?: string[];
+    risk?: string[];
+    dir?: string;
+    output?: string;
+    json?: boolean;
+}
+interface AgentReadinessWorkflowState {
+    present: boolean;
+    path: string;
+    status?: string;
+    workflowId?: string;
+    currentPhaseId?: string;
+    completedPhases: number;
+    pendingPhases: number;
+}
+interface AgentReadinessTeamSyncState {
+    present: boolean;
+    path: string;
+    activeWorkCount: number;
+    handoffCount: number;
+    latestActiveSummary?: string;
+    latestHandoffSummary?: string;
+}
+interface AgentReadinessProjectInstructions {
+    present: boolean;
+    path: string;
+}
+interface AgentReadinessLocalSignals {
+    workflow: AgentReadinessWorkflowState;
+    teamSync: AgentReadinessTeamSyncState;
+    projectInstructions: AgentReadinessProjectInstructions;
+}
+interface AgentReadinessCheck {
+    id: string;
+    title: string;
+    status: AgentReadinessCheckStatus;
+    severity: AgentReadinessGapSeverity;
+    score: number;
+    maxScore: number;
+    evidence: string[];
+    action: string;
+}
+interface AgentReadinessGap {
+    checkId: string;
+    severity: AgentReadinessGapSeverity;
+    message: string;
+    action: string;
+}
+interface AgentReadinessRecommendedServicePack {
+    id: AgentReadinessServiceTier;
+    name: string;
+    duration: string;
+    fit: string;
+    deliverables: string[];
+    exitCriteria: string[];
+}
+interface AgentReadinessAuditReport {
+    version: "snipara.agent_readiness_audit.v1";
+    generatedAt: string;
+    target: {
+        id: AgentReadinessTarget;
+        label: string;
+        posture: string;
+    };
+    task?: string;
+    score: {
+        total: number;
+        band: AgentReadinessScoreBand;
+        max: 100;
+        summary: string;
+    };
+    checks: AgentReadinessCheck[];
+    gaps: AgentReadinessGap[];
+    explicitInputs: {
+        changedFiles: string[];
+        contextRefs: string[];
+        proofGates: string[];
+        acceptanceCriteria: string[];
+        declaredRisks: string[];
+    };
+    localSignals: AgentReadinessLocalSignals;
+    recommendedServicePack: AgentReadinessRecommendedServicePack;
+    suggestedCommands: string[];
+    caveats: string[];
+}
+interface BuildAgentReadinessAuditOptions extends AgentReadinessAuditCommandOptions {
+    cwd?: string;
+    now?: Date;
+    localSignals?: AgentReadinessLocalSignals;
+}
+declare function collectAgentReadinessLocalSignals(rootDir?: string): AgentReadinessLocalSignals;
+declare function buildAgentReadinessAuditReport(options?: BuildAgentReadinessAuditOptions): AgentReadinessAuditReport;
+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";
@@ -2835,6 +3044,12 @@ interface TeamSyncCommandOptions {
     next?: string;
     attention?: string;
     risk?: string;
+    adapterPack?: boolean;
+    adapterTarget?: string;
+    context?: string[];
+    proof?: string[];
+    acceptance?: string[];
+    conflictPosture?: string;
     since?: string;
     dir?: string;
     includeSessionContext?: boolean;
@@ -2861,6 +3076,39 @@ interface TeamSyncSweepResult {
     archivedWork: TeamSyncWorkRecord[];
     summary: TeamSyncSummary;
 }
+type AgenticHandoffAdapterTarget = "codex" | "claude-code" | "cursor" | "orca" | "windsurf" | "custom";
+type AgenticHandoffConflictPosture = "continue" | "wait" | "split_work" | "review_only" | "handoff";
+interface AgenticHandoffAdapterPack {
+    version: "snipara.ade_adapter_pack.v1";
+    target: {
+        id: AgenticHandoffAdapterTarget;
+        label: string;
+        instruction: string;
+    };
+    contextPack: {
+        summary: string;
+        files: string[];
+        contextRefs: string[];
+        workflow?: {
+            goal?: string;
+            status?: string;
+            currentPhaseId?: string;
+            currentPhaseTitle?: string;
+        };
+        resumeCommands: string[];
+        constraints: string[];
+    };
+    conflictPosture: AgenticHandoffConflictPosture;
+    proofGates: string[];
+    acceptanceCriteria: string[];
+    receiptExpectation: {
+        required: boolean;
+        command: string;
+        requiredFields: string[];
+    };
+    prompt: string;
+    caveats: string[];
+}
 interface TeamSyncCompletionEvidenceOptions {
     summary?: string;
     workflowGoal?: string;
@@ -2888,6 +3136,7 @@ interface AgenticHandoffArtifact {
         whereToResume: string[];
     };
     suggestedCommands: string[];
+    adapter?: AgenticHandoffAdapterPack;
 }
 declare function buildTeamSyncStartWorkRecord(input: TeamSyncRecordInput): TeamSyncWorkRecord;
 declare function buildTeamSyncHandoffRecord(input: TeamSyncRecordInput): TeamSyncHandoffRecord;
@@ -3308,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, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, 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, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, evaluateProjectPolicyGates, extractCommandFromToolInput, extractFilesFromToolInput, 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 };