snipara-companion 1.4.13 → 1.4.14

package/README.md

@@ -12,6 +12,25 @@ In this repository, the source currently lives in `packages/cli`, and the instal
 
 This package complements `snipara-mcp`. It does not replace it.
 
+## Quickstart
+
+```bash
+# 1. Install
+npm install -g snipara-companion
+
+# 2. Point this workspace at a Snipara project (writes local .snipara/ config)
+snipara-companion init            # interactive; or: snipara-companion login
+
+# 3. Use it in your agent workflow
+snipara-companion brief           # what changed, why, impact, next action, safe-to-proceed
+snipara-companion status          # current work across workflow, git, and Team Sync
+snipara-companion handoff --summary "<what changed>" --next "<next step>"
+```
+
+Local continuity commands work without a Snipara account; commands that read
+hosted context or memory need `init`/`login` first. Run
+`snipara-companion --help` for the full command list.
+
 ```mermaid
 flowchart LR
     Project["Local project"] --> Companion["snipara-companion"]
@@ -92,114 +111,9 @@ yarn global add snipara-companion
 snipara-companion
 ```
 
-## New In 1.4.13
-
-- Adds `snipara-companion memory invalidate <memory-id>` and
-  `snipara-companion memory supersede <old-memory-id> <new-memory-id>` so agents
-  can apply Memory V2 lifecycle corrections through companion when a recalled
-  memory is obsolete or replaced.
-- Keeps lifecycle mutation outside read-only hygiene commands: `memory compact`
-  remains dry-run only, while invalidate/supersede require explicit memory IDs.
-
-## New In 1.4.5
-
-- `workflow phase-commit` and `workflow final-commit` now complete matching
-  local Team Sync work items when the workflow outcome is completed.
-- Matching stays conservative: workflow-goal text wins, and file/token fallback
-  is only used when no workflow goal is available, so deploy or promotion
-  threads are not closed from implementation evidence alone.
-- Text output now reports completed Team Sync work when workflow commits clean up
-  local active items.
-
-## New In 1.4.4
-
-- Adds `snipara-companion memory local -- <args...>` as a thin bridge to the
-  open `snipara-memory` engine for no-account local memory workflows.
-- Adds `snipara-companion eval export` to write a `snipara-evals` case from
-  local workflow, Team Sync, file, command, and expected-signal inputs.
-- Adds `snipara-companion eval run` to execute `snipara-evals` through `npx` or a
-  configured local runner.
-- Clarifies the open Mini Snipara stack boundary: local continuity and evals are
-  open, while team-wide presence, shared locks, GitHub checks, dashboards, and
-  Cloud code graph remain hosted Snipara capabilities.
-
-## New In 1.4.8
-
-- Adds `snipara-companion collaboration guard --ack-review-only` so enforced
-  release guards can acknowledge review-only stale-state and
-  decision-consistency warnings without requiring
-  `SNIPARA_COLLABORATION_GUARD=0`. The hosted `REVIEW_REQUIRED` verdict stays
-  visible in the guard payload; `BLOCKED`, `REQUIRES_ACK`, active-session
-  conflicts and blocking leases still fail.
-- Updates the Infomaniak deploy guard to use the review-only ack path for
-  release UX false positives while keeping the emergency env bypass reserved for
-  true guard outages.
-
-## New In 1.4.2
-
-- Adds `snipara-companion collaboration start|watch|claim|guard|release|status`
-  for safe parallel coding presence, auto-claims, advisory/exclusive resource
-  claims, hosted guard checks, and conflict alarms across humans and agents.
-- Adds `snipara-companion collaboration hooks install` plus guard profiles for
-  blocking pre-commit, pre-push, pre-deploy, schema/migration, and package
-  release checks.
-- Adds `snipara-companion collaboration ide-status` for editor extensions and
-  local companion UIs that need compact live collaboration state.
-- Hardens local code impact so stale or incomplete local overlay caches report
-  missing target files instead of silently returning an empty impact set.
-- Adds `snipara-companion workflow impact-gate` for committed local workflow
-  phases that are ahead of upstream but not pushed yet. It compares
-  `upstream..HEAD`, separates dirty working-tree files, runs local code-overlay
-  impact on the committed code files, and maps the result back to completed
-  workflow phases.
-
-## New In 1.4.1
-
-- Makes local code overlay Git hooks background by default so `git commit` and
-  `git push` return quickly while Snipara refreshes local overlay state and
-  push-time promotion asynchronously.
-- Adds `snipara-companion code hooks install --synchronous` for teams that
-  intentionally want foreground hook work, plus a configurable background
-  reindex delay for pre-push promotion.
-
-## New In 1.3.7
-
-- Hardens `memory-guard check` with `--confirmed-by-user "<confirmation>"`
-  for explicit, auditable overrides after the user has reviewed destructive or
-  contradictory signals.
-- Adds stable guard exit codes in strict mode: `20` for confirmation required,
-  `21` for unavailable memory/context guidance, and `22` for invalid guard
-  options.
-- Validates destructive checks before hosted calls so vague commands such as
-  `--destructive` without `--intent` or `--command` fail fast.
-- Extends `snipara-companion init --with-hooks` so it also installs local code
-  overlay Git hooks (`post-commit` sync and `pre-push` promotion/reindex).
-
-## New In 1.3.6
-
-- Adds `snipara-companion memory audit` for a read-only memory hygiene pass that
-  combines hosted memory health, cleanup candidates, and compaction dry-run.
-- Adds `memory health`, `memory clean-candidates`, and `memory compact` as
-  direct companion maintenance commands. `memory compact` always sends
-  `dry_run=true` and does not mutate memory.
-- Extends `memory-guard check` with `--intent`, `--destructive`, and
-  `--require-confirmation` so agents can surface memory/context contradictions
-  and ask the user before irreversible actions.
-
-## New In 1.3.0
-
-- Adds top-level Git-style agent work commands: `status`, `brief`, `timeline`,
-  `verify`, `handoff`, and `workflow resume`.
-- Adds `snipara-companion verify` for transparent verification plans based on
-  companion code impact auto-source selection plus local package scripts.
-- Reframes companion as the day-two continuity surface after
-  `npx create-snipara` installs the project.
-
-## New In 1.2.0
-
-- Adds `snipara-companion intelligence brief` for a local Project Intelligence brief that composes hosted resume context, memory health, and code impact into one agent-ready output.
-- Adds `workflow scaffold --preset project-intelligence-continuity-layer` for the full memory + code graph + workflow continuity roadmap.
-- Updates generated agent workflow instructions so new work can call the Project Intelligence brief before risky changes and scaffold the roadmap preset for multi-phase delivery.
+## Changelog
+
+Release notes have moved to [CHANGELOG.md](./CHANGELOG.md).
 
 ## Agentic Work Commands
 
@@ -214,6 +128,7 @@ snipara-companion timeline
 snipara-companion workflow phase-commit build --summary "tests green"
 snipara-companion workflow impact-gate
 snipara-companion verify --changed-files src/auth.ts --diff-summary "auth hardening"
+snipara-companion run --task "ship auth hardening" --changed-files src/auth.ts --release
 snipara-companion handoff --summary "status command shipped" --next "publish package"
 snipara-companion workflow resume --include-session-context
 ```
@@ -270,66 +185,6 @@ Output includes:
 - missing checks and caveats
 - suggested next commands
 
-## New In 1.1.15
-
-- Expands `init --client` to Claude Code, Cursor, Windsurf, Codex, Gemini, Mistral, ChatGPT, VS Code, Continue, and custom MCP clients.
-- Keeps Claude Code, Cursor, and Windsurf as hook-capable presets while treating Mistral, ChatGPT, VS Code, Continue, and custom clients as MCP-first setup presets.
-- Prints Codex TOML or HTTP MCP references for MCP-first clients instead of generating unsupported legacy hooks.
-
-## New In 1.1.14
-
-- Adds `npx -y snipara-companion@latest automations install/status/diff/update` for installing dashboard-generated automation hook bundles locally.
-- `init --with-hooks` now delegates hook installation to the hosted automation config bundle so Claude Code, Cursor, and Windsurf use the same templates as Project Automation.
-- Managed automation files are tracked in `.snipara/automations/manifest.json` and are not overwritten after local edits unless `--force` is used.
-- Automation REST calls now use `www.snipara.com` while MCP calls stay on `api.snipara.com`, avoiding FastAPI IP rate limits on Stuck Guard and generated hook installs.
-
-## New In 1.1.13
-
-- Adds `snipara-companion stuck-guard status/check/simulate` for hosted Memory Guard / Stuck Guard decisions.
-- `pre-tool` now emits canonical `tool_call` events and prints Rescue Packs when hosted Stuck Guard returns `inject` or `enforce`.
-- `post-tool` now emits canonical `tool_result` events with status, exit code, command, classification, and a redacted/truncated preview.
-
-## New In 1.1.12
-
-- Documents the GitHub PR Answer Packs boundary: use `create-snipara --github`
-  for the hosted GitHub App setup, and use `snipara-companion` only for local
-  planning, code impact checks, workflow state, and memory commits.
-
-## New In 1.1.10
-
-- Snipara Sandbox guidance now points existing projects to `npx create-snipara repair --with-runtime`
-- Managed workflow phases marked `needs_runtime` suggest Snipara Sandbox installation only when needed
-
-## New In 1.1.4
-
-- `snipara-companion onboard-folder` previews and applies dashboardless business-folder imports from local or LLM-materialized sources
-- `snipara-companion workflow start/status/resume/phase-start/phase-commit` keeps a visible LLM plan in `.snipara/workflow/current.json` and persists each phase through hosted memory so compacted agents can resume safely
-- `snipara-companion final-commit` persists the final workflow outcome with `snipara_end_of_task_commit`
-- `snipara-companion code symbol-card` and `snipara-companion code impact` expose paid Context safeguards directly from the companion CLI
-
-## New In 1.1.2
-
-- `snipara-companion doctor` and Snipara Sandbox hints detect provider keys from local `.env` files without printing secret values
-
-## New In 1.1.1
-
-- `snipara-companion doctor` diagnoses Snipara auth, Snipara Sandbox, Snipara Sandbox MCP, provider keys, and Docker
-- `workflow run` prints contextual Snipara Sandbox hints for full/orchestrated/execution-heavy work
-- `workflow run --no-runtime-hint` hides Snipara Sandbox guidance for scripted terminal output
-
-## New In 1.1.0
-
-- `business-collections` commands for Team Business Context presets and reusable business docs
-- `client-projects` commands for creating and listing project-scoped client context workspaces
-- `upload --metadata/--metadata-file` plus convenience metadata flags for single-file business/client uploads
-
-## New In 1.0.0
-
-- direct `snipara-companion code` access for `callers`, `imports`, `neighbors`, and `shortest-path`
-- `workflow run --mode lite|standard|full|orchestrate` for hosted-first workflow routing; `auto` remains a STANDARD compatibility alias
-- `snipara-companion shared-context` for project-linked standards and team guidance
-- automatic fallback to project token auth when a stale `SNIPARA_API_KEY` overrides a valid local login
-
 ## Supported Client Presets Today
 
 The built-in `init` and `automations` flows share these client names:
@@ -713,8 +568,9 @@ metadata, and referenced-from provenance.
 
 ### Project Intelligence Briefs
 
-Use `intelligence brief` when a task needs one local entrypoint for continuity,
-memory authority, and code impact:
+Use `intelligence brief` when a task needs a local continuity readout for
+memory authority, code impact, verification hints, and the Project Intelligence
+Judgment Card:
 
 ```bash
 snipara-companion intelligence brief \
@@ -727,8 +583,24 @@ The command calls hosted `snipara_resume_context` and `snipara_memory_health`.
 When changed files are provided, code impact uses companion auto-source
 selection, so dirty/ahead worktrees use the local overlay and clean configured
 checkouts use hosted graph impact. It prints continuity signals, memory health,
-risk and verification hints, degraded surfaces, and the next companion commands
-to keep the workflow resumable.
+risk and verification hints, degraded surfaces, and the Judgment Card's
+weighted readiness, evidence, and required actions.
+
+Use top-level `run` when the agent should make a production-oriented go/no-go
+judgment in one pass:
+
+```bash
+snipara-companion run \
+  --task "ship auth hardening" \
+  --changed-files src/auth.ts tests/auth.test.ts \
+  --diff-summary "auth hardening" \
+  --release
+```
+
+`run --release` composes the Project Intelligence brief, collaboration guard,
+package-surface review, verification plan, and final Judgment Card. Review-only
+guard findings can be acknowledged with the printed guard action card command;
+blocking conflicts still make the release judgment non-proceedable.
 
 For the full Project Intelligence and Continuity Layer roadmap, scaffold the
 built-in managed workflow plan:
@@ -760,6 +632,7 @@ Semantics:
 - `snipara-companion timeline` = local timeline of workflow starts, phase starts, phase commits, final commits, and Team Sync handoffs
 - `snipara-companion handoff` = top-level agent-ready Markdown/JSON handoff artifact plus the same local/hosted Team Sync handoff persistence
 - `snipara-companion intelligence brief` = one local Project Intelligence brief that combines resume context, memory health, and code impact for a task
+- `snipara-companion run` = production Project Intelligence flow that combines the brief, guard action cards, package review, verification hints, and a final weighted Judgment Card
 - `snipara-companion workflow start --plan-file` = records the visible LLM plan locally so phase state survives agent compaction; prefer JSON plans with explicit ids for stable machine phase state
 - `snipara-companion workflow scaffold --preset project-intelligence-continuity-layer` = creates a four-phase managed plan for memory authority, code impact, continuity summaries, and release/docs surfaces
 - `snipara-companion workflow phase-start` = marks the current phase and prints the required Snipara context gate plus code-impact / symbol-card gates; runtime-marked phases also get a stable Snipara Sandbox session binding
@@ -976,7 +849,7 @@ To test a packed tarball manually, use `npm exec --package`:
 
 ```bash
 npm pack
-npm exec --package ./snipara-companion-1.4.13.tgz snipara-companion -- --help
+npm exec --package ./snipara-companion-1.4.14.tgz snipara-companion -- --help
 ```
 
 Do not use `npx /path/to/snipara-companion-*.tgz`. npm will try to execute the tarball itself instead of

package/dist/index.d.ts

@@ -1240,6 +1240,18 @@ declare function normalizeGuardTag(tag: string): string;
 declare function categoryFromGuardTag(tag: string): string;
 declare function detectReleaseSurfacesFromFiles(root: string, files: string[]): ReleaseSurface[];
 declare function getStagedFiles(root: string): string[];
+/**
+ * Recall and evaluate guard guidance before a risky action.
+ *
+ * Given a trigger (failure | pre-commit | commit | pre-final | manual) and
+ * optional touched files (or `--staged`), it detects release surfaces and
+ * destructive/contradictory intent, recalls tagged memory and source context,
+ * and returns findings plus whether the caller must stop or confirm. Honors an
+ * explicit `confirmedByUser` override so a reviewed destructive action can
+ * proceed. Backs the strict-mode exit codes used by Git hooks.
+ *
+ * @returns Findings, warnings, and a decision the caller can act on.
+ */
 declare function runMemoryGuardCheck(options?: MemoryGuardCheckOptions): Promise<MemoryGuardCheckResult>;
 
 type LocalCodeOverlayMode = "working_tree" | "local_commit";
@@ -1438,6 +1450,20 @@ interface HostedCodeOverlayUploadPayload {
 }
 declare function getLocalCodeOverlayCachePath(cwd?: string): string;
 declare function getLocalCodePromotionStatePath(cwd?: string): string;
+/**
+ * Build a local code graph overlay over the working tree or a local commit.
+ *
+ * Walks candidate files (working tree, or a commit when `mode` is
+ * "local_commit"), parses supported languages into files/symbols/imports, and
+ * records why files were excluded (ignored, unsupported language, too large,
+ * secret pattern, read error). Honors `.sniparaignore`, per-file size and file
+ * count caps (`maxFiles`, `maxFileBytes`), and adds warnings when limits are
+ * hit. This overlay backs the offline impact/callers/imports queries; it is
+ * best-effort, not authoritative.
+ *
+ * @returns A `LocalCodeOverlayManifest` with files, symbols, imports, excluded
+ *   samples, and warnings.
+ */
 declare function buildLocalCodeOverlay(options?: LocalCodeOverlayOptions): LocalCodeOverlayManifest;
 declare function summarizeLocalCodeOverlay(manifest: LocalCodeOverlayManifest): LocalCodeOverlaySummary;
 declare function writeLocalCodeOverlayCache(manifest: LocalCodeOverlayManifest): string;
@@ -1455,6 +1481,154 @@ declare function buildLocalImpactResult(options: LocalCodeQueryCommandOptions):
 declare function buildCodeHooksInstallPlan(options?: CodeHooksInstallCommandOptions): Record<string, unknown>;
 declare function buildCodePromotionResult(options?: CodePromoteCommandOptions): Promise<Record<string, unknown>>;
 
+/**
+ * Project Intelligence Judgment Card.
+ *
+ * Pure scoring and explanation layer for agent-facing "can I proceed?"
+ * decisions. It intentionally consumes already-fetched surfaces instead of
+ * adding network calls, so commands can use it in production paths without
+ * changing hosted behavior.
+ */
+type ProjectJudgmentCanProceed = "yes" | "review" | "block";
+type ProjectJudgmentState = "ready" | "watch" | "review" | "proof_required" | "blocked";
+type ProjectJudgmentSeverity = "info" | "low" | "medium" | "high" | "critical";
+type ProjectJudgmentActionType = "run_check" | "inspect" | "handoff" | "acknowledge" | "package_review" | "deploy_review" | "resolve_blocker";
+interface ProjectJudgmentReason {
+    code: string;
+    severity: ProjectJudgmentSeverity;
+    message: string;
+    points: number;
+    source: string;
+}
+interface ProjectJudgmentAction {
+    type: ProjectJudgmentActionType;
+    title: string;
+    command?: string;
+    reason?: string;
+    severity: ProjectJudgmentSeverity;
+    safeToAck?: boolean;
+}
+interface ProjectJudgmentEvidence {
+    source: string;
+    label: string;
+    detail?: string;
+}
+interface ProjectIntelligenceJudgmentCard {
+    version: "project-intelligence.judgment-card.v1";
+    generatedAt: string;
+    task?: string;
+    target: {
+        branch?: string;
+        changedFiles: string[];
+    };
+    score: number;
+    band: "high" | "medium" | "low" | "blocked";
+    state: ProjectJudgmentState;
+    canProceed: ProjectJudgmentCanProceed;
+    summary: string;
+    reasons: ProjectJudgmentReason[];
+    requiredActions: ProjectJudgmentAction[];
+    advisories: ProjectJudgmentAction[];
+    evidence: ProjectJudgmentEvidence[];
+    caveats: string[];
+}
+interface BuildProjectJudgmentCardInput {
+    task?: string;
+    branch?: string;
+    changedFiles?: string[];
+    resumeContext?: Record<string, unknown>;
+    memoryHealth?: Record<string, unknown>;
+    codeImpact?: Record<string, unknown>;
+    verificationPlan?: Record<string, unknown>;
+    guard?: Record<string, unknown>;
+    advisoryObservability?: Record<string, unknown>;
+    teamSyncReadiness?: Record<string, unknown>;
+    errors?: Array<{
+        surface: string;
+        message: string;
+    }>;
+}
+declare function buildProjectJudgmentCard(input: BuildProjectJudgmentCardInput): ProjectIntelligenceJudgmentCard;
+declare function formatProjectJudgmentCard(card: ProjectIntelligenceJudgmentCard): string[];
+
+interface VerifyCommandOptions {
+    task?: string;
+    qualifiedName?: string;
+    symbolKey?: string;
+    filePath?: string;
+    changedFiles?: string[];
+    diffSummary?: string;
+    limit?: number;
+    skipImpact?: boolean;
+    json?: boolean;
+}
+interface VerificationCheck {
+    kind: "test" | "lint" | "type-check" | "build" | "inspection" | "command";
+    title: string;
+    command?: string;
+    file?: string;
+    source: "code-impact" | "package-script" | "fallback";
+    reason?: string;
+}
+interface VerificationGap {
+    code: string;
+    severity: "low" | "medium" | "high";
+    message: string;
+}
+interface VerificationRisk {
+    level: string;
+    score?: number;
+    source: "code-impact" | "fallback";
+}
+interface VerificationPlan {
+    version: "snipara.verification_plan.v1";
+    generatedAt: string;
+    task?: string;
+    target: {
+        qualifiedName?: string;
+        symbolKey?: string;
+        filePath?: string;
+        changedFiles: string[];
+    };
+    impactedFiles: string[];
+    recommendedChecks: VerificationCheck[];
+    risk: VerificationRisk;
+    missingChecks: VerificationGap[];
+    caveats: string[];
+    suggestedCommands: string[];
+    codeImpact?: Record<string, unknown>;
+    codeImpactSourceSelection?: CodeGraphSourceSelection;
+    judgmentCard?: ProjectIntelligenceJudgmentCard;
+    errors: Array<{
+        surface: string;
+        message: string;
+    }>;
+}
+interface BuildVerificationPlanOptions extends VerifyCommandOptions {
+    cwd?: string;
+    codeImpact?: Record<string, unknown>;
+    codeImpactSourceSelection?: CodeGraphSourceSelection;
+    errors?: Array<{
+        surface: string;
+        message: string;
+    }>;
+}
+/**
+ * Build a transparent verification plan for the current change.
+ *
+ * Combines code-impact signals (direct related tests, action checks, coverage
+ * gaps) with package scripts inferred from the impacted files, dedupes the
+ * resulting checks, and records explicit gaps (impact unavailable/skipped, no
+ * direct tests, no impacted files) so the plan is honest about what it can and
+ * cannot verify. Pure: it returns a plan and never executes any check.
+ *
+ * @param options Changed files / file path, optional code impact, cwd, and
+ *   `skipImpact`.
+ * @returns A plan of recommended checks plus a list of coverage gaps.
+ */
+declare function buildVerificationPlan(options: BuildVerificationPlanOptions): VerificationPlan;
+declare function verifyCommand(options: VerifyCommandOptions): Promise<void>;
+
 interface ProjectIntelligenceBriefOptions {
     task?: string;
     branch?: string;
@@ -1477,12 +1651,28 @@ interface ProjectIntelligenceBrief {
     memoryHealth?: Record<string, unknown>;
     codeImpact?: Record<string, unknown>;
     codeImpactSourceSelection?: CodeGraphSourceSelection;
+    verificationPlan?: VerificationPlan;
+    judgmentCard?: ProjectIntelligenceJudgmentCard;
     errors: Array<{
         surface: string;
         message: string;
     }>;
     suggestedCommands: string[];
 }
+/**
+ * Build a Project Intelligence continuity brief for the current task.
+ *
+ * Gathers three best-effort signals through the hosted client — resume context
+ * (`snipara_resume_context`), memory health, and local code impact — and merges
+ * them with the changed/recent files and a list of suggested next commands.
+ * Each source is wrapped independently: a failure is recorded in `brief.errors`
+ * rather than thrown, so callers always receive a usable (possibly partial)
+ * brief.
+ *
+ * @param options Task, branch, changed/recent files, token budget, and skip
+ *   flags (`skipImpact`, `skipMemoryHealth`).
+ * @returns A `project-intelligence-brief-v1` document.
+ */
 declare function buildProjectIntelligenceBrief(options: ProjectIntelligenceBriefOptions): Promise<ProjectIntelligenceBrief>;
 declare function projectIntelligenceBriefCommand(options: ProjectIntelligenceBriefOptions): Promise<void>;
 
@@ -1587,69 +1777,47 @@ declare function memoryLocalCommand(options: LocalMemoryCommandOptions): Promise
 declare function evalExportCommand(options: EvalExportOptions): Promise<void>;
 declare function evalRunCommand(options: EvalRunOptions): Promise<void>;
 
-interface VerifyCommandOptions {
+interface ProjectRunCommandOptions {
     task?: string;
-    qualifiedName?: string;
-    symbolKey?: string;
-    filePath?: string;
+    branch?: string;
     changedFiles?: string[];
+    recentFiles?: string[];
     diffSummary?: string;
-    limit?: number;
+    maxTokens?: number;
+    release?: boolean;
     skipImpact?: boolean;
+    skipMemoryHealth?: boolean;
+    skipGuard?: boolean;
+    skipPackageReview?: boolean;
     json?: boolean;
 }
-interface VerificationCheck {
-    kind: "test" | "lint" | "type-check" | "build" | "inspection" | "command";
-    title: string;
-    command?: string;
-    file?: string;
-    source: "code-impact" | "package-script" | "fallback";
-    reason?: string;
-}
-interface VerificationGap {
-    code: string;
-    severity: "low" | "medium" | "high";
-    message: string;
+interface ProjectRunGuardResult {
+    command: string;
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    payload?: Record<string, unknown>;
+    error?: string;
 }
-interface VerificationRisk {
-    level: string;
-    score?: number;
-    source: "code-impact" | "fallback";
+interface ProjectRunPackageReview {
+    command: string;
+    status: "skipped" | "ok" | "error";
+    packageName: "snipara-companion";
+    data?: unknown;
+    error?: string;
 }
-interface VerificationPlan {
-    version: "snipara.verification_plan.v1";
+interface ProjectIntelligenceRunResult {
+    version: "project-intelligence.production-run.v1";
     generatedAt: string;
-    task?: string;
-    target: {
-        qualifiedName?: string;
-        symbolKey?: string;
-        filePath?: string;
-        changedFiles: string[];
-    };
-    impactedFiles: string[];
-    recommendedChecks: VerificationCheck[];
-    risk: VerificationRisk;
-    missingChecks: VerificationGap[];
-    caveats: string[];
+    release: boolean;
+    brief: ProjectIntelligenceBrief;
+    guard?: ProjectRunGuardResult;
+    packageReview?: ProjectRunPackageReview;
+    judgmentCard: ProjectIntelligenceJudgmentCard;
     suggestedCommands: string[];
-    codeImpact?: Record<string, unknown>;
-    codeImpactSourceSelection?: CodeGraphSourceSelection;
-    errors: Array<{
-        surface: string;
-        message: string;
-    }>;
 }
-interface BuildVerificationPlanOptions extends VerifyCommandOptions {
-    cwd?: string;
-    codeImpact?: Record<string, unknown>;
-    codeImpactSourceSelection?: CodeGraphSourceSelection;
-    errors?: Array<{
-        surface: string;
-        message: string;
-    }>;
-}
-declare function buildVerificationPlan(options: BuildVerificationPlanOptions): VerificationPlan;
-declare function verifyCommand(options: VerifyCommandOptions): Promise<void>;
+declare function buildProjectIntelligenceRun(options: ProjectRunCommandOptions): Promise<ProjectIntelligenceRunResult>;
+declare function projectIntelligenceRunCommand(options: ProjectRunCommandOptions): Promise<void>;
 
 type SyncDocumentKind = "DOC" | "BINARY";
 type WorkflowMode = "lite" | "standard" | "auto" | "full" | "orchestrate";
@@ -1920,6 +2088,19 @@ declare function buildWorkflowPhaseCommitSummary(args: {
     phase: Pick<ManagedWorkflowPhase, "id" | "title">;
     summary: string;
 }): string;
+/**
+ * Compute the impact gate for committed-but-unpushed workflow phases.
+ *
+ * Compares `upstream..HEAD`, separates unpushed code changes from non-code and
+ * dirty working-tree files, runs local code-overlay impact on the committed
+ * code files, and maps the result back to completed workflow phases. Surfaces
+ * reason codes such as `dirty_working_tree_not_included` and phase files that
+ * fall outside the unpushed diff, so a phase is not treated as verified on
+ * stale or partial evidence.
+ *
+ * @returns A `WorkflowImpactGateResult` with changed files, local impact,
+ *   matched phases, and reason codes.
+ */
 declare function buildWorkflowImpactGate(options?: {
     cwd?: string;
     base?: string;
@@ -2298,6 +2479,17 @@ declare function buildAgenticHandoffMarkdown(artifact: AgenticHandoffArtifact):
 declare function teamSyncSweepCommand(options: TeamSyncCommandOptions): Promise<void>;
 
 declare const COLLABORATION_STATE_RELATIVE_PATH: string;
+type CollaborationGuardActionKind = "safe_to_ack" | "needs_handoff" | "needs_test" | "needs_package_review" | "blocking_conflict" | "guard_unavailable";
+interface CollaborationGuardActionCard {
+    kind: CollaborationGuardActionKind;
+    title: string;
+    reason: string;
+    severity: "info" | "watch" | "warning" | "critical";
+    safeToAck: boolean;
+    command?: string;
+    conflictCode?: string;
+    resource?: string;
+}
 interface CollaborationCommandOptions {
     summary?: string;
     files?: string[];
@@ -2391,6 +2583,12 @@ declare function parseCollaborationResources(values: string[] | undefined): Coll
 declare function deriveLocalCollaborationResourcesFromFiles(files: string[] | undefined, rootDir?: string, maxFiles?: number): CollaborationResource[];
 declare function buildCollaborationHooksInstallPlan(options?: CollaborationHooksInstallOptions): Record<string, unknown>;
 declare function collaborationIdeStatusCommand(options: CollaborationCommandOptions): Promise<void>;
+declare function buildCollaborationGuardActionCards(evaluation: CollaborationGuardEvaluation | undefined, context?: {
+    profile?: string;
+    enforced?: boolean;
+    ackReviewOnly?: boolean;
+    reviewOnlyAcknowledged?: boolean;
+}): CollaborationGuardActionCard[];
 interface HostedGuardPayload {
     files: string[];
     resources: CollaborationResource[];
@@ -2477,6 +2675,17 @@ interface RuntimeDetectionReport {
 }
 declare function detectRuntimeEnvironment(cwd?: string, env?: RuntimeEnvironment): RuntimeDetectionReport;
 declare function shouldSuggestRuntimeForWorkflow(query: string, mode: WorkflowMode): boolean;
+/**
+ * Recommend whether work should be routed to snipara-orchestrator.
+ *
+ * Scores intent signals from the query and workflow mode (orchestrate mode,
+ * production / proof / htask / multi-agent / parallel patterns) plus contextual
+ * signals (changed-file count, active Team Sync collisions, policy auto-route).
+ * The returned recommendation's level escalates with the accumulated score
+ * (suggest → confirm → auto).
+ *
+ * @returns A recommendation with its reasons, or `null` when no signal fires.
+ */
 declare function getOrchestratorRecommendation(query: string, mode: WorkflowMode, options?: OrchestratorRecommendationOptions): OrchestratorRecommendation | null;
 declare function formatOrchestratorRecommendationReason(reason: OrchestratorRecommendationReason): string;
 declare function shouldSuggestOrchestratorForWorkflow(query: string, mode: WorkflowMode): boolean;
@@ -2589,4 +2798,4 @@ interface WrittenOrchestratorHandoff {
 declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions): OrchestratorHandoffArtifact;
 declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, COLLABORATION_STATE_RELATIVE_PATH, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCollaborationActor, buildCollaborationHooksInstallPlan, buildEvalCaseArtifact, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collaborationIdeStatusCommand, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, parseCollaborationResources, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveQueryFromToolInput, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, COLLABORATION_STATE_RELATIVE_PATH, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildEvalCaseArtifact, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collaborationIdeStatusCommand, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveQueryFromToolInput, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };