Evidence
How Workspace Intelligence decides which facts can be trusted.
Evidence is the source of understanding; documentation is an output, not the authority.
This is the most important rule in Workspace Intelligence.
Why evidence exists
Without evidence, a model becomes a story. It may be useful, but it is not operationally safe.
Evidence lets Workspai say:
- this project exists,
- this runtime was observed,
- this command is available,
- this report was generated,
- this gate passed,
- this fact is stale,
- this release is blocked,
- this agent context was refreshed.
Evidence levels
| Level | Meaning |
|---|---|
| Verified | Proven by a current command, report, contract, or gate |
| Observed | Found in workspace files, manifests, scripts, or markers |
| Inferred | Derived from weaker signals and should be treated carefully |
| Stale | Was true before, but inputs changed or freshness expired |
| Unknown | No reliable evidence exists yet |
Evidence artifacts
Common Workspai evidence includes:
- workspace model reports,
- workspace context packs,
- agent customization packs,
- doctor workspace/project evidence,
- graph-aware Doctor diagnosis evidence,
- analyze reports,
- project test coverage reports,
- readiness reports,
- pipeline reports,
- canonical Workspace Intelligence run reports,
- model snapshots,
- model diffs,
- impact reports,
- verify reports,
- explain and trace narratives,
- workspace intelligence history.
The artifact name alone is not proof of freshness. Current evidence also binds its schema, producer, workspace/project identity, inputs, and generation time. For the Knowledge Graph, that includes the model revision and live-input fingerprint. For a repair, it includes the immutable plan, checkpoint, event timeline, and terminal transaction state.
Portable workspace archives also carry versioned capability, manifest, and operation evidence. Verification can inspect an archive before import or hydration without treating dependencies, secrets, or machine-local project links as portable source.
Verification
Verification is where evidence becomes a gate.
npx workspai workspace intelligence run --for-agent generic --strict --jsonThat runner produces the authoritative cross-stage result at
.workspai/reports/workspace-intelligence-run-last-run.json. For targeted
inspection or for the separate governance/release boundary, use:
npx workspai workspace verify --strict --json
npx workspai pipeline --json --strictVerification should evaluate:
- graph integrity,
- changed projects,
- affected dependents,
- policies,
- freshness,
- required reports,
- release readiness.
When required evidence is missing, Verify can return a structured resolution
hint with the exact sourceCommand and exact sourceArtifact. Run that producer,
then verify again. Do not infer a command from a familiar-looking report name,
and do not mark the gate successful because an unrelated command passed.
The canonical intelligence runner distinguishes three terminal outcomes:
| Outcome | Exit code | Meaning |
|---|---|---|
passed | 0 | Required stages and gates accepted current evidence |
failed | 1 | An operational stage failed; dependent stages may be skipped |
blocked | 2 | A structured gate or strict warning prevented acceptance |
A blocked run can still refresh context, agent grounding, history, and explanation so consumers receive current evidence about the blocker. That continued reporting must not be rendered as a passed release gate.
Agent safety
AI agents should not receive unbounded context. They should receive scoped, fresh, evidence-backed context. That is the difference between a helpful agent and an agent that confidently acts on stale assumptions.