workspai 0.57.0 → 0.59.0

package/docs/agent-entry.md

@@ -0,0 +1,194 @@
+# Canonical-First Agent Entry
+
+Workspai gives coding agents one portable way to enter an adopted project
+without treating a broad repository scan as the source of architectural truth.
+
+The protocol is:
+
+```text
+Host discovery
+  → portable project entry
+  → canonical identity and evidence
+  → freshness and integrity checks
+  → active Goal handoff
+  → bounded Graph retrieval
+  → targeted live source inspection
+```
+
+This is deliberately **host-first, not model-first**. A model does not decide
+which repository instruction file is loaded. Codex, Claude Code, Gemini CLI,
+Qwen Code, Kimi Code, GitHub Copilot, Cursor, Windsurf, Amazon Q, Grok, and
+other agent harnesses each own their discovery behavior. Workspai projects one
+canonical protocol through the entry surface each host supports.
+
+## Start from an adopted project
+
+Adopt or import the project once:
+
+```bash
+npx workspai adopt .
+```
+
+When the eventual agent host is not known, run the canonical chain with
+`--for-agent generic`:
+
+```bash
+npx workspai workspace intelligence run --for-agent generic --strict --json
+```
+
+`generic` creates one consumer-neutral context pack and projects lightweight
+entry surfaces for **all supported agent hosts**. It does not build a separate
+Model or Graph for every provider. A later host can therefore discover the
+same canonical evidence without repeating the expensive intelligence run.
+Choosing a named agent may tune the shared context consumer, but the canonical
+chain still preserves portable entry coverage for every supported host.
+
+Workspai writes a portable entry contract at
+`.workspai/agent-entry.v1.json`, a bounded project lens at
+`.workspai/reports/project-context-agent.json`, and host adapters when project
+grounding is managed.
+
+At the start of an agent session, issue a receipt from the project directory:
+
+```bash
+npx workspai agent bootstrap --for-agent codex --strict --json
+```
+
+Use `generic` when the host has no dedicated identifier. Use the legacy
+`orca` input only for compatibility; Workspai resolves it to `grok`.
+
+Audit every supported host in CI or before publishing project grounding:
+
+```bash
+npx workspai project agent-entry verify --for-agent all --strict --json
+```
+
+## What the receipt proves
+
+The `workspai.agent-bootstrap-receipt.v1` payload checks:
+
+- canonical project-to-workspace membership;
+- entry manifest and project-context integrity hashes;
+- host discovery files without overwriting authored repository state;
+- presence and schema validity of the report index, agent context, Workspace
+  Model, and Knowledge Graph;
+- persisted Model/Graph compatibility;
+- live project input compatibility, unless explicitly skipped;
+- active Goal Pack and agent-handoff bindings;
+- portable output with no machine-local absolute paths.
+
+The receipt does not claim that a model followed the instructions. It proves
+that the host has a valid route to current Workspai evidence and tells the
+consumer what it may claim next. The portable manifest keeps `generic` as its
+provider-neutral bootstrap command; each runtime receipt replaces that step in
+`requiredReadOrder` with the resolved host (or `all` for a complete host audit),
+so a consumer is never routed back through the wrong adapter.
+
+The generated workspace name is a logical identity, never a filesystem path.
+Project-local artifacts use `.workspai/...`; canonical workspace artifacts use
+the `workspace:` URI prefix. When an agent requires direct file access, it
+resolves the exact local workspace root at runtime from the adopted project:
+
+```bash
+workspai project workspace status --json
+```
+
+That resolver intentionally returns absolute paths to the local process. Its
+contract classifies them as machine-local, non-portable, forbidden to persist,
+and forbidden to disclose. Entry manifests, project lenses, bootstrap receipts,
+answers, shared logs, commits, prompts, and telemetry must not copy those paths.
+
+| Status     | Meaning                                                               | Consumer rule                                                               |
+| ---------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `ready`    | Host entry, contracts, integrity, and live evidence passed            | Continue with bounded Graph retrieval and targeted source reads             |
+| `degraded` | Evidence is usable with an explicit limitation                        | Disclose the limitation; do not claim complete architecture or verification |
+| `blocked`  | Required discovery, binding, contract, integrity, or freshness failed | Refresh or repair evidence before architectural or verification claims      |
+
+An active Goal is reported independently as `ready`, `stale`, or `invalid`.
+A stale Goal remains `present: true`; the receipt includes a complete refresh
+command in `nextActions`. Absence is represented as `present: false` with
+`status: none`, never as a validation failure.
+
+`--strict` returns exit code `2` for both `degraded` and `blocked`. Without
+`--strict`, a blocked receipt still returns exit code `2`; degraded evidence is
+returned for an explicitly limited read-only workflow.
+
+`--no-live-inputs` is an intentional degraded mode. It checks persisted
+compatibility but cannot prove that the source tree still matches the last
+intelligence run.
+
+## Authority boundaries
+
+Workspai does not replace source code with generated summaries:
+
+- live source owns exact implementation behavior;
+- the canonical Workspace Model owns workspace identity and structural truth;
+- the Knowledge Graph is a model-bound, proof-backed retrieval projection;
+- CLI evidence owns readiness, verification, repair, and Goal lifecycle claims;
+- the project entry contract owns the order in which an agent reaches those
+  sources.
+
+This means an agent begins with canonical evidence, then verifies and deepens
+it through narrow source inspection. It must not silently replace missing or
+stale workspace evidence with an unbounded repository scan.
+
+## Host projection
+
+| Host                                                     | Project discovery surface                                |
+| -------------------------------------------------------- | -------------------------------------------------------- |
+| Generic and unsupported model-only clients               | `.workspai/PROJECT-GROUNDING.md` plus explicit bootstrap |
+| Codex, Kimi Code, GitHub Copilot, Cursor, Windsurf, Grok | `AGENTS.md`                                              |
+| Claude Code                                              | `CLAUDE.md` adapter                                      |
+| Gemini CLI                                               | `GEMINI.md` adapter                                      |
+| Qwen Code                                                | `QWEN.md` adapter                                        |
+| Amazon Q                                                 | `.amazonq/rules/workspai-agent-entry.md`                 |
+
+The adapters contain routing instructions, not duplicated model or graph
+state. The manifest records whether each surface is native, adapted, or a
+portable fallback and whether Workspai could manage it safely.
+
+This matrix was last checked against official host documentation on
+2026-08-16: [Codex `AGENTS.md`](https://learn.chatgpt.com/docs/agent-configuration/agents-md),
+[Claude Code memory](https://code.claude.com/docs/en/memory),
+[Gemini CLI context files](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md),
+[Qwen Code settings](https://github.com/QwenLM/qwen-code/blob/main/docs/users/configuration/settings.md),
+[Kimi Code `AGENTS.md`](https://www.kimi.com/code/docs/en/kimi-code-cli/customization/agents),
+[GitHub Copilot repository instructions](https://docs.github.com/en/copilot/concepts/prompting/response-customization),
+[Cursor rules](https://docs.cursor.com/context/rules-for-ai),
+[Windsurf `AGENTS.md`](https://docs.windsurf.com/windsurf/cascade/agents-md),
+[Amazon Q project rules](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/context-project-rules.html),
+and [Grok skills and instructions](https://docs.x.ai/build/features/skills-plugins-marketplaces).
+DeepSeek, Mistral, hosted model APIs, and other model-only consumers do not
+define a provider-wide repository entry surface independently of the agent
+host. They use the generic portable bootstrap unless their host maps to one of
+the verified surfaces above. Workspai does not invent a model-specific file
+name from undocumented behavior.
+
+If an authored instruction file or symbolic link prevents safe management,
+Workspai preserves repository ownership and reports degraded or blocked host
+coverage. It does not replace the file to make a check pass.
+
+## Consumer integration
+
+IDEs and agent runtimes should:
+
+1. discover the host-native instruction file;
+2. run `workspai agent bootstrap --for-agent <host> --json`;
+3. validate the receipt schema from the installed CLI contract catalog;
+4. stop broad discovery when the receipt is blocked;
+5. read an applicable active Goal handoff before planning changes;
+6. use the bounded Graph query returned by `nextActions`;
+7. open only returned proofs and target source files;
+8. make mutation and verification claims only through the governed CLI flow.
+
+Do not infer support from the package version alone. Discover
+`projectAgentEntry` and `agentBootstrapReceipt` through
+`contracts/published-contract-catalog.v1.json`.
+
+## Package boundary
+
+The CLI currently owns adoption, synchronization, receipt orchestration, and
+exit semantics. The entry manifest and receipt are versioned, portable
+contracts rather than CLI-internal objects. Future independent Model, Graph,
+Goal, or agent packages can therefore implement their own providers behind the
+same contract without changing the project-facing protocol.

package/docs/ci-workflows.md

@@ -46,7 +46,7 @@ Validate or preview the current CLI announcement locally:
 npm --workspace workspai run check:release-announcement
 npm --workspace workspai run release:announcement -- \
   --product workspai-cli \
-  --tag v0.57.0 \
+  --tag v0.59.0 \
   --markdown-output /tmp/workspai-discord-announcement.md
 ```
 

package/docs/commands-reference.md

@@ -8,6 +8,20 @@ For behavior and workflows, see
 [workspace-operations.md](./workspace-operations.md) and
 [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md).
 
+Start with the outcome-oriented root help when you do not yet know a command:
+
+```bash
+npx workspai --help
+npx workspai <command> --help
+npx workspai commands --json
+```
+
+Root help presents the canonical `Understand → Impact → Act → Verify` path,
+common human workflows, interactive official-kit discovery through `create
+project`, and a complete ownership-grouped command map. Scoped help carries
+exact flags and examples. `commands --json` remains the machine-complete
+inventory used to prevent the human map from drifting.
+
 ## Workspace lifecycle
 
 ```bash
@@ -19,6 +33,9 @@ npx workspai pipeline [--json] [--strict] [--skip-verify] [--skip-analyze] [--sk
 npx workspai analyze [--workspace <path>] [--json] [--strict] [--output <file>]
 npx workspai readiness [--workspace <path>] [--json] [--strict] [--skip-verify]
 npx workspai autopilot release [--mode <audit|safe-fix|enforce>] [--json] [--output <file>] [--since <ref>] [--parallel] [--max-workers <n>]
+npx workspai goal <intent> [--workspace <path>] [--scope <workspace|project:name>] [--for-agent <generic|claude|codex>] [--max-attempts <1-25>] [--refresh] [--dry-run] [--json]
+npx workspai goal <--status [goal-id]|--list|--activate <goal-id>|--cancel <goal-id>|--prepare <goal-id>|--verify <goal-id>> [--workspace <path>] [--no-run] [--json]
+npx workspai agent bootstrap [--project <path>] [--for-agent <host>] [--no-live-inputs] [--strict] [--json]
 ```
 
 Recommended CI:
@@ -57,6 +74,7 @@ npx workspai doctor
 npx workspai doctor workspace [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
 npx workspai doctor project [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
 npx workspai project coverage [--project <path>] [--target <0-100>] [--run] [--strict] [--json]
+npx workspai project agent-entry [verify] [--project <path>] [--for-agent <host|all>] [--no-live-inputs] [--strict] [--json]
 npx workspai workspace list
 npx workspai workspace foundation ensure [--force] [--json]
 npx workspai workspace share [--output <file>] [--include-paths] [--no-doctor]
@@ -69,8 +87,8 @@ npx workspai workspace goal plan <release-readiness|dependency-security|test-cov
 npx workspai workspace goal status <goal-id> [--json]
 npx workspai workspace goal verify <goal-id> [--no-run] [--reuse-intelligence] [--json]
 npx workspai workspace model [--workspace <path>] [--json] [--write] [--strict] [--cache] [--incremental] [--include-paths] [--include-evidence] [--scan-depth <count>]
-npx workspai workspace context --for-agent [generic|codex|claude|cursor|orca] [--workspace <path>] [--scope project:<name>] [--json] [--write] [--agent-sync|--no-agent-sync] [--target <targets>] [--preset minimal|enterprise] [--project-grounding managed|local|off] [--include-evidence] [--scan-depth <count>] [--strict]
-npx workspai workspace agent-sync [--workspace <path>] [--write] [--refresh-context] [--strict] [--json] [--preset minimal|enterprise] [--target all|vscode|agents,copilot,cursor,claude,codex,orca] [--project-grounding managed|local|off] [--experimental-hooks] [--hydrate-prompts]
+npx workspai workspace context --for-agent [generic|codex|claude|gemini|qwen|kimi|grok|copilot|cursor|windsurf|amazon-q] [--workspace <path>] [--scope project:<name>] [--json] [--write] [--agent-sync|--no-agent-sync] [--target <targets>] [--preset minimal|enterprise] [--project-grounding managed|local|off] [--include-evidence] [--scan-depth <count>] [--strict]
+npx workspai workspace agent-sync [--workspace <path>] [--write] [--refresh-context] [--strict] [--json] [--preset minimal|enterprise] [--target all|vscode|agents,copilot,cursor,claude,codex,gemini,qwen,kimi,grok,windsurf,amazon-q] [--project-grounding managed|local|off] [--experimental-hooks] [--hydrate-prompts]
 npx workspai workspace remediation-plan [--json] [--write] [--ci] [--include-paths]
 npx workspai workspace repair <capabilities|plan|propose|approve|decide|execute|resume|status|list|rollback|cancel> [--workspace <path>] [--card <id>] [--action-id <id>] [--project <name>] [--proposal <file>] [--transaction <id>] [--approved-by <actor>] [--decision <choice>] [--max-risk safe|guarded|invasive] [--allow-breaking] [--allow-force] [--no-auto-rollback] [--json]
 npx workspai workspace snapshot [--workspace <path>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
@@ -153,6 +171,24 @@ portable verdict is written to
 [Verified engineering goals](./workspace-intelligence-runner.md#verified-engineering-goals)
 for the supported scopes, safety constraints, and verification boundary.
 
+Top-level `goal <intent>` is the plain-language planning front door. It binds
+the intent to the current canonical Model and Graph, resolves project/workspace
+scope, runs capability/retrieval preflight, and atomically writes a Goal Pack,
+portable agent handoff, and active-goal index. Use `goal --status`, `--list`,
+`--activate`, or `--cancel` for discovery/lifecycle; deterministic goals may use
+`--prepare` and `--verify`. It does not silently mutate source or let an agent
+claim verification. Lifecycle operations are mutually exclusive, cannot be
+combined with an intent or planning-only flags, and `--no-run` is valid only
+with `--verify`. See [Goal Packs](./goal-packs.md).
+
+`agent bootstrap` is the project-local canonical-first preflight. It validates
+the host discovery route, project/workspace binding, public artifact schemas,
+integrity hashes, Model/Graph freshness, live source inputs, and active Goal
+handoff before broad repository discovery. `project agent-entry verify` uses
+the same receipt and can audit every supported host with `--for-agent all`.
+Blocked receipts exit `2`; strict mode also maps degraded evidence to exit `2`.
+See [Canonical-first agent entry](./agent-entry.md).
+
 `workspace feedback record` is a non-interactive machine interface. It requires
 exactly one JSON object on stdin and `--json`; an empty stdin or interactive TTY
 is rejected. Required fields are `actionId`, `summary`, and `outcome`. The

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -28,6 +28,7 @@ root:
 | Artifact                                       | Writer                                                                            | Schema / format             | Portability and reader purpose                                                        |
 | ---------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------- |
 | `.workspai/workspace-link.local.json`          | `adopt`, `import`, project creation, `workspace sync`, `project workspace relink` | `project-workspace-link.v1` | Machine-local absolute binding; always gitignored and never an agent evidence payload |
+| `.workspai/agent-entry.v1.json`                | Project lens reconciliation and `workspace agent-sync --write`                    | `workspai.agent-entry.v1`   | Portable host-discovery, canonical read-order, authority, and integrity contract      |
 | `.workspai/reports/project-context-agent.json` | Project lens reconciliation and `workspace agent-sync --write`                    | `project-context-agent.v1`  | Portable bounded model/graph/proof projection for project-local agents                |
 | `.workspai/PROJECT-GROUNDING.md`               | Project lens reconciliation                                                       | Markdown                    | Portable human/agent entry guide with path-free workspace references                  |
 | `AGENTS.md` managed section                    | Project lens reconciliation in `managed` mode                                     | Managed Markdown block      | Preserves user content and routes compatible agents to project/workspace evidence     |
@@ -42,6 +43,11 @@ machine-local link publishable. The context is bounded but not count-only: it
 includes topology, API/deployment/test surfaces, blockers, portable proofs,
 and model/graph freshness for the selected project.
 
+`agent bootstrap --json` and `project agent-entry verify --json` emit a
+non-persisted `workspai.agent-bootstrap-receipt.v1` payload. The receipt proves
+the selected host route, contract validity, integrity, persisted and live
+freshness, and active Goal bindings without exposing the machine-local link.
+
 ## Naming conventions
 
 | Pattern           | Meaning                                | Examples                                                     |
@@ -62,6 +68,9 @@ and model/graph freshness for the selected project.
 | `workspace remediation-plan --write` | `.workspai/reports/artifact-remediation-plan-last-run.json` | `artifact-remediation-plan-v1`              | `contracts/artifact-remediation-plan.v1.json`                           |
 | `workspace repair *`                 | `.workspai/reports/workspace-repair-last-run.json`          | `workspai.workspace-repair-transaction.v1`  | `contracts/workspace-intelligence/workspace-repair-transaction.v1.json` |
 | `workspace repair capabilities`      | CLI capability output                                       | `workspai.workspace-repair-capabilities.v1` | `contracts/workspace-repair-capabilities.v1.json`                       |
+| `goal <intent>`                      | `.workspai/reports/goal-pack-last-run.json`                 | `workspai.goal-pack.v1`                     | `contracts/workspace-intelligence/goal-pack.v1.json`                    |
+| `goal <intent>` / lifecycle options  | `.workspai/goals/index.json`                                | `workspai.goal-index.v1`                    | `contracts/workspace-intelligence/goal-index.v1.json`                   |
+| `goal --status/--list/... --json`    | stdout                                                      | `workspai.goal-lifecycle-result.v1`         | `contracts/workspace-intelligence/goal-lifecycle-result.v1.json`        |
 | `analyze`                            | `.workspai/reports/analyze-last-run.json`                   | `rapidkit-analyze-v1`                       | `contracts/analyze-last-run.v1.json`                                    |
 | `readiness`                          | `.workspai/reports/release-readiness-last-run.json`         | `release-readiness-v1`                      | `contracts/release-readiness.v1.json`                                   |
 | `pipeline`                           | `.workspai/reports/pipeline-last-run.json`                  | `rapidkit-pipeline-v1`                      | `contracts/pipeline-last-run.v1.json`                                   |
@@ -70,6 +79,14 @@ and model/graph freshness for the selected project.
 
 Side/cache (not gates): `.workspai/reports/doctor-workspace-cache.json` (`doctor-workspace-cache-v2`).
 
+Every Goal Pack also has an immutable-instance directory under
+`.workspai/goals/<goal-id>/` containing `goal-pack.json` and
+`agent-handoff.json`. These are portable planning/projection artifacts, not
+verification gates. Only CLI-owned verified-goal and Repair Engine evidence may
+authorize mutation or claim completion.
+The sibling `.workspai/goals/index.json` is the canonical active-goal discovery
+and lifecycle registry; consumers must not infer activity from directory order.
+
 Doctor Studio handoff:
 `doctor-remediation-plan-v2` (`contracts/doctor-remediation-plan.v2.json`) is emitted in JSON
 responses and persisted to `.workspai/reports/doctor-remediation-plan-last-run.json` by

package/docs/contracts/COMMAND_OWNERSHIP_MATRIX.md

@@ -33,6 +33,8 @@ These commands are implemented and orchestrated by Workspai CLI:
 - `infra`
 - `commands`
 - `create`
+- `goal`
+- `agent`
 - `project`
 - `shell activate`
 
@@ -57,6 +59,8 @@ These nested Commander commands are implemented and orchestrated by Workspai CLI
 - `product manifest`
 - `product manifest create`
 - `product plan`
+- `agent bootstrap`
+- `project agent-entry`
 - `project commands`
 - `project coverage`
 - `project archives`

package/docs/contracts/README.md

@@ -74,6 +74,8 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `analyze-last-run.v1.json` — analyze evidence
 - `pipeline-last-run.v1.json` — governance pipeline orchestration
 - `project-entry-capability.v1.json` — open-ended adopt/import contract for readable projects
+- `workspace-intelligence/project-agent-entry.v1.json` — portable host discovery, canonical read order, authority boundaries, and integrity for an adopted project
+- `workspace-intelligence/agent-bootstrap-receipt.v1.json` — per-session proof of workspace membership, host coverage, schema validity, freshness, live inputs, and active Goal bindings
 - `adopt-effects.v1.json` — dry-run disclosure of project metadata, conditional repository-control reconciliation, and workspace operations before adoption
 - `create-planner-capabilities.v1.json` — native, official, and existing capability lanes
 - `agent-customization-pack.v1.json` — generated instructions, prompts, skills, agents, optional hooks, MCP-ready design metadata, target matrix, and drift state for AI agent surfaces
@@ -114,6 +116,11 @@ These schemas describe durable artifacts or bounded query results. A command's
 stdout may wrap an artifact with operation metadata such as `status`,
 `outputPath`, or a structured error; that envelope follows
 `cli-operation-result.v1.json` and does not change the nested artifact contract.
+`status: "success"` means the command completed and returned its contracted
+artifact; it does not override a policy gate. For gated operations such as
+`workspace verify --strict`, the envelope `exitCode`, process exit code, and
+nested gate exit code are identical even when the artifact was produced
+successfully and the gate blocked progression.
 
 CLI commands: see [commands-reference.md](../commands-reference.md) and the
 [CLI README](../../README.md#one-intelligence-chain).

package/docs/goal-packs.md

@@ -0,0 +1,235 @@
+# Goal Packs — Plain Language to Governed Work
+
+`workspai goal` is the simple front door for an engineering outcome. It turns
+one plain-language intent into a portable, versioned Goal Pack bound to the
+current Workspace Model and proof-backed Knowledge Graph.
+
+```bash
+# Run inside an adopted project; scope defaults to that project.
+npx workspai goal "Raise test coverage to at least 85%"
+
+# Goals are not limited to coverage or another built-in metric.
+npx workspai goal "Add retry with exponential backoff for transient requests"
+npx workspai goal "Refactor the authentication boundary"
+npx workspai goal "Improve startup latency" --scope project:web
+npx workspai goal "Document the release workflow"
+
+# Plan for the whole canonical workspace.
+npx workspai goal "Prepare this workspace for release" --scope workspace
+
+# Inspect the complete machine contract without writing artifacts.
+npx workspai goal "Map the authentication architecture" --dry-run --json
+```
+
+The command plans work. It does **not** edit source, call a model, install an
+agent plugin, approve a repair, or claim that the outcome is complete.
+
+Goal intent is open-ended within the engineering workspace. The category is a
+retrieval and verification hint, not an allowlist. An objective that does not
+match the local deterministic classifier is retained as a low-confidence
+general Goal instead of being discarded; the original text remains the
+authority. Genuine compound ambiguity, missing numeric coverage targets,
+missing evidence, unsafe scope, or stale bindings still stop before mutation.
+
+## What it produces
+
+A successful plan atomically publishes four portable artifacts:
+
+| Artifact                                       | Purpose                                                                               |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `.workspai/goals/<goal-id>/goal-pack.json`     | Canonical intent, scope, evidence bindings, policy, criteria, and orchestration state |
+| `.workspai/goals/<goal-id>/agent-handoff.json` | Bounded consumer projection for `generic`, `claude`, or `codex`                       |
+| `.workspai/goals/index.json`                   | Active-goal and lifecycle discovery authority for agents and IDEs                     |
+| `.workspai/reports/goal-pack-last-run.json`    | Latest Goal Pack for IDE, CI, and automation discovery                                |
+
+Agents start from the index. They do not infer the active objective by walking
+directories or treating the newest timestamp as authority.
+
+```bash
+workspai goal --status --json
+workspai goal --list --json
+workspai goal --activate <goal-id> --json
+workspai goal --cancel <goal-id> --json
+```
+
+The files contain logical workspace/project identity and relative artifact
+paths. They do not copy the machine-local workspace root, linked-project path,
+credentials, raw model responses, or unrestricted command output.
+
+## Scope resolution
+
+- From an adopted or linked project, the default scope is that exact project.
+- From a workspace root, the default scope is all registered projects.
+- `--scope project:<name>` selects one project explicitly.
+- `--scope workspace` selects the complete canonical workspace explicitly.
+- `--workspace <path>` is available for automation that cannot rely on the
+  current directory.
+
+An unadopted directory is rejected. `goal` never silently creates or selects a
+different workspace.
+
+## Evidence and freshness
+
+Goal planning requires a persisted canonical Model and a Graph whose
+`source.hash` still matches that Model. Missing or mismatched evidence fails
+closed with a renewal command. Use `--refresh` to run the complete Workspace
+Intelligence chain before planning:
+
+```bash
+npx workspai goal "Fix the authentication regression" --refresh --json
+```
+
+The Goal Pack records both bindings and their exact hash semantics. The Model
+uses its stable structural projection; Graph and Goal artifacts use canonical
+JSON. The Graph binding also records its stable live-input fingerprint, so an
+evidence-only rerun does not make an unchanged Goal stale merely because the
+artifact timestamp changed. A Goal fingerprint is an identity key and is never
+presented as a file digest.
+
+The original source binding remains immutable. A later source state is accepted
+only when it is sealed by a Goal-bound, approved, closed CLI Repair transaction
+whose plan, proposal, checkpoint output, exact-target verification, canonical
+Model, Graph, and closure receipt all still validate. Any unlinked edit,
+post-closure edit, or unrelated workspace drift makes the Goal stale and
+requires a new Goal Pack.
+
+## Honest preflight states
+
+`ready-to-plan` means intent, scope, at least one bounded retrieval anchor, and required
+measurement capability are available. It does not mean source changed or the
+goal passed. `needs-evidence` means a measurable target is valid but its
+machine-readable producer or baseline still needs setup. A native C/C++
+project without instrumented LCOV, Cobertura, or LLVM output is therefore
+reported as `needs-evidence`, never as ready.
+
+`blocked` means the CLI cannot provide bounded proof-backed retrieval for the
+selected intent and scope. Workspai refuses to hand broad source inspection to
+an agent until Workspace Intelligence is refreshed or the intent is clarified.
+
+Only a `ready-to-plan` Goal may become the active objective automatically.
+Planning a Goal that needs confirmation or evidence records it for review but
+does not replace the current active Goal.
+
+Preflight also carries the current Workspace Intelligence status, blocked
+stages, objective-first retrieval queries, deterministic category recall, and
+bounded graph anchors. The complete user objective receives the primary anchor
+budget; generic category matches cannot crowd it out. When only structured
+category evidence is available, retrieval is reported as `partial`, not falsely
+as objective-grounded.
+
+## Relationship to verified goals
+
+The two goal surfaces have different jobs:
+
+| Surface                            | Job                                                                                                                           |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `workspai goal "<intent>"`         | Compile plain language, resolve scope, pin Model/Graph evidence, and prepare an agent handoff                                 |
+| `workspai workspace goal plan ...` | Create or resume one of the shipped deterministic success contracts: release readiness, dependency security, or test coverage |
+
+When a plain-language intent maps exactly to one of those three measurable
+contracts, the Goal Pack includes the correct `workspace goal plan` command.
+For example, a coverage intent without a percentage becomes
+`needs-confirmation`; Workspai does not invent a target.
+
+For a supported deterministic contract, the lifecycle bridge is explicit:
+
+```bash
+workspai goal --prepare <goal-id> --json
+workspai goal --verify <goal-id> --json
+```
+
+Preparation is refused while clarification or measurement evidence is
+missing. Verification is refused until a CLI verified-goal contract is linked,
+and only CLI evidence may transition the lifecycle to `verified`.
+Only the selected `activeGoalId` may enter preparation or verification. A
+completed verified goal clears the active selection. `--list` and `--cancel`
+remain available when an old Goal is stale, so operators can recover safely;
+`--status`, `--activate`, `--prepare`, and `--verify` require current bindings.
+
+The immutable Goal Pack also owns the execution-cycle budget. Every repair
+proposal is linked in the Goal index and every verification attempt is recorded
+in the verified-goal status artifact. Proposal planning and verification are
+serialized independently, refuse to exceed `executionPolicy.maxAttempts`, and
+remain bounded even when concurrent IDE or agent requests race. Consumers must
+restore both durable counters and use the greater value as the current cycle;
+they cannot reset a local retry counter. If the baseline already satisfies the
+criteria, the consumer should call the verifier immediately and avoid an
+unnecessary source change.
+
+Every other Goal is still executable through a compatible consumer, but its
+semantic outcome is not falsely presented as machine-verifiable. The consumer
+must assess the final diff or answer against the complete immutable objective,
+while the CLI independently owns scope, repair transactions, build/test/audit
+checks, canonical workspace verification, rollback, and the attempt budget.
+Such a result is evidence-reviewed; only the three exact producer contracts may
+use the lifecycle claim `verified`. Its `workspace-verify` success criterion and
+final orchestration step explicitly describe safety and evidence freshness; they
+never describe that signal as proof of an arbitrary semantic outcome.
+
+## Ownership and safety boundary
+
+```text
+User intent
+  -> CLI: resolve Model, Graph, scope, policy, and success contract
+  -> Agent: inspect bounded evidence and propose one focused source change
+  -> Human: approve the immutable repair plan
+  -> CLI Repair Engine: checkpoint, execute, reconcile, verify, keep or roll back
+```
+
+The agent handoff is a projection, not a second source of truth. Agent plugins,
+IDE chat, MCP, and future independent packages may render or transport it, but
+they cannot widen scope, grant network access, authorize mutation, mark a goal
+verified, or replace CLI evidence.
+
+Current Goal Packs use `proposal-only` mutation mode: the CLI command itself
+does not invoke a model or mutate source. A compatible IDE or agent consumer
+may execute an inspected proposal only by submitting it to the existing CLI
+Repair Engine, binding the transaction to the active Goal fingerprint, and
+calling the exact Goal verifier after the transaction closes. A closed repair,
+generic test pass, or consumer message cannot mark the Goal verified. This
+boundary is designed to remain compatible with the independent Decisions
+architecture.
+
+Goal consumers must also preserve metric integrity. The Workspai extension does
+not expose file deletion to deterministic verified Goals. Its test-coverage
+Goal may write only test-owned source, fixtures, or snapshots; a general Goal
+may create, replace, or delete only inspected source through an approved,
+rollback-protected CLI Repair transaction. This prevents a model from reaching
+a numeric coverage target by shrinking or redefining the measured surface
+without crippling legitimate goals such as removing a deprecated module.
+
+## Options
+
+```text
+--workspace <path>      Explicit canonical workspace
+--scope <scope>         workspace or project:<name>
+--for-agent <consumer>  generic, claude, or codex (default: generic)
+--max-attempts <count>  Bounded execution-cycle budget, 1–25 (default: 5)
+--refresh               Refresh Workspace Intelligence before planning
+--dry-run               Validate and preview without writes
+--status [goal-id]       Validate active or named Goal bindings
+--list                   List registered Goal Packs
+--activate <goal-id>     Select the active agent objective
+--cancel <goal-id>       Cancel without deleting evidence
+--prepare <goal-id>      Link a deterministic verification contract
+--verify <goal-id>       Run CLI-owned verification
+--no-run                 Read verification evidence without executing producers
+--json                  Machine-readable result
+```
+
+Choose exactly one lifecycle option. Lifecycle options cannot be combined with
+an intent, `--scope`, `--refresh`, or `--dry-run`; `--no-run` applies only to
+`--verify`. Invalid combinations fail before workspace resolution or writes.
+
+Schemas:
+
+- [`goal-pack.v1.json`](../contracts/workspace-intelligence/goal-pack.v1.json)
+- [`goal-agent-handoff.v1.json`](../contracts/workspace-intelligence/goal-agent-handoff.v1.json)
+- [`goal-plan-result.v1.json`](../contracts/workspace-intelligence/goal-plan-result.v1.json)
+- [`goal-index.v1.json`](../contracts/workspace-intelligence/goal-index.v1.json)
+- [`goal-lifecycle-result.v1.json`](../contracts/workspace-intelligence/goal-lifecycle-result.v1.json)
+
+Every lifecycle operation uses the same `workspai.goal-lifecycle-result.v1`
+success envelope. Failures use the shared CLI operation result with an
+operation-specific code such as `goal.prepare.failed`; consumers never parse
+terminal prose or infer a lifecycle state from directories.