Axiom

Build is governed DAG traversal. Phases are nodes. Dependencies are edges. Parallelism is discovered, not hardcoded. GOV is the only hardcoded path.

Constraints

MUST:     Hardcode only CANONIC_GOV — discover repos, fleet, scopes, phases, DAG edges
MUST:     Gate GOV boundary at compile time — build FAILS if runtime files exist in GOV
MUST:     Gate .gitignore at compile time — build FAILS if GOV .gitignore is missing required patterns
MUST:     Discover phases via glob (build_phases/[0-9][0-9]*-*)
MUST:     Discover DAG edges from PIPELINE.toml (GOV-governed, not hardcoded in orchestrator code)
MUST:     Use GovGraph (galaxy BFS) for all cross-scope INTEL and LEARNING discovery
MUST:     Register all build tools in PIPELINE.toml with reads/writes/depends declarations
MUST:     Carry _generated marker on .md files written back to GOV (CLAUDE.md, books, scaffolds)
MUST:     Auto-scaffold missing closure artifacts (INTEL, LEARNING, COVERAGE, ROADMAP, VOCAB, README) from CANON.md
MUST:     Scaffold before attest — 255 compliance is the default, not the goal
MUST:     Never overwrite hand-authored files — only scaffold when missing or _generated
MUST NOT: Require _generated marker on .json — the extension itself declares runtime
MUST:     Preserve BUILD_ENV audit trail (LEDGER/build/)
MUST:     Fail fast if PIPELINE.toml is missing or drifted from discovered phases
MUST:     Use DAG-parallel runner as sole entry point — no sequential fallback
MUST NOT: Use inherits-chain-only INTEL discovery (deleted, replaced by graph BFS)
MUST NOT: Maintain fallback paths for missing galaxy.json (fail fast)
MUST NOT: Hardcode scope paths, fleet paths, repo paths, or phase paths
MUST NOT: Write runtime artifacts (.json, .css, .js, .pyc, .pptx, caches) into GOV tree
MUST NOT: Write GOV source (.md contracts) into runtime except via _generated compile outputs
MUST NOT: Rely on .gitignore as primary boundary defense — compiler gate is primary, .gitignore is governed secondary

COVERAGE:

SPEC

Pipeline

Boundary

~/CANONIC/    = GOV      pure .md contracts, human-readable
~/.canonic/   = RUNTIME  compiled .json, scripts, caches, fleet sites

Optimizations

INTEL

Compiler Architecture

Phase Inventory (17 phases)

Validation Gates

Caching

Deploy Chain

• _data/ and decks/ are gitignored in source (generated by build)
• Builds take 8-12 minutes
• Cloudflare lowercases URLs; GitHub Pages serves case-insensitively

Known Gotchas

• ThreadPoolExecutor is correct for galaxy enrichment (I/O-bound, not CPU-bound)
• Blog/paper format oscillation traced to freshness cache skipping compiled.add() and stale cleanup
• BFS non-determinism traced to unsorted neighbor iteration (fixed: sorted())
• SKIP_INCREMENTAL=1 forces full galaxy rebuild
• Runtime (~/.canonic/bin/) is not versioned in GitHub (RUNTIME_GOVERNED gap)

LEARNING

ROADMAP

Now

• [x] DAG-parallel phase orchestrator (build-dag)
• [x] ProcessPoolExecutor scope compilation (build-surfaces)
• [x] Parallel fleet site compilation (03-surfaces)
• [x] Parallel catalog emitters (7 concurrent)
• [x] Parallel galaxy enrichment (ThreadPoolExecutor)
• [x] Inheritance chain caching (lru_cache)
• [x] Incremental galaxy (mtime hash-skip)
• [x] Parallel wallet publishing (09-econ)
• [x] Graph-native discovery kernel (gov_graph.py — shared GovGraph + BFS extractors)
• [x] PIPELINE.toml (GOV-governed pipeline manifest, replaces DAG.json)
• [x] Delete extract_intel_chain/extract_learning_chain (replaced by BFS)
• [x] Graph-native system prompts and catalog emitters
• [x] gorunner.pro fleet migration (Cloudflare Pages → GitHub Pages pipeline)
• [x] PIPELINE.toml dependency fix (build-surfaces depends on build-galaxy-json)
• [x] Build telemetry dashboard (phase timings over time)
• [x] Pure DAG Compiler: legacy sequential runner deleted, build-dag promoted to build, PIPELINE.toml 17/17 phases
• [x] Metalearning dependency: compile-claude-md depends on build-learning (intake-promote → CLAUDE.md closure)

Later

• [ ] ProcessPoolExecutor for galaxy enrichment (currently ThreadPool, I/O-bound — ThreadPool is correct for now)
• [ ] Scope partitioning for large fleet sites (ProcessPoolExecutor 8 workers already active)
• [ ] ACCESSIBILITY_AUDIT — lighthouse_audit emits accessibility.json per page, color contrast validation against design tokens
• [ ] DEPENDENCY_GRAPH — export galaxy as DOT/JSON for external visualization, circular dependency detection as artifact

VOCAB

INHERITANCE CHAIN

SERVICES

SERVICES compose primitives — INTEL + CHAT + COIN. Every service governed. Every scope discovered.

MUST:     Maintain TRIAD integrity (CANON.md + VOCAB.md + README.md)
MUST:     Treat SPEC as scope identity (`{SCOPE}` directory), not as a file
MUST:     Every SERVICE scope include ROADMAP.md, COVERAGE.md, LEARNING.md, and `{SCOPE}.md` as governed content surfaces
MUST:     Discover SERVICE scopes from filesystem only (no manual catalog)
MUST:     Keep http:// and magic:// on the same namespace (transport differs, scope path matches)
MUST:     CANON.md = axiom + universal constraints (no service names, no paths, no implementation)
MUST:     README.md = how to run the CANON (nothing else)
MUST:     {SCOPE}.md = SPEC — the interface (purpose, routes, projections, ecosystem)
MUST:     SHOP.md = public projection file (per scope, filesystem-discoverable)
MUST:     VAULT.md = private projection file (per scope, filesystem-discoverable)
MUST:     Runtime implementation remains under ~/.canonic; this workspace is governance-first
MUST NOT: Hardcode service names in CANON constraints (law speaks universals)
MUST NOT: Define ungoverned terms outside VOCAB.md
MUST NOT: Treat `{SCOPE}.md` as SPEC identity
MUST NOT: Move architecture/lifecycle into README
MUST NOT: Leak private projections to public surfaces
MUST NOT: Maintain duplicate mapping tables outside generated manifest outputs
MUST NOT: Add runtime jargon to governance contracts
MUST:     Ledger-consuming services declare source ledgers, scope filters, and closure gates
MUST:     Learning governance remains live — closure claims require fresh DISCOVER → GENERATE → RELINK evidence

hadleylab-canonic

HADLEYLAB ships software. Every app, book, paper, deal, and patent is PROOF that MAGIC works. COIN = WORK. LEARNING = COMPUTE.

MUST:     Every app, book, paper, deal, or patent is evidence of MAGIC
MUST:     All scopes inherit canonic-canonic/CANONIC.md governance
MUST:     All users governed under USERS/ via SERVICES/USER
MUST:     Cross-index INTEL across users (INTEL.md)
MUST:     Shared events propagate to ALL affected user dashboards
MUST:     Maintain governance workspace purity (.md files only)
MUST:     Ledger all COIN (validated work) through MAGIC 255
MUST:     Compile all INTEL from governed sources
MUST:     Keep frontend/runtime implementation under ~/.canonic (hidden runtime)
MUST:     Surface governed TALK, Library, and SERVICES scopes (no orphan content)
MUST:     Derive nav labels from governed scope names (no hardcoded strings)
MUST NOT: Publish without governance (CANON.md required)
MUST NOT: Duplicate primitives — compose from INTEL, CHAT, COIN
MUST NOT: Silo intelligence inside a single user when multiple are affected
MUST NOT: Expose VAULT contents outside NDA scope
MUST NOT: Store runtime artifacts in governance workspace

canonic-canonic

SPEC is governance. `canonic-canonic/` is the spec root.

MUST:     Keep this repo governance-only (.md/.pdf)
MUST:     Publish workspace mapping in CANONIC.git (no hardcoded repo lists)
MUST:     Preserve three primary lanes: FOUNDATION, INDUSTRIES, MAGIC
MUST NOT: Commit runtime artifacts here (runtime belongs in ~/.canonic/)
MUST:     Sell MAGIC tiers — the product, not the proof (proof is hadleylab-canonic)
MUST NOT: Embed beta-test app URLs in platform page content