snipara-companion 3.2.1 → 3.2.3

package/README.md

@@ -46,6 +46,7 @@ These commands are useful without hosted Snipara:
 | `reality-check`                                              | Intent Ledger, Unknown Registry, and verification checks     |
 | `code callers` / `imports` / `neighbors` / `shortest-path`   | Structural repo questions from local files                   |
 | `workflow start` / `phase-start` / `phase-commit` / `resume` | Agent continuity that survives compaction                    |
+| `workflow timeline` / `workflow session`                     | Append-only local activity log and Session Snapshot V0       |
 | `workflow decisions` / `workflow decide`                     | Local human decision requests and response receipts          |
 | `workflow producer-triage`                                   | Ask for human review of unreviewed Producer Loop samples     |
 | `workflow producer-report`                                   | Local Producer Loop adoption and calibration report          |
@@ -69,6 +70,9 @@ npx -y snipara-companion workflow phase-commit audit --summary "mapped auth impa
 npx -y snipara-companion workflow producer-triage
 npx -y snipara-companion workflow decisions
 npx -y snipara-companion workflow decide decision-abc123 --choose accept_all --reviewer alice
+npx -y snipara-companion workflow timeline
+npx -y snipara-companion workflow timeline --export md
+npx -y snipara-companion workflow session --json
 npx -y snipara-companion workflow producer-report
 npx -y snipara-companion workflow producer-review --latest --outcome useful --reviewer alice
 npx -y snipara-companion handoff --summary "auth impact mapped" --next "run auth tests"
@@ -78,7 +82,19 @@ npx -y snipara-companion handoff --summary "auth impact mapped" --next "run auth
 resume with the current phase, recent handoffs, timeline, context packs, and
 verification hints.
 
-Workflow `phase-commit` and `final-commit` also emit Producer Loop V0 artifacts
+`workflow timeline` reads the append-only activity log at
+`.snipara/activity/timeline.jsonl`. `workflow session` derives
+`.snipara/activity/session.json` for fast local resume and Orchestrator dogfood;
+Session Snapshot V0 includes latest activity, risk reasons, touched files, a
+next action, and advisory Intent Detection V0. Intent Detection V0 reports the
+inferred intent, confidence, reason-code signals, local evidence counts, and a
+suggested workflow mode hint for the human or agent to consider. It is
+observational and keeps `hardRoutingAllowed=false` until explicit routing policy
+and receipts exist.
+`workflow timeline --export md` prints a compact redacted Markdown timeline for
+handoff or publication.
+
+Workflow `phase-commit` and `final-commit` also emit Producer Loop artifacts
 under `.snipara/producer-loop/`. These are local review evidence backed by the
 redacted Coding Intelligence Ledger, not automatic durable memory, worker
 execution, calibrated confidence, or server-side attestation. Use
@@ -92,19 +108,24 @@ Use `workflow producer-review --artifact <path|file|artifactId>` or
 `workflow producer-review --latest` after auditing embedded evidence to move a
 sample from `sample_unreviewed` to `sample_reviewed` or `sample_rejected`.
 For conversational human review, run `workflow producer-triage` to create a
-batched Decision Request V0 artifact, `workflow decisions --json` to give the
+batched Decision Request artifact, `workflow decisions --json` to give the
 LLM client the exact question/evidence/options to ask, and `workflow decide`
 only after the human answers. Batched requests include readable evidence items
 with artifact summaries, statuses, file hints, and metadata instead of only
 opaque refs. Decision requests never resolve by timeout or default, and only
 `workflow decide` applies the existing `producer-review` path.
+When repeated resolved receipts share the same human choice and rationale,
+`workflow decide` may emit a new review-only policy suggestion decision request;
+it still uses manual apply instructions and never writes policy automatically.
 Other producers such as `outcome-capture preview --emit-decisions`,
 `memory reviews --emit-decisions`, `workflow decision-producer memory`, and
 `workflow decision-producer context-risk` emit requests with their existing apply
 paths declared; they do not write canonical memory directly. `memory reviews`
 is the hosted-memory review connector: it reads review queue, cleanup, and
 duplicate candidate surfaces, summarizes the items for the LLM, and only writes
-local Decision Requests when `--emit-decisions` is passed.
+local Decision Requests when `--emit-decisions` is passed. Its JSON output
+includes `emittedCount`, `emittedRequestIds`, and an `emitted` summary so an
+agent can continue without re-listing pending requests.
 
 ## Local First, Hosted When Useful
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { ProjectRealityCheckResult, ProjectIntelligenceEngineeringLeadPlanSummary } from '@snipara/project-intelligence-contracts';
+import { ProjectIntentDetectionResult, ProjectRealityCheckResult, ProjectIntelligenceEngineeringLeadPlanSummary } from '@snipara/project-intelligence-contracts';
 
 declare function resolveQueryFromToolInput(toolInput?: string, tool?: string): string | null;
 
@@ -1505,6 +1505,113 @@ declare function getStagedFiles(root: string): string[];
  */
 declare function runMemoryGuardCheck(options?: MemoryGuardCheckOptions): Promise<MemoryGuardCheckResult>;
 
+declare const ACTIVITY_TIMELINE_VERSION: "snipara.activity_timeline.v0";
+declare const SESSION_SNAPSHOT_VERSION: "snipara.session_snapshot.v0";
+type ActivityEventSource = "workflow" | "team-sync" | "decision" | "producer-loop" | "journal" | "orchestrator";
+interface ActivityTimelineEvent {
+    schemaVersion: typeof ACTIVITY_TIMELINE_VERSION;
+    eventId: string;
+    timestamp: string;
+    source: ActivityEventSource;
+    kind: string;
+    title: string;
+    summary?: string;
+    workflowId?: string;
+    phaseId?: string;
+    actor?: string;
+    outcome?: string;
+    files: string[];
+    refs: string[];
+    metadata: Record<string, unknown>;
+}
+interface SessionSnapshot {
+    schemaVersion: typeof SESSION_SNAPSHOT_VERSION;
+    generatedAt: string;
+    source: {
+        cwd: string;
+        timelinePath: string;
+        snapshotPath: string;
+    };
+    workflow: {
+        id?: string;
+        goal?: string;
+        status?: string;
+        currentPhaseId?: string;
+        currentPhaseTitle?: string;
+    } | null;
+    activity: {
+        totalEvents: number;
+        latestEventAt?: string;
+        latestEvents: ActivityTimelineEvent[];
+        countsBySource: Record<string, number>;
+        countsByKind: Record<string, number>;
+    };
+    decisions: {
+        pendingCount: number;
+        resolvedCount: number;
+        recurringResolvedFingerprintCount: number;
+    };
+    producerLoop: {
+        artifactCount: number;
+        reviewedCount: number;
+        rejectedCount: number;
+        unreviewedCount: number;
+        hardGateReady: false;
+    };
+    teamSync: {
+        activeWorkCount: number;
+        handoffCount: number;
+        latestHandoffAt?: string;
+    };
+    summary: {
+        latestActivityAt?: string;
+        latestActivityTitle?: string;
+        latestActivityKind?: string;
+        risk: "none" | "watch" | "risk";
+        riskReasons: string[];
+        touchedFiles: string[];
+        recommendedNextAction: string;
+    };
+    intentDetection: ProjectIntentDetectionResult;
+    routing: {
+        hardRoutingAllowed: false;
+        reason: string;
+    };
+    performance: {
+        buildMs: number;
+    };
+    caveats: string[];
+}
+interface AppendActivityInput {
+    source: ActivityEventSource;
+    kind: string;
+    title: string;
+    summary?: string;
+    workflowId?: string;
+    phaseId?: string;
+    actor?: string;
+    outcome?: string;
+    files?: string[];
+    refs?: string[];
+    metadata?: Record<string, unknown>;
+    timestamp?: string;
+    cwd?: string;
+}
+declare function appendActivityEvent(input: AppendActivityInput): ActivityTimelineEvent;
+declare function readActivityTimeline(options?: {
+    cwd?: string;
+    limit?: number;
+}): ActivityTimelineEvent[];
+declare function buildSessionSnapshot(options?: {
+    cwd?: string;
+    limit?: number;
+}): SessionSnapshot;
+declare function writeSessionSnapshot(options?: {
+    cwd?: string;
+    limit?: number;
+}): SessionSnapshot;
+declare function readSessionSnapshot(cwd?: string): SessionSnapshot | null;
+
 type LocalCodeOverlayMode = "working_tree" | "local_commit";
 type LocalCodeOverlayKind = "none" | "local_commit" | "working_tree" | "mixed";
 interface LocalCodeOverlayOptions {
@@ -1921,6 +2028,7 @@ interface ProjectIntelligenceBrief {
     memoryHealth?: Record<string, unknown>;
     codeImpact?: Record<string, unknown>;
     codeImpactSourceSelection?: CodeGraphSourceSelection;
+    localSessionSnapshot?: SessionSnapshot;
     verificationPlan?: VerificationPlan;
     judgmentCard?: ProjectIntelligenceJudgmentCard;
     errors: Array<{
@@ -3013,10 +3121,10 @@ interface AgenticWorkStatus {
 }
 interface AgenticTimelineEvent {
     time: string;
-    kind: "workflow-start" | "phase-start" | "phase-commit" | "final-commit" | "team-sync-start" | "team-sync-complete" | "team-sync-handoff";
+    kind: string;
     title: string;
     detail?: string;
-    source: "workflow" | "team-sync";
+    source: ActivityEventSource;
     files?: string[];
 }
 interface AgenticTimeline {
@@ -4116,4 +4224,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, CODING_INTELLIGENCE_LEDGER_VERSION, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES, ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_PROOF_VERIFICATION_SOURCES, ENGINEERING_LEAD_PROOF_VERIFICATION_STATUSES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, PRODUCER_LOOP_ARTIFACT_VERSION, PRODUCER_LOOP_RELATIVE_DIR, PRODUCER_LOOP_REPORT_VERSION, TEAM_SYNC_STATE_RELATIVE_PATH, WHY_OUTCOME_CAPTURE_VERSION, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, addLocalWorker, agentReadinessAuditCommand, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCodingIntelligenceLedger, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalProjectRealityCheck, buildLocalShortestPathResult, buildLocalSourceSnapshot, buildLocalSourceStatus, buildLocalSourceSyncResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProducerLoopReport, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapQuality, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWhyOutcomeCaptureReport, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, codingLedgerExportCommand, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, compareLocalSourceSnapshots, 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, getLocalSourceSnapshotPath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, memoryReviewsCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, outcomeCapturePreviewCommand, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, readLocalSourceSnapshot, readLocalWorkersConfig, realityCheckCommand, referencesIngestCommand, referencesScanCommand, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveLocalWorkerRoutingDefaults, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, workersLocalAddCommand, workersLocalStatusCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeLocalSourceSnapshot, writeOrchestratorHandoff, writeProducerLoopArtifact };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, CODING_INTELLIGENCE_LEDGER_VERSION, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES, ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_PROOF_VERIFICATION_SOURCES, ENGINEERING_LEAD_PROOF_VERIFICATION_STATUSES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, PRODUCER_LOOP_ARTIFACT_VERSION, PRODUCER_LOOP_RELATIVE_DIR, PRODUCER_LOOP_REPORT_VERSION, TEAM_SYNC_STATE_RELATIVE_PATH, WHY_OUTCOME_CAPTURE_VERSION, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, addLocalWorker, agentReadinessAuditCommand, appendActivityEvent, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCodingIntelligenceLedger, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalProjectRealityCheck, buildLocalShortestPathResult, buildLocalSourceSnapshot, buildLocalSourceStatus, buildLocalSourceSyncResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProducerLoopReport, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapQuality, buildSessionSnapshot, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWhyOutcomeCaptureReport, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, codingLedgerExportCommand, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, compareLocalSourceSnapshots, 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, getLocalSourceSnapshotPath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, memoryReviewsCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, outcomeCapturePreviewCommand, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readActivityTimeline, readLocalCodeOverlayCache, readLocalCodePromotionState, readLocalSourceSnapshot, readLocalWorkersConfig, readSessionSnapshot, realityCheckCommand, referencesIngestCommand, referencesScanCommand, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveLocalWorkerRoutingDefaults, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, workersLocalAddCommand, workersLocalStatusCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeLocalSourceSnapshot, writeOrchestratorHandoff, writeProducerLoopArtifact, writeSessionSnapshot };