snipara-companion 3.2.13 → 3.2.15

package/README.md

@@ -22,6 +22,27 @@ npx -y snipara-companion impact src/auth/session.ts --source local
 npx -y snipara-companion source init .
 ```
 
+## Companion Continuity Contract V1
+
+Editor integrations and post-activation workflows can ask Companion for one
+machine-readable "continue this workspace" payload:
+
+```bash
+npx -y snipara-companion@latest continue-workspace --include-session-context --json
+```
+
+The payload version is `snipara.companion.continuity.v1`. It is designed for
+native editor commands, status bars, panels, and agent handoffs that need to
+resume real work without rescanning or reimplementing Snipara semantics. It
+includes project binding, session bootstrap entries and quality warnings,
+workflow phase state, Team Sync handoff summary, passive source snapshot status,
+session snapshot summary, stable local artifact paths, and recommended next
+actions.
+
+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.
+
 Example output excerpt:
 
 ```text
@@ -56,6 +77,7 @@ These commands are useful without hosted Snipara:
 | `workflow start` / `phase-start` / `phase-commit` / `resume` | Agent continuity that survives compaction                    |
 | `workflow timeline` / `workflow session`                     | Append-only local activity log and Session Snapshot V0       |
 | `workflow decisions` / `workflow decide`                     | Local human decision requests and response receipts          |
+| `run --emit-policy-decisions`                                | Project Policy review requests in the agent workflow         |
 | `workflow producer-triage`                                   | Ask for human review of unreviewed Producer Loop samples     |
 | `workflow producer-report`                                   | Local Producer Loop adoption and calibration report          |
 | `workflow producer-review`                                   | Mark local Producer Loop samples reviewed or rejected        |

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { ProjectIntentDetectionResult, ProjectPolicyDecision, ProjectRealityCheckResult, ProjectIntelligenceEngineeringLeadPlanSummary, ProjectPolicyRule, OutcomeIntelligenceCalibration, ControlledWorkerExecutionMode, ControlledWorkerExecutionReceipt } from '@snipara/project-intelligence-contracts';
+import { ProjectIntentDetectionResult, ProjectPolicyDecision, ProjectRealityCheckResult, ProjectIntelligenceEngineeringLeadPlanSummary, ProjectPolicyRule, DecisionRequest, OutcomeIntelligenceCalibration, ControlledWorkerExecutionMode, ControlledWorkerExecutionReceipt } from '@snipara/project-intelligence-contracts';
 
 declare function resolveQueryFromToolInput(toolInput?: string, tool?: string): string | null;
 
@@ -2073,6 +2073,14 @@ interface RealityCheckCommandOptions {
 declare function buildLocalProjectRealityCheck(options: RealityCheckCommandOptions): ProjectRealityCheckResult;
 declare function realityCheckCommand(options: RealityCheckCommandOptions): Promise<void>;
 
+interface DecisionRequestWriteResult {
+    status: "written" | "duplicate_pending" | "duplicate_resolved";
+    requestId: string;
+    fingerprint: string;
+    path?: string;
+    relativePath?: string;
+}
+
 interface MemoryHealthCommandOptions {
     scope?: MemoryScope;
     includeInactive?: boolean;
@@ -2463,6 +2471,7 @@ interface ProjectRunCommandOptions {
     servedJudgmentId?: string;
     skipAdvisorReceipts?: boolean;
     outcomeReceiptFiles?: string[];
+    emitPolicyDecisions?: boolean;
     json?: boolean;
 }
 interface ProjectRunGuardResult {
@@ -2509,11 +2518,20 @@ interface ProjectIntelligenceRunResult {
     guard?: ProjectRunGuardResult;
     packageReview?: ProjectRunPackageReview;
     policyGates: ProjectPolicyGatesResult;
+    policyDecisionRequests?: ProjectRunPolicyDecisionRequests;
     advisorReceiptCapture?: ProjectRunAdvisorReceiptCapture;
     outcomeCalibration?: OutcomeIntelligenceCalibration;
     judgmentCard: ProjectIntelligenceJudgmentCard;
     suggestedCommands: string[];
 }
+interface ProjectRunPolicyDecisionRequests {
+    version: "project-intelligence.policy-decision-requests.v1";
+    emitted: boolean;
+    requestCount: number;
+    requests: DecisionRequest[];
+    writes: DecisionRequestWriteResult[];
+    caveats: string[];
+}
 declare function buildProjectIntelligenceRun(options: ProjectRunCommandOptions): Promise<ProjectIntelligenceRunResult>;
 declare function projectIntelligenceRunCommand(options: ProjectRunCommandOptions): Promise<void>;
 

package/dist/index.js

@@ -16928,6 +16928,7 @@ var MIN_WORKFLOW_SURFACE_TOKENS = 200;
 var STALE_BOOTSTRAP_MEMORY_DAYS = 90;
 var TASK_COMMIT_TIMEOUT_MS = 3e4;
 var FINAL_COMMIT_TIMEOUT_MS = 9e4;
+var COMPANION_CONTINUITY_CONTRACT_VERSION = "snipara.companion.continuity.v1";
 var FINAL_COMMIT_RETRY_TIMEOUT_MS = 45e3;
 var FINAL_COMMIT_SUMMARY_MAX_CHARS = 1200;
 var FINAL_COMMIT_RETRY_SUMMARY_MAX_CHARS = 600;
@@ -24482,6 +24483,191 @@ async function sessionBootstrapCommand(options) {
     printSessionBootstrapQuality(buildPrintedBootstrapQuality(printedBootstrap));
   }
 }
+function emptySessionMemoriesResult() {
+  return {
+    critical: { memories: [], count: 0, tokens: 0 },
+    daily: { memories: [], count: 0, tokens: 0 },
+    total_tokens: 0
+  };
+}
+function readLocalJsonFile(relativePath2) {
+  const absolutePath = path20.join(process.cwd(), relativePath2);
+  if (!fs21.existsSync(absolutePath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs21.readFileSync(absolutePath, "utf-8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function summarizeSourceSnapshot(snapshot) {
+  if (!snapshot) {
+    return {
+      status: "missing",
+      snapshotPath: path20.join(".snipara", "source", "latest.json"),
+      nextAction: "Run snipara-companion source sync --json after meaningful local code or docs movement."
+    };
+  }
+  const summary = snapshot.summary && typeof snapshot.summary === "object" && !Array.isArray(snapshot.summary) ? snapshot.summary : {};
+  return {
+    status: "present",
+    snapshotPath: path20.join(".snipara", "source", "latest.json"),
+    generatedAt: snapshot.generatedAt,
+    revision: snapshot.revision,
+    totalFiles: summary.totalFiles,
+    totalBytes: summary.totalBytes,
+    skipped: summary.skipped
+  };
+}
+function summarizeWorkflowStateForContinuity(workflow2) {
+  if (!workflow2) {
+    return {
+      status: "missing",
+      statePath: WORKFLOW_STATE_RELATIVE_PATH,
+      nextAction: "Run snipara-companion workflow start for multi-phase work."
+    };
+  }
+  return {
+    status: workflow2.status,
+    workflowId: workflow2.workflowId,
+    goal: workflow2.goal,
+    currentPhaseId: workflow2.currentPhaseId,
+    statePath: WORKFLOW_STATE_RELATIVE_PATH,
+    phases: workflow2.phases.map((phase) => ({
+      id: phase.id,
+      title: phase.title,
+      status: phase.status
+    }))
+  };
+}
+function summarizeTeamSyncForContinuity() {
+  const state = loadTeamSyncState();
+  const summary = buildTeamSyncSummary(state);
+  const latestHandoff = state.handoffs.at(-1);
+  return {
+    statePath: path20.relative(process.cwd(), getTeamSyncStatePath()),
+    activeWorkCount: summary.activeWorkCount,
+    staleWorkCount: summary.staleWorkCount,
+    completedWorkCount: summary.completedWorkCount,
+    archivedWorkCount: summary.archivedWorkCount,
+    handoffCount: summary.handoffCount,
+    latestHandoff: latestHandoff ? {
+      summary: latestHandoff.summary,
+      next: latestHandoff.next,
+      attention: latestHandoff.attention,
+      createdAt: latestHandoff.createdAt
+    } : null
+  };
+}
+function buildCompanionContinuityPayload(args) {
+  const config = args.configured ? loadConfig() : null;
+  const workflow2 = readWorkflowState2();
+  const sessionSnapshot = readSessionSnapshot();
+  const sourceSnapshot = readLocalJsonFile(path20.join(".snipara", "source", "latest.json"));
+  return {
+    version: COMPANION_CONTINUITY_CONTRACT_VERSION,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    configured: args.configured,
+    project: config ? {
+      projectId: config.projectId,
+      apiUrl: config.apiUrl,
+      sessionId: config.sessionId
+    } : null,
+    artifacts: {
+      workflowStatePath: WORKFLOW_STATE_RELATIVE_PATH,
+      teamSyncStatePath: path20.relative(process.cwd(), getTeamSyncStatePath()),
+      sessionSnapshotPath: path20.join(".snipara", "activity", "session.json"),
+      sourceSnapshotPath: path20.join(".snipara", "source", "latest.json")
+    },
+    bootstrap: args.bootstrap,
+    bootstrapQuality: args.bootstrapQuality,
+    localWarmSnapshot: {
+      storedEntries: args.warmSnapshotStoredEntries
+    },
+    sessionContext: {
+      included: args.includeSessionContext,
+      maxTokens: args.maxContextTokens
+    },
+    workflow: summarizeWorkflowStateForContinuity(workflow2),
+    teamSync: summarizeTeamSyncForContinuity(),
+    source: summarizeSourceSnapshot(sourceSnapshot),
+    sessionSnapshot: sessionSnapshot ? {
+      latestActivityAt: sessionSnapshot.summary.latestActivityAt,
+      latestTitle: sessionSnapshot.summary.latestActivityTitle,
+      latestKind: sessionSnapshot.summary.latestActivityKind,
+      risk: sessionSnapshot.summary.risk,
+      riskReasons: sessionSnapshot.summary.riskReasons,
+      touchedFiles: sessionSnapshot.summary.touchedFiles,
+      nextAction: sessionSnapshot.summary.recommendedNextAction
+    } : null,
+    nextActions: [
+      {
+        id: "open_bootstrap_brief",
+        label: "Open bootstrap brief",
+        command: "snipara-companion session-bootstrap --include-session-context --max-context-tokens 1000",
+        when: "bootstrap has entries or session context is included"
+      },
+      {
+        id: "refresh_source_snapshot",
+        label: "Refresh source snapshot",
+        command: "snipara-companion source sync --json",
+        when: "source.status is missing or local code/docs changed"
+      },
+      {
+        id: "run_impact_gate",
+        label: "Run code impact before risky edits",
+        command: 'snipara-companion code impact --changed-files <files> --diff-summary "next edit"',
+        when: "the next edit is multi-file, risky, or user-visible"
+      },
+      {
+        id: "commit_task_context",
+        label: "Commit durable task context",
+        command: 'snipara-companion task-commit --summary "<done>" --files <files>',
+        when: "a durable phase or task is complete"
+      }
+    ]
+  };
+}
+async function continueWorkspaceCommand(options) {
+  const configured = isConfigured();
+  const resolvedContextTokens = options.maxContextTokens !== void 0 ? options.maxContextTokens : options.includeSessionContext ? DEFAULT_SESSION_CONTEXT_TOKENS : 0;
+  let bootstrap = emptySessionMemoriesResult();
+  let warmSnapshotStoredEntries = 0;
+  if (configured) {
+    const client = createClient(15e3);
+    bootstrap = await client.getSessionMemories(options.maxCriticalTokens, resolvedContextTokens);
+    const config = loadConfig();
+    const warmSnapshot = createLocalQueryCache({
+      cwd: process.cwd(),
+      projectId: config.projectId,
+      sessionId: config.sessionId
+    }).storeWarmSnapshot(bootstrap);
+    warmSnapshotStoredEntries = warmSnapshot.storedEntries;
+  }
+  const bootstrapQuality = buildSessionBootstrapQuality(bootstrap, {
+    expectedMaxTokens: (options.maxCriticalTokens ?? DEFAULT_FULL_WORKFLOW_CRITICAL_TOKENS) + resolvedContextTokens
+  });
+  const payload = buildCompanionContinuityPayload({
+    configured,
+    bootstrap,
+    bootstrapQuality,
+    includeSessionContext: resolvedContextTokens > 0,
+    maxContextTokens: resolvedContextTokens,
+    warmSnapshotStoredEntries
+  });
+  if (options.json) {
+    printJson2(payload);
+    return;
+  }
+  console.log(import_chalk6.default.bold("Snipara Companion Continuity"));
+  console.log(`Version: ${COMPANION_CONTINUITY_CONTRACT_VERSION}`);
+  console.log(`Configured: ${configured ? "yes" : "no"}`);
+  console.log(`Workflow: ${payload.workflow.status ?? "unknown"}`);
+  console.log(`Source: ${payload.source.status ?? "unknown"}`);
+  console.log("Next: snipara-companion continue-workspace --json for editor integrations");
+}
 async function recallCommand(options) {
   ensureConfigured();
   const client = createClient(15e3);
@@ -30389,6 +30575,9 @@ var ADVISOR_RECEIPT_WRITE_LIMIT = 6;
 function normalizeStringList6(values) {
   return [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
 }
+function uniqueStrings18(values) {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
 function isRecord17(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -30646,6 +30835,73 @@ function verificationExecutedFromEvidence(evidence) {
     (item) => item.command ? `${item.label}: ${item.command} (${item.status})` : `${item.label}: ${item.status}`
   );
 }
+function buildPolicyDecisionRequest(args) {
+  const decision = args.run.policyGates.projectPolicyDecision;
+  if (!decision || decision.verdict === "allow") return void 0;
+  const changedFiles = args.run.brief.changedFiles.slice(0, 24);
+  const matchedRules = decision.matchedRules.slice(0, 8);
+  const options = decision.verdict === "block" ? ["respect_block", "request_exception", "mark_policy_stale"] : ["approve_once", "require_changes", "mark_policy_stale", "keep_advisory"];
+  const recommendation = decision.verdict === "block" ? "respect_block" : "approve_once";
+  return buildDecisionRequest({
+    producer: {
+      kind: "project_policy_review",
+      command: "run --emit-policy-decisions",
+      sourceRef: decision.receipt.receiptId
+    },
+    decision: `project_policy_${decision.verdict}`,
+    question: decision.verdict === "block" ? "Project Policy blocked this action. Should the agent stop, request an exception, or mark the policy stale?" : "Project Policy requires human review. May the agent proceed once, change plan, or mark the policy stale?",
+    evidence: {
+      summary: `Project Policy verdict ${decision.verdict} for task '${args.run.brief.task ?? "unspecified"}'. Receipt ${decision.receipt.receiptId}.`,
+      refs: uniqueStrings18([decision.receipt.receiptId, ...decision.receipt.ruleRefs]),
+      items: matchedRules.map((rule) => ({
+        ref: rule.source.ref,
+        title: rule.title,
+        summary: rule.requirement,
+        kind: rule.source.kind,
+        status: rule.strength,
+        metadata: {
+          ruleId: rule.id,
+          scope: rule.scope,
+          confidence: rule.confidence,
+          reviewStatus: rule.source.reviewStatus ?? null
+        }
+      })),
+      reasonCodes: uniqueStrings18(["project_policy_review", ...decision.reasonCodes]),
+      files: changedFiles,
+      applyPath: "manual_context_review",
+      applyCommand: "Resolve with `snipara-companion workflow decide <request-id> --choose <option> --reviewer <name>`; if policy is stale, update or invalidate the cited decision/policy before rerunning `snipara-companion run`."
+    },
+    options,
+    recommendation,
+    rationale: "Project Policy decisions stay agent-first: the agent asks for explicit human governance and records a response receipt; no dashboard or silent policy mutation is required.",
+    blocking: true,
+    fingerprintParts: [
+      "project_policy_review_v1",
+      decision.receipt.receiptId,
+      decision.verdict,
+      decision.receipt.ruleRefs,
+      changedFiles
+    ]
+  });
+}
+function emitPolicyDecisionRequests(run) {
+  const requests = [buildPolicyDecisionRequest({ run })].filter(
+    (request) => Boolean(request)
+  );
+  const writes = requests.map((request) => writeDecisionRequest(request));
+  return {
+    version: "project-intelligence.policy-decision-requests.v1",
+    emitted: true,
+    requestCount: requests.length,
+    requests,
+    writes,
+    caveats: [
+      "Policy decision requests never apply policy changes automatically.",
+      "Resolve them with workflow decide so the human choice is recorded as a local response receipt.",
+      "Marking a policy stale is a governance signal; the cited memory or policy still needs explicit update or invalidation."
+    ]
+  };
+}
 async function recordFirstPartyAdvisorReceipts(args) {
   const allRecommendations = args.judgmentCard.advisorRecommendations;
   if (args.options.skipAdvisorReceipts) {
@@ -30937,7 +31193,7 @@ async function buildProjectIntelligenceRun(options) {
       ...!options.skipPackageReview && packageReview?.status !== "ok" ? [packageReviewCommand3()] : []
     ] : []
   ];
-  return {
+  const result = {
     version: "project-intelligence.production-run.v1",
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     release: Boolean(options.release),
@@ -30950,6 +31206,10 @@ async function buildProjectIntelligenceRun(options) {
     judgmentCard,
     suggestedCommands: [...new Set(suggestedCommands3)]
   };
+  if (options.emitPolicyDecisions) {
+    result.policyDecisionRequests = emitPolicyDecisionRequests(result);
+  }
+  return result;
 }
 async function projectIntelligenceRunCommand(options) {
   const result = await buildProjectIntelligenceRun(options);
@@ -33118,6 +33378,9 @@ program.command("lead-plan").description("Create a fail-closed Companion Enginee
 program.command("run").description("Run the production Project Intelligence judgment flow for a task or release").option("--task <task>", "Current task or change summary").option("--branch <branch>", "Branch to scope continuity signals").option("--changed-files <changedFiles...>", "Changed files to analyze").option("--recent-files <recentFiles...>", "Recently touched files for continuity lookup").option("--diff-summary <diffSummary>", "Natural-language summary for code impact").option("--max-tokens <number>", "Resume context token budget", "4000").option("--release", "Run release-oriented guard and package surface review").option("--skip-impact", "Do not run companion code impact").option("--skip-memory-health", "Do not call snipara_memory_health").option("--skip-guard", "Skip collaboration guard during release runs").option("--skip-package-review", "Skip npm package surface review").option("--served-judgment-id <id>", "Served judgment id to use for first-party advisor receipts").option("--skip-advisor-receipts", "Skip first-party advisor influence receipt capture").option(
   "--outcome-receipts <files...>",
   "Outcome Intelligence V0 receipt JSON files for local calibration"
+).option(
+  "--emit-policy-decisions",
+  "Write local Decision Requests for Project Policy review/block findings"
 ).option("--json", "Print raw JSON").action(async (options) => {
   await projectIntelligenceRunCommand({
     task: options.task,
@@ -33134,6 +33397,7 @@ program.command("run").description("Run the production Project Intelligence judg
     servedJudgmentId: options.servedJudgmentId,
     skipAdvisorReceipts: Boolean(options.skipAdvisorReceipts),
     outcomeReceiptFiles: options.outcomeReceipts,
+    emitPolicyDecisions: Boolean(options.emitPolicyDecisions),
     json: Boolean(options.json)
   });
 });
@@ -34867,6 +35131,19 @@ program.command("session-bootstrap").description(
     json: options.json
   });
 });
+program.command("continue-workspace").description("Print the stable Companion Continuity Contract for editor integrations").option("--max-critical-tokens <number>", "Durable memory token budget").option(
+  "--include-session-context",
+  "Include short-lived session carryover in addition to durable memory"
+).option("--max-context-tokens <number>", "Short-lived session context token budget").option("--json", "Print raw JSON").action(async (options) => {
+  const maxCriticalTokens = options.maxCriticalTokens !== void 0 ? parseInt(options.maxCriticalTokens, 10) : void 0;
+  const maxContextTokens = options.maxContextTokens !== void 0 ? parseInt(options.maxContextTokens, 10) : void 0;
+  await continueWorkspaceCommand({
+    maxCriticalTokens,
+    maxContextTokens,
+    includeSessionContext: Boolean(options.includeSessionContext || options.maxContextTokens),
+    json: options.json
+  });
+});
 program.command("task-commit").description("Persist durable outcomes after meaningful task work, not every git commit").requiredOption("-s, --summary <summary>", "Task summary").option("-c, --category <category>", "Category").option("-o, --outcome <outcome>", "Outcome", "completed").option("-f, --files <files...>", "Files touched").option("--json", "Print raw JSON").action(async (options) => {
   await taskCommitCommand({
     summary: options.summary,

package/docs/FULL_REFERENCE.md

@@ -21,6 +21,35 @@ snipara-companion code impact --changed-files src/app.ts --diff-summary "next ed
 snipara-companion task-commit --summary "completed durable change" --files src/app.ts
 ```
 
+## Companion Continuity Contract V1
+
+For editor integrations and "continue this workspace" flows, use the stable JSON
+contract instead of rebuilding Companion internals:
+
+```bash
+snipara-companion continue-workspace --include-session-context --json
+```
+
+The response version is `snipara.companion.continuity.v1`. It includes:
+
+- `project`: configured project id, API URL, and session id when available.
+- `bootstrap` and `bootstrapQuality`: pushed session memories plus token,
+  freshness, and warning metadata.
+- `workflow`: active workflow id, goal, current phase, phase statuses, and local
+  state path.
+- `teamSync`: active/stale/completed counts and latest handoff summary.
+- `source`: passive `.snipara/source/latest.json` status; no source sync is
+  performed by this command.
+- `sessionSnapshot`: latest local activity summary, risks, touched files, and
+  recommended next action.
+- `artifacts` and `nextActions`: stable local paths and commands an editor can
+  surface to the user.
+
+This contract starts after `create-snipara` has activated the workspace. Editor
+extensions should orchestrate these commands and render the payload, not fork
+local source scanning, First Work Brief, memory candidate, or Hosted MCP config
+logic.
+
 In this repository, the source currently lives in `packages/cli`, and the installed executable is `snipara-companion`.
 
 This package complements `snipara-mcp`. It does not replace it.
@@ -259,6 +288,13 @@ snipara-companion workflow resume --include-session-context
   path declared. Repeated resolved receipts with the same human choice and
   rationale can emit a review-only policy suggestion decision request; the
   suggestion still has a manual apply path and is never auto-applied.
+- `run --emit-policy-decisions` keeps Project Policy administration agent-first:
+  when reviewed project policy evidence produces a `require_review` or `block`
+  verdict, Companion writes a local `project_policy_review` Decision Request.
+  The human resolves it with `workflow decide`; choices such as approving once,
+  requiring changes, respecting a block, requesting an exception, or marking
+  policy stale are recorded as receipts. No policy is edited or invalidated
+  automatically.
 - `memory reviews --scope project --emit-decisions` reads hosted memory review
   queue, clean-candidate, and duplicate-candidate surfaces, summarizes each item,
   and writes local Decision Request artifacts without mutating hosted memory.

package/package.json

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