Verified Engineering Goals

A request such as “prepare this workspace for release” is useful, but it does not define what success means. A Verified Engineering Goal gives that request a durable scope, baseline, safety policy, required checks, evidence, and final verdict.

Workspai introduced three goal kinds in 0.52.0; they remain the supported verified outcome families in the current CLI:

• Release readiness — the workspace readiness and verification gates must pass.
• Dependency security — fresh project or workspace audit evidence must show no blocking vulnerabilities.
• Test coverage — measured coverage must reach the selected percentage.

Plan the outcome

For a person or agent, begin with the intent-first front door:

npx workspai goal "Prepare this workspace for release" --for-agent generic
npx workspai goal "Raise test coverage to 85%" --for-agent generic

Workspai compiles the request into an immutable Goal Pack and agent handoff. In an adopted project it binds the project automatically. In a multi-project workspace it asks for one canonical scope; non-interactive consumers receive a machine-readable decision and valid --scope choices. Coverage goals bind to the selected project's canonical runtime instead of re-detecting it later.

Use the template planner when automation already knows the goal kind:

# Whole-workspace release goal
npx workspai workspace goal plan release-readiness --json

# One project's dependency-security goal
npx workspai workspace goal plan dependency-security --scope project:api --json

# One project's coverage goal
npx workspai workspace goal plan test-coverage --scope project:web --target 75 --json

Planning writes the goal under .workspai/goals/<goal-id>/. Keep the returned goal ID: another terminal, CI job, IDE, or agent can resume the same objective instead of rebuilding its own checklist.

By default, builds and tests remain required, while forced repairs and breaking changes are not authorized. Change those constraints only when the engineering decision genuinely requires it; they are part of the recorded goal, not hidden agent preferences.

The lifecycle index records planned, active, blocked, verified, and terminal attempts without selecting two actionable goals at once. Attempts preserve their evidence fingerprint and runtime binding, so resuming a Goal cannot silently widen its scope or verify a different project.

Check progress and verify the result

npx workspai workspace goal status <goal-id> --json
npx workspai workspace goal verify <goal-id> --json

Verification runs against current canonical workspace evidence. The latest governed result is also published at:

.workspai/reports/verified-goal-last-run.json

A planned, active, or blocked goal is not done. Only a verified verdict means the recorded success criteria currently agree with the evidence.

Why dependency repair is different

Changing package.json, pyproject.toml, or another manifest does not prove that a vulnerability is gone. Dependency repair carries an explicit project transaction. It must reconcile the manifest and lockfile, rerun the focused audit, pass the declared tests, pass the declared build, and finish with canonical Workspace Intelligence verification—in that order.

This prevents an IDE or agent from reporting success while the lockfile is stale, the installed tree still contains the vulnerable package, or the update breaks the project. The final workspace gate remains responsible for dependent blockers outside the local project.

Consumer boundary

The goal and its status are versioned contracts. CLI, CI, IDE, Studio, and agent consumers should read those artifacts rather than infer completion from a chat message or a source diff.

• Verified Goal contract
• Verified Goal Status contract
• Goal Pack contract
• Goal Agent Handoff contract
• Doctor Dependency Repair Transaction contract

The contract catalog shows every field and constraint. The command catalog shows the canonical invocations and produced artifacts.