snipara-companion 3.2.25 → 3.2.27

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## 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
+  contract: `--summary` plus `--output`, without the nonexistent `--operation`
+  or `--content` flags or an out-of-scope target.
+- Adds a package-doc regression test that executes the documented command shape
+  and rejects the unsupported flags if they return to the README or full
+  reference.
+
 ## New In 3.2.25
 
 - Adds `snipara-companion context-control plan` and `apply` for local,

package/README.md

@@ -99,13 +99,11 @@ 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 \
-  --operation write_file \
-  --target demo.json \
-  --content '{"ok":true}' \
   --summary "record reviewed context state" \
   --output .snipara/context-control/plans/demo.json
 
@@ -126,13 +124,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
     }
   ]
@@ -145,7 +145,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

@@ -33089,6 +33089,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 +33409,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 +33688,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

@@ -232,7 +232,7 @@ snipara-companion workflow sync-policy-ledger
 snipara-companion workflow producer-report
 snipara-companion workflow producer-review --latest --outcome useful --reviewer alice
 snipara-companion workflow run --adaptive-routing-dry-run --route-local-workers "document a scoped change"
-snipara-companion context-control plan --operation write_file --target demo.json --content '{"ok":true}' --summary "record reviewed context state"
+snipara-companion context-control plan --summary "record reviewed context state" --output .snipara/context-control/plans/demo.json
 snipara-companion context-control apply --plan .snipara/context-control/plans/demo.json
 snipara-companion context-control drift
 snipara-companion context-control validate --manifest snipara.project-context.json
@@ -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

package/package.json

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