workspai 0.65.0 → 0.67.0

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -25,13 +25,15 @@ exclude the canonical marker.
 These paths are relative to each registered project root, not the workspace
 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     |
+| 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/reports/project-knowledge-graph-reference.json` | Workspace Model publication                                                       | `project-knowledge-graph-reference.v1` | Small portable reference whose projection hash is verified against the canonical graph |
+| `.workspai/PROJECT-GROUNDING.md`                           | Project lens reconciliation                                                       | Markdown                               | Portable human/agent entry guide with path-free workspace references                   |
+| `.agents/skills/workspai-*/SKILL.md`                       | Project lens reconciliation                                                       | Agent Skill                            | Project-native wrappers that resolve canonical workspace playbooks without local paths |
+| `AGENTS.md` managed section                                | Project lens reconciliation in `managed` mode                                     | Managed Markdown block                 | Preserves user content and routes compatible agents to project/workspace evidence      |
 
 The project link is validated against the canonical workspace contract and a
 SHA-256 binding over workspace identity, project identity, portable relative
@@ -40,13 +42,20 @@ absolute paths before writing. `managed`, `local`, and `off` grounding modes
 control portable project surfaces and converge by removing stale managed
 sections and ignore rules during transitions; they never make the
 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.
+includes compact topology, representative API/deployment/test surfaces,
+blockers, portable proof locators, and model/graph freshness for the selected
+project. Complete graph evidence is retrieved through bounded search instead
+of duplicated into every 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.
+Its top-level status covers agent grounding only; project-environment and
+release readiness are emitted as separate dimensions so consumers cannot treat
+successful grounding as release approval. The receipt exposes distinct project
+reference and workspace graph paths and blocks when the project reference hash
+is not the exact current canonical projection.
 
 ## Naming conventions
 
@@ -123,10 +132,12 @@ Entries beginning with `reports/` are relative to `.workspai/`; paths such as
 | Command                                         | Artifact                                                                                                                     | Schema                                 | Contract file                                                                |
 | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
 | `workspace model --write`                       | `workspace-model.json`                                                                                                       | `workspace-model.v1`                   | `contracts/workspace-intelligence/workspace-model.v1.json`                   |
-| `workspace model --write`                       | `workspace-knowledge-graph.json`                                                                                             | `workspace-knowledge-graph.v1`         | `contracts/workspace-intelligence/workspace-knowledge-graph.v1.json`         |
+| `workspace model --write`                       | `workspace-knowledge-graph.json` (canonical workspace aggregate)                                                             | `workspace-knowledge-graph.v1`         | `contracts/workspace-intelligence/workspace-knowledge-graph.v1.json`         |
+| `workspace model --write`                       | Project-local `.workspai/reports/project-knowledge-graph-reference.json`                                                     | `project-knowledge-graph-reference.v1` | `contracts/workspace-intelligence/project-knowledge-graph-reference.v1.json` |
 | `workspace snapshot`                            | `workspace-model-snapshot.json`                                                                                              | `workspace-model-snapshot.v1`          | `contracts/workspace-intelligence/workspace-model-snapshot.v1.json`          |
 | `workspace diff`                                | `workspace-model-diff-last-run.json`                                                                                         | `workspace-model-diff.v1`              | `contracts/workspace-intelligence/workspace-model-diff.v1.json`              |
 | `workspace impact --from <diff>`                | `workspace-impact-last-run.json`                                                                                             | `workspace-impact.v1`                  | `contracts/workspace-intelligence/workspace-impact.v1.json`                  |
+| `workspace graph benchmark-suite --write`       | `workspace-intelligence-benchmark-last-run.json`                                                                             | `workspace-intelligence-benchmark.v1`  | `contracts/workspace-intelligence/workspace-intelligence-benchmark.v1.json`  |
 | `analyze --json`                                | `analyze-last-run.json`                                                                                                      | `rapidkit-analyze-v1`                  | `contracts/analyze-last-run.v1.json`                                         |
 | `workspace verify`                              | `workspace-verify-last-run.json`                                                                                             | `workspace-verify.v1`                  | `contracts/workspace-intelligence/workspace-verify.v1.json`                  |
 | `workspace context --write`                     | `workspace-context-agent.json`                                                                                               | `workspace-context.v1`                 | `contracts/workspace-intelligence/workspace-context.v1.json`                 |
@@ -152,10 +163,15 @@ status/exit coherence, hard-failure skip propagation, and the aggregate verdict.
 See [Unified Workspace Intelligence Runner](../workspace-intelligence-runner.md)
 for the normative user and integration semantics.
 
-`workspace-model.json` and `workspace-knowledge-graph.json` are published under
-one workspace lock as a rollback-capable artifact transaction. Individual file
-replacement is atomic, and a partial set failure restores both preimages. The
-model is canonical; the graph is derived and cannot mutate it during the run.
+`workspace-model.json`, the canonical workspace `workspace-knowledge-graph.json`,
+and each registered project's compact
+`.workspai/reports/project-knowledge-graph-reference.json` are published under
+one workspace lock as a rollback-capable multi-root artifact transaction.
+Individual replacement is atomic, and a partial set failure restores every
+preimage. Each reference integrity-binds the exact project projection and points
+to the canonical aggregate through a portable `workspace:` URI, avoiding graph
+duplication in every linked repository. The model remains canonical and the
+graph remains derived.
 The graph contract fixes `source.kind` to `workspace-model`,
 `source.artifact` to `.workspai/reports/workspace-model.json`, and `source.hash`
 to the model's stable structural SHA-256. Current-state consumers must reject a
@@ -397,9 +413,10 @@ Separate from the on-disk artifacts above, Workspai CLI emits a structured
 **NDJSON log stream on stderr** when `--log-format json` (or `RAPIDKIT_LOG_FORMAT=json`)
 is set. This is the deterministic progress/outcome channel for IDEs and CI.
 
-| Stream                  | Schema version     | Contract file                     | Doc                                                  |
-| ----------------------- | ------------------ | --------------------------------- | ---------------------------------------------------- |
-| CLI log events (stderr) | `cli-log-event-v1` | `contracts/cli-log-event.v1.json` | [CLI_LOG_EVENT_STREAM.md](./CLI_LOG_EVENT_STREAM.md) |
+| Stream                                      | Schema version                | Contract file                                | Doc                                                     |
+| ------------------------------------------- | ----------------------------- | -------------------------------------------- | ------------------------------------------------------- |
+| CLI log events (stderr)                     | `cli-log-event-v1`            | `contracts/cli-log-event.v1.json`            | [CLI_LOG_EVENT_STREAM.md](./CLI_LOG_EVENT_STREAM.md)    |
+| Live activity events (machine-local NDJSON) | `workspace-activity-event.v1` | `contracts/workspace-activity-event.v1.json` | [Workspai Live Activity](../workspace-live-activity.md) |
 
 **Channel rule:** command **results** go to stdout (`--json`); **progress/lifecycle**
 events go to stderr (`--log-format json`). The two never mix.
@@ -431,8 +448,9 @@ canonical file. Legacy files remain readable during the compatibility window.
 2. **Workspace Intelligence chain:** run `workspace intelligence run --for-agent generic --strict --json` to preserve Model → Diff → Impact → Doctor + Contract Verify + Analyze → Readiness → Verify → Context → Agent Sync → Explain. `pipeline` is the broader governance/release orchestrator and `autopilot` is a separate release surface; neither redefines the canonical chain. Use `pipeline-last-run.json` only for the pipeline orchestration summary.
 3. **Do not** use `workspace.json.projects` (removed in schema 1.0).
 4. Prefer `schemaVersion` constants in each artifact; legacy `v1` on readiness is accepted when reading old reports.
-5. **Agent retrieval:** start with `AGENTS.md` and `.workspai/reports/INDEX.json`, then use `workspace graph search <query> --limit <n> --json` or MCP `searchWorkspaceGraph` for question-sized facts. Use `--scope project:<name>` when the task has one registered project boundary, inspect `budget.omitted` before assuming the result is complete, and follow returned proof paths to source evidence. Read the full context, model, or graph only when the bounded result is insufficient.
+5. **Agent retrieval:** inside an adopted project, start with `.workspai/agent-entry.v1.json` (or the host projection that routes to it), then read `.workspai/reports/project-context-agent.json`; its `intelligence.projection` states exactly how much representative graph data was bounded. At workspace scope, start with `AGENTS.md` and `.workspai/reports/INDEX.json`. In either scope, use `workspace graph search <query> --limit <n> --json` or MCP `searchWorkspaceGraph` for question-sized facts. Use `--scope project:<name>` for one registered project, inspect `budget.omitted` before assuming completeness, and follow proof paths to source evidence. Read the full context, model, or graph only when the bounded result is insufficient.
 6. **Agent customization state:** use `.workspai/reports/agent-customization-pack.json` to inspect generated surfaces and drift; regenerate with `workspace agent-sync --write --refresh-context --preset enterprise`.
+7. **Operational Skill selection:** use `.workspai/reports/workspace-skills-index.json`. Its `selection.decisions` distinguishes evidence-backed generated Skills from suppressed candidates and records scoped projects and supporting signals. A missing specialized Skill means the current canonical evidence did not prove that capability; it is not permission to assume one.
 
 ## Agent customization files (repo hooks)
 
@@ -443,32 +461,34 @@ failure, all touched files are restored; an interrupted transaction is recovered
 before the next agent-sync. `agent-customization-pack.json` is written last and
 serves as the completed-generation marker.
 
-| Path                                                                    | Consumer                                                       |
-| ----------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `AGENTS.md`                                                             | Copilot, Cursor, Claude Code, Codex, Grok (open standard)      |
-| `.github/copilot-instructions.md`                                       | GitHub Copilot / VS Code Chat                                  |
-| `.github/instructions/workspai-workspace.instructions.md`               | Copilot workspace scope and command discipline                 |
-| `.github/instructions/workspai-evidence.instructions.md`                | Copilot scoped `.workspai/**` and compatibility evidence rules |
-| `.github/prompts/workspai-diagnose.prompt.md`                           | Copilot prompt library                                         |
-| `.github/prompts/workspai-repair.prompt.md`                             | Copilot repair workflow prompt                                 |
-| `.github/prompts/workspai-release-readiness.prompt.md`                  | Copilot release readiness workflow prompt                      |
-| `.github/prompts/workspai-project-onboard.prompt.md`                    | Copilot project onboarding workflow prompt                     |
-| `.github/prompts/workspai-adopt-project.prompt.md`                      | Copilot adopt/import workflow prompt                           |
-| `.github/skills/workspai-grounding/SKILL.md`                            | Copilot skills                                                 |
-| `.github/skills/workspai-workspace-intelligence/SKILL.md`               | Enterprise Workspace Intelligence skill                        |
-| `.github/skills/workspai-workspace-intelligence/resources/mcp-tools.md` | MCP tool and evidence-retrieval reference                      |
-| `.github/agents/workspai-advisor.agent.md`                              | Read-only workspace advisor agent                              |
-| `.github/agents/workspai-repair.agent.md`                               | Blocker repair agent                                           |
-| `.github/agents/workspai-release.agent.md`                              | Release safety agent                                           |
-| `.github/agents/workspai-project-onboarder.agent.md`                    | Project onboarding agent                                       |
-| `.cursor/rules/workspai-grounding.mdc`                                  | Cursor always-on rule                                          |
-| `CLAUDE.md`                                                             | Claude Code (imports `@AGENTS.md`)                             |
-| `.claude/rules/workspai-evidence.md`                                    | Claude Code scoped evidence rule                               |
-| `.claude/rules/rapidkit-evidence.md`                                    | Legacy compatibility alias pointing to the canonical rule      |
-| `.workspai/AGENT-GROUNDING.md`                                          | Tool-agnostic operator doc                                     |
-| `.workspai/reports/agent-customization-pack.json`                       | Versioned output inventory, target matrix, drift state         |
-| `.workspai/reports/workspai-mcp-design.json`                            | Read-mostly MCP-ready design manifest                          |
-| `.vscode/workspai-agent-hooks.json`                                     | Optional advisory VS Code agent hooks (`--experimental-hooks`) |
+| Path                                                                    | Consumer                                                                                               |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `AGENTS.md`                                                             | Copilot, Cursor, Claude Code, Codex, Grok (open standard)                                              |
+| `.agents/skills/workspai-grounding/SKILL.md`                            | Provider-neutral Agent Skills grounding                                                                |
+| `.agents/skills/workspai-*/SKILL.md`                                    | Generated workspace operational skills                                                                 |
+| `.github/copilot-instructions.md`                                       | GitHub Copilot / VS Code Chat                                                                          |
+| `.github/instructions/workspai-workspace.instructions.md`               | Copilot workspace scope and command discipline                                                         |
+| `.github/instructions/workspai-evidence.instructions.md`                | Copilot scoped `.workspai/**` and compatibility evidence rules                                         |
+| `.github/prompts/workspai-diagnose.prompt.md`                           | Copilot prompt library                                                                                 |
+| `.github/prompts/workspai-repair.prompt.md`                             | Copilot repair workflow prompt                                                                         |
+| `.github/prompts/workspai-release-readiness.prompt.md`                  | Copilot release readiness workflow prompt                                                              |
+| `.github/prompts/workspai-project-onboard.prompt.md`                    | Copilot project onboarding workflow prompt                                                             |
+| `.github/prompts/workspai-adopt-project.prompt.md`                      | Copilot adopt/import workflow prompt                                                                   |
+| `.github/skills/workspai-grounding/SKILL.md`                            | Copilot skills                                                                                         |
+| `.github/skills/workspai-workspace-intelligence/SKILL.md`               | Enterprise Workspace Intelligence skill                                                                |
+| `.github/skills/workspai-workspace-intelligence/resources/mcp-tools.md` | MCP tool and evidence-retrieval reference                                                              |
+| `.github/agents/workspai-advisor.agent.md`                              | Read-only workspace advisor agent                                                                      |
+| `.github/agents/workspai-repair.agent.md`                               | Blocker repair agent                                                                                   |
+| `.github/agents/workspai-release.agent.md`                              | Release safety agent                                                                                   |
+| `.github/agents/workspai-project-onboarder.agent.md`                    | Project onboarding agent                                                                               |
+| `.cursor/rules/workspai-grounding.mdc`                                  | Cursor always-on rule                                                                                  |
+| `CLAUDE.md`                                                             | Claude Code (imports `@AGENTS.md`)                                                                     |
+| `.claude/rules/workspai-evidence.md`                                    | Claude Code scoped evidence rule                                                                       |
+| `.claude/rules/rapidkit-evidence.md`                                    | Legacy compatibility alias pointing to the canonical rule                                              |
+| `.workspai/AGENT-GROUNDING.md`                                          | Tool-agnostic operator doc                                                                             |
+| `.workspai/reports/agent-customization-pack.json`                       | Versioned output inventory, target matrix, drift state                                                 |
+| `.workspai/reports/workspai-mcp-design.json`                            | Implemented read-mostly MCP runtime manifest, served/planned tool inventory, and protocol capabilities |
+| `.vscode/workspai-agent-hooks.json`                                     | Optional advisory VS Code agent hooks (`--experimental-hooks`)                                         |
 
 Some `rapidkit-*` prompt, skill, Cursor, MCP-design, and hook paths remain available for older consumers during the rebrand window. New consumers should use the `workspai-*` paths first.
 

package/docs/contracts/COMMAND_OWNERSHIP_MATRIX.md

@@ -36,6 +36,7 @@ These commands are implemented and orchestrated by Workspai CLI:
 - `goal`
 - `agent`
 - `project`
+- `live`
 - `shell activate`
 
 Reason: workspace-level policy, registry, and platform orchestration live in npm wrapper.

package/docs/contracts/NAMING_AND_COEXISTENCE.md

@@ -4,19 +4,19 @@ Rules for **operational intelligence** artifacts so npm CLI, VS Code extension,
 
 ## Canonical vs generated surfaces
 
-| Layer | Canonical (workspace-native) | Generated (agent-sync) |
-| ----- | ---------------------------- | ---------------------- |
-| Operational playbooks | `.workspai/skills/{skillId}.md` | Legacy `.rapidkit/skills/{legacySkillId}.md` read fallback |
-| Skills index | `.workspai/reports/workspace-skills-index.json` | — |
-| Copilot skill umbrella | `.github/skills/workspai-workspace-intelligence/SKILL.md` | `.github/skills/rapidkit-workspace-intelligence/SKILL.md` legacy consumer surface |
-| Explain report | `.workspai/reports/workspace-explain-last-run.json` | — |
-| Action / repair feedback | `.workspai/reports/workspace-intelligence-history.json` (`kind: agent-action`, `doctor-fix`) | — |
+| Layer                    | Canonical (workspace-native)                                                                 | Generated (agent-sync)                                                            |
+| ------------------------ | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Operational playbooks    | `.workspai/skills/{skillId}.md`                                                              | Legacy `.rapidkit/skills/{legacySkillId}.md` read fallback                        |
+| Skills index             | `.workspai/reports/workspace-skills-index.json`                                              | —                                                                                 |
+| Copilot skill umbrella   | `.github/skills/workspai-workspace-intelligence/SKILL.md`                                    | `.github/skills/rapidkit-workspace-intelligence/SKILL.md` legacy consumer surface |
+| Explain report           | `.workspai/reports/workspace-explain-last-run.json`                                          | —                                                                                 |
+| Action / repair feedback | `.workspai/reports/workspace-intelligence-history.json` (`kind: agent-action`, `doctor-fix`) | —                                                                                 |
 
-**Rule:** Never add a standalone `workspace skills generate` command. Operational skills are produced only by `workspace agent-sync --write` (extend the Agent Customization Pack).
+**Rule:** Never add a standalone `workspace skills generate` command. Operational skills are produced only by `workspace agent-sync --write` (extend the Agent Customization Pack). Templates are candidates, not guaranteed output: agent-sync materializes a candidate only when the canonical model, graph, contract, or command surface proves it applies. The skills index records generated and suppressed decisions with their evidence signals.
 
 ## Skill identifiers
 
-Built-in operational skill ids use the `workspai-*` prefix:
+Built-in operational skill candidates use the `workspai-*` prefix:
 
 - `workspai-diagnose-api-failure`
 - `workspai-release-readiness`
@@ -27,17 +27,19 @@ Built-in operational skill ids use the `workspai-*` prefix:
 Paths are derived from id via `operationalSkillPath()` in `src/contracts/workspace-artifact-paths.ts`.
 Legacy `rapidkit-*` skill and prompt paths may remain for older consumers during the rebrand window; new consumers should read the `workspai-*` paths first.
 
+`workspai-release-readiness` is workspace-applicable. API diagnosis, schema migration, dependency upgrade, and contract rename are emitted only for projects with matching evidence. Runtime, test, delivery, and polyglot skills are derived dynamically. Every emitted skill states why it exists, its scoped projects, observed signals, registered lifecycle boundary, and safe verification commands. Absence of evidence suppresses a skill rather than presenting a generic playbook as a detected capability.
+
 ## Command coexistence
 
-| User intent | Command | Notes |
-| ----------- | ------- | ----- |
-| Project / release / blocker narrative | `workspace explain …` | Primary explain surface |
-| Shorthand alias | `workspace why …` | Same parser as `explain` |
-| Diff → blast radius → gates | `workspace trace --from <diff>` | Slice of explain (`kind: trace`) |
-| Graph node centrality | `workspace graph explain <project>` | Graph-topology slice; see **Graph explain coexistence** below |
-| Record agent outcome | `workspace feedback record --json` | Appends `kind: agent-action` to history, no separate feedback file |
-| Record Doctor repair outcome | `doctor workspace|project --fix --json` | Writes `doctor-fix-result-last-run.json` and appends `kind: doctor-fix` to history |
-| MCP read bridge | `workspace mcp serve` | Read-mostly stdio JSON-RPC; maps Phase 4 explain + skills tools |
+| User intent                           | Command                             | Notes                                                              |
+| ------------------------------------- | ----------------------------------- | ------------------------------------------------------------------ |
+| Project / release / blocker narrative | `workspace explain …`               | Primary explain surface                                            |
+| Shorthand alias                       | `workspace why …`                   | Same parser as `explain`                                           |
+| Diff → blast radius → gates           | `workspace trace --from <diff>`     | Slice of explain (`kind: trace`)                                   |
+| Graph node centrality                 | `workspace graph explain <project>` | Graph-topology slice; see **Graph explain coexistence** below      |
+| Record agent outcome                  | `workspace feedback record --json`  | Appends `kind: agent-action` to history, no separate feedback file |
+| Record Doctor repair outcome          | `doctor workspace                   | project --fix --json`                                              | Writes `doctor-fix-result-last-run.json` and appends `kind: doctor-fix` to history |
+| MCP read bridge                       | `workspace mcp serve`               | Read-mostly stdio JSON-RPC; maps Phase 4 explain + skills tools    |
 
 ## Graph explain coexistence (4.11)
 

package/docs/contracts/README.md

@@ -28,8 +28,8 @@ Canonical JSON lives in **`../../contracts/`** (CLI package root, published in t
 | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
 | `npm run generate:contracts`                | Regenerate runtime surface, create planner, agent customization pack, import-stack parity, module-layout, infra-stack |
 | `npm run check:generated-contracts`         | Verify committed JSON matches generators                                                                              |
-| `npm run sync:shared-contracts`             | Generate canonical JSON and sync root plus locally available consumer mirrors                                          |
-| `npm run sync:parity-snapshot`              | Compatibility alias for canonical and consumer mirror synchronization                                                  |
+| `npm run sync:shared-contracts`             | Generate canonical JSON and sync root plus locally available consumer mirrors                                         |
+| `npm run sync:parity-snapshot`              | Compatibility alias for canonical and consumer mirror synchronization                                                 |
 | `npm run check:parity-snapshot`             | Verify mirrors match canonical                                                                                        |
 | `npm run contracts:prepush`                 | Sync local consumers and require generated canonical CLI mirrors to be committed                                      |
 | `npm run validate:contracts`                | Shared-contract checks and focused contract tests                                                                     |
@@ -88,7 +88,7 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `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
+- `workspace-intelligence/agent-bootstrap-receipt.v1.json` — per-session proof of workspace membership, host coverage, schema validity, freshness, live inputs, active Goal bindings, and explicitly separated grounding/environment/release readiness
 - `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
@@ -96,6 +96,9 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `project-archive.v1.json`, `workspace-snapshot.v1.json`, and `workspace-snapshot.v2.json` — recoverable lifecycle records
 - `infra-plan.v1.json`, `private-product-manifest.v1.json`, and `product-factory-plan.v1.json` — infrastructure and product planning payloads
 - `workspace-model-cache.v1.json`, `workspace-watch-event.v1.json`, `doctor-project-scan.v2.json`, and `doctor-workspace-cache.v2.json` — cache/watch/diagnostic support contracts
+- `workspace-activity-event.v1.json` — local-first run/block/operation/touch stream consumed by `workspai live`; observational only, never Evidence/Decision authority
+- `workspace-activity-monitor-snapshot.v1.json` and `workspace-activity-monitor-fleet.v1.json` — deterministic local and bounded fleet projections
+- `workspace-activity-board.v1.json` — renderer-neutral bounded Live projection for terminal, SVG, IDE and web consumers
 
 Workspace intelligence (`../../contracts/workspace-intelligence/`):
 
@@ -107,6 +110,7 @@ Workspace intelligence (`../../contracts/workspace-intelligence/`):
 - `workspace-knowledge-graph-change-overlay.v1.json` — proposed/change-set facts and relations without mutating the base graph
 - `workspace-knowledge-search.v1.json` — bounded ranked retrieval for CLI, MCP, IDE, and agent consumers
 - `workspace-graph-token-efficiency.v1.json` — reproducible corpus-versus-retrieval payload measurement
+- `workspace-intelligence-benchmark.v1.json` — fixed multi-scenario retrieval benchmark with separately classified measured evaluation evidence
 - `model-usage-event.v1.json` — privacy-bounded model, tool, milestone, and verified-outcome events with explicit measurement provenance
 - `workspace-intelligence-evaluation.v1.json` — live/final token, cost, latency, activity, and verified-outcome evaluation
 - `workspace-intelligence-evaluation-comparison.v1.json` — task-aligned comparison of two completed evaluation strategies

package/docs/real-world-qualification.md

@@ -66,6 +66,17 @@ npm run test:real-world:enterprise -- \
   --report "$QUALIFICATION_ROOT/enterprise-command-surface.json"
 ```
 
+The enterprise harness resolves a real project from the graph, workspace
+contract, model, or imported-project registry. It never assumes a fixture
+project name. Snapshot names are unique per run, so the harness can be repeated
+against the same isolated workspace without creating a false lifecycle failure.
+Graph queries may target either managed or linked projects. Project archive and
+delete dry runs use a separate lifecycle target and are emitted only for a
+managed project physically contained by the workspace. When a workspace has
+only linked external projects, the report records
+`coverage.projectLifecycle: skipped-no-managed-project`; it does not misreport
+that safety boundary as a command failure.
+
 ## Safety and interpretation
 
 - Reference repositories are cloned locally with `git clone --shared`; no
@@ -82,13 +93,18 @@ npm run test:real-world:enterprise -- \
 - Dependency installation, project build/test/start/init, infrastructure
   mutation, publication, and model network calls are not permitted.
 - Agent customization and destructive project operations are dry-run only.
+- Runtime candidates describe observed nested composition; the authoritative
+  project runtime controls repair-adapter assertions. An aggregate boundary with
+  runtime `unknown` therefore follows the governed manual-repair path instead of
+  promoting its first nested runtime candidate.
 - Goal qualification publishes one system-understanding Goal inside the
   isolated test workspace, validates its lifecycle binding, and previews
   runtime-specific coverage and release-readiness goals without executing
   project tests or mutating project source.
-- Exit codes `1` and `2` may be valid domain outcomes when their documented JSON
-  contracts parse successfully; unexpected process, timeout, buffer, or schema
-  failures fail qualification.
+- Exit codes `1` and `2` are accepted only for commands whose contract explicitly
+  permits a governed block and only when the JSON payload contains a recognized
+  blocked/not-ready outcome. Graph lookup, project lifecycle, process, timeout,
+  buffer, malformed JSON, and schema failures fail qualification.
 - A real repository warning remains evidence, not a CLI defect. Fix the CLI only
   when detection, classification, contract, portability, or command semantics
   are wrong.

package/docs/workspace-intelligence-benchmark.md

@@ -0,0 +1,82 @@
+# Workspace Intelligence Benchmark
+
+Workspai exposes two deliberately separate measurement lanes:
+
+1. deterministic retrieval-payload estimates from the Workspace Knowledge Graph;
+2. observed model/tool usage and verified outcomes recorded by `workspace eval`.
+
+They are combined in one report for presentation, but their provenance is never
+collapsed into one unsupported “tokens saved” claim.
+
+## Run the fixed suite
+
+```bash
+npx workspai workspace graph benchmark-suite agent-core.v1 --json
+npx workspai workspace graph benchmark-suite agent-core.v1 --write --json
+```
+
+The `agent-core.v1` suite runs five stable scenario categories:
+
+- architecture and runtime discovery;
+- dependency and ownership discovery;
+- interface and contract discovery;
+- change-safety and verification discovery;
+- build and delivery discovery.
+
+For each category, Workspai selects the first evidence-backed entity from a
+published kind priority (then stable entity ID), records that target ID/kind,
+and queries its unique real label (or stable identity key when labels collide).
+The scenario passes only when that exact target entity is retrieved. This keeps
+the benchmark applicable to arbitrary architectures without hiding a
+repository-specific query or pretending that an irrelevant fixed phrase
+measures retrieval quality.
+
+The suite is offline, deterministic, bounded, and repository-neutral. It reads
+the proof-indexed source corpus once and applies the same retrieval limit to
+every scenario. The report contains per-scenario results plus median and p95
+retrieval sizes. Empty scenarios remain visible as `empty`; they are never
+silently removed from the denominator.
+
+With `--write`, the artifact is:
+
+```text
+.workspai/reports/workspace-intelligence-benchmark-last-run.json
+contracts/workspace-intelligence/workspace-intelligence-benchmark.v1.json
+```
+
+## Add measured model evidence
+
+Finalize a task evaluation first:
+
+```bash
+npx workspai workspace eval init repair-readiness workspace-intelligence --json
+# record provider/tool/outcome events through workspace eval record --json
+npx workspai workspace eval report --json
+npx workspai workspace graph benchmark-suite agent-core.v1 --write --json
+```
+
+The benchmark classifies evaluation provenance as `measured`, `mixed`,
+`estimated`, or `unavailable`. Provider-reported and tokenizer-counted calls are
+measured. Estimated and unavailable calls remain explicitly labelled.
+
+For a baseline comparison:
+
+```bash
+npx workspai workspace graph benchmark-suite agent-core.v1 \
+  --from .workspai/reports/baseline-evaluation.json \
+  --write --json
+```
+
+`trustedMeasuredReductionPercent` is non-null only when:
+
+- current and baseline task IDs match;
+- both outcomes are verified and comparable;
+- every model call in both runs is provider-reported or tokenizer-counted.
+
+## Claim boundary
+
+The graph lane estimates JSON retrieval payload size using `characters / 4`
+against readable proof-source text. It does not prove equivalent answer quality,
+model billing savings, or task completion. The evaluation lane can report real
+usage only to the precision supplied by its recorded source. Verified task
+success remains a separate required outcome signal.