workspai 0.45.0 → 0.47.0

package/docs/examples/ci-agent-grounding.yml

@@ -10,6 +10,7 @@ name: Workspai Agent Grounding
 on:
   pull_request:
     paths:
+      - '.workspai/**'
       - '.rapidkit/**'
       - 'AGENTS.md'
       - 'CLAUDE.md'
@@ -34,17 +35,21 @@ jobs:
       - name: Install Workspai CLI
         run: npm install --no-save workspai
 
-      - name: Run governance pipeline
-        run: npx workspai pipeline --json --strict
+      - name: Run canonical Workspace Intelligence chain
+        # Exit 1 = hard execution failure; exit 2 = completed but evidence-blocked.
+        # Continue here only so the durable run report and blocker evidence can
+        # always be uploaded; the final step below still fails either outcome.
+        run: npx workspai workspace intelligence run --for-agent codex --strict --json
+        continue-on-error: true
+        id: intelligence
+
+      - name: Run separate governance pipeline
+        run: npx workspai pipeline --json --strict --no-agent-sync
         continue-on-error: true
         id: pipeline
 
-      - name: Sync and verify agent grounding
-        run: |
-          npx workspai workspace agent-sync --write --refresh-context --strict --json --preset enterprise
-          node ./node_modules/workspai/scripts/check-agent-customization-drift.mjs --workspace .
-        env:
-          RAPIDKIT_NO_AGENT_SYNC: '0'
+      - name: Verify agent grounding drift
+        run: node ./node_modules/workspai/scripts/check-agent-customization-drift.mjs --workspace .
 
       - name: Upload agent grounding artifacts
         if: always()
@@ -54,12 +59,13 @@ jobs:
           path: |
             .workspai/reports/INDEX.json
             .workspai/reports/workspace-context-agent.json
+            .workspai/reports/workspace-intelligence-run-last-run.json
             .workspai/reports/agent-customization-pack.json
             .workspai/reports/workspai-mcp-design.json
             .workspai/reports/pipeline-last-run.json
             AGENTS.md
           if-no-files-found: ignore
 
-      - name: Fail if pipeline blocked
-        if: steps.pipeline.outcome == 'failure'
+      - name: Fail if canonical chain or pipeline blocked
+        if: steps.intelligence.outcome == 'failure' || steps.pipeline.outcome == 'failure'
         run: exit 1

package/docs/from-code-to-shared-understanding.md

@@ -1,45 +1,76 @@
 # From Code to Shared Understanding
 
-How Workspai transforms projects and repositories into workspace intelligence for developers, CI, and AI agents.
-
-This Mermaid diagram is kept in the internal documentation because GitHub renders it correctly. The main npm README uses a PNG version of the same diagram so it remains visible on npm package pages.
+Workspai gives everyone the same understanding of your software, without asking
+you to replace your frameworks or move existing source code.
 
 ```mermaid
 flowchart TB
+    Code["Your projects and repositories"]
+
+    Routes["Create a project<br/>Adopt it in place<br/>or Import a repository"]
+
+    Workspace["Workspai builds one model of<br/>projects, dependencies, rules, and commands"]
+
+    Change["What changed?<br/>What is affected?<br/>Is the evidence ready?"]
+
+    Outputs["Context, impact, verification,<br/>explanations, and release evidence"]
+
+    Code --> Routes
+    Routes --> Workspace
+    Workspace --> Change
+    Change --> Outputs
+
+    Outputs --> Developers["Developers"]
+    Outputs --> CI["CI and releases"]
+    Outputs --> IDEs["IDEs"]
+    Outputs --> Agents["AI agents"]
+    Outputs --> MCP["MCP clients"]
+```
+
+## What This Means
+
+1. **Connect your software.** Create something new, adopt an existing project
+   without moving it, or import a repository.
+2. **Understand the workspace.** Workspai builds one model of the projects and
+   how they relate.
+3. **Understand change and verify it.** Workspai shows affected areas and checks
+   the evidence needed for a safe decision.
+4. **Share the result.** Developers, CI, IDEs, AI agents, and MCP clients consume
+   the same workspace truth instead of building separate assumptions. The
+   current CLI exposes a read-mostly `workspace mcp serve` bridge; a dedicated
+   `packages/mcp` boundary is planned.
 
-    Code["Code & Repositories"]
-    Projects["Projects"]
-    Workspace["Workspace"]
-
-    Code --> Projects
-    Projects --> Workspace
-
-    subgraph Intelligence["Workspace Intelligence"]
-        Model["Workspace Model"]
-        Context["Agent Context"]
-        Impact["Impact Analysis"]
-        Verify["Verification"]
-        Evidence["Evidence & Gates"]
-    end
-
-    Workspace --> Model
-    Workspace --> Context
-    Workspace --> Impact
-    Workspace --> Verify
-    Workspace --> Evidence
-
-    Model --> Dev["Developers"]
-    Model --> CI["CI"]
-    Model --> Agents["AI Agents"]
-
-    Context --> Agents
-
-    Impact --> Dev
-    Impact --> CI
-
-    Verify --> CI
-    Verify --> Agents
-    Evidence --> Dev
-    Evidence --> CI
-    Evidence --> Agents
+This is the user-facing view. The implementation uses a versioned chain of
+model, change, evidence, verification, context, grounding, and explanation
+steps. Contributors and integrations can inspect the complete contracts:
+
+- [`workspace-intelligence-chain.v1.json`](../contracts/workspace-intelligence-chain.v1.json)
+- [`workspace-intelligence-architecture.v1.json`](../contracts/workspace-intelligence-architecture.v1.json)
+
+The unified runner also has a deterministic execution envelope: `sync` runs
+before Model and baseline resolution runs after Model/before Diff. These appear
+as two `preflight` entries, not as extra chain stages. The 11 canonical stages,
+baseline lifecycle, exit codes, and failure propagation are specified in
+[Unified Workspace Intelligence Runner](./workspace-intelligence-runner.md).
+
+The npm README uses a PNG rendering because npm package pages do not reliably
+render Mermaid. When this source changes, regenerate
+`From Code to Shared Understanding.png` before publishing.
+
+## Execute the Contract
+
+Run the complete canonical chain in its versioned order:
+
+```bash
+npx workspai workspace intelligence run --for-agent codex --json
 ```
+
+For enterprise CI and release enforcement, add `--strict`. A warning or
+needs-attention verdict then produces a blocked report and exit code `2`:
+
+```bash
+npx workspai workspace intelligence run --for-agent codex --strict --json
+```
+
+`pipeline` is the broader governance/release orchestrator. It does not replace
+or reorder the canonical Workspace Intelligence chain.

package/docs/graph-benchmark-methodology.md

@@ -0,0 +1,121 @@
+# Graph Retrieval Benchmark Methodology
+
+This document defines what Workspai measures when it reports graph retrieval
+payload reduction, how to reproduce a result, and what the result does—and does
+not—prove.
+
+## The question being measured
+
+For one query, how much smaller is the bounded, proof-carrying graph response
+than the readable source corpus that supplied the graph's proofs?
+
+This is useful because AI agents do not need every indexed file for every
+question. It is deliberately narrower than “How many tokens will this model
+bill?” or “Will the model produce an equally good answer?”
+
+## Run it
+
+From a Workspai workspace:
+
+```bash
+npx workspai workspace model --write --json
+npx workspai workspace graph benchmark "authentication endpoint" --limit 12 --json
+```
+
+The result conforms to
+[`workspace-graph-token-efficiency.v1.json`](../contracts/workspace-intelligence/workspace-graph-token-efficiency.v1.json).
+It records:
+
+- the query and result limit;
+- the graph schema, entity/relation/proof counts, source artifact, and source
+  model SHA-256;
+- the number and size of readable, deduplicated proof-source artifacts;
+- the bounded retrieval size and match count;
+- unreadable artifacts rather than silently excluding them;
+- the estimate formula, reduction ratio, percentage, and claim boundary.
+
+## Baseline and formula
+
+The current methodology is `indexed-corpus-vs-bounded-retrieval.v1`.
+
+```text
+corpus characters    = sum(unique readable proof-source files)
+retrieval characters = compact JSON length of bounded search response
+estimated tokens     = ceil(characters / 4)
+reduction ratio      = corpus estimated tokens / retrieval estimated tokens
+reduction percent    = (corpus - retrieval) / corpus × 100
+```
+
+`characters / 4` is intentionally labelled as an estimate. It is portable and
+reproducible without downloading a tokenizer, but it is not exact for every
+language, model, or tokenizer.
+
+## Current fixture observation
+
+The 16-project development workspace produced the following result on
+2026-07-21 for `api endpoint --limit 8`:
+
+| Measure                         | Observed value |
+| ------------------------------- | -------------: |
+| Graph entities                  |          1,738 |
+| Graph relations                 |          2,244 |
+| Graph proofs                    |          2,106 |
+| Readable proof-source artifacts |            392 |
+| Corpus estimated tokens         |        134,105 |
+| Retrieval estimated tokens      |          2,812 |
+| Returned entities               |              8 |
+| Retrieval ratio                 |         47.69× |
+| Payload reduction               |          97.9% |
+
+Source-model SHA-256:
+`2b8abd415420cc421707c726e6f6c96641554594e84440bf2e539f04ba5836e8`.
+
+This row demonstrates that measurement is possible. It is not a representative
+cross-project benchmark and must not be marketed as a universal Workspai result.
+
+## What can be claimed today
+
+Safe wording:
+
+> Workspai can return bounded, proof-carrying workspace context instead of the
+> complete indexed corpus. On the current 16-project development fixture, one
+> `api endpoint` query reduced the estimated retrieval payload by 97.9%; results
+> vary by workspace and query.
+
+Unsafe wording:
+
+- “Workspai always reduces model tokens by 97.9%.”
+- “Agents are 47.69× cheaper with no quality loss.”
+- “Workspai beats another product” without a shared corpus and evaluation
+  harness.
+
+## Gate for a public headline benchmark
+
+Before publishing a general token-efficiency number, the benchmark suite must:
+
+1. pin public repositories and exact commit SHAs;
+2. publish fixed question sets and graph configuration;
+3. compare at least three baselines:
+   - entire readable corpus;
+   - a realistic grep/top-file retrieval strategy;
+   - bounded Workspai graph retrieval;
+4. count with at least one real, named tokenizer in addition to the portable
+   character estimate;
+5. measure answer relevance or task completion so smaller context is not treated
+   as automatically better context;
+6. repeat runs and publish variance, failures, unreadable files, hardware, and
+   software versions;
+7. publish raw machine-readable results and a one-command reproduction path;
+8. report median and range—not only the best repository.
+
+## Performance is a separate benchmark
+
+Payload size and graph speed answer different questions. Build time, incremental
+update time, peak memory, artifact size, and p50/p95 query latency must be
+measured separately. Do not infer runtime performance from the token-efficiency
+report.
+
+For normal interactive use, prefer `workspace graph search` or the MCP
+`searchWorkspaceGraph` tool. Use the complete graph artifact for interchange,
+offline analysis, audits, and consumers that explicitly require the entire
+workspace representation.

package/docs/workspace-intelligence-runner.md

@@ -0,0 +1,186 @@
+# Unified Workspace Intelligence Runner
+
+`workspace intelligence run` is the canonical contract-backed entrypoint for
+refreshing Workspace Intelligence evidence in one deterministic execution. Use
+it from a Workspai workspace root:
+
+```bash
+npx workspai workspace intelligence run --for-agent codex --strict --json
+```
+
+The authoritative result is written atomically to
+`.workspai/reports/workspace-intelligence-run-last-run.json` with schema
+`workspace-intelligence-run.v1`. JSON stdout returns the same report payload.
+Consumers should read the persisted report when they need durable evidence and
+use the process exit code for the immediate automation verdict.
+
+## Execution envelope and canonical chain
+
+The runner separates prerequisite operations from the versioned intelligence
+chain. `sync` and baseline handling are reported in `preflight`; they are not
+additional chain stages.
+
+```text
+Execution order
+
+sync
+  -> model
+  -> baseline resolution
+  -> diff
+  -> impact
+  -> doctor-evidence
+  -> contract-evidence
+  -> analyze-evidence
+  -> readiness-evidence
+  -> verify
+  -> context
+  -> agent-sync
+  -> explain
+```
+
+The report always contains exactly two ordered `preflight` entries:
+
+| ID         | Execution point              | Successful result     | Purpose                                            |
+| ---------- | ---------------------------- | --------------------- | -------------------------------------------------- |
+| `sync`     | Before `model`               | `synchronized`        | Reconcile workspace inventory and contract inputs. |
+| `baseline` | After `model`, before `diff` | `created` or `reused` | Ensure Diff has an explicit structural baseline.   |
+
+The report always contains exactly these 11 ordered `stages`:
+
+| Order | Stage                | Contract role                                           |
+| ----: | -------------------- | ------------------------------------------------------- |
+|     1 | `model`              | Build and persist the current workspace model.          |
+|     2 | `diff`               | Compare the current model with the selected baseline.   |
+|     3 | `impact`             | Calculate affected projects and transitive consequence. |
+|     4 | `doctor-evidence`    | Refresh workspace and project health evidence.          |
+|     5 | `contract-evidence`  | Verify the workspace contract.                          |
+|     6 | `analyze-evidence`   | Refresh structural and operational analysis.            |
+|     7 | `readiness-evidence` | Refresh pre-verify release-readiness evidence.          |
+|     8 | `verify`             | Produce the definitive evidence-backed gate.            |
+|     9 | `context`            | Build agent context from the same current evidence.     |
+|    10 | `agent-sync`         | Project canonical context into agent and IDE surfaces.  |
+|    11 | `explain`            | Explain the resulting release posture and blockers.     |
+
+The machine-readable authority is
+[`workspace-intelligence-chain.v1.json`](../contracts/workspace-intelligence-chain.v1.json).
+Commands, websites, IDEs, CI jobs, and agent instructions must not define a
+different order or insert `sync` or `snapshot-baseline` into `stages`.
+
+## Baseline semantics
+
+On the first run, the runner creates
+`.workspai/reports/workspace-model-snapshot.json` and reports:
+
+```json
+{
+  "id": "baseline",
+  "status": "passed",
+  "result": "created"
+}
+```
+
+On later runs, it reuses the existing snapshot and reports `result: "reused"`.
+`baselineCreated` is `true` only when that run created the baseline.
+
+The runner does not silently replace an existing baseline immediately before
+Diff. Doing so would erase the change boundary and incorrectly report no
+changes. Refresh or replace a baseline only through the explicit
+`workspace snapshot` workflow after the intended structural state has been
+accepted.
+
+## Status and exit semantics
+
+| Report status | Exit code | Meaning                                                                                        |
+| ------------- | --------: | ---------------------------------------------------------------------------------------------- |
+| `passed`      |       `0` | Every operation executed and no gate blocked the run.                                          |
+| `failed`      |       `1` | A required operation threw or could not complete. Downstream stages are recorded as `skipped`. |
+| `blocked`     |       `2` | Execution completed, but one or more evidence or verification gates rejected readiness.        |
+
+The canonical mapping is `passed` → `0`, `failed` → `1`, and `blocked` → `2`.
+
+A `blocked` evidence stage does not stop the chain. Context, grounding, and
+Explain must still be refreshed so humans and agents receive the current
+blocker evidence. A hard `failed` stage stops execution work and every
+downstream canonical stage is recorded with `status: "skipped"`, `exitCode: 0`,
+and `durationMs: 0`.
+
+Stage invariants:
+
+- `passed` requires `exitCode: 0`;
+- `blocked` requires a non-zero stage exit code;
+- `failed` requires `exitCode: 1`;
+- `skipped` requires `exitCode: 0` and `durationMs: 0`;
+- report status and exit code are derived from all preflight and stage results;
+- every stage artifact list must exactly match the runtime registry.
+
+`--strict` promotes warning-grade readiness states such as Analyze
+`needs-attention` and Readiness `warn` into blocked stage verdicts. It does not
+turn evidence blockers into execution failures: the aggregate exit remains `2`,
+not `1`.
+
+## Report contract
+
+The durable report contains:
+
+```json
+{
+  "schemaVersion": "workspace-intelligence-run.v1",
+  "chainSchemaVersion": "workspai-workspace-intelligence-chain-v1",
+  "generatedAt": "2026-07-18T00:00:00.000Z",
+  "workspacePath": "/absolute/machine-local/path",
+  "baselineCreated": false,
+  "preflight": [],
+  "status": "blocked",
+  "exitCode": 2,
+  "stages": [],
+  "artifactPath": ".workspai/reports/workspace-intelligence-run-last-run.json"
+}
+```
+
+The abbreviated arrays above illustrate the envelope only; conforming reports
+must contain exactly two preflight entries and 11 stages. The complete JSON
+Schema is
+[`workspace-intelligence-run.v1.json`](../contracts/workspace-intelligence/workspace-intelligence-run.v1.json).
+Structural schema validation is necessary but not sufficient. Workspai also
+enforces stage order, registered artifacts, baseline coherence, failure
+propagation, and aggregate verdict semantics before writing the report.
+
+`workspacePath` and some underlying evidence can contain machine-local absolute
+paths. Do not treat the run report as a portable workspace identity contract or
+publish it without applying the relevant redaction policy.
+
+## CI consumption
+
+The simplest hard gate is:
+
+```bash
+npx workspai workspace intelligence run --for-agent codex --strict --json
+```
+
+Both exit `1` and exit `2` fail a normal CI step. If artifacts must be uploaded
+after a blocked run, allow the runner step to continue, upload with `if: always()`,
+then fail the job from the recorded step outcome. See
+[`examples/ci-agent-grounding.yml`](./examples/ci-agent-grounding.yml).
+
+Automation must distinguish:
+
+- exit `1`: repair execution, environment, permissions, corruption, or another
+  hard runtime failure;
+- exit `2`: inspect Analyze, Readiness, Verify, and Explain evidence and resolve
+  the reported blockers;
+- exit `0`: consume the newly refreshed artifacts.
+
+Do not parse terminal prose. Read `status`, `exitCode`, `preflight`, `stages`,
+and their registered artifacts from the JSON report.
+
+## Relationship to other commands
+
+`workspace intelligence run` is the canonical Workspace Intelligence chain.
+`pipeline` is a broader governance/release orchestrator and `autopilot release`
+is a separate release surface. Neither command may replace, reorder, extend, or
+silently partially execute the canonical intelligence chain.
+
+Individual commands such as `workspace model`, `workspace diff`, and
+`workspace verify` remain useful for inspection and targeted renewal. A partial
+manual sequence must not be documented or treated as an equivalent replacement
+for the unified runner.