Decision: adopt Traceo + Ariel wiring + ratify applicability for 5 repos

date: 2026-05-01 status: proposed title: Adopt Traceo + Ariel wiring as PETROVA artefacts and ratify governance applicability supersedes: []

Decision: adopt Traceo + Ariel wiring + ratify applicability for 5 repos

Context

Sub-project A (PR #8, merged 2026-05-01) introduced the integration spine and reserved a slot for Traceo alongside ARES. The traceo slot shipped as a stub — TraceoIntegration in cli/src/types.ts and a non-functional traceoProbe in cli/src/probes/traceo.ts. No governance commitment was made about which repos must be wired, no VTM schema was ratified, and no CLI verb existed for operators to invoke the probe in consumer-repo CI.

Sub-project B (PRs #9 and #10, merged 2026-05-01) filled the ARES gap and, in doing so, established the patterns this decision follows: MR-13 (intent/observation split), MR-14 (read-only probe contract), MR-15 (registry applicability declarations), and the 06-ares-wire.md prompt shape. Sub-project C closes the traceo gap in the same way.

The authoritative specification is docs/superpowers/specs/2026-05-01-petrova-traceo-ariel-spec.md. Ariel, the service that owns diagram baselines, currently exposes a CLI and a FastAPI wrapper hosted by traceo-mcp-server at /api/ariel/baselines (POST to create, GET by baseline_id to retrieve). The HEAD-of-branch route and the by-label lookup route are not yet implemented in traceo-mcp-server; those are tracked as a separate cross-repo follow-up and are outside this PR’s scope. The spec’s §1.3 verdict classifies Ariel at the β (beta) maturity tier, which directly informs one of the five decisions below.

Decision

Five things, atomically in this PR:

Real traceo probe. cli/src/probes/traceo.ts is replaced with a read-only probe that executes three ordered checks: (a) Ariel GET — confirm the baseline recorded in .petrova/contract.yaml is reachable at the configured endpoint and returns HTTP 200; (b) fs.statSync VTM — confirm the Visual Traceability Map file referenced by the contract exists on disk at the declared path; (c) mermaid validate — confirm the VTM parses as valid Mermaid syntax (no render errors). Outcomes are ok | degraded | failing | unreachable, consistent with the spine’s ProbeOutcome type. The probe never creates or modifies baselines or VTMs; it is strictly observational. This upholds MR-13 (intent/observation split) and MR-14 (probe read-only contract). ProbeContext is extended with three optional fields — http? (HTTP client for Ariel calls), repoPath? (file-system root for statSync), and validateMermaid? (injected validator function) — to keep the probe unit-testable without live network or disk access.
New CLI verb petrova traceo-validate <path>. A new flat command is registered in commander under the petrova binary (house style: flat verbs, not sub-namespaced act commands). The spec proposed a hypothetical act namespace; that shape is not adopted here because no existing petrova act namespace exists and introducing one for a single verb would break the established command surface documented by docs/superpowers/specs/2026-04-30-petrova-integration-spine-design.md. The verb invokes the same three-check sequence as the probe, accepts a --endpoint flag (overrides PETROVA_TRACEO_ENDPOINT env var), and exits with code 0 on ok, code 1 on degraded or failing, and code 2 on unreachable. This makes it directly usable in consumer-repo CI without requiring the full petrova doctor harness.
Schema downgrade — baseline_id from URI scheme to opaque string. The initial spec draft specified baseline_id as a string matching the pattern ^ariel://. That pattern is dropped: baseline_id is now a plain non-empty string, expected to be the UUID returned by Ariel POST. Two new optional evidence fields are added to the traceo contract block: traceo_endpoint (string, the Ariel base URL at the time the baseline was recorded, for auditing) and mermaid_validated_at (ISO-8601 datetime string, set by traceo-validate on each successful validation pass). The downgrade is justified by the spec’s §1.3 β verdict: no Ariel HTTP server resolves the ariel:// URI scheme; the traceo-mcp-server FastAPI wrapper accepts opaque UUID strings only. Retaining the URI scheme constraint would guarantee false-negative probe runs for every consumer from day one. Backward compatibility is maintained because the canary contract (petrova-hq) declares traceo: not_applicable with no evidence block.
Adopt core/prompts/07-traceo-wire.md + core/templates/docs/spec/vtm-template.md. 07-traceo-wire.md is an 8-gated-taskset prompt, structurally parallel to 06-ares-wire.md: taskset 0 runs petrova doctor preflight to confirm the spine is healthy before any Traceo work begins; tasksets 1–7 walk the operator through baseline creation (Ariel POST), VTM authoring from the template, traceo-validate green-pass, .petrova/contract.yaml flip, and a final verification round per MR-10. Operator-private values (deployment URLs, auth token names, consumer repo paths) are represented as <<PLACEHOLDER>> tokens per the 00-bootstrap.md convention; none are hardcoded. vtm-template.md provides the standard VTM skeleton (title, diagram, legend, baseline reference block) that taskset 3 instructs the operator to copy and populate. Both files live in the core/ submodules; they are adopted here by bumping the submodule pointer.
Governance applicability — registry.yaml declares integrations_applicability.traceo: required for 5 repos. The five governed repos that must wire Traceo are: kahn-hq, stratt-hq, choco-hq, devarno-cloud, and grace-hq. Two repos are exempt: petrova-hq stays not_applicable because it is the canary (can observe but cannot observe itself); traceo-mcp-server stays not_applicable because it is the Ariel host (the service being integrated cannot hold a dependency on its own baseline). A consumer declaring traceo.status: not_applicable while governance says required is a designed CI failure — it surfaces on the dashboard as failing per the registry-schema contract, consistent with the ARES precedent.

The 5 actual wirings are NOT performed by this PR. Each is a separate operator-driven event — a Ariel POST to create the baseline, a VTM authoring session, a traceo-validate pass, and a consumer-repo PR — sequenced per docs/runbooks/traceo-wire-rollout.md and gated by a dated decision doc inside each consumer repo. This decision ratifies governance intent; the wirings are downstream operator work.

Alternatives considered

Probe only — leave VTM authoring to ad-hoc operator action. Rejected: without a canonical VTM template and the 07-traceo-wire.md prompt to drive authoring, each consumer repo would produce a structurally different VTM. The probe’s fs.statSync check would pass on any file at the declared path, including an empty one. Drift between consumer mermaid renderings and what the probe expects as valid Mermaid would surface only at render time, not at wiring time. The template and prompt are the forcing function that makes the probe meaningful.
Keep the aspirational ariel:// URI scheme for baseline_id. Rejected: the spec’s §1.3 β verdict is explicit — no Ariel HTTP server resolves the ariel:// scheme, and the traceo-mcp-server FastAPI wrapper returns and consumes opaque UUIDs only. Encoding a URI scheme that no runtime can dereference into the contract schema is a foot-gun for downstream consumers: probe check (a) would fail for every wired repo on first run, producing unreachable outcomes that appear to be network failures but are actually schema mismatches. The opaque string approach is strictly more honest about what Ariel currently returns, and the β verdict signals that the scheme question should be revisited when Ariel reaches stable maturity.
Bundle the 5 wirings into this PR. Rejected: the same logic that kept the 6 ARES wirings out of sub-project B applies here. A single merge that performs 5 Ariel POSTs, authors 5 VTMs, and opens 5 consumer-repo PRs would mutate cross-org production state in one unreviewed step. MR-7 (operator-gated decisions) requires each wiring to have its own dated decision doc approved before the wiring occurs. The runbook establishes wave ordering and gate reviews precisely to ensure that a bad baseline or a broken VTM in wave 1 is caught before waves 2 and 3 begin.

Consequences

For code:

traceoProbe becomes load-bearing. Running petrova doctor --slug=<repo> on a wired consumer will now report a meaningful outcome instead of the stub’s hardcoded unreachable.
ProbeContext gains three optional extension fields (http?, repoPath?, validateMermaid?). This is additive and does not break existing probe implementations for ARES or any future integration.
The new petrova traceo-validate <path> verb is available immediately after this PR merges; consumer CI pipelines can reference it before any repo is actually wired (it will exit 2 / unreachable until the endpoint is reachable).
baseline_id validation in the contract parser changes from a URI-scheme regex to a non-empty-string check. Existing canary contracts (all declaring not_applicable) are unaffected.

For docs:

New: core/prompts/07-traceo-wire.md (in the core/prompts submodule) — the operator-facing wiring prompt.
New: core/templates/docs/spec/vtm-template.md (in the core/templates submodule) — the canonical VTM skeleton.
New: docs/runbooks/traceo-wire-rollout.md — wave ordering (grace-hq → kahn-hq → gate review → choco-hq / stratt-hq / devarno-cloud), per-repo pre-flight checklist, and the per-repo decision-doc template that each consumer operator fills in before wiring.
New: this decision doc, plus the spec (docs/superpowers/specs/2026-05-01-petrova-traceo-ariel-spec.md) and plan (docs/superpowers/plans/2026-05-01-petrova-traceo-ariel-plan.md) that preceded it.

For invariants:

No new MRs are introduced. MR-13 (intent/observation split) and MR-14 (read-only probe contract) are reinforced by the probe’s three-check, zero-write design. MR-15 (registry applicability declarations) gains a second integration entry — traceo joins ares in the governed integrations set.
The integrations_applicability table in registry.yaml now covers two integrations for all 7 governed repos. A repo that is required for both and wired for neither will surface two distinct failing signals on the dashboard — by design, not a gap.
MR-1 (spec-grounded decisions) is upheld: every schema change and applicability decision above cites a specific section of the spec. No invariant in this document is invented without a spec or existing MR as its ground.

References

Spec: docs/superpowers/specs/2026-05-01-petrova-traceo-ariel-spec.md
Plan: docs/superpowers/plans/2026-05-01-petrova-traceo-ariel-plan.md
Runbook: docs/runbooks/traceo-wire-rollout.md
Sub-project B decision: docs/decisions/2026-05-01-ares-wire-adoption.md
Sub-project A spec and integration-spine meta-rules: docs/superpowers/specs/2026-04-30-petrova-integration-spine-design.md, docs/decisions/2026-04-30-integration-spine-meta-rules.md
Cross-repo follow-up tracker: HEAD-of-branch route + by-label lookup route in traceo-mcp-server (/api/ariel/baselines currently supports POST + GET by baseline_id only; full routing is tracked as a follow-on issue in traceo-mcp-server)

Operator approval

Tick all four boxes before flipping status: proposed → status: ratified and merging:

Confirm the 7-repo applicability table per spec §1.2: 5 repos (kahn-hq, stratt-hq, choco-hq, devarno-cloud, grace-hq) declared required; 2 repos (petrova-hq, traceo-mcp-server) declared not_applicable. No governed repo is missing or miscategorised.
Confirm wave ordering: grace-hq → kahn-hq (wave 1), gate review, then choco-hq / stratt-hq / devarno-cloud (wave 2, with devarno-cloud last because it is the superproject). Acknowledge that waves are strictly serial and no wave-2 wiring begins before the gate review passes.
Confirm https://traceo.devarno.cloud as the placeholder fallback endpoint in 07-traceo-wire.md and vtm-template.md. This value will be replaced with the real Traceo deployment URL once it is known; the PETROVA_TRACEO_ENDPOINT environment variable allows per-repo override without re-deploying the spine or editing any PETROVA artefact.
Confirm the schema downgrade: baseline_id drops the ^ariel:// pattern and becomes a plain non-empty string (UUID from Ariel POST). New optional evidence fields traceo_endpoint? and mermaid_validated_at? are additive and backward-compatible. The canary contract (petrova-hq) holds traceo: not_applicable with no evidence block and is unaffected.

Sign-off

Subagent: writing-plans (sub-project C implementer)
Human: <> (<>)