snipara-companion 4.2.2 → 4.2.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.

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

@@ -38936,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,
@@ -48771,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.2",
+  "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": {