Migration Guide

Product Terminology Migration

Veritas now uses the product vocabulary in reference/glossary.md. Pre-glossary names should be renamed, not preserved as a public surface.

Current implementation names to migrate:

Near-term rename targets:

1. Rename generated .veritas/ files to standards/map/settings language.
2. Rename schema files and field names after generated files are settled.
3. Rename CLI command groups from implementation names to readiness, feedback, and recommendations.
4. Keep exact current implementation names only in migration notes, schema references, and code comments needed to explain an active rename.

Run Snapshots Move to .surface/runs/

Veritas writes run snapshots to .surface/runs/.

New paths:

.surface/runs/<run-id>.console.json
.surface/runs/latest.json

When updating an existing local checkout:

1. Add .surface/ to your .gitignore if it is not already there (run snapshots are derived and should not be committed).
2. The next veritas readiness writes to the new path automatically.
3. Remove stale ignore entries for the retired Veritas-local console directory once that directory is gone.

If you pass a --read-model flag explicitly to the Surface Console, set it to .surface/runs/latest.json or omit it entirely, since .surface/runs/latest.json is now the default.

Claims Are Now Authored, Not Generated Per Run

Veritas requires a committed claim store at veritas.claims.json. Per-run claim generation is no longer supported.

To migrate:

1. Run veritas claim init in the repo root.
2. Review the generated claim IDs, surfaces, policies, and metadata.
3. Commit veritas.claims.json.
4. Update any automation that referenced run-scoped claim IDs to use the stable authored claim IDs.

See claim-authoring.md for the full authoring workflow.

Repo Map Evidence Checks Are Explicit Objects

Repo Maps now use explicit evidence-check objects. Removed command arrays such as requiredEvidenceCheckCommands, defaultEvidenceCheckCommands, and surfaceEvidenceCheckCommands[].evidenceChecks fail runtime validation with a migration-oriented error.

Before:

{
  "evidence": {
    "requiredEvidenceCheckCommands": ["npm run ci:fast"],
    "defaultEvidenceCheckCommands": ["npm test"],
    "surfaceEvidenceCheckCommands": [
      { "nodeIds": ["src/api"], "evidenceChecks": ["npm run api:test"] }
    ]
  }
}

After:

{
  "evidence": {
    "evidenceChecks": [
      { "id": "ci-fast", "command": "npm run ci:fast", "method": "validation" },
      { "id": "unit-tests", "command": "npm test", "method": "validation" },
      { "id": "api-tests", "command": "npm run api:test", "method": "validation" }
    ],
    "requiredEvidenceCheckIds": ["ci-fast"],
    "defaultEvidenceCheckIds": ["unit-tests"],
    "evidenceCheckRoutes": [
      { "componentIds": ["src/api"], "evidenceCheckIds": ["api-tests"] }
    ]
  }
}

Owned repos can update .veritas/repo-map.json manually or rerun veritas init --force and reapply local policy edits.

Evidence Check Commands No Longer Run Through a Shell

veritas readiness now tokenizes evidenceCheck commands and executes them directly instead of passing the full string through SHELL -lc.

This closes a config-level command-injection path, but it changes the evidence-check contract:

• shell requirement operators such as &&, ||, |, >, and < are no longer interpreted
• environment-variable expansion such as $FOO is no longer interpreted
• quoting still works for grouping argv tokens

How To Migrate

Recommended:

1. Split compound evidenceCheck flows into multiple evidenceChecks entries.
2. Keep each evidenceCheck to one executable plus its argv.

Before:

{
  "evidenceChecks": [{ "id": "ci", "command": "npm run ci:fast && npm test", "method": "validation" }],
  "requiredEvidenceCheckIds": ["ci"]
}

After:

{
  "evidenceChecks": [
    { "id": "ci-fast", "command": "npm run ci:fast", "method": "validation" },
    { "id": "unit-tests", "command": "npm test", "method": "validation" }
  ],
  "requiredEvidenceCheckIds": ["ci-fast", "unit-tests"]
}

If you previously relied on shell expansion, move that logic into a real script and call the script as the evidenceCheck.

Evidence Check Output Now Uses Inherited StdIO

Evidence Check commands now run with inherited stdio instead of redirecting stdout into stderr.

Operational effect:

• evidenceCheck stdout stays on stdout
• evidenceCheck stderr stays on stderr
• CLI callers that assumed veritas readiness emitted only JSON on stdout must now parse the trailing JSON payload instead of the entire stream

This is intentional. The command no longer rewrites evidence-check output streams behind the operator’s back.