snipara-companion 1.4.13 → 1.4.15

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