crumb wire rollout

CRUMB Wiring Rollout Runbook

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

After the sub-project D PR merges, the operator wires the 2 required repos in two waves. This runbook codifies the order, the gate between them, and the per-repo decision-doc template.

Prerequisites

• gh auth status clean for the GitHub account that has repo scope on devarno-cloud/crumb (read-only is sufficient for the probe; write is needed when authoring cards in Phase 3 of the prompt).
• Operator has cloned devarno-cloud/crumb locally OR is comfortable opening a PR via the GitHub web UI.
• npm i in cli/ keeps ajv + ajv-formats + js-yaml available for petrova crumb-validate.

Waves

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

Wave	Repo	Why this slot
1	grace-hq	only 1 card today; smallest blast radius for procedure validation
2	stratt-hq	10 cards already in CRUMB; canary for batch-counting + multi-card freshness checks

After wave 2, run a gate review:

• Did the probe correctly resolve + count matching blobs? Did card_count evidence match reality after the operator updated it?
• Did the verb correctly validate a real CRUMB card?
• Did the vendored schema accept all current cards under the wave’s prefix? If a real card violates the vendored schema, the schema is stale — open a decision doc + sync PR before continuing.

Phase 2 — none in this rollout

When kahn-hq / choco-hq / devarno-cloud have cards, a separate dated decision doc flips them to required and a Phase 2 wave-3 ratifies. Out of scope for sub-project D.

Per-wave checklist

For each repo, in order:

1. Open Claude Code in the consumer repo.
2. Paste core/playbook/prompts/08-crumb-wire.md (PETROVA submodule pointer captures the canonical version).
3. Run Phase 0 (preflight) → Phase 1 (audit) → halt.
4. Author cards in CRUMB via PR (Phase 3); merge that PR.
5. Validate locally (Phase 4); confirm green.
6. Open consumer-repo PR with decision doc + contract flip (Phase 6).
7. Confirm petrova doctor --slug=<repo> reports crumb: ok after both PRs merge.
8. Merge the consumer-repo PR.

Per-repo decision-doc template

Copy this into the consumer repo as docs/decisions/YYYY-MM-DD-wire-crumb-<repo>.md at Phase 6 of the prompt:

---
title: Wire <repo> to CRUMB
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/crumb-wire-rollout.md` in petrova-codes, this repo is in wave <N>. Sub-project D's adoption decision (petrova-codes:`docs/decisions/2026-05-01-crumb-wire-adoption.md`) ratified `integrations_applicability.crumb: required` for this repo on 2026-05-01.

## Decision

Authorise the wiring per `core/playbook/prompts/08-crumb-wire.md` (Phase 0 + Phases 1–6). Cards landed in `devarno-cloud/crumb#<PR>` under `src/content/cards/<prefix>-*.md`. Project prefix `<prefix>`. Initial card count `<N>`.

Rollback: revert this repo's contract block to `status: pending`. Cards in CRUMB are kept as historical knowledge artefacts (CRUMB cards are append-only by convention).

## Consequences

- `petrova doctor --slug=<repo>` reports `crumb: ok` once propagated.
- `.petrova/contract.yaml.integrations.crumb.status` flips from `pending` to `wired` in this PR.
- Card additions in CRUMB after this point continue to extend coverage; the `card_count` evidence field is updated by the operator on milestone PRs.

Rollback (whole programme)

If a wave surfaces an unfixable issue:

1. Revert .petrova/contract.yaml.integrations.crumb to status: pending in the affected consumer (PR).
2. Optionally archive the cards in CRUMB (or leave them — they’re append-only knowledge artefacts).
3. Open a new dated decision doc explaining what failed; link from petrova-codes sub-project D’s decision doc.
4. Continue the next wave only after the procedure is fixed.

The 2 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 crumb: ok AND the CRUMB-side PR is merged on main.
• petrova-codes: state file at state/<repo>.yaml shows current_status.crumb: ok after the next sweep.
• If current_status.crumb == "degraded", inspect the latest probe_history entry — usually count drift (cards added without contract bump) or stale-evidence (>30d). Update evidence.card_count and evidence.last_generated_at via a follow-up consumer-repo PR.

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.
• Sub-project C Traceo rollout: docs/runbooks/traceo-wire-rollout.md.
• Submodule update mechanics: docs/runbooks/submodule-bump.md.
• Tracked follow-up: autonomous flashcard generator (sub-project E candidate; reads consumer guidance docs and emits CRUMB-shaped cards).
• Tracked follow-up: CRUMB-side .github/workflows/crumb-validate.yml running petrova crumb-validate src/content/cards/*.md.