snipara-companion 1.3.6 → 1.3.8

package/README.md

@@ -59,6 +59,19 @@ 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
@@ -459,6 +472,8 @@ snipara-companion upload --path docs/spec.md --file ./docs/spec.md
 snipara-companion upload --path clients/acme/current.md --file ./current.md --asset-class BUSINESS_DOCUMENT --usage-mode current_truth --source-kind local_agent --client-id acme
 snipara-companion upload --path diagrams/network.vsdx --file ./diagrams/network.vsdx --kind BINARY --format vsdx --reindex
 snipara-companion upload --path docs/spec.md --file ./docs/spec.md --reindex
+snipara-companion references scan --allow-domain docs.stripe.com --allow-domain docs.github.com
+snipara-companion references ingest --upload --reindex
 snipara-companion business-collections list
 snipara-companion business-collections ensure --preset business_response_playbook
 snipara-companion business-collections ensure --preset offer_templates
@@ -552,6 +567,29 @@ snipara-companion task-commit --summary "Validated PR Answer Pack release docs"
 Only add a dedicated `snipara-companion github answer-packs` command if Snipara
 ships a public API for manual regeneration or inspection outside the dashboard.
 
+### External References
+
+Use `references` when repository docs point at source material the agent may not
+be able to fetch directly, such as SDK docs, vendor runbooks, RFCs, or client
+pages:
+
+```bash
+snipara-companion references scan \
+  --allow-domain docs.stripe.com \
+  --allow-domain docs.github.com
+
+snipara-companion references ingest --dry-run
+snipara-companion references ingest --upload --reindex
+```
+
+`scan` writes `.snipara/references/manifest.json` with each URL, source file,
+line number, domain, and allowlist status. URLs are only ingested when their
+domain is allowlisted in the manifest or passed with `--allow-domain` at ingest
+time. `ingest` fetches allowed URLs into local Markdown snapshots under
+`.snipara/references/snapshots/`; `--upload` sends those snapshots to Snipara as
+external reference documents with source URL, content hash, fetch time, HTTP
+metadata, and referenced-from provenance.
+
 ### Project Intelligence Briefs
 
 Use `intelligence brief` when a task needs one local entrypoint for continuity,
@@ -661,6 +699,11 @@ 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
@@ -668,6 +711,13 @@ 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
 
 Companion separates two concepts:

package/dist/index.d.ts

@@ -1000,6 +1000,7 @@ interface MemoryGuardFinding {
     code: "recent_failure" | "release_surface" | "manual" | "destructive_intent" | "contradiction";
     message: string;
 }
+type MemoryGuardBlockReason = "confirmation_required" | "guidance_unavailable";
 interface MemoryGuardContradiction {
     source: "memory" | "context";
     reason: string;
@@ -1020,6 +1021,7 @@ interface MemoryGuardCheckOptions {
     status?: string;
     destructive?: boolean;
     requireConfirmation?: boolean;
+    confirmedByUser?: string;
     strict?: boolean;
     json?: boolean;
     limit?: number;
@@ -1027,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[];
@@ -1047,6 +1058,7 @@ interface MemoryGuardCheckResult {
     destructive: boolean;
     contradictions: MemoryGuardContradiction[];
     requiresConfirmation: boolean;
+    confirmation: MemoryGuardConfirmation;
     confirmationPrompt?: string;
     memoryAvailable: boolean;
     contextAvailable: boolean;
@@ -1628,6 +1640,91 @@ declare function buildAgenticTimeline(options?: {
     cwd?: string;
 }): AgenticTimeline;
 
+declare const MANIFEST_VERSION = "snipara.references.v1";
+type ReferenceStatus = "allowed" | "pending" | "denied" | "unsupported";
+interface ReferenceOccurrence {
+    file: string;
+    line: number;
+    label?: string;
+}
+interface ReferenceManifestItem {
+    id: string;
+    url: string;
+    normalizedUrl: string;
+    domain: string;
+    status: ReferenceStatus;
+    reason: string;
+    discoveredAt: string;
+    occurrences: ReferenceOccurrence[];
+    latestSnapshotPath?: string;
+    latestFetchStatus?: number;
+    latestFetchAt?: string;
+    latestContentHash?: string;
+    latestError?: string;
+}
+interface ReferenceManifest {
+    version: typeof MANIFEST_VERSION;
+    generatedAt: string;
+    root: string;
+    allowDomains: string[];
+    denyDomains: string[];
+    items: ReferenceManifestItem[];
+}
+interface ScanReferencesOptions {
+    root?: string;
+    output?: string;
+    allowDomain?: string[];
+    denyDomain?: string[];
+    extensions?: string[];
+    maxFiles?: number;
+    json?: boolean;
+}
+interface IngestReferencesOptions {
+    manifest?: string;
+    outputDir?: string;
+    allowDomain?: string[];
+    ids?: string[];
+    max?: number;
+    timeoutMs?: number;
+    maxBytes?: number;
+    destinationPrefix?: string;
+    upload?: boolean;
+    reindex?: boolean;
+    dryRun?: boolean;
+    json?: boolean;
+}
+interface ScanSummary {
+    manifest: ReferenceManifest;
+    outputPath: string;
+    scannedFiles: number;
+    foundUrls: number;
+    allowed: number;
+    pending: number;
+    denied: number;
+    unsupported: number;
+}
+interface IngestSummary {
+    manifestPath: string;
+    selected: number;
+    fetched: number;
+    uploaded: number;
+    failed: number;
+    dryRun: boolean;
+    snapshots: Array<{
+        id: string;
+        url: string;
+        snapshotPath?: string;
+        destinationPath?: string;
+        status?: number;
+        uploaded?: boolean;
+        error?: string;
+    }>;
+}
+declare function scanReferences(options?: ScanReferencesOptions): ScanSummary;
+declare function ingestReferences(options?: IngestReferencesOptions): Promise<IngestSummary>;
+declare function referencesScanCommand(options: ScanReferencesOptions): Promise<void>;
+declare function referencesIngestCommand(options: IngestReferencesOptions): Promise<void>;
+
 type CacheStrategy = "exact" | "nearby" | "warm";
 interface QueryCacheScope {
     cwd?: string;
@@ -2050,4 +2147,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, 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 };
+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, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, normalizeGuardTag, normalizeWorkflowPlanInput, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveQueryFromToolInput, runMemoryGuardCheck, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };