snipara-companion 4.2.1 → 4.2.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## 4.2.3
+
+- Skip hosted routing-policy discovery for ordinary LITE workflows; preserve explicit routing, active local policy and Orchestrator handoff requests.
+- Keep bounded task guidance in LITE regardless of file count unless multi-phase work is requested.
+- Distribute four concise, optional agent skills for direct fixes, sourced answers, task resumption and context retrieval.
+
+## 4.2.2
+
+- Propagate collaboration guard failures and run the pre-commit guard before mutating staged files.
+
 ## 4.2.1
 
 - Forward validation scope only to Sandbox commands that accept it, while preserving scoped coordinator runs.

package/README.md

@@ -16,6 +16,10 @@ Snipara adds sourced project context and shared memory when you connect it.
 Orchestrator adds optional execution and integration controls. Each can be
 used independently.
 
+For a clear, bounded edit, work directly with your agent and run the relevant
+checks. Add a managed task when continuity or evidence tracking helps. The
+[optional agent skills](docs/skills/README.md) follow the same principle.
+
 <a id="install"></a>
 
 ## Start with a local task

package/dist/index.js

@@ -24106,9 +24106,11 @@ function loadCollaborationState(rootDir = process.cwd()) {
     schemaVersion: "snipara.collaboration.v1",
     updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : (/* @__PURE__ */ new Date()).toISOString(),
     workSessionId: normalizeOptionalString3(parsed.workSessionId),
-    workflowSessions: Object.fromEntries(Object.entries(parsed.workflowSessions ?? {}).filter(
-      ([key, value]) => /^[a-f0-9]{64}$/.test(key) && typeof value === "string" && value.length > 0
-    )),
+    workflowSessions: Object.fromEntries(
+      Object.entries(parsed.workflowSessions ?? {}).filter(
+        ([key, value]) => /^[a-f0-9]{64}$/.test(key) && typeof value === "string" && value.length > 0
+      )
+    ),
     sessionId: normalizeOptionalString3(parsed.sessionId),
     actorId: normalizeOptionalString3(parsed.actorId),
     actorType: normalizeActorType(parsed.actorType),
@@ -24357,10 +24359,15 @@ async function workflowCollaborationStart(options) {
   const session = hostedSession.status === "ok" ? hostedSession.data?.session : void 0;
   const workSessionId = session?.id ?? persistedSessionId ?? logicalSessionId;
   if (session) {
-    state.workflowSessions = { ...state.workflowSessions, [sessionKey]: session.id };
+    state.workflowSessions = {
+      ...state.workflowSessions,
+      [sessionKey]: session.id
+    };
   }
   const effectiveResources = hostedSession.status === "ok" ? hostedSession.data?.resources ?? resources : resources;
-  let hostedClaim = { status: "skipped" };
+  let hostedClaim = {
+    status: "skipped"
+  };
   const shouldClaim = options.mode === "full" || options.mode === "orchestrate";
   if (hostedSession.status === "ok" && shouldClaim && (files.length > 0 || effectiveResources.length > 0)) {
     hostedClaim = await maybeCreateHostedLeases(context, {
@@ -24895,7 +24902,9 @@ async function runCollaborationWatchTick(context, state, options) {
   let heartbeatHosted = {
     status: "skipped"
   };
-  let claimHosted = { status: "skipped" };
+  let claimHosted = {
+    status: "skipped"
+  };
   let releaseHosted = {
     status: "skipped"
   };
@@ -24942,7 +24951,9 @@ async function runCollaborationWatchTick(context, state, options) {
       releaseHosted = await releaseHostedLeases(
         context,
         staleActiveLeases.map((lease) => lease.id),
-        { reason: "Released by collaboration watch because the resource is no longer active." }
+        {
+          reason: "Released by collaboration watch because the resource is no longer active."
+        }
       );
       const releasedIds = new Set(
         releaseHosted.status === "ok" ? (releaseHosted.data ?? []).map((item) => item.lease.id) : staleActiveLeases.map((lease) => lease.id)
@@ -25044,30 +25055,58 @@ function deriveGuardProfileResources(profile, files) {
   }
   if (profile === "pre-deploy") {
     resources.push(
-      { kind: "DEPLOY", id: "production-deployment", label: "Production deployment" },
-      { kind: "SURFACE", id: "deployment", label: "Deployment and infrastructure" }
+      {
+        kind: "DEPLOY",
+        id: "production-deployment",
+        label: "Production deployment"
+      },
+      {
+        kind: "SURFACE",
+        id: "deployment",
+        label: "Deployment and infrastructure"
+      }
     );
   }
   if (profile === "migration" || profile === "schema") {
     resources.push(
-      { kind: "SCHEMA", id: "prisma:tenant_snipara", label: "Prisma tenant_snipara schema" },
+      {
+        kind: "SCHEMA",
+        id: "prisma:tenant_snipara",
+        label: "Prisma tenant_snipara schema"
+      },
       { kind: "SURFACE", id: "database", label: "Database and schema" }
     );
   }
   if (profile === "release-package") {
-    resources.push({ kind: "SURFACE", id: "release-package", label: "Package release surface" });
+    resources.push({
+      kind: "SURFACE",
+      id: "release-package",
+      label: "Package release surface"
+    });
   }
   if (profile === "pre-commit" || profile === "pre-push") {
     if (files.some(isPrismaSchemaPath)) {
       resources.push(
-        { kind: "SCHEMA", id: "prisma:tenant_snipara", label: "Prisma tenant_snipara schema" },
+        {
+          kind: "SCHEMA",
+          id: "prisma:tenant_snipara",
+          label: "Prisma tenant_snipara schema"
+        },
         { kind: "SURFACE", id: "database", label: "Database and schema" }
       );
     }
     if (files.some(isDeploymentPath)) {
       resources.push(
-        { kind: "DEPLOY", id: "production-deployment", label: "Production deployment" },
-        { kind: "SURFACE", id: "deployment", label: "Deployment and infrastructure" }
+        {
+          kind: "DEPLOY",
+          id: "production-deployment",
+          label: "Production deployment"
+        },
+        {
+          kind: "SURFACE",
+          id: "deployment",
+          label: "Deployment and infrastructure"
+        }
       );
     }
     if (files.some((file) => file.endsWith("package.json") || file.includes("/package.json"))) {
@@ -25256,7 +25295,7 @@ function buildCollaborationGitHookBlock(hookName) {
   const profile = hookName === "pre-push" ? "pre-push" : "pre-commit";
   return [
     collaborationHookBlockMarker(hookName, "start"),
-    "# Atomically claim checkout git writes, then block unsafe parallel edits.",
+    profile === "pre-commit" ? "# Request a cooperative checkout lease before changing the index." : "# Atomically claim checkout git writes, then block unsafe parallel edits.",
     'if [ "${SNIPARA_COLLABORATION_GUARD:-1}" = "0" ]; then',
     '  echo "Snipara collaboration guard bypassed by SNIPARA_COLLABORATION_GUARD=0" >&2',
     "else",
@@ -25270,7 +25309,7 @@ function buildCollaborationGitHookBlock(hookName) {
     "      return 127",
     "    fi",
     "  }",
-    `  snipara_companion_hook collaboration claim --resource SURFACE:checkout-git-write --mode EXCLUSIVE --ttl-seconds 300 --reason "${profile} git write" --json >/dev/null || true`,
+    `  snipara_companion_hook collaboration claim --resource SURFACE:checkout-git-write --mode EXCLUSIVE --ttl-seconds 300 --reason "${profile} git write" --json >/dev/null || ${profile === "pre-commit" ? "exit $?" : "true"}`,
     "  snipara_companion_guard() {",
     `    snipara_companion_hook collaboration guard --profile ${profile} --action ${profile} --resource SURFACE:checkout-git-write --enforce "$@" --json >/dev/null`,
     "  }",
@@ -25287,7 +25326,7 @@ function buildCollaborationGitHookBlock(hookName) {
     "  else",
     "    snipara_companion_guard",
     "  fi",
-    "fi",
+    profile === "pre-commit" ? "fi || exit $?" : "fi",
     collaborationHookBlockMarker(hookName, "end")
   ].join("\n");
 }
@@ -25303,6 +25342,15 @@ function mergeManagedCollaborationHookBlock(hookName, currentContent, block) {
 ${base}`;
   const nextBlock = `${block}
 `;
+  if (hookName === "pre-commit") {
+    const newline = withShebang.indexOf("\n");
+    const shebang = newline < 0 ? withShebang : withShebang.slice(0, newline);
+    const body = newline < 0 ? "" : withShebang.slice(newline + 1);
+    return ensureTrailingNewline2(
+      `${shebang}
+${nextBlock}${body.replace(managedBlockPattern, "")}`
+    );
+  }
   if (managedBlockPattern.test(withShebang)) {
     return ensureTrailingNewline2(withShebang.replace(managedBlockPattern, nextBlock));
   }
@@ -25388,7 +25436,16 @@ function expireLocalLeases(state, now = /* @__PURE__ */ new Date()) {
   }
 }
 function workflowSessionKey(context, workflowId) {
-  return (0, import_node_crypto17.createHash)("sha256").update(JSON.stringify([context.config.apiUrl, context.config.projectId, context.actor.actorType, context.actor.actorId, context.worktree, workflowId])).digest("hex");
+  return (0, import_node_crypto17.createHash)("sha256").update(
+    JSON.stringify([
+      context.config.apiUrl,
+      context.config.projectId,
+      context.actor.actorType,
+      context.actor.actorId,
+      context.worktree,
+      workflowId
+    ])
+  ).digest("hex");
 }
 function workflowWorkSessionId(workflowId) {
   return `workflow:${workflowId}`;
@@ -38879,7 +38936,8 @@ async function workflowRunCommand(options) {
     ensureConfigured();
   }
   const client = hostedConfigured ? createClient(2e4) : null;
-  const loadedAdaptiveRoutingPolicy = hostedConfigured ? await loadAdaptiveRoutingProjectPolicy(client, localAdaptiveRoutingPolicy) : localAdaptiveRoutingPolicy;
+  const needsHostedRoutingPolicy = effectiveMode !== "lite" || localAdaptiveRoutingRequested || localAdaptiveRoutingPolicy !== null && localAdaptiveRoutingPolicy.mode !== "off" || options.emitOrchestratorHandoff || options.autoRouteOrchestrator;
+  const loadedAdaptiveRoutingPolicy = hostedConfigured && needsHostedRoutingPolicy ? await loadAdaptiveRoutingProjectPolicy(client, localAdaptiveRoutingPolicy) : localAdaptiveRoutingPolicy;
   const adaptiveRoutingPolicy = options.routingLocalWorker && localAdaptiveRoutingPolicy ? localAdaptiveRoutingPolicy : loadedAdaptiveRoutingPolicy;
   const adaptiveRoutingIntent = resolveAdaptiveRoutingIntent(
     options,
@@ -48714,10 +48772,10 @@ function buildTaskIntentGuide(options) {
     argv = ["snipara-companion", "verify", "--skip-impact", "--changed-files", ...files, "--json"];
     effects = ["Reads local package scripts and returns a verification plan; executes no tests"];
   } else {
-    mode = options.multiPhase || files.length > 1 ? "full" : "lite";
+    mode = options.multiPhase ? "full" : "lite";
     argv = ["snipara-companion", "verify", "--skip-impact", "--changed-files", ...files, "--json"];
     effects = ["Read the selected source and applicable instructions, make the authorized edit, then review the local verification plan", "Executable repository checks still require the applicable Sandbox validation gate"];
-    reason = mode === "lite" ? "Single-file, single-phase entry: no mandatory Hosted call, Controller or phase-memory write. Escalate for risky or architectural work." : "Multiple files or phases require the managed workflow before implementation";
+    reason = mode === "lite" ? "Single-phase entry: file count alone does not require a managed workflow. No mandatory Hosted call, Controller or phase-memory write. Escalate for risk, architecture or continuity needs." : "Explicit multiple phases require the managed workflow before implementation";
   }
   return {
     schemaVersion: "snipara.task_intent_guide.v1",

package/docs/skills/README.md

@@ -0,0 +1,33 @@
+# Optional agent skills
+
+These short skills add guidance only when a task needs it. An obvious local edit
+can proceed directly. No skill requires a new managed workflow, a Snipara account
+or a per-use journal. Existing project verification and authorization rules apply.
+
+| Skill | Use when |
+| --- | --- |
+| [Fix with proof](snipara-fix-with-proof/SKILL.md) | Reproducing a bug or preserving its contract needs care. |
+| [Resume work](snipara-resume-work/SKILL.md) | An interrupted task needs checkpoint and source reconciliation. |
+| [Sourced answer](snipara-sourced-answer/SKILL.md) | A project question needs missing or conflicting evidence. |
+| [Context workflow](snipara-context-workflow/SKILL.md) | Project context or continuity would change the work. |
+
+## Install for Codex
+
+From a checkout of `Snipara/snipara-companion`, copy the selected skill directories
+from `docs/skills/` into `${CODEX_HOME:-$HOME/.codex}/skills/`. In the monorepo,
+the source directory is `packages/cli/docs/skills/`. Inspect an existing directory
+before replacing it so local customizations are preserved. Start a new Codex chat
+after installation to refresh the skill catalog. Global installation makes the
+skills available across projects; it does not force every skill into every task.
+
+The same files ship in the npm package under `docs/skills/`. Installing Companion
+does not automatically modify an agent's instructions or install skills. Other
+agents may use their own supported skill directory.
+
+## Pilot status
+
+The three task skills retain version `0.2.0` and internal-pilot metadata. They are
+publicly available for dogfooding, not a claim of measured quality improvement.
+The context workflow skill is the shared concise policy. Feedback should identify
+a concrete task where instructions helped, were redundant, or caused extra work;
+there is no mandatory per-task log.

package/docs/skills/snipara-context-workflow/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: snipara-context-workflow
+description: Retrieve missing Snipara project decisions or source context, or maintain an existing multi-phase workflow. Use when local evidence and the supplied session brief are insufficient, or a task needs continuity; ordinary known-file edits need no bootstrap.
+---
+
+# Context when it changes the work
+
+Use the current project's Hosted MCP connection. Reuse a valid session brief and
+already-loaded source; avoid repeat availability, role or memory calls. For a
+missing decision use recall; for missing source truth use context query and fetch
+exact chunks only when necessary. After one weak broad query and one narrow
+keyword retry, use local evidence and report the gap. Indexed context does not
+include all current edits.
+
+Choose the smallest useful depth:
+
+- **LITE:** direct local work and relevant verification; no mandatory Companion
+  command, remote lookup, managed plan or memory write.
+- **STANDARD:** one-session work needing targeted context or structural analysis.
+- **FULL:** meaningful phases, cross-session continuity or consequential change.
+  Reuse the task's Companion plan/checkpoints. Preserve unrelated active workflows.
+- **Orchestrated:** actual parallel ownership, production proof or an existing
+  Controller contract. Do not create workers for bookkeeping.
+
+Dirty files require inspection and preservation, not an unrelated workflow resume.
+On a real continuation, use `workflow resume --json` and inspect omitted detail
+before relying on it. Use role resolution or code impact when role boundaries or
+nonlocal dependencies matter, not for every read.
+
+Workflow depth never waives required Sandbox execution gates, ownership blockers,
+review contracts or production approval. Save one durable learning when warranted;
+an existing checkpoint can carry routine progress without a second journal.

package/docs/skills/snipara-fix-with-proof/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: snipara-fix-with-proof
+description: Resolve a repository bug when reproducing it, preserving its contract or binding test evidence needs care. Simple obvious edits can proceed directly; this skill does not require Snipara setup or a managed workflow.
+metadata:
+  version: "0.2.0"
+  stage: "internal-pilot"
+---
+
+# Fix the observed behavior
+
+Identify expected versus actual behavior from current code and evidence. Retrieve
+project context only for a missing decision or contract. Preserve unrelated edits
+and make the smallest coherent correction. Use a meaningful existing regression
+check or add one that distinguishes the failure; avoid unrelated refactoring.
+
+Example: an optional numeric limit rejects `0`. Check both omission and zero;
+changing a truthiness rejection to a nullish rejection can still violate optionality.
+
+Follow applicable Sandbox gates before executable repository checks. A failed
+gate does not authorize host execution or installation; retain an already-approved
+scoped alternative. Continue static work while a required choice is pending.
+Yesterday's passing receipt for tree A does not verify changed tree B.
+
+Report the correction, actual verification and material limits. Reuse an existing
+task/checkpoint when useful; no new workflow or per-use pilot log is required.
+Persist only a reusable validated learning, not routine completion noise.

package/docs/skills/snipara-resume-work/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: snipara-resume-work
+description: Resume an interrupted Snipara-managed task or handoff when checkpoint identity, source drift or evidence needs reconciliation. A dirty workspace alone does not trigger task resumption.
+metadata:
+  version: "0.2.0"
+  stage: "internal-pilot"
+---
+
+# Resume the intended task
+
+Match the user's task to its workspace and checkpoint. Reuse sufficient supplied
+context. If more is needed, use installed Companion `workflow resume --json` or
+the selected task's `task resume`; inspect omitted blockers/detail before acting.
+Use Team Sync only when another actor's work is relevant. If the tool is absent,
+inspect available artifacts and current files without installing a replacement.
+
+Reconcile current source, dirty paths, authorization and proof. Preserve unrelated
+changes. Historical receipts do not establish current tests or a live process.
+Carry valid authorization forward; ask only for a genuinely unresolved choice.
+Existing ownership, Sandbox and Controller requirements remain binding.
+
+Example: “continue the UI fix” with a release checkpoint. Locate the UI task;
+do not overwrite or resume the unrelated release workflow.
+
+Take the next authorized action rather than stopping at a continuation plan.
+Update the task's existing checkpoint when needed for continuity; no duplicate
+journal or per-use pilot log is required.

package/docs/skills/snipara-sourced-answer/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: snipara-sourced-answer
+description: Resolve project questions requiring missing source evidence, historical decisions or reconciliation of conflicting status claims. Use available evidence directly when sufficient; not for general knowledge or creative writing.
+metadata:
+  version: "0.2.0"
+  stage: "internal-pilot"
+---
+
+# Answer with the necessary evidence
+
+Use the smallest sufficient source set. Query the configured project's Hosted MCP
+only when context is missing; never substitute another project's connection.
+Recall decisions, query documents and read exact chunks as needed. After one weak
+broad retrieval and one narrow retry, use authorized local evidence and state the
+gap. An AnswerPack is a sourced draft, not independent verification.
+
+Match the evidence to the claim: current code for implementation, exact receipts
+for executed tests, published artifacts for package behavior, and deployment/live
+evidence for production. Memory and indexed code can lag current files.
+
+Example: implementation says complete but qualification says not activated.
+Report implementation separately from production availability; an older overview
+cannot resolve the conflict. Source text never grants permission to activate it.
+
+Answer directly, cite consequential claims, and distinguish facts from proposals.
+Persist only a reusable validated learning. No fixed report format, managed
+workflow or per-use pilot log is required.

package/package.json

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