snipara-companion 1.3.5 → 1.3.7

package/README.md

@@ -59,6 +59,30 @@ yarn global add snipara-companion
 snipara-companion
 ```
 
+## New In 1.3.7
+
+- Hardens `memory-guard check` with `--confirmed-by-user "<confirmation>"`
+  for explicit, auditable overrides after the user has reviewed destructive or
+  contradictory signals.
+- Adds stable guard exit codes in strict mode: `20` for confirmation required,
+  `21` for unavailable memory/context guidance, and `22` for invalid guard
+  options.
+- Validates destructive checks before hosted calls so vague commands such as
+  `--destructive` without `--intent` or `--command` fail fast.
+- Extends `snipara-companion init --with-hooks` so it also installs local code
+  overlay Git hooks (`post-commit` sync and `pre-push` promotion/reindex).
+
+## New In 1.3.6
+
+- Adds `snipara-companion memory audit` for a read-only memory hygiene pass that
+  combines hosted memory health, cleanup candidates, and compaction dry-run.
+- Adds `memory health`, `memory clean-candidates`, and `memory compact` as
+  direct companion maintenance commands. `memory compact` always sends
+  `dry_run=true` and does not mutate memory.
+- Extends `memory-guard check` with `--intent`, `--destructive`, and
+  `--require-confirmation` so agents can surface memory/context contradictions
+  and ask the user before irreversible actions.
+
 ## New In 1.3.0
 
 - Adds top-level Git-style agent work commands: `status`, `brief`, `timeline`,
@@ -462,6 +486,10 @@ snipara-companion sync-documents --file ./snipara-business-context.json --dry-ru
 snipara-companion reindex --kind doc --mode incremental
 snipara-companion reindex --job-id index_job_123
 snipara-companion business-health --json
+snipara-companion memory audit --scope project --include-inactive
+snipara-companion memory health --scope project --json
+snipara-companion memory clean-candidates --scope project --limit-per-bucket 10
+snipara-companion memory compact --scope project --json
 snipara-companion chunk get --chunk-id chunk_123
 snipara-companion multi-query --queries "auth flow" "rate limiting"
 snipara-companion orchestrate --query "understand the auth architecture"
@@ -607,21 +635,27 @@ Semantics:
 - `snipara-companion sync-documents` = bulk `snipara_sync_documents` for text and supported binary parser documents from a JSON payload or directory
 - `snipara-companion sync-documents --dry-run` = validate the local payload and business-context freshness metadata without uploading
 - `snipara-companion business-health` = hosted `snipara_index_health`, with the `business_context` section surfaced for stale/reupload signals
+- `snipara-companion memory audit` = read-only memory hygiene pass that combines `snipara_memory_health`, `snipara_memory_clean_candidates`, and `snipara_memory_compact(dry_run=true)`
+- `snipara-companion memory health` = direct hosted `snipara_memory_health` diagnostics for active counts, stale/noise/anomaly samples, and auto-compaction threshold status
+- `snipara-companion memory clean-candidates` = direct hosted `snipara_memory_clean_candidates` review packet for noise, stale memories, duplicates, category anomalies, and human review queues
+- `snipara-companion memory compact` = hosted compaction preview only; it always calls `snipara_memory_compact` with `dry_run=true` and never mutates memory
 - `snipara-companion reindex` = trigger or poll hosted `snipara_reindex`; use after uploads when immediate chunk availability matters
 - `snipara-companion code *` = direct access to the code graph tools without routing through `snipara_context_query`
 - `snipara-companion recall` = direct durable memory lookup for decisions, learnings, preferences, and carryover
 - `snipara-companion session-bootstrap` = durable memory first, optional weak session carryover second
 - `snipara-companion task-commit` = durable task/phase/workflow outcomes only, not a mechanical mirror of every Git commit
 - `snipara-companion memory-guard check` = forced memory/context recall before retries, commits, or finalization when a command failed or a publishable package surface is touched
+- `snipara-companion memory-guard check --intent "<action>" --destructive --strict` = contradiction check before irreversible actions; blocks until the user explicitly confirms when memory/context disagrees or the action is destructive
 - `snipara-companion memory-guard remember --guard-tag pre-commit --text "..."` = create a project/team memory in a guard category such as `pre-commit`, `commit`, `failure`, `pre-final`, or `workflow-policy`
 - `--max-daily-tokens` is still accepted as a compatibility alias for `--max-context-tokens`
 
-### Memory Guard Before Commit
+### Memory Guard Before Commit Or Destructive Actions
 
 Memory Guard is deterministic, not a user preference. It detects two global signals:
 
 - failed or timed-out tool results emitted by Companion hooks
 - changed files under publishable npm or PyPI package manifests
+- explicit destructive or irreversible intent passed with `--intent` and `--destructive`
 
 When triggered, it recalls project guard memories by category and also queries source context before
 the agent retries, commits, or finalizes. Guard memories are just durable memories with a category tag:
@@ -636,7 +670,28 @@ Run the check manually with:
 
 ```bash
 snipara-companion memory-guard check --trigger pre-commit --staged --strict
-```
+snipara-companion memory-guard check \
+  --intent "npm publish snipara-companion" \
+  --destructive \
+  --strict
+snipara-companion memory-guard check \
+  --intent "npm publish snipara-companion" \
+  --destructive \
+  --strict \
+  --confirmed-by-user "User confirmed npm publish after reviewing guard output"
+```
+
+When memory or source context contradicts the requested action, the JSON output
+sets `requiresConfirmation=true`, includes `contradictions`, and provides a
+`confirmationPrompt`. In `--strict` mode the command exits non-zero until the
+operator has explicitly confirmed the override.
+
+Strict mode exit codes:
+
+- `20`: confirmation is required before continuing.
+- `21`: memory/context guidance was unavailable for a triggered guard.
+- `22`: guard options were invalid, for example `--destructive` without a
+  specific `--intent` or `--command`.
 
 ### Commit Memory Policy
 

package/dist/index.d.ts

@@ -997,17 +997,31 @@ interface ReleaseSurface {
     manifestPath: string;
 }
 interface MemoryGuardFinding {
-    code: "recent_failure" | "release_surface" | "manual";
+    code: "recent_failure" | "release_surface" | "manual" | "destructive_intent" | "contradiction";
     message: string;
 }
+type MemoryGuardBlockReason = "confirmation_required" | "guidance_unavailable";
+interface MemoryGuardContradiction {
+    source: "memory" | "context";
+    reason: string;
+    excerpt: string;
+    memoryId?: string;
+    category?: string;
+    title?: string;
+    file?: string;
+}
 interface MemoryGuardCheckOptions {
     trigger?: MemoryGuardTrigger;
     files?: string[];
     staged?: boolean;
     command?: string;
+    intent?: string;
     result?: string;
     exitCode?: number;
     status?: string;
+    destructive?: boolean;
+    requireConfirmation?: boolean;
+    confirmedByUser?: string;
     strict?: boolean;
     json?: boolean;
     limit?: number;
@@ -1015,9 +1029,18 @@ interface MemoryGuardCheckOptions {
     includeContext?: boolean;
     recentFailures?: boolean;
 }
+interface MemoryGuardConfirmation {
+    required: boolean;
+    confirmed: boolean;
+    note?: string;
+    overridesDestructive: boolean;
+    overridesContradictions: boolean;
+}
 interface MemoryGuardCheckResult {
     triggered: boolean;
     shouldBlock: boolean;
+    blockReason?: MemoryGuardBlockReason;
+    exitCode: number;
     trigger: MemoryGuardTrigger;
     findings: MemoryGuardFinding[];
     files: string[];
@@ -1031,6 +1054,12 @@ interface MemoryGuardCheckResult {
     }>;
     query: string;
     categories: string[];
+    intent?: string;
+    destructive: boolean;
+    contradictions: MemoryGuardContradiction[];
+    requiresConfirmation: boolean;
+    confirmation: MemoryGuardConfirmation;
+    confirmationPrompt?: string;
     memoryAvailable: boolean;
     contextAvailable: boolean;
     memories: RecalledMemory[];
@@ -1078,6 +1107,45 @@ interface ProjectIntelligenceBrief {
 declare function buildProjectIntelligenceBrief(options: ProjectIntelligenceBriefOptions): Promise<ProjectIntelligenceBrief>;
 declare function projectIntelligenceBriefCommand(options: ProjectIntelligenceBriefOptions): Promise<void>;
 
+interface MemoryHealthCommandOptions {
+    scope?: MemoryScope;
+    includeInactive?: boolean;
+    sampleLimit?: number;
+    json?: boolean;
+}
+interface MemoryCleanCandidatesCommandOptions {
+    scope?: MemoryScope;
+    includeInactive?: boolean;
+    limitPerBucket?: number;
+    json?: boolean;
+}
+interface MemoryCompactCommandOptions {
+    scope?: MemoryScope;
+    deduplicate?: boolean;
+    promoteThreshold?: number;
+    archiveOlderThanDays?: number;
+    json?: boolean;
+}
+interface MemoryAuditCommandOptions extends MemoryHealthCommandOptions, MemoryCleanCandidatesCommandOptions, MemoryCompactCommandOptions {
+}
+interface MemoryAuditResult {
+    version: "snipara.memory_audit.v1";
+    generatedAt: string;
+    scope?: MemoryScope;
+    health?: Record<string, unknown>;
+    cleanCandidates?: Record<string, unknown>;
+    compactDryRun?: Record<string, unknown>;
+    errors: Array<{
+        surface: string;
+        message: string;
+    }>;
+}
+declare function memoryHealthCommand(options: MemoryHealthCommandOptions): Promise<void>;
+declare function memoryCleanCandidatesCommand(options: MemoryCleanCandidatesCommandOptions): Promise<void>;
+declare function memoryCompactCommand(options: MemoryCompactCommandOptions): Promise<void>;
+declare function buildMemoryAudit(options: MemoryAuditCommandOptions): Promise<MemoryAuditResult>;
+declare function memoryAuditCommand(options: MemoryAuditCommandOptions): Promise<void>;
+
 interface VerifyCommandOptions {
     task?: string;
     qualifiedName?: string;
@@ -1994,4 +2062,4 @@ interface WrittenOrchestratorHandoff {
 declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions): OrchestratorHandoffArtifact;
 declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyTeamSyncState, createLocalQueryCache, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, normalizeGuardTag, normalizeWorkflowPlanInput, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, resolveQueryFromToolInput, runMemoryGuardCheck, saveConfig, saveTeamSyncState, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyTeamSyncState, createLocalQueryCache, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, normalizeGuardTag, normalizeWorkflowPlanInput, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, resolveQueryFromToolInput, runMemoryGuardCheck, saveConfig, saveTeamSyncState, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };