Skip to content

cogni-dao/cogni / .claude/skills/node-wizard-scorecard

node-wizard-scorecard

Verified

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:

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:

GateEvidenceStatusNext action
Launch pack factsnode repo URL, parent PR, candidate URLpass/blockedmissing fact to recover
Branch protectionnode repo main requires the standard CI checks (and a PR) before mergepass/blockedenable branch protection on the spawned node repo — required checks = the standard CI set
Child customization PRPR URL in node repopass/blockedcreate PR from node repo branch
Child CIrequired checks greenpass/blockedfix child PR
Child main imageghcr.io/<owner>/<repo>:sha-<child-main-sha> exists after mergepass/blockedreport missing image/tag
Parent birth PRmerged or still openpass/blockedwait/ask human to merge parent PR
Parent pinparent gitlink pins the image-producing child main SHApass/blockedask operator to update/publish parent pin
Candidate flightrequested through operator APIpass/blockedcall operator flight API only when eligible
Candidate verificationcandidate /version matches launched child SHApass/blockedrun agent-first validation
Agent-first validationcandidate API exercised using https://cognidao.org/knowledge/prove-node-agent-apipass/blockedpresent 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; https://cognidao.org/knowledge/operator-pipeline-contract 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 -> 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:

CheckEvidenceStatus
Registration worksnew agent registration succeeds against the candidate nodepass/blocked
Agent graph call worksregistered 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 itpass/blocked
Knowledge is livecreate a knowledge contribution and confirm the node repo-spec exposes a DoltHub knowledge.remote.urlpass/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 activecandidate node reports an active/current epoch or equivalent live epoch statepass/blocked
Base RPC is liveGET /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

  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.
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: 468kUpdated Claude CodeCodexVerifiedInstall
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: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 321kUpdated Claude CodeCodexVerifiedInstall