PROJECT_CONTEXT.md

codegen — Project Context

Overview

• What: Meta-tooling repo that generates and installs AI-agent harnesses (Claude Code) into developer machines. Produces launcher scripts, hook systems, subagent prompt files, and scaffold templates consumed by downstream Phoenix and static-site projects.
• Location: codegen runs from different roots per machine/OS — Linux servers (production/staging, dashboard box ~/apps/codegen) and operator Macs (~/Areas/Optimum/codegen). Root is never hardcoded; scripts derive it from BASH_SOURCE. Installed artifacts land in ~/.claude/, /usr/local/bin/ (or ~/bin/) — these are install targets, not source. See context/deployment-topology.md.
• Stack: Bash + Python (generator pipeline), Elixir/ExUnit (test harness), Jinja2-like template rendering via process_template.py
• Data flow: manifest.yaml → generate.sh → rendered agent .md files → install.sh → ~/.claude/agents/, hooks, launchers

Required Platforms

required_platforms: [darwin, linux]

Canonical support-set contract: unique lowercase OS IDs matching [a-z0-9][a-z0-9-]*, non-empty. Missing, empty, duplicate, or placeholder values fail loud during shaping — a pitch touching a platform-sensitive premise MUST cover every listed ID with an acceptance row before it can reach SHAPED/Ready.. See context/shaper-discipline.md § Completeness Contract for Required-Platform Coverage Pitches.

Domain Context Files

Load this index always. Load every row whose trigger matches the prompt. Files are NOT small — mean ~19 KB, several rows ~41-44 KB; six rows at worst-case is ~60k tokens (~9% of a 200k window). Cost of a wrong-area read is one row; cost of a missing read is a stale plan. Hard cap: 6 rows.

File	Domain	Load when prompt mentions...	Update when changing...
context/core.md	Manifest + generator pipeline	manifest.yaml, generate.sh, harness install, install.sh, hook_registrations.py, codegen-build, codegen-scaffold, codegen-call, generator pipeline, manifest schema, guard_bundle_flag, config single source, yq mikefarah, npm install root, mise trust, install.sh fatal-exit, process_template include ordering, FIFO stderr capture, process substitution	harnesses/, install.sh, codegen-scaffold, templates/generator/, generator scripts, manifest schema
context/enforcement-compiler.md	Enforcement compiler (registry to hook scripts)	enforcement_compiler.py, registry.yaml, kind: denial, kind: registration, renderer-neutral regex tokens, pattern dialect, COMMAND/FILE_PATH source, hook generation, negated class, bash vs TS renderer parity, registry generated compiler-owned, compiler template regeneration, hook alphabetical ordering	shared/enforcement/registry.yaml, enforcement_compiler.py, generated no-*.sh hooks
context/harnesses.md	Claude harness specifics	claude-build, claude-debug, claude-shape, dispatch.sh, launcher, system prompt, modes, tools-header, new launcher mode, claude-ops, claude-babysit, babysit mode, drain supervisor, CLAUDE_ROLE, per-mode hook bypass, claude-experiment.sh, harness-parity launcher tests, operator vs batch divergence, transcript access, context_files, mode-context, ROLE_CONTEXT_FILES, resolve_mode_context, mode declared context, FIFO stderr capture, process substitution, stdout transparency, loop-signal-bridge, run_supervised_loop, SIGINT SIGTERM group forward	harnesses/claude/, launcher scripts, mode definitions, system-prompt-*.txt, harnesses/shared/*_test.sh launcher tests and timing fixtures
context/subagents.md	Subagent templates + roles	developer-phoenix-backend, developer-phoenix-frontend, developer-static, reviewer, codegen-commit, .md.j2 template, agent rendering, include-order contract, rule adjacency, StructuredOutput grant, flag-to-tool parity, reviewer-schema-grant-parity, json-schema unsatisfiable	shared/subagents/, .md.j2 files, agent prompt bodies, rule includes in templates
context/rules-core.md	Core discipline rules	bash-discipline, output-style, session-log, cwd-discipline, STYLE_GUIDE, INDEX.md, rule file organization, make install rebake	shared/rules/_core/*.md, shared/rules/INDEX.md, shared/rules/STYLE_GUIDE.md
context/rules-roles.md	Role-specific behavioral rules	orchestrator rules, developer rules, reviewer rules, codegen-commit, deterministic commit step, context-curator rules, never-implement, full-cycle, delegation, INCONCLUSIVE table, measurement probe, scoping guard, claim kind, state-machine exit code, case-clause order, exit-code regression test, reviewer case-source read, post-review curator gate ownership	shared/rules/roles/*.md
context/reviewer-patterns.md	Reviewer verification techniques	verifying large role-deletion, claim-ledger cross-check, reviewer audit technique, structural change verification, self-referential update check, contradiction detection, scope re-derivation	large structural pitches with claim ledgers, role/architecture deletion verification
context/curator-routing.md	Curator routing targets (this project)	curator routing, context-curator targets, where learnings go, [local] vs [shared], retrospective routing, shared vs local learning, hook-layering routing, ownership test, no owner create file, cap deny is not a split trigger	context/curator-routing.md (self), shared/rules/ layout changes
context/rules-stacks.md	Stack-specific and cross-stack rules	phoenix rules, static rules, git-readonly, result-json, LiveView patterns, ExUnit, Oban, migrations, static site stack	shared/rules/stacks/phoenix/, stacks/static/, shared/rules/shared/*
context/recipes.md	Recipe catalog	recipe, recipe INDEX, static-vite-scaffold, phoenix-feature-test-setup, oban-job-rescheduling, mox-verify-on-exit-scope, elixir-context-test-structure, nodejs-detached-process-cleanup, oban-ecto-multi-atomic-enqueue, refactor-grep-reader-scope	shared/recipes/*.md
context/usage-rules-corpus.md	Usage-rules corpus + codegen-document	codegen-document, usage_rules corpus, INDEX.md, cache-scoped, naming bijection, record format, generate_usage_rule, extract_dependencies, git fork, hex fallback, pipe-delimited, backward-compatible	codegen-document script, record format changes, function signature evolution, shared/usage_rules/
context/subagent-influence-stack.md	LLM subagent constraint layers & debugging	subagent wrong behavior, influence stack, rule violation, system prompt, Jinja includes, rules baking, delegation prompt, trigger table, recipe on-demand model	shared/rules/, CLAUDE.md, harnesses/*/hooks/, .md.j2 templates, subagent templates
context/claude-token-mechanics.md	Token budgeting, prompt caching mechanics & per-role tuning	token mechanics, context window, prompt caching, billing, Read cost, auto-compact, /context load, transcript JSONL, resident token cost, cache hit rate, token budget thresholds, token tuning, budget optimization, cost per role, Opus vs Haiku, Read discipline vs Bash grep, split rendering cost, cross-harness coordination cost, rejected optimization, subagent isolation, memory_tokens	config.yaml, harnesses/*/modes, templates/generator/, token budget thresholds, output-style.md, bash-discipline.md
context/hooks.md	Hook system (bash + tests)	PreToolUse, SubagentStop, Stop hook, Elixir orchestration loop, LoopGate, hook test, run-tests.sh, empty xargs discovery, gate-pending snapshot, core-gated hook overlap, gate verdict, hook registration, orchestrator hook bypass, resolve_role, ops bypass, per-role gate, AGENT_TYPE gate, gate-result.json verdict, codegen-log, session-log writer, marker flags, .active sentinel, positional-role, slug-class regex, session-log contract, codegen-commit, deterministic commit step, denial ledger, denial-ledger-replay, command_invokes unparseable, split_command_segments, bash -n indirection	harnesses/*/hooks/, hook scripts and test runners, hook_registrations.py, harnesses/*/hooks/orchestrator-*.sh
context/hook-authoring-patterns.md	Hook authoring patterns (how-to)	how to write a hook, SubagentStop fix-up, Stop hook authoring, hook test authoring, hooks-lib, output protocol, gate verdict flow, hook registration, transcript lag, kind: registration vs denial, hook layering, measurement vs enforcement, DENY+ALLOW, ≥14 cases, hook relocation, diff-scanning hook scope, hook porting, diff source widening, file-extension scope, scope independence, self-referential blast radius, test-fixture false-positive, denial ledger	harnesses/*/hooks/, _test.sh, hooks-lib, hook authoring
context/launcher-hook-matrix.md	Launcher mode × orchestrator-hook bypass matrix	new launcher mode, claude-ops, claude-babysit, babysit mode, drain supervisor, CLAUDE_ROLE bypass, resolve_role, AGENT_TYPE gate, orchestrator hook leak, which hook gates, per-role bypass, ops bypass, ops mode, per-mode hook bypass, hook discipline, build orchestrator gate, debug bypass, shape bypass, hook_registrations.py, signal field	harnesses/claude/hooks/launcher-hook-matrix.md, harnesses/*/hooks/, per-hook bypass profiles
context/pitch-writing-guide.md	Pitch authoring and shape-mode prose discipline	pitch, proposal, async communication, why-focused, rule rationale, launcher review, pitch path resolution, codegen/pitches, repo-relative path, abs-in-cwd path, authoring spine, output contract, split_subject, one-clause test, SUBSUMED, scope subset, bilateral deferral record, handoff gap, handoff_receipt, handoffs, stamp-handoff-receipt	codegen/pitches/draft/, pitch-format-validator.sh, ready.md.j2, pitch YAML frontmatter
context/pitch-lifecycle.md	Pitch frontmatter schema, directories, ship mechanics	pitch lifecycle, pitch frontmatter, blocks_on, Blocks-on legacy, pitch-format-validator, draft ready building shipped archive studio transcripts, Kahn topological sort, ordered_slugs, ship mv, File.rename!, claim_pitch, possession, building directory, dirty_tree_exit_code, pitch design hardcoded readers, grep reader scope, handoffs, handoff_receipt, bilateral deferral record, cross-pitch ownership, reconcile_handoffs, write_handoff_receipt, archive preserves recovery dossier, recovery ref retention, reader inventory, resolve_pitch_source, pitch_arg_for, stranded claim reconciled at startup	codegen/pitches/ lifecycle state, scope/evidence/history, pitch-format-validator.sh + .ts twin, test_harness/lib/codegen_test_harness/loop_queue.ex, test_harness/lib/mix/tasks/codegen.pitches.scope.ex, test_harness/lib/mix/tasks/codegen.loop.ex
context/scaffold.md	Scaffolding for downstream apps	scaffold.sh, eex_render, mutations, AGENTS.md.j2, PROJECT_CONTEXT.md.j2, ocg setup, codegen-scaffold, generated-app git repo, GIT_CEILING_DIRECTORIES, clean initial commit, downstream app scaffolding, static SEO baseline, vite publicDir, robots.txt	codegen-scaffold, shared/scaffold/, .j2 template files, app scaffold templates, shared/apps/, generated-app git initialization/commit, static vite SEO
context/scaffold-mutations.md	Scaffold mutation scripts + guard tests	scaffold mutations, guard test discovery, credo cleanup, portable sed, eex_render postcondition, mutation flag discipline, PageController route strip, mutation unit tests, app_module derivation, SCHEMA_VERSION staleness, clean-tree fixture baseline	shared/scaffold/mutations/, mutation scripts, credo_fix.sh, eex_render.sh
context/test-coverage.md	Per-language test coverage tooling + gaps	test coverage, coverage gaps, what tests exercise X, untested paths, test inventory, ExCoveralls, c8, vitest, istanbul, kcov, coverage.py	context/test-coverage.md (self)
context/test-harness.md	ExUnit test harness for stacks (suite, not the engine under test)	test_harness, test-stacks, last_green, record-green.sh, stack scaffold test, clean fixture baseline, prepare_codegen_build_baseline, ExUnit max-cases, ExUnit assertions, role resolver, orchestration loop, mix codegen.loop, mix codegen.loop.queue, mix codegen.pitches.scope, LoopGate, LoopQueue, LoopQueueDrain, claude-build --queue, flake triage, hermetic regression guards, scope: frontmatter, post-review curator gate ownership	test_harness/, install round trips, fixture baseline/git preparation, ExUnit tests (*_test.exs), last_green.json, role_resolver.ex
context/test-harness-pitfalls.md	ExUnit/fixture/seam/flake test gotchas (test-authoring seam, distinct from test-harness.md's suite inventory)	test harness pitfall, exunit fixture, seam override, flake triage, event-hardened fixture, owned PID/PGID cleanup, empty BSD xargs, clean scaffold baseline, ecto timestamp, port env charlist, npm extension race, role resolver ripple, seam threading, test-seam bypass coverage gap, invoke_fn codegen_call_fn, acceptance bar integration fixture, build path isolation, mix build path, Mix.shell, capture_io stdout, arity beam stale, capture_io return value, exit-code assertion, state-machine exit constant, test refactoring state change, engine build isolation, spawn env clear, UndefinedFunctionError phantom, static ordered_fn livelock, drain re-ships forever, ExUnit.TimeoutError red herring	test_harness/ fixtures/install tests, seam signatures, flake-prone tests, clean-tree baselines, process cleanup/readiness, MIX_BUILD_PATH assignment, per-purpose build paths, spawn boundary env clear
context/shaper-discipline.md	Shape-mode authoring discipline (Rules A–J)	shaper rules, ask-vs-decide, deferral-with-draft, decompose-then-split, derive-and-write edges, Rules A–J, shape mode discipline, sweep-class, completeness contract, full-vocabulary sweep, producer/verifier reconciliation, operator-owned surface, user-facing surface removal, keep-vs-remove fork, BREAKING disposition, closed vocabulary, split tripwire, standalone-promise test, THESIS-DEFEATING DEFERRAL, delegated enumeration, codegen-call, spike-builder, spike SETS, negative control, contract-declaration-site completeness, capability-removal reachability, incomplete replacement, WIRED RECONCILED PRESERVED, born-dead code, proxy probe, empirical-usage-grounding, format/syntax-change consumer completeness, opaque reader, probe-completeness, recursive ledger, sub-surface, ready hand-off, ready auto-loop, orchestrate not investigate, round ceiling	context/shaper-discipline.md (self), shared/prompt-fragments/_authoring-spine.txt, shared/prompt-fragments/_probing.txt, harnesses/shared/prompt-bodies/shape.txt, harnesses/claude/commands/ready.md.j2
context/test-monitoring.md	Long-test progress monitoring patterns	test monitoring, make test-stacks progress, background test, pgrep poll, tail -f log, non-blocking test run, watch test output	context/test-monitoring.md (self)
context/test-benchmarking.md	Benchmark mode (BENCH=1) artifacts + viewer + role-model-binding campaigns	BENCH=1, REASON, benchmark capture, screenshot, bench artifacts, mix codegen.bench, summarize.js, JSONL harness_summary, last_green.json coexistence, playwright, agent prohibition, make bench, make test-stacks BENCH, human-operator discretion, benchmark-coverage, makefile-targets, bench-prereqs, bench-preflight, spend-free gate, zero-model check, role-model-sweep, role-model-binding, candidate model, binding campaign, fixed binding, dispatch provenance, campaign matrix, role_model_sweep	test_harness/bench/, bench_artifacts.ex, BenchMetrics, bench viewer mix tasks, role_model_sweep.ex, codegen.bench.role_model_sweep.ex
context/development.md	Dev workflow + make targets	make install, make test, mix-build-path-parity, one build root one MIX_ENV, core-gated tail overlap, TAIL_OVERLAP_MIN_CORES, EXUNIT_MAX_CASES, make test-stacks, CI/CD, Makefile, contribution, README, env vars, harness-parity, parallel harness-parity, launcher tests, exact-once population, dev loop, tech stack, coding conventions, developer-no-self-gate, test budget, rule-anchor-check, seam-registry anchor text, undocumented gate	Makefile test scheduling/targets, templates/generator/run-all-tests.sh, README.md, STYLE_GUIDE.md, .env.sample, CI workflows, harnesses/shared/*_test.sh
context/bash-patterns.md	Bash stub/test isolation patterns (PATH-stub leakage, RED-then-GREEN proof idiom)	stateful stub, counter file, test isolation, RED-then-GREEN proof, bash test patterns, ambient env leakage, CLAUDE_ROLE, git show, dirname sourcing, PIPESTATUS, jq null safety, yq null safety, portable sed, macOS symlink, grep footguns, PATH stub, pathname expansion, noglob, set -f, hook deletion full-vocabulary grep, run-tests.sh not a registered hook, zsh completion bash -n misparse, newline-list membership testing, os.path.relpath symlink resolution, mise trust records, scaffold makefile printf tabs, module-scope case block variables, test discovery harness parity wiring, bash test set parity relative paths, bash module organization hook-manifest, launcher flag pre-processing, trailing defaulted positional arguments, stub heredoc exit code control, printf hyphen prefix escape, jq filter rebinding select	harnesses/claude/hooks/codegen-propose_test.sh, harnesses/claude/hooks/lib/hooks-lib.sh, context/bash-patterns.md, context/hook-authoring-patterns.md
context/repo-structure.md	Repository artifact ownership & structure	repo layout, structure, where does X go, file tree, top-level files, codegen root, which directory, where to add, artifact location, file organization, repo anatomy, ocg vs codegen-build, codegen-scaffold, ai-agents orphaned, self-meta codegen/, codegen/logging, context vs templates, shared vs templates, bin/ utilities, CLAUDE.md symlink, AGENTS.md source, codegen-propose, analysis-proposals, proposed-change record, turn-waste to proposal, scaffold schema version, per-app manifest, staleness preflight, codegen-build refuse, SCHEMA_VERSION, codegen-advise	harnesses/, shared/, templates/, test_harness/, top-level scripts/directories, codegen-scaffold, .gitignore, Makefile scheduler/target changes
context/deployment-topology.md	Deployment locations, path derivation, multi-location topology, multi-node fleet drain (codegen-drain), fleet-safe dependency-bound assignment	deployment, server, prod, staging, dashboard box, Hetzner, CODEGEN_DIR, OCG_CODEGEN_DIR, hardcode, BASH_SOURCE, multi-location, install target vs source, codegen root, where does codegen run, three-repo ordering, context codegen platform, worktree cwd ephemeral, codegen-drain, drain-nodes.yaml, possession, fleet, multi-node, ssh lands as root, ssh -n, stdin ownership, run_as, .incoming, quiescence gate, scp -p, watcher column, watcher probe, pgrep self-match, argv scanning, queue.lock, liveness probe, watcher=yes watcher=no, assign --auto, lane to node, auto-partition, --json partition, codegen.pitches.scope --json, reachable_nodes, CODEGEN_DRAIN_SCOPE_CMD, building column, building_count, claimed pitch, in-flight count, health verdict, box health, box_probe_cmd, classify_health, wedged, orphaned process, ppid 1, probe_fail, probe_ok, slug_confidence, git head behind ahead dirty, fleet supervisor, codegen_drain_log_stale_secs, codegen_drain_role_max_etime_secs, fleet_snapshot, fleet_probe_cmd, PROBE_DONE, inventory_nodes, dependency_preflight, DEPENDENCY-BOUND, dependency_bound, fleet_partition, --fleet-safe, --externally-referenced, dependency chains stay local, strand dependent, targeted assign refuses, complete fleet topology, fail-closed fleet snapshot, handoff_receipt fleet transfer, bilateral handoff record, recovery-bound assignment, cross-node recovery-bound refusal, refuse_if_recovery_bound, recovery dossier, recoveries/, recovery ref, dossier/ref transfer unsupported	harnesses/, install.sh, context/deployment-topology.md (self), codegen-drain
context/fail-closed-posture.md	Fail-closed enforcement + anti-wedge exceptions	INCONCLUSIVE classification, two-signal pre-commit-guard, anti-wedge fail-open survivor, best-effort sidecar pattern, test comment drift, confinement guard scope, fail-loud exemptions, static-site-build-check, classify_orientation_violations, all-or-nothing partition, mixed violation set, orientation-doc repair routing	pre-commit-guard.sh, subagent-read-discipline.sh, build-agent-app-confinement.sh, build-worker-cwd-guard.sh, orchestrator-no-source-edit.sh, shared/scaffold/phoenix/scaffold.sh, persistence helpers with optional observability
context/loop.md	The Elixir orchestration loop engine (single-cycle build driver)	orchestration loop, OrchestrationLoop, mix codegen.loop, BuildLock, BuildSignalHandler, warm-resume, resume checkpoint, escalate_model, max-budget-usd, spend cap, infra abort, LoopGate, gate verdict, LLM vs deterministic, curator doc check, index-parity, factcheck, ev:learned routing, duration_ms, telemetry, terminal marker, terminal-state.json, terminal cause, terminal reason, BEAM OS PID, CODEGEN_BUILD_INVOCATION_ID, gate failure owner, flake check, role-model-binding.json, dispatch provenance, InterruptedCycleRecovery, build-result.json, recovery dossier, reconciliation_required, recovery preflight, materialize, recovery_mode, park_failure, run_orientation_preflight, classify_orientation_violations, orientation-doc violations, curator-writable doc, maybe_advise, advisor_plan, codegen-advise, born-dead detector, defer-marker, test-coverage deletion floor, TestCoverageFloor, test-deletion-exempt, whole-pitch builds, codegen-commit, deterministic commit step, claim_source_after_reconcile, resolve_pitch_source, pitch_source_at, sibling_live_state_source, argv_slug, stale pitch source, building probe inventory, no commit subject available, stranded claim reconciled at startup	test_harness/lib/mix/tasks/codegen.loop.ex, test_harness/lib/codegen_test_harness/orchestration_loop.ex, loop_gate.ex, build_lock.ex, build_signal_handler.ex, interrupted_cycle_recovery.ex, born_dead_detector.ex, test_coverage_floor.ex
context/loop-queue-drain.md	Multi-pitch queue drain engine	LoopQueueDrain, queue drain, codegen.loop.queue, --queue, build-queue.sh, ordered_slugs, blocks_on, transient?, watchdog timeout, pitch_budget_secs, CODEGEN_BUILD_QUEUE_BUDGET_USD, CODEGEN_BUILD_QUEUE_PITCH_BUDGET_SECS, CODEGEN_BUILD_QUEUE_MAX_CONSECUTIVE_FAILS, circuit breaker, queue-fail branch, handle_exit_zero, false-0, ship verification, terminal marker, terminal-state.json, terminal_marker_fn, blind retry, deterministic exhaustion, draft_fn, skeleton draft, document-system-prompt, drafted_count, publish, git_publish_fn, publish_preflight_fn, publish_or_halt, recovery branch, park_published_commit, unpublished commit, git push, git rebase, babysit push, watched node, exit 4, dirty_tree_exit_code, handle_exit_dirty_retired, building/, claim_pitch, possession, ship-with-warning, auto-demotion, build_failures, demoted_from, demote_reason, status SHAPING, Build failure history, record_build_failure, write_demotion, write_build_failures, build_failure_evidence, format_failure_row, failure_owner_phase, escape_history_cell, truncate_summary, resolve_pitch_path, dependents_of, CODEGEN_BUILD_QUEUE_MAX_PITCH_FAILS, max_pitch_fails, demote pitch back to draft, load_deps_fn, ensure_decode_deps, Jason unloaded, UndefinedFunctionError, boot-time force-load, Code.ensure_loaded, decode dep, resident module, beam churn, stale _build queue crash, failure_summary, terminal_reason fallback, terminal_cause, empty result evidence, undiagnosable exhaustion, gate clear result empty, classify_drain_failure, format_failure_block, ship_not_verified, transient_exhausted, gate_failed, gate_never_ran_this_cycle, stale clear verdict cause, failure cause, contradiction warn, failure block, InterruptedCycleRecovery, reconciliation_required, recovery preflight, queue startup recovery, prioritize_recovered_slug, reconcile_opts, state.recovery, stranded building claim, park_failure, record_park_history_row, finish_park, duplicate history row, recovery dossier, queue-fail dossier, startup parks stranded claim, ordinary order precedence, recovery informational, record_counted_history, context-free counted write, crash-looping drain, uncounted interrupted attempt, max_pitch_fails_from_env, pitch_arg_for, child pitch argument, relaunch names building, expected_slug adhoc, build-result mismatch, append_history_row, byte offset grapheme slice, binary_part, history row corruption, queue-fail dossier pitch_path	test_harness/lib/codegen_test_harness/loop_queue_drain.ex, loop_queue.ex
context/cycle-record.md	Cycle log (codegen-log), gate-pending artifacts, gate verdict truth table	codegen-log, cycle log, gate-pending, gate-result.json, cycle-state.json, write_gate_result, derive_verdict, verdict truth table, extract_witness, witness fallback, doc-shaped witness, context-index-parity witness, witness discipline, gate-verdicts.jsonl, graded_tree_sha, ev kinds, .active sentinel, no git-tracked logs, no cross-box log transport, recovery dossier, dossier stages, machine-local gitignored ephemeral artifact, recoveries//.json, schema_version, transaction identity, timeline, wall_ms, unaccounted_ms, preflight-timings.jsonl, cycle-summary.jsonl, emit_loop_telemetry, build_timeline, where did the time go, codegen-log init, codegen-log verdict, codegen-log exit, codegen-log committed, codegen-log show, ev waiver, jq canonical reader forms	harnesses/claude/hooks/lib/gate-result.sh, codegen/gate-pending/, codegen/logging/
context/call-contract.md	Call envelope contract	call envelope, codegen-call contract, result.status, retry_meta, session_id null, harness asymmetry, transient error, LoopQueue.transient?, call-dispatch.sh, usage block, cache_read_input_tokens, metrics field, ajv schema validation, stream idle watchdog, watchdog cause, late result event, MCP server child, process group, guardian, orphan cleanup	harnesses/claude/call-dispatch.sh
context/role-config.md	Role→model/effort/tools config, escalation ladder	config.yaml, role model mapping, escalate_model, escalate_effort, fallback rung, switch_model_reason, tool_map, RoleResolver, per-role effort, harness block, load-role.sh, thinking_tokens, ROLE_THINKING_TOKENS, MAX_THINKING_TOKENS, role-model-sweep, fixed binding suppression, campaign arm	templates/generator/config.yaml
context/turn-waste-analysis.md	Turn-waste analysis (codegen-analyze/codegen-propose)	codegen-analyze, codegen-propose, turn-waste, wasted turns, COUNTER_CONFIDENCE_PRIOR, DROP_COUNTERS, COUNTER_FIX_TYPE, analysis-proposals, forbidden_bash counter, re_read counter, context_missed counter, subagent_interruption dropped	analysis/, codegen-analyze, codegen-propose
context/port-allocation.md	Port allocation (resource_manager.sh)	resource_manager, port allocation, ~/.ocg/resources.json, mkdir lock, worktree port, playwright port, phoenix port, global registry, TARGET_REPO_PATH	resource_manager.sh
context/slash-commands.md	Slash commands (Claude custom commands)	slash commands, /command, /document, /rule, /release-new-version, /poke-holes, /ready, /babysit, commands_source, commands_dir, install_commands, prompts_dir, prompts_source, handoff reconciliation, stamp-handoff-receipt, bilateral handoff record, handoff_receipt fleet transfer	harnesses/claude/commands/
context/downstream-docs.md	Downstream AGENTS.md/CLAUDE.md rendering (shared/apps/)	shared/apps, AGENTS-phoenix.md.j2, AGENTS-static.md.j2, downstream AGENTS.md, downstream CLAUDE.md, rule-render-freshness, committed symlink, scaffold docs render	shared/apps/
context/size-governance.md	Size governance (byte caps, line caps, budget gates)	40960 byte cap, context file cap, curator-context-size-gate, prompt-size-budget, prompt_size_budget.py, prompt-budgets.txt, STYLE_GUIDE line cap, size governance, retire compact action, cap deny not split trigger, per-domain budget	templates/generator/prompt-budgets.txt, harnesses/claude/hooks/curator-context-size-gate.sh

Always Load

Tier-0 foundational docs — the launcher loads these on every shape session regardless of pitch content. Basenames only; launcher resolves each to context/<name>. Keep this list short (foundational orientation only).

• repo-structure.md
• core.md
• pitch-writing-guide.md

Generator Pipeline

Module	Purpose
templates/generator/generate.sh	Entry point — renders .md.j2 templates for a given harness
templates/generator/process_template.py	Jinja-style {% include %} processor — inlines rule files into agent prompts
templates/generator/hook_registrations.py	Writes settings.json hook entries from hook source dir
templates/generator/manifest-lib.sh	Bash lib for parsing manifest YAML fields (wraps yq)
templates/generator/config.yaml	Role/model/effort/tools mapping; read by load-role.sh (debug/shape/ops) and directly via yq by build dispatch
install.sh	Manifest-driven install loop — reads manifest fields (paths, dirs); hardcodes its own install phases directly (install_steps:/uninstall_steps: manifest fields are declared but read by nothing); defines content_stable_cp
uninstall.sh	Removes installed artifacts; hardcodes its own removal phases directly (does NOT read manifest uninstall_steps:)
codegen-build	Top-level launcher: requires --harness flag; delegates to harnesses/<harness>/dispatch.sh, which always drives the deterministic Elixir orchestration loop
codegen-scaffold	Scaffolds a new downstream app from shared/scaffold/ templates — subcommands create (full scaffold) and integrate (symlinks only)
codegen-call	One-shot structured LLM call binary: requires --harness, --model, --effort, --system-prompt
codegen-advise	Same-harness stronger-model advisor: fixed claude_code → claude_code/opus mapping, wraps codegen-call, {plan, confidence} out
config.sh	Shared env/path config sourced by all scripts
resource_manager.sh	Global port allocator (~/.ocg/resources.json) — see context/port-allocation.md; NOT an install-artifact tracker, NOT sourced by install.sh/uninstall.sh
utils.sh	Common bash utilities: OCG_CMD only; content_stable_cp is in install.sh
update_ai_tools.sh	Updates Claude CLI and other AI tool deps after install

Integration Points

• Downstream apps: consume installed agents (~/.claude/agents/*.md), hooks (~/.claude/hooks/*.sh), and launchers (claude-build) — not this repo directly
• Claude Code: hooks registered in ~/.claude/settings.json via hook_registrations.py; agents discovered from ~/.claude/agents/
• test_harness: ExUnit suite in test_harness/ validates scaffold output — runs mix test against generated apps

Environment Variables

Variable	Purpose	Notes
CODEGEN_DIR	Absolute path to this repo	Set by launchers
INSTALL_DIR	Where launchers land (/usr/local/bin etc.)	Default: ~/bin
ZSH_COMPLETION_DST	Zsh completions install path	Set in config.sh
ANTHROPIC_API_KEY	Claude API key	Not required — Claude Code authenticates via CLI OAuth (~/.claude.json); dispatchers unset it for hermetic builds
CLAUDE_MODEL	Override default model per mode	Optional