feat(build): 3x3 build-recipe contract + CLI-surface reconciliation (closes #57)

[mdheller]

Closes #57. cc @mdheller. Related: #76.

Lands the one net-new, schema-shaped slice from the Prophet CLI & System Architecture spec (intake 2026-07-31). Everything else the spec commits to is already-real elsewhere and is consumed, not rebuilt (sourceos-spec Genesis/Inception/Twin, source-os/runtime/quorumd, estate gitops-promote / gate.yml / canary lifecycle, TriTRPC transport skins, prophet-platform deploy plane). This repo owns only the ordering + gate contract and the surface reconciliation.

1. 3x3 build-recipe contract (DAG + health-gate teeth)

• build/recipes.yaml — prophet build local|region|macro, each an ordered, acyclic chain of 3 stages. Every stage declares depends_on + a required health gate, so stage N+1 cannot start until stage N verifies.
  • local: genesis → inception → twin-bridge
  • region: security/storage → bus/HOPE → work/agents
  • macro: federated-twin → policy/replication → macro-agents/search
• manifests/build-recipes.schema.json — schema-as-code. It is the single source of truth for the tier enum and stage keys; scripts/validate_build_recipes.py reads them back, so schema and validator cannot silently drift.
• scripts/validate_build_recipes.py — proves the ordering is a DAG: no cycles, no forward edges, no skip edges, and every stage has a real gate (required: true + non-empty check; anything weaker is treated as missing).

Teeth (both ways)

Accept fixture (build/recipes.yaml) VERIFIES. Reject fixtures under build/fixtures/ each fire:

fixture	fault
reject-forward-dep.yaml	stage depends on a later stage
reject-missing-gate.yaml	stage missing its health gate
reject-unknown-tier.yaml	unknown tier
reject-cycle.yaml	cycle in depends_on

--self-test asserts accept passes AND every reject fires with the expected reason. Negative control confirmed: weakening a reject fixture makes --self-test exit non-zero.

2. Command-tree reconciliation (decision-as-data)

• manifests/cli-surface.json + scripts/validate_cli_surface.py reconcile the spec command tree (context/config/build/fs/graph/docker/conda/minio/rsync/kafka/work/vocab/gib/search/opencog/genesis/inception/twin/bridge/agents) onto the canonical verb model in docs/CLI_SURFACE_POLICY.md.
• Teeth: verb drift fires both ways (declared-but-not-in-policy, and in-policy-but-not-declared); every noun resolves only to canonical verbs (no competing command language); per the phase-1 policy, deferred nouns must not scaffold empty subtrees; the whole spec tree must be accounted for.
• Only nouns with a real delegate are adopted (build, vocab, search, agents); the remaining 16 are deferred as follow-up (surface growth is policy-gated).

Wiring

• make validate → validate-manifests → both self-tests. Also make validate-recipes / make validate-surface.
• New python CI workflow .github/workflows/build-recipes.yml; validate.yml gains Python + pyyaml so make validate stays green.

Local teeth results

python3 scripts/validate_build_recipes.py --self-test   # PASS (accept + 4 rejects; negative control fails as expected)
python3 scripts/validate_cli_surface.py  --self-test   # PASS (accept + 4 drift rejects)

Follow-up (out of this slice)

Deferred noun-namespace adoption (the 16 nouns without a real delegate) — filed separately @mdheller; surface growth is policy-gated and must not scaffold empty subtrees.