Node Wizard Scorecard

---
name: node-wizard-scorecard
description: Use when an agent receives a Cogni node wizard launch pack, takes over a newly published throwaway node, or must prove the node-wizard launch path end-to-end across child customization PR, child CI/image, parent pin, operator flight request, and candidate /version verification.
---

# Node Wizard Scorecard

Use this as the first response after receiving a node launch pack. The goal is
not to save the throwaway node; the goal is to prove the node-wizard launch path
is reproducible by an external agent without privileged manual bridges.

## Setup

If the workspace root does not contain `.env.cogni`, run
`/contribute-to-cogni` against the production operator and save the returned env
file at the repo root before doing launch work. Use that token to recall the
launch handoff knowledge block (`node-launch-handoff`) and search for agent
starter-kit knowledge before designing the customization PR.

## First Response

Do not send the full matrix before a child customization PR exists. Before that
point, report only launch facts plus the next concrete action. A status table
with `READY` rows is misleading because the path has not produced a deployable
artifact and human merge latency may still be ahead.

Pre-PR first response:

```markdown
Launch facts:

- node repo:
- parent PR:
- candidate URL:

Current gate: child customization PR not opened
Next action: create a minimal node repo PR and report its URL
```

Humans may send only a repo URL, parent PR, or short status fragment. Recover
the rest from GitHub/operator state; do not ask the human to fill out the
scorecard.

## Required Matrix

Return this matrix only after the child customization PR exists, or when
reporting a terminal blocker that prevents opening one:

| Gate                   | Evidence                                                                 | Status         | Next action                                                                               |
| ---------------------- | ------------------------------------------------------------------------ | -------------- | ----------------------------------------------------------------------------------------- |
| Launch pack facts      | node repo URL, parent PR, candidate URL                                  | `pass/blocked` | missing fact to recover                                                                   |
| Branch protection      | node repo `main` requires the standard CI checks (and a PR) before merge | `pass/blocked` | enable branch protection on the spawned node repo — required checks = the standard CI set |
| Child customization PR | PR URL in node repo                                                      | `pass/blocked` | create PR from node repo branch                                                           |
| Child CI               | required checks green                                                    | `pass/blocked` | fix child PR                                                                              |
| Child main image       | `ghcr.io/<owner>/<repo>:sha-<child-main-sha>` exists after merge         | `pass/blocked` | report missing image/tag                                                                  |
| Parent birth PR        | merged or still open                                                     | `pass/blocked` | wait/ask human to merge parent PR                                                         |
| Parent pin             | parent gitlink pins the image-producing child main SHA                   | `pass/blocked` | ask operator to update/publish parent pin                                                 |
| Candidate flight       | requested through operator API                                           | `pass/blocked` | call operator flight API only when eligible                                               |
| Candidate verification | candidate `/version` matches launched child SHA                          | `pass/blocked` | run agent-first validation                                                                |
| Agent-first validation | candidate API exercised using `docs/guides/agent-api-validation.md`      | `pass/blocked` | present human scorecard                                                                   |

## Rules

- **Every spawned node repo's `main` MUST have branch protection requiring the
  standard CI checks (and a PR) before merge.** This is the precondition that
  gives operator "merge on green" real teeth and a backstop: without it, a PR
  whose checks were skipped or never ran can merge _vacuously_ and the operator's
  own merge gate becomes the only authority. With it, an RBAC-holder can safely
  approve the standard CI workflows on — and merge — external-dev PRs to that
  repo (including PRs the agent itself authored from a fork), because branch
  protection independently enforces that the standard checks went green.
- Do not push directly to child `main`.
- Do not merge your own child or parent PR. Stop at ready/mergeable and report
  the human/operator merge row as pending.
- Do not hand-edit the operator gitlink from the child-repo agent.
- Do not infer GHCR success from a commit existing; the image tag must exist.
- Do not request flight until the parent pin and child image agree.
- Candidate flight must be requested through the operator API. Do not use
  source-repo deploy workflows or other privileged manual deploy paths.
- DNS is automatic — never hand-create a `<node>-test` record. The flight upserts
  it (`reconcile-node-dns.sh`; ci-cd.md Axiom 21). A fresh-flight `NXDOMAIN` is
  almost always negative-cache — re-check `dig <host> +short @1.1.1.1`.
- **Edge is automatic-but-fragile — DO NOT assume a flighted node serves
  externally (KNOWN GAP).** The `node-substrate` edge reconcile writes the Caddy
  route, but on a fresh node the running config may not pick it up → the node is
  Argo-Healthy and serves **in-cluster** yet returns external **000** (proven on
  beacon prod, 2026-06-16). External 000 + DNS resolving + pod Healthy = the
  **edge-reload gap (bug.5031 / PR #1697)**, not negative cache. Heal + the full
  substrate-gaps table (doltgres-DB-missing `Init:CrashLoopBackOff`, preview
  global-lease freeze, prod-promote `sourceSha` footgun, no-LLM-backend) live in
  `node-wizard-expert` SKILL.md → "Substrate E2E is NOT yet hands-off". Mirror
  this into the hub entry `node-formation-wizard-scorecard`.
- After merge, use the child repo's current `main` SHA as `sourceSha`. GitHub
  merge commits differ from PR head commits, and the child push build tags
  `sha-${github.sha}`.
- If a gate is blocked by missing operator authority, report the blocker instead
  of inventing a privileged workaround.

## Human Scorecard Timing

Do not present the node formation scorecard to the human until candidate flight
has succeeded, candidate `/version` matches the launched SHA, and agent-first
API validation has passed. The human-facing report must include critical repo
links, child PR/check status, image tag and digest, parent pin status, flight
status, candidate `/version`, and a short explanation of the child-build ->
operator-pin -> candidate-flight CI/CD path. Use
`docs/spec/node-ci-cd-contract.md` for the CI/CD facts and
`docs/guides/agent-api-validation.md` for the post-flight API exercise.

## Fresh Boot Health

After candidate flight and `/version` match, prove the freshly booted node is
usable, not just deployed:

| Check                                  | Evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Status         |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| Registration works                     | new agent registration succeeds against the candidate node                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `pass/blocked` |
| Agent graph call works                 | registered agent gets a successful graph/completions response; ask for a haiku. **Known gap:** a fresh node with no LLM/LiteLLM secret provisioned **times out** here (deployed ≠ usable) — report `blocked` with the timeout, don't paper over it                                                                                                                                                                                                                                                                                   | `pass/blocked` |
| Knowledge is live                      | create a knowledge contribution and confirm the node repo-spec exposes a DoltHub `knowledge.remote.url`                                                                                                                                                                                                                                                                                                                                                                                                                              | `pass/blocked` |
| Knowledge round-trips (sync + recover) | **the load-bearing durability proof, not just "a contribution exists".** Register a domain (bearer, on-demand) → contribute an entry **and** create a work item → human-merge the contribution → `pushMainOnMerge` `dolt_push` lands on the DoltHub remote → recover it by a **fresh clone** and assert the entry + work_item + commit log come back. See "Dolt round-trip recovery" below — this is what proves the node's knowledge actually persists and is recoverable, the gap that silently hid data-loss until it was needed. | `pass/blocked` |
| Epoch is active                        | candidate node reports an active/current epoch or equivalent live epoch state                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `pass/blocked` |

### Dolt round-trip recovery (how to run the `Knowledge round-trips` check)

Proving "recover" is the non-obvious part — **plain `dolt clone` (Dolt CLI) does NOT
work on healthy Doltgres data**: it fails `could not find root value: main; table has
unknown fields`. That is the Dolt engine being unable to read the Doltgres dialect, NOT
corruption. (When the SAME `table has unknown fields` appears from DoltHub's **web-SQL**
runner, that IS a corrupted repo — the diagnostic differs by tool.) Recover doltgres-native:

```bash
# creds: JWK keyid written to the node's OpenBao at cogni/<env>/<node>/DOLT_CREDS_{JWK,KEYID}
docker run -d --name dolt-recover -p 5433:5432 \
  -e DOLTGRES_PASSWORD=recoverpw -v "$HOME/.dolt:/root/.dolt:ro" dolthub/doltgresql:0.57.3
psql "postgresql://doltgres@127.0.0.1:5433/doltgres" \
  -c "SELECT DOLT_CLONE('<owner>/<repo>');"        # SELECT, not CALL
psql "postgresql://doltgres@127.0.0.1:5433/<repo>" \
  -c "SELECT domain,title FROM knowledge WHERE content LIKE '%<marker>%';" \
  -c "SELECT id,type,title FROM work_items WHERE id='<work-item-id>';" \
  -c "SELECT LEFT(commit_hash,10),message FROM dolt_log ORDER BY date DESC LIMIT 6;"
```

Report `blocked` (do NOT paper over) if any of: DoltHub target is the canonical repo
rather than a throwaway (a fresh spawn must sync to a throwaway, e.g. via the per-env
`KNOWLEDGE_DOLTHUB_REMOTE_URL` override), `DOLT_CREDS` absent so the push is a silent
no-op, or the recovered clone is missing the entry / work item / commit. **Known root
cause (2026-08):** DoltHub is an unsupported Doltgres remote — its Dolt-native GC cannot
walk Doltgres roots and can prune a live base chunk, silently corrupting a long-lived
mirror. Prefer a Doltgres-native remote (filesystem/S3) for durable mirrors; back up the
Doltgres volume (the app `db-backup` job does NOT cover it).

Include these rows in the human-facing scorecard when they are relevant to a
fresh node spawn. If a row is blocked by missing credentials or absent endpoint
surface, report the exact blocker instead of substituting a weaker health check.

## Minimal v0 Path

1. Confirm launch-pack facts and recall the knowledge handoff.
2. Confirm the node repo `main` has branch protection requiring the standard CI
   checks before merge (the backstop for operator run-ci + merge-on-green);
   enable it if missing.
3. Open a child node customization PR.
4. Wait for child PR CI, human/operator merge, and child `main` image tag.
5. Right before flighting, ensure the parent birth PR is merged or explicitly
   ask the human to merge it.
6. Confirm the parent pin references that image-producing child SHA.
7. Request candidate-a flight through the operator API.
8. Verify candidate `/version`, run agent-first API validation, and complete
   fresh boot health checks.
9. Run the **Dolt knowledge round-trip health** check (Fresh Boot Health, above):
   contribute + create a work item → human-merge → confirm `dolt_push` landed →
   recover by a fresh doltgres-native `SELECT DOLT_CLONE(...)` and assert the
   entry + work_item + commit log return. Deployed ≠ durable until this passes.
10. Present the node formation scorecard to the human.