traceo wire rollout

Traceo + Ariel Wiring Rollout Runbook

Spec: docs/superpowers/specs/2026-05-01-petrova-traceo-ariel-spec.md Plan: docs/superpowers/plans/2026-05-01-petrova-traceo-ariel-plan.md Decision: docs/decisions/2026-05-01-traceo-wire-adoption.md Prompt: core/playbook/prompts/07-traceo-wire.md

After the sub-project C PR merges, the operator wires the 5 required repos in three waves. This runbook codifies the order, the gate between phases, and the per-repo decision-doc template.

Prerequisites

The operator must have:

• Access to the deployed Traceo MCP server (knows the deployment URL — goes into <<TRACEO_DEPLOYMENT_URL>>).
• Auth token housed in env var <<TRACEO_AUTH_TOKEN_NAME>> (e.g. PETROVA_TRACEO_TOKEN, or whatever the local convention is).
• npm install -g @mermaid-js/mermaid-cli (or per-CI-run via npx in workflows).
• pip install ariel (or pinned in the consumer’s pyproject.toml dev deps).

Waves

Phase 1 — strictly serial (one at a time, observe between)

Wave	Repo	Why this slot
1	grace-hq	smallest well-bounded spec surface (15 drift-watches DW-01..DW-15, 4 retroactive decisions, 7 milestones); ideal canary for the procedure itself
2	kahn-hq	first production / focused agent-fleet contracts; confirms procedure transfers from experimental → production profile

After wave 2, run a gate review:

• Did petrova traceo-validate surface false positives or fail to validate diagrams that mmdc actually compiles?
• Did Ariel POST baselines work as expected for the canary, or surface auth/format issues?
• Did the mermaid validator’s CI shell-out integrate cleanly with both repos’ workflow conventions?
• If yes to any: fix core/playbook/prompts/07-traceo-wire.md (submodule PR + parent pointer bump) and/or cli/src/verbs/traceo_validate.ts first, then proceed.
• If no: proceed to Phase 2.

Phase 2 — pipelined (all three may be in flight)

Wave	Repo
3a	choco-hq
3b	stratt-hq
3c	devarno-cloud

devarno-cloud is last because it’s a 28-submodule superproject — VTM authoring across submodules is the most complex case.

Pipelining rule: consumer-repo PRs (decision doc + VTM + CI workflow + contract flip) may be in flight in parallel during Phase 2. Ariel POST baselines are serialised per-repo (one POST per consumer; not a shared resource — pipelining is safe).

Per-wave checklist

For each repo, in order:

1. Open Claude Code in the consumer repo.
2. Paste core/playbook/prompts/07-traceo-wire.md (PETROVA submodule pointer captures the canonical version).
3. Run tasksets 0 (preflight) → 1–8 inclusive in order. Halt at every gate per the prompt’s halt-rules section.
4. Confirm the validator passes locally and in CI.
5. Confirm petrova doctor --slug=<repo> reports traceo: ok after the PR merges (run from petrova-codes worktree).
6. Merge the consumer-repo PR.

Per-repo decision-doc template

Copy this into the consumer repo as docs/decisions/YYYY-MM-DD-wire-traceo-<repo>.md at taskset 7 of the prompt:

---
title: Wire <repo> to Traceo + Ariel
date: YYYY-MM-DD
status: ratified
mr_compliance: [MR-1, MR-7, MR-13]
ranks_under: <repo's north-star intent doc>
---

## Context

Per `docs/runbooks/traceo-wire-rollout.md` in petrova-codes, this repo is in wave <N>. Sub-project C's adoption decision (petrova-codes:`docs/decisions/2026-05-01-traceo-wire-adoption.md`) ratified `integrations_applicability.traceo: required` for this repo on 2026-05-01.

## Decision

Authorise the wiring per `core/playbook/prompts/07-traceo-wire.md` (taskset-ladder 0 + 1–8). Ariel baseline UUID `<UUID>` registered against Traceo deployment `<<TRACEO_DEPLOYMENT_URL>>`. VTM lives at `docs/spec/vtm.md`. CI workflow: `.github/workflows/traceo-validate.yml`.

Rollback: drop the CI workflow, revert the contract block to `status: pending`. Baseline can be archived via `ariel baseline archive <UUID>` (or left in Ariel; baselines are immutable historical records).

## Consequences

- Mermaid diagrams in `docs/spec/vtm.md` validate on every push.
- `petrova doctor --slug=<repo>` reports `traceo: ok` once propagated.
- `.petrova/contract.yaml.integrations.traceo.status` flips from `pending` to `wired` in this PR.

Rollback (whole programme)

If a wave surfaces an unfixable issue:

1. Revert .petrova/contract.yaml.integrations.traceo to status: pending in the affected consumer (PR).
2. Drop the .github/workflows/traceo-validate.yml job.
3. Optionally archive the Ariel baseline (ariel baseline archive <UUID>) — or leave it for historical reference.
4. Open a new dated decision doc explaining what failed; link from petrova-codes sub-project C’s decision doc.
5. Continue the next wave only after the procedure is fixed.

The 5 required declarations in registry.yaml are NOT rolled back — governance intent survives transient wiring failures.

Validation between hops

After each wave:

• Consumer repo: petrova doctor --slug=<repo> reports traceo: ok AND a real traceo-validate CI run is green on the default branch.
• petrova-codes: state file at state/<repo>.yaml shows current_status.traceo: ok after the next sweep.
• If current_status.traceo == "degraded", inspect the latest probe_history entry — usually a Traceo deployment hiccup. Re-run petrova doctor to refresh.

Cross-references

• Sub-project A integration-spine rollout: docs/runbooks/integration-spine-rollout.md.
• Sub-project B ARES rollout (parallel runbook): docs/runbooks/ares-wire-rollout.md.
• Submodule update mechanics: docs/runbooks/submodule-bump.md (when the prompt itself is updated post-gate-review).
• Onboarding new repos: docs/runbooks/onboard-repo.md.
• Cross-repo follow-up: HEAD + by-label routes for traceo-mcp-server’s /api/ariel/baselines (out of scope here; tracked separately).