snipara-companion 3.2.26 → 3.2.28

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.2.28
+
+- Adds bounded Outcome Loop retrieval correlation to generated Codex, Claude,
+  Cursor, VS Code/Continue, and generic HTTP MCP references through
+  `SNIPARA_SESSION_ID` / `X-Snipara-Session-Id`.
+- Prints the active correlation session during `init` and documents the
+  explicit `correlation_context.session_id` fallback for MCP clients that
+  cannot inject environment-backed headers.
+- Keeps the correlation identifier telemetry-only and project-scoped; it does
+  not alter authentication or authorization.
+
+## New In 3.2.27
+
+- Scopes `context-control drift` dirty Git detection to the ProjectContext
+  manifest, declared manifest sources, local Decision Requests, and
+  `.snipara/context-control/` artifacts. Dirty files outside that scope remain
+  visible but no longer force permanent `DRIFT_DETECTED` in shared checkouts.
+- Clarifies the Context as Code V0 boundary: manifests are local declarative
+  metadata and do not refresh hosted context, reconcile manifest-vs-hosted
+  state, or mutate hosted memory. Hosted refresh/apply remains V1 work.
+- Adds executable documentation smoke tests that run the README and full
+  reference `context-control` examples against the built local CLI, closing the
+  loop that previously allowed narrative examples to drift from command reality.
+
 ## New In 3.2.26
 
 - Fixes the published `context-control plan` examples so they use the real CLI

package/README.md

@@ -49,6 +49,18 @@ Use this after `create-snipara` activation. `create-snipara` remains the
 canonical engine for first workspace setup; Companion owns the repeatable local
 continuity loop after that.
 
+## Retrieval And Outcome Correlation
+
+`snipara-companion init` creates and prints a bounded workspace session ID.
+Export it as `SNIPARA_SESSION_ID` before starting Codex, Claude, Cursor, VS Code,
+Continue, or another HTTP MCP client. Generated configs forward it as
+`X-Snipara-Session-Id`, while canonical execution events use the same Companion
+session automatically. Clients without environment-backed headers can pass the
+same value as `correlation_context.session_id` on retrieval tools.
+
+The identifier is opaque, project-scoped telemetry. It does not grant access or
+change authorization, and explicit per-call correlation remains authoritative.
+
 Example output excerpt:
 
 ```text
@@ -99,7 +111,8 @@ These commands are useful without hosted Snipara:
 `context-control` is the local trust layer for Project Intelligence state. It
 borrows Terraform's useful product grammar without copying Terraform: preview a
 bounded context mutation, inspect drift, then apply only the exact reviewed
-plan.
+plan. V0 is intentionally local-only: it creates trust artifacts for review, not
+hosted context mutations.
 
 ```bash
 npx -y snipara-companion context-control plan \
@@ -123,13 +136,15 @@ locally:
       "path": "docs/architecture.md",
       "authority": "canonical",
       "tier": "HOT",
-      "tags": ["architecture"]
+      "required": true,
+      "description": "Architecture context that agents should treat as canonical."
     }
   ],
   "policies": [
     {
       "id": "review-context-changes",
-      "description": "Human review required before changing canonical context",
+      "scope": "memory.canonical",
+      "requirement": "Human review required before changing canonical context.",
       "reviewRequired": true
     }
   ]
@@ -142,7 +157,12 @@ npx -y snipara-companion context-control plan --manifest snipara.project-context
 ```
 
 The manifest is declarative metadata only. Validation and local reconciliation
-do not upload documents, approve memory, or mutate hosted Snipara state.
+do not upload documents, approve memory, refresh hosted context, or mutate
+hosted Snipara state. `context-control drift` scopes dirty Git signals to the
+manifest, manifest sources, local Decision Requests, and `.snipara/context-control/`
+artifacts so unrelated checkout noise does not become permanent drift. A future
+V1 hosted refresh/apply surface should compare manifest state against hosted
+context before allowing real hosted mutations.
 
 ### Local Worker Registry
 

package/dist/index.js

@@ -5641,6 +5641,7 @@ Claude Code should apply this workflow automatically for project-specific work;
 
 - Bound Snipara project: \`${projectSlug}\`
 - Hosted MCP endpoint: \`${buildHostedMcpEndpoint(projectSlug)}\`
+- Keep \`SNIPARA_SESSION_ID\` equal to the active Companion session. Generated MCP configs send it as \`X-Snipara-Session-Id\`; when a client cannot send that header, pass the same value as \`correlation_context.session_id\` on retrieval tools.
 - At the start of substantial work, validate the hosted MCP surface with a tool-oriented call, then use \`snipara_recall\` and a targeted \`snipara_context_query\` before falling back to local search.
 - Do not treat empty MCP resources/templates as an outage. If the tool surface looks incomplete, call \`snipara_help(list_all=true)\` and compare exact tool names.
 - Use \`snipara_context_query\` for docs, business context, architecture notes, runbooks, and source truth. Use \`snipara_get_chunk\` for exact cited sections when references are returned.
@@ -5660,6 +5661,7 @@ function buildSharedWorkflowInstructionBlock(projectSlug, client) {
 This workspace is bound to Snipara project \`${projectSlug}\` for ${formatClientName(client)}. Agents should use Snipara automatically for project-specific context, decisions, and workflow state.
 
 - Hosted MCP endpoint: \`${buildHostedMcpEndpoint(projectSlug)}\`
+- Keep \`SNIPARA_SESSION_ID\` equal to the active Companion session. Generated MCP configs send it as \`X-Snipara-Session-Id\`; when a client cannot send that header, pass the same value as \`correlation_context.session_id\` on retrieval tools.
 - At the start of substantial work, validate the hosted MCP surface with a tool-oriented call, then use \`snipara_recall\` and a targeted \`snipara_context_query\` before falling back to local search.
 - Do not treat empty MCP resources/templates as an outage. If the tool surface looks incomplete, call \`snipara_help(list_all=true)\` and compare exact tool names.
 - Use \`snipara_context_query\` for docs, business context, architecture notes, runbooks, and source truth. Use \`snipara_get_chunk\` for exact cited sections when references are returned.
@@ -5911,6 +5913,7 @@ function generateCodexConfigString(projectSlug) {
 type = "streamable_http"
 url = "https://api.snipara.com/mcp/${projectSlug}"
 bearer_token_env_var = "SNIPARA_API_KEY"
+env_http_headers = { "X-Snipara-Session-Id" = "SNIPARA_SESSION_ID" }
 `;
 }
 function generateGenericMcpReferenceString(client, projectSlug) {
@@ -5920,7 +5923,8 @@ function generateGenericMcpReferenceString(client, projectSlug) {
         name: "snipara",
         url: `https://api.snipara.com/mcp/${projectSlug}`,
         headers: {
-          "X-API-Key": "${SNIPARA_API_KEY}"
+          "X-API-Key": "${SNIPARA_API_KEY}",
+          "X-Snipara-Session-Id": "${SNIPARA_SESSION_ID}"
         }
       },
       null,
@@ -5935,7 +5939,8 @@ function generateGenericMcpReferenceString(client, projectSlug) {
           type: "http",
           url: `https://api.snipara.com/mcp/${projectSlug}`,
           headers: {
-            "X-API-Key": "${SNIPARA_API_KEY}"
+            "X-API-Key": "${SNIPARA_API_KEY}",
+            "X-Snipara-Session-Id": "${SNIPARA_SESSION_ID}"
           }
         }
       }
@@ -5995,6 +6000,7 @@ async function callSniparaTool(name: string, args: Record<string, unknown>): Pro
     headers: {
       "Content-Type": "application/json",
       "X-API-Key": SNIPARA_API_KEY,
+      "X-Snipara-Session-Id": process.env.SNIPARA_SESSION_ID || "",
     },
     body: JSON.stringify({
       jsonrpc: "2.0",
@@ -6561,12 +6567,13 @@ async function initCommand(options) {
     existingProjectId: existingConfig.projectId,
     selectedProject
   });
+  const sessionId = `sess_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
   saveConfig(
     {
       apiKey,
       apiUrl: existingConfig.apiUrl,
       projectId: projectIdentifier,
-      sessionId: `sess_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      sessionId,
       client: selectedClient
     },
     { cwd: projectDir, scope: "workspace" }
@@ -6688,6 +6695,10 @@ async function initCommand(options) {
   console.log(`Companion config: ${configPaths.companion}`);
   console.log(`Selected project: ${formatProjectChoice(selectedProject)}`);
   console.log(`Selected client:  ${formatClientName(selectedClient)}`);
+  console.log(`Correlation session: ${sessionId}`);
+  console.log(
+    "Export SNIPARA_SESSION_ID with this value before starting the MCP client so served context and execution outcomes share one bounded session."
+  );
   if (options.withHooks) {
     console.log("\nNext steps:");
     if (hookClient === "cursor") {
@@ -33089,6 +33100,35 @@ function parseDirtyFile2(line) {
   const renameParts = withoutStatus.split(" -> ");
   return renameParts[renameParts.length - 1]?.replace(/^"|"$/g, "");
 }
+function resolveGitDriftScopePaths(cwd) {
+  const scopePaths = [
+    PROJECT_CONTEXT_MANIFEST_DEFAULT_PATH,
+    CONTEXT_CONTROL_RELATIVE_DIR,
+    path30.join(".snipara", "decisions")
+  ];
+  const manifestPath = resolveManifestPath(cwd);
+  if (!fs30.existsSync(manifestPath)) {
+    return normalizeScopePaths(scopePaths, cwd);
+  }
+  const manifestRead = readJsonFileSafe(manifestPath);
+  if (!manifestRead.value) {
+    return normalizeScopePaths(scopePaths, cwd);
+  }
+  const validation = validateProjectContextManifest({ manifest: manifestRead.value });
+  const manifestSourcePaths = validation.manifest?.sources.map((source2) => source2.path) ?? [];
+  return normalizeScopePaths([...scopePaths, ...manifestSourcePaths], cwd);
+}
+function normalizeScopePaths(scopePaths, cwd) {
+  return uniqueStrings20(
+    scopePaths.map((scopePath) => normalizeProjectRelativePath(scopePath, cwd).replace(/\/+$/g, ""))
+  );
+}
+function isPathInsideScope(filePath, scopePaths) {
+  const normalized = filePath.replace(/\\/g, "/").replace(/\/+$/g, "");
+  return scopePaths.some(
+    (scopePath) => normalized === scopePath || normalized.startsWith(`${scopePath}/`)
+  );
+}
 function slugify2(value) {
   const slug2 = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 64);
   return slug2 || "context-control-state";
@@ -33380,25 +33420,39 @@ function readJsonFileSafe(filePath) {
 }
 function collectGitDriftSignals(cwd) {
   const revision = resolveGitBaseRevision(cwd);
+  const scopePaths = resolveGitDriftScopePaths(cwd);
+  const relevantDirtyFiles = revision.dirtyFiles.filter(
+    (file) => isPathInsideScope(file, scopePaths)
+  );
   const upstream = runGit3(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], cwd);
   const upstreamCounts = upstream ? runGit3(["rev-list", "--left-right", "--count", `${upstream}...HEAD`], cwd) : void 0;
   const [behind = 0, ahead = 0] = upstreamCounts ? upstreamCounts.split(/\s+/g).map((part) => Number.parseInt(part, 10) || 0) : [];
-  const dirtySignal = revision.dirty ? {
-    id: "git-working-tree-dirty",
+  const dirtySignal = revision.dirty ? relevantDirtyFiles.length > 0 ? {
+    id: "git-working-tree-dirty-relevant",
     surface: "git",
     state: "DRIFT_DETECTED",
-    summary: "Working tree has local uncommitted changes.",
-    expected: "Clean working tree for release-grade context-control reconciliation.",
-    observed: revision.dirtyFiles.join(", "),
-    refs: revision.dirtyFiles,
+    summary: "Working tree has uncommitted changes in context-control or ProjectContext scope.",
+    expected: "Manifest, manifest sources, Decision Requests, and context-control artifacts are clean.",
+    observed: relevantDirtyFiles.join(", "),
+    refs: relevantDirtyFiles,
     severity: "watch",
-    reasonCodes: ["git_working_tree_dirty"]
+    reasonCodes: ["git_working_tree_dirty_relevant"]
+  } : {
+    id: "git-working-tree-dirty-out-of-scope",
+    surface: "git",
+    state: "IN_SYNC",
+    summary: "Working tree has uncommitted changes, but none are in context-control or ProjectContext scope.",
+    expected: `Only scoped dirty paths affect context-control drift: ${scopePaths.join(", ")}.`,
+    observed: `${revision.dirtyFiles.length} out-of-scope dirty file(s)`,
+    refs: revision.dirtyFiles,
+    severity: "info",
+    reasonCodes: ["git_working_tree_dirty_out_of_scope"]
   } : {
     id: "git-working-tree-clean",
     surface: "git",
     state: "IN_SYNC",
-    summary: "Working tree is clean.",
-    refs: [],
+    summary: "Working tree has no uncommitted changes.",
+    refs: scopePaths,
     severity: "info",
     reasonCodes: ["git_working_tree_clean"]
   };
@@ -33645,6 +33699,8 @@ function buildLocalProjectDriftReport(options = {}) {
     ],
     caveats: [
       "Project Drift V0 is a read-only local report.",
+      "Git dirty-file drift is scoped to the ProjectContext manifest, manifest sources, Decision Requests, and .snipara/context-control artifacts; use git status for full working-tree release readiness.",
+      "Project Drift V0 validates manifest health locally but does not refresh hosted context state; hosted manifest-vs-context reconciliation is V1 work.",
       "UNKNOWN is never treated as IN_SYNC; verify missing or unreadable evidence before applying changes."
     ]
   });

package/docs/FULL_REFERENCE.md

@@ -339,13 +339,18 @@ snipara-companion workflow resume --include-session-context
   Git bases by default, writes only under `.snipara/context-control/`, and emits
   an apply receipt linked to the plan hash.
 - `context-control drift` is a read-only Project Drift V0 report. It checks Git
-  working tree/upstream state, managed workflow state, pending Decision
-  Requests, saved plans and receipts, and ProjectContext manifest health.
-  `UNKNOWN` is never treated as `IN_SYNC`.
+  upstream state, scoped Git dirty files, managed workflow state, pending
+  Decision Requests, saved plans and receipts, and ProjectContext manifest
+  health. Dirty Git files only become drift when they touch the ProjectContext
+  manifest, manifest sources, local Decision Requests, or
+  `.snipara/context-control/`; unrelated checkout noise remains visible without
+  classifying the project as `DRIFT_DETECTED`. `UNKNOWN` is never treated as
+  `IN_SYNC`.
 - `context-control validate --manifest snipara.project-context.json` validates
   Context as Code V0. The manifest is JSON metadata declaring context sources,
-  tiers, authority, tags, owners, freshness, and review policies. It does not
-  upload content or mutate hosted Snipara state.
+  tiers, authority, freshness, and review policies. It does not upload content,
+  refresh hosted context, reconcile manifest-vs-hosted state, or mutate hosted
+  Snipara state; hosted refresh/apply belongs to the future V1 surface.
 - `lead-plan` turns local workflow state, Team Sync, file scope, context refs,
   proof gates, and acceptance criteria into an advisory Engineering Lead Plan.
   It emits worker recommendations and handoff contracts, keeps
@@ -816,6 +821,15 @@ Mistral generates MCP-first files (`MISTRAL.md`, Vibe config, Le Chat connector
 reference, and LangChain `ChatMistralAI.bindTools` snippets); Mistral request
 hooks are model request hooks, not local agent lifecycle hooks.
 
+All generated HTTP/SSE references include a bounded correlation header sourced
+from `SNIPARA_SESSION_ID`. Set it to the session printed by `init` before
+starting Codex, Claude, Cursor, VS Code/Continue, GLM, or another generic MCP
+host. The hosted server uses the header only for project-scoped retrieval
+telemetry and ignores invalid values. If the host cannot inject environment
+headers, pass the same value as `correlation_context.session_id` on
+`snipara_context_query`, `snipara_recall`, `snipara_search`, `snipara_ask`, and
+`snipara_get_chunk`.
+
 OpenClaw hooks remain separate:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "3.2.26",
+  "version": "3.2.28",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {