cogni-dao/cogni / .claude/skills/node-wizard-scorecard
node-wizard-scorecard
VerifiedUse 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:
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 https://cognidao.org/knowledge/prove-node-agent-api | pass/blocked | present human scorecard |
Rules
- Every spawned node repo's
mainMUST 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>-testrecord. The flight upserts it (reconcile-node-dns.sh; https://cognidao.org/knowledge/operator-pipeline-contract Axiom 21). A fresh-flightNXDOMAINis almost always negative-cache — re-checkdig <host> +short @1.1.1.1. - Edge is automatic-but-fragile — DO NOT assume a flighted node serves
externally (KNOWN GAP). The
node-substrateedge 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-missingInit:CrashLoopBackOff, preview global-lease freeze, prod-promotesourceShafootgun, no-LLM-backend) live innode-wizard-expertSKILL.md → "Substrate E2E is NOT yet hands-off". Mirror this into the hub entrynode-formation-wizard-scorecard. - After merge, use the child repo's current
mainSHA assourceSha. GitHub merge commits differ from PR head commits, and the child push build tagssha-${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 -> deploy verb (POST /api/v1/deploy/workloads, env=candidate-a) CI/CD path. Use
https://node-template.cognidao.org/knowledge/node-ci-sovereignty for the CI/CD facts and
https://cognidao.org/knowledge/prove-node-agent-api 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 |
| Base RPC is live | GET /readyz?deep=1 forces a live Base RPC read and returns 200; GET /api/v1/public/treasury/snapshot returns staleWarning:false with blockNumber>0. Missing EVM_RPC_URL is fatal, while a transient vendor failure on default /readyz remains non-draining and emits substrate.evm_rpc.unreachable. | 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:
# 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
- Confirm launch-pack facts and recall the knowledge handoff.
- Confirm the node repo
mainhas branch protection requiring the standard CI checks before merge (the backstop for operator run-ci + merge-on-green); enable it if missing. - Open a child node customization PR.
- Wait for child PR CI, human/operator merge, and child
mainimage tag. - Right before flighting, ensure the parent birth PR is merged or explicitly ask the human to merge it.
- Confirm the parent pin references that image-producing child SHA.
- Request candidate-a flight through the operator API.
- Verify candidate
/version, run agent-first API validation, and complete fresh boot health checks. - Run the Dolt knowledge round-trip health check (Fresh Boot Health, above):
contribute + create a work item → human-merge → confirm
dolt_pushlanded → recover by a fresh doltgres-nativeSELECT DOLT_CLONE(...)and assert the entry + work_item + commit log return. Deployed ≠ durable until this passes. - Present the node formation scorecard to the human.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |