agent-bios 0.1.0

package/codex/guides/cli-multi-model-workflow.md

@@ -0,0 +1,194 @@
+---
+guide_id: cli-multi-model-workflow
+language: en
+status: active
+use_when:
+  - work spans multiple models or CLI agents
+  - a handoff crosses a context reset, or parallel worktree branches run
+  - running unattended LLM batches or orchestrated subagent fleets
+  - allocating tiers, spawning subagents, or planning model switches
+  - resuming a halted staged pipeline or writing a handoff
+---
+
+# CLI Multi-Model Workflow
+
+Scoped extension of the global Multi-Model Workflow rules. Rules use portable role slots; only **Driving Codex CLI Directly** and **Environment Binding** name concrete tools or models.
+
+## When To Use
+
+- Use for multiple models/agents, handoffs across clear/new sessions, unattended fleets, or parallel worktrees. Routine auto-compaction is not a handoff.
+- Skip single-session, single-model work with no handoff.
+
+## Role Slots And Tiers
+
+- FRONTIER: hardest bounded design, authority-changing decisions, triage, final verdicts.
+- HELM: standing main/judgment seat; orchestration and bounded escalation.
+- WORKHORSE: implementation volume and per-item judgments. SWEEP: cheap wide reads, candidate finding, mechanical passes.
+- VERIFIER-A/B: different review kinds, preferably cross-family. INDEPENDENT-PR-REVIEWER: final review from a different family than the author.
+
+- Bind concrete models in Environment Binding and allocate by **difficulty × blast radius**. The main defaults to HELM; first-of-kind/authority-changing mains use FRONTIER at a session boundary; trivial work stays direct.
+- Apply the same allocation to subagents. Prefer spawning a bounded FRONTIER judgment over switching the loaded main; a context cannot switch its own model.
+- Keep architecture, interfaces, scope, tradeoffs, and user-facing decisions in the main. Delegate volume work.
+- A cheaper implementation tier requires stronger verification; never economize on both.
+
+## When To Spawn
+
+Main-context pollution is usually costlier than spawn overhead. Apply these gates in order; the first that fires decides:
+
+1. **Independence:** verification or review always spawns; isolation is the purpose.
+2. **Parallelism:** independent items spawn in parallel with per-item tracking.
+3. **Residual context:** spawn work whose working log is much larger than the conclusion the main needs, such as broad reads, searches, tests, or implementation bursts.
+4. **Specifiability:** keep work local when it needs the main's live context or unresolved round-trips, especially deep debugging. Grind alone is not a FRONTIER reason.
+5. **De-minimis:** do work directly when its dispatch packet would be larger than the work.
+
+- Escalate by spawning FRONTIER first; switch the main only when the judgment is not delegable.
+- Every spawn gets a bounded report contract, artifact paths instead of pasted context, and an explicit model/effort pin. Never dump a worker transcript into the main.
+- Explicit no-fan-out overrides standing authorization.
+
+## Delegation Mechanics And Teammate Persistence
+
+Delegate execution, not decisions. A unit is delegable only when it is decision-complete, self-containedly specifiable, machine-checkable at done-when, and bounded in blast radius.
+
+- Re-cut units containing unresolved choice, discovery-before-spec, untestable completion, or unfrozen interfaces. A worker asking which direction to take is a sizing failure; the decision returns to the main.
+- Bundle related sub-floor tasks up to the decision-complete ceiling. A scout is read-only and reports file:line evidence for named pending decisions, probing the highest kill-risk unknown first.
+- Prompt constants, thresholds, signatures, and judgment criteria are decisions even when stored in code. Discard decision-tainted worker output when review would cost more than a clean re-dispatch.
+- Worker cost grows with request count × transcript prefix. Batch independent reads, minimize edit rounds, and dispatch independent workers/messages together.
+- Use a resident teammate only for dependent slices in one burst. Verify that the CLI preserves its model and context; resume-after-completion may silently change both. Retire after the burst or cache TTL, and persist durable knowledge in files.
+- After a discard or direction change, respawn once a routine round costs about as much as a fresh slice. Recover unique in-flight state to files first.
+- Redirects to busy workers may queue rather than preempt. Check artifacts before destructive redirects, phrase them conditionally, and stop an actively harmful worker by scoped PID/worktree authority.
+- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. Cross-reset state belongs in files, not task boards or transcripts.
+- Review cost scales with the diff, so layered review preserves delegation savings. Lower reviewer tier before dropping a review kind.
+
+## Driving Codex CLI Directly
+
+Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a hermetic worker; put required hermetic rules in its prompt/schema.
+
+| Profile | Reach | Use |
+|---|---|---|
+| inherit | real `CODEX_HOME`, project cwd | full global/project AGENTS.md and user config |
+| hermetic | temporary home, auth only, user config ignored | independent lens with prompt-owned criteria |
+| custom | caller-populated home | exact curated instructions/config |
+
+- Control instruction home, working directory, config overrides, task prompt, and output schema independently. The repo wrapper owns setup and teardown.
+- Inherit review is discipline-aware; hermetic review is an independent kind. Confirm reach with a contrast phrase from AGENTS.md before trusting independence.
+- Concrete flags, versions, sandbox defaults, and dispatch bindings live in Environment Binding.
+
+## Default Frame
+
+| Stage | Owner | Artifact / exit |
+|---|---|---|
+| 0 Triage | current session | difficulty/blast-radius call; dials fixed |
+| 1 Design | FRONTIER | dated design with measured background, done-when, concept map, allocation; owner approval |
+| 2 Design verify | VERIFIER-A+B | findings union and revision; zero material issues |
+| 3 Implement | WORKHORSE | smallest viable diff; deterministic gates green |
+| 4 Implementation verify | SWEEP → WORKHORSE → FRONTIER | at least two reviewer kinds; strongest model on verdicts |
+| 5 PR review | INDEPENDENT-PR-REVIEWER | clean cross-family review |
+| 6 Merge verify | implementing session | freshly fetched merged state green |
+| 7 Close | current session | docs/handoff synced; no silently parked items |
+
+- A T1+ kickoff names the session model, orchestration authorization, this guide, and main-as-orchestrator delegation mode.
+- T0 mechanical/low-risk uses stages 3→4 (→5 for shared merge); T1 normal work uses the full skeleton with a lightweight design; T2 authority-changing/first-of-kind/release work raises design and verdict review.
+- Put stage transitions on context-reset boundaries so model changes are free and the design doubles as handoff. Keep a loaded session only when live state is load-bearing.
+- Apply the **convergence heuristic by reviewer kind**: same-kind convergence raises confidence but shares blind spots; different-kind divergence is expected, so act on the union.
+- If verification broadens the issue boundary, return to design and re-triage; the second identical loopback stops for owner choice. Halts resume from valid artifacts. Persist per-item outcomes.
+
+## Model Switching And The Prompt Cache
+
+- Prompt caches are per model; each mid-session switch reprocesses the loaded transcript once. Batch work by model and switch at reset boundaries.
+- Prefer a spawned FRONTIER decision. Switch the main only when context fidelity outweighs handoff cost and the judgment cannot be delegated.
+- Avoid unplanned alternation. Planned escalate/return and explicit A/B comparisons are valid when each cache miss is budgeted.
+
+## Cross-Verification Economy
+
+- Once cross-verification is warranted, keep kind diversity and tune effort first. Losing a kind loses an error class.
+- Run deterministic gates before LLM review. Funnel SWEEP finders → WORKHORSE judgments → FRONTIER triage/verdicts.
+- On family collapse, record the downgrade and label clean verdicts PROPOSED until diversity is restored.
+- A silent/dead lens is incomplete, never clean. Confirm liveness from usage/error/report evidence; rerun, swap provider, or report PROPOSED.
+
+## Unattended Batch Safety
+
+- The parent owns per-item completion and a **code-level circuit breaker**. For dispatchers you do not control, verify equivalent protection or attend the run.
+- Default breaker: halt after 3 consecutive cross-item provider limit/auth/transport failures after bounded backoff. Persist undone items and alert or swap provider.
+- Item-specific failures are poison items: cap at 2–3 attempts, then dead-letter them as complete-with-failure. Resume only unfinished/invalid items; whole-batch reruns require cheap idempotence.
+- Persist per-item outcome, token, and cost records for recalibration.
+
+## Halt And Resume
+
+- Resume-first from artifacts that parse, pass schema, and match their recorded source/config/HEAD fingerprint; unverifiable means invalid.
+- Resubmit one invalid unit unless failures are broadly correlated, which is structural and halts the run.
+- Treat halt→continue as normal operation.
+
+## Sessions, Branches, Worktrees
+
+- Sessions bind to their starting directory. Use the CLI's native relocation/resume mechanism; never copy transcript files.
+- For a new worktree, relocate natively or write a handoff and start fresh. Re-integrate branches serially and re-verify after each merge.
+- Mark superseded worktrees/handoffs dead so later resume cannot select them.
+- After resume/clear/relocation, verify pwd, branch, and HEAD against the pinned handoff before acting.
+
+## Handoff Contract
+
+Write for the next agent and re-verification, not narrative. Required content:
+
+1. One-line current state.
+2. Pinned worktree, branch, HEAD, upstream/merge-base, author tier, and active fallback/family collapse.
+3. CONFIRMED claims whose cited command or anchored file evidence independently re-establishes them.
+4. Separate PROPOSED/OPEN items, including inherited claims not re-verified this session.
+5. Ordered next actions and the literal first command: model, orchestration authorization, and guide load for T1+.
+6. Credentials only by env-var/gitignored slot; scrub secrets from excerpts and commands.
+
+- A broken evidence anchor demotes CONFIRMED to PROPOSED. If pinned state fails or no trustworthy handoff exists, rebuild from source artifacts and write a fresh handoff before acting.
+- Store handoffs in the working repo's isolated dated docs path, never this instruction-SSOT repo. Re-verify load-bearing claims on resume.
+
+## Environment Binding (edit per environment)
+
+This is the human-readable projection of concrete models/tools; `config/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
+
+Binding (2026-07-13):
+
+| Slot | Binding | Notes |
+|---|---|---|
+| FRONTIER | Claude Fable 5 · GPT-5.6 Sol (read-only; max default, task-fit effort including Ultra) | bounded hardest decisions and verdicts |
+| HELM | Claude Opus 4.8 (xhigh) · GPT-5.6 Sol (xhigh main; main Ultra requires explicit selection; bounded FRONTIER Ultra allowed) | standing main; Codex defaults bypass, explicit sandbox narrows |
+| WORKHORSE | Claude Sonnet 5 · GPT-5.6 Terra (high) | implementation and per-item judgment |
+| SWEEP | Claude Haiku 4.5 · GPT-5.6 Luna (low) | clear repeatable scans and mechanical work |
+| VERIFIER-A | onto-mcp review | logic/authority kind; tier units per funnel |
+| VERIFIER-B | `ultracode-for-codex` CLI v0.4.5 (Codex-backed; callable from Claude or Codex) | code/execution kind |
+| INDEPENDENT-PR-REVIEWER | Codex CLI | adversarial `gh pr diff` review |
+| Claude relocation | EnterWorktree, `/cd`, `--worktree`; resume is directory-scoped | verified 2.1.207 |
+| Codex relocation | `codex resume` (cwd-filtered; `--all` lifts), fork | verified 0.144.1 |
+| Claude teammate | named mailbox continuation; completed-agent message may cold-rerun on main model | keep resident; avoid completed resume |
+| Rate-limit fallback | OpenAI limited → VERIFIER-A on Anthropic; Claude limited → VERIFIER-B on Codex | record family collapse |
+
+Codex direct-drive (verified 0.144.1, 2026-07-12):
+
+- `codex-helm` defaults the HELM main to `--dangerously-bypass-approvals-and-sandbox`; explicit `--sandbox` wins in any flag order. Non-Ultra defaults native multi-agent off; explicit main Ultra defaults it on.
+- HELM is instructed to dispatch tiers through internal `codex-run`, which pins model/effort/sandbox. FRONTIER uses a separate `gpt-5.6-sol`, read-only root: max by default, Ultra for divisible work, lower effort when cost/latency dominates. Nested multi-agent is enabled only for Ultra. Native `codex exec` spawn cannot pin role/effort.
+- This is an instruction-backed, live-E2E-verified default, not a security boundary: main bypass and arbitrary expert `-c` remain available by design. `frontier.toml` omits fixed effort for native surfaces that accept overrides.
+- `codex-run` owns reach, stdin, schema, profiles, expert `-c`, channel preservation, and exit status. Keep it internal.
+
+Dispatch packets:
+
+| Target | Required packet / default |
+|---|---|
+| GPT-5.6 Sol FRONTIER | outcome, evidence, decision boundary, stop/verification; task-fit effort; read-only |
+| GPT-5.6 Terra WORKHORSE | outcome, frozen scope/inputs, authority, done-when, evidence/report, escalation; high |
+| GPT-5.6 Luna SWEEP | exact search space, rules, ambiguity behavior, stop, output; low; no architecture/debugging |
+| Claude Opus 4.8 HELM | xhigh for agentic work; high minimum for sensitive judgment; lower only when bounded/cost-led |
+| Claude Sonnet 5 WORKHORSE | exact scope, apply-to-all rules, tools, verification, report; high default |
+| Claude Haiku 4.5 SWEEP | closed, high-volume, latency-sensitive work with exact schema/examples |
+
+Use only task-relevant tools; parallelize independent calls. Worker report: `status`, `files_or_items_touched`, `evidence`, `verification`, `risks_or_escalations`. Official basis: OpenAI [model](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.6), [migration](https://developers.openai.com/api/docs/guides/upgrading-to-gpt-5p6-sol), [prompting](https://developers.openai.com/api/docs/guides/prompt-guidance-gpt-5p6), [Codex models](https://learn.chatgpt.com/docs/models); Anthropic [subagents](https://code.claude.com/docs/en/sub-agents), [model effort](https://code.claude.com/docs/en/model-config).
+
+## Evidence Base
+
+Single owner of numeric defaults; one production environment, 2026-07. Recalibration updates this table and dependent inline thresholds.
+
+| Evidence | Result / rule supported |
+|---|---|
+| 15 sessions, 3,758 requests, 10 switches | switches consumed 13.9% of uncached input; avoid unplanned switching |
+| 285-call limit incident | 208 post-limit dispatches and 34/35 lost items; breaker default 3 |
+| 99 staged reviews | 15.2% halted after most compute; resume-first |
+| three-task delegation probe | batched worker 5 requests/$0.23 vs loaded FRONTIER direct 6/$3.35; cache TTL 5 min; completed resume cost 2–5× |
+| two live delegation sessions | tiering saved ~3.3×; discarded prefixes made fresh respawn cheaper; unpinned reviewers inherited FRONTIER |
+| Codex reach contrast | inherit ~16.5K vs hermetic ~8.7K tokens; schema and stdout/stderr contract verified |
+| Codex native-spawn probe + HELM E2E | requested max/Ultra native children recorded xhigh/role null; separate read-only roots recorded max and Ultra successfully |

package/codex/guides/coding-staged-workflow.md

@@ -0,0 +1,70 @@
+---
+guide_id: coding-staged-workflow
+language: en
+status: active
+use_when:
+  - meaningful development work needing execution depth, review loops, and stop conditions
+  - architecture changes, new features, cross-module or ontology changes, review-driven fixes
+  - the user asks to design ("설계") before implementation
+  - judging materiality of review findings and deciding when to stop or redesign
+  - choosing the per-domain verification mix (code, ontology, config/data, spreadsheets, docs)
+---
+
+# Coding Guidelines: Staged Workflow
+
+This guide is a scoped extension of the global Coding Guidelines. Use it for meaningful development work to choose execution depth, review loops, and stop conditions.
+
+It operates inside the existing global rules for requested scope, concept economy, LLM/tools/code boundary, verification discipline, and documentation hygiene.
+
+For trivial edits, use the lightweight inspect-edit-verify path from the global Coding Guidelines.
+
+When the user asks to "설계" or design, stay in design mode. Focus on high-level design and implementation-process design, then present the plan, tradeoffs, review gates, and implementation trigger. Move to implementation after the user asks to implement or approves the plan.
+
+## When To Use
+
+- Use this workflow for architecture changes, new features, cross-module behavior changes, ontology changes, review-driven fixes, or work that affects user-visible behavior, authority, lifecycle, validation, failure handling, or roadmap commitments.
+- Use the lightweight path for small text edits, narrow config changes, or single-file adjustments whose completion criteria and verification are obvious.
+- Increase workflow depth when new evidence shows broader risk than the initial request suggested.
+
+## Stages
+
+1. High-level design: define the goal, scope, architecture direction, affected concepts, tradeoffs, and completion criteria.
+2. Implementation-process design: turn the design into an ordered work plan with dependencies, verification points, review gates, and redesign triggers.
+3. Implementation: make the smallest viable functional changes that satisfy the approved design and process plan.
+
+## Review Loop
+
+- At each stage, run review loops as appropriate: self review, subagent review when available, and structured multi-lens review when the repository or domain supports one (concrete tool: Environment Binding below).
+- Iterate until material issues reach zero: review, identify material issues, fix them, and review again.
+- Use the severity contract for materiality — the canonical definition is the ladder below; external review tools map their levels onto it: blocker, high, and medium are material; low and info are non-material.
+- Treat blocker as primary happy-path or core-contract failure.
+- Treat high as supported user, environment, data, or execution path failure.
+- Treat medium as meaningful weakening of trust, auditability, reproducibility, completeness, or decision quality.
+- Treat low and info as non-blocking unless requested or promoted by new evidence.
+
+## Verification Menus
+
+Per-domain menus for the global Verification Discipline loop; pick the narrowest reliable mix that proves the changed behavior, meaning, or contract.
+
+- Code: a layered mix of unit tests, integration tests for E2E segments, targeted E2E for changed flows, and full E2E for release or high-risk changes.
+- Ontology: static graph checks, concept economy gates, changed-path integration checks, and competency-question E2E checks.
+- Config or data: real parsers, schema checks, fixture validation, and sample transformations.
+- Spreadsheets: static workbook checks, fixture-based output checks, cross-sheet flow checks, visual/layout checks, and real Microsoft Excel engine recalculation for formula-dependent results.
+- Docs: links, terminology, current behavior alignment, and references to isolated historical notes.
+
+## Stop Conditions
+
+- If the issue boundary expands compared with the previous review, stop and ask the user to choose redesign/rework or continuing the current iteration.
+- Consider the boundary expanded when review reveals a broader affected purpose, failure condition, impact area, concept boundary, architecture boundary, or severity class.
+- Before calling the work done, report the current stage, review results, remaining material issues, verification results, and any stop reason.
+
+## Environment Binding (edit per environment)
+
+The only section of this guide that names concrete tools. Dated; expires ~8 weeks after the date or when the bound tool changes.
+
+Binding (2026-07):
+
+| Slot | Binding | Notes |
+|---|---|---|
+| Structured multi-lens review | onto-mcp review (private MCP) | consumes/emits the severity contract defined in Review Loop |
+| Subagent review | host CLI's native review mechanism | e.g. Claude Code `/code-review` or Agent-tool reviewers |

package/codex/guides/implementation-map.md

@@ -0,0 +1,34 @@
+---
+guide_id: implementation-map
+language: en
+status: active
+use_when:
+  - creating or updating IMPLEMENTATION_MAP.html in a repo with implementation code
+  - building the single SVG service blueprint inside it
+  - deciding what belongs in the current-state dashboard vs isolated history notes
+---
+
+# Implementation Map Guide
+
+Scoped extension of the **Implementation Map** section of the global instructions. Use this when creating or updating `IMPLEMENTATION_MAP.html` for a repo with implementation code.
+
+## Purpose
+
+`IMPLEMENTATION_MAP.html` is a **current-state dashboard** — it answers "where is this work now, what decides next, and what is at risk," not "what happened." It is not a changelog, handoff log, or accumulated project diary.
+
+## Build / rebuild rules
+
+- Rebuild it around the current task, current architecture, current risks, current decisions, and current verification status.
+- Compress completed history into the smallest useful summary; keep detailed past progress, abandoned alternatives, and long completed-task lists in isolated notes (`docs/`, `design/`, `archive/`).
+- The first viewport must show current goal, phase, health, next decision, and main risk.
+- Make it a self-contained HTML view with compact visual sections for status, architecture, roadmap, decisions, risks, verification, and change impact.
+- Update it before committing, when writing a handoff, or after meaningful architecture, roadmap, risk, decision, or verification changes.
+
+## The SVG service blueprint
+
+Include exactly **one** self-contained SVG service blueprint that visualizes the whole service or implemented system at the right level of abstraction. Build it using `${CODEX_HOME:-$HOME/.codex}/guides/svg-visualization-guide.md`.
+
+- Keep the blueprint focused on a single judgment question; use compact nodes rather than exhaustive file or task lists.
+- Use stable lanes, a legend, fixed role colors, short labels, and explicit arrows to separate: inputs, runtime/tools, LLM work, canonical artifacts, views, gates, quality checks, postponed work, and downstream/future work.
+- Distinguish time flow from authority flow, and distinguish canonical artifacts from JSON/YAML/Markdown/HTML projections.
+- Validate SVG syntax and layout hygiene when practical; ensure text does not overlap, and keep hot-path work visually separate from postponed or excluded work.

package/codex/guides/llm-capability-boundary-examples.md

@@ -0,0 +1,123 @@
+---
+guide_id: llm-capability-boundary-examples
+parent: llm-capability-boundary
+language: en
+status: active
+use_when:
+  - looking for worked precedents of boundary and field-authority design
+  - designing cases similar to sidecar submit, structured-output hybrid, MCP schema projection, or projection enrichment
+---
+
+# LLM And Capability Boundary: Worked Examples
+
+This guide is a scoped extension of
+`${CODEX_HOME:-$HOME/.codex}/guides/llm-capability-boundary.md`.
+Each example records a problem, the structural path taken, and the learning.
+
+## Lens Sidecar To Finding Ledger
+
+Problem:
+
+- Lens markdown was heterogeneous.
+- Finding-ledger LLM had to reread and normalize noisy markdown.
+- Runtime could not strongly guarantee ids, refs, artifact paths, or validation
+  scaffolds.
+
+Structural path:
+
+- Add `submit_lens_findings` as a batched submit tool.
+- LLM submits semantic finding fields once.
+- Runtime writes `round1/{lens}.findings.yaml`.
+- Runtime owns `session_id`, `lens_id`, `candidate_id`, `source_ref`,
+  `human_output_ref`, validation, and YAML serialization.
+- Optional markdown is rendered from the sidecar.
+- When every lens output is a sidecar, runtime writes `finding-ledger.yaml`
+  deterministically.
+
+Learning:
+
+- Machine artifacts should not depend on LLM prose formatting.
+- Batched submit reduces partial-output and per-call overhead.
+- Prompt packets can become audit packets when runtime owns the artifact.
+- A tool-capable route is required; text-only fallback should fail clearly for
+  this contract.
+
+## Structured Output Hybrid
+
+Problem:
+
+- Provider strict schema can enforce short enums.
+- Long evidence refs can contain quotes or source text that make provider enum
+  schemas brittle.
+- Pure post-hoc validation catches shape but not meaning.
+
+Structural path:
+
+- Use provider strict schema for short closed fields.
+- Keep `evidence_refs` as string arrays in provider schema.
+- Compute runtime allowed refs from prompt packet projections.
+- Reject unsupported refs at submit time.
+- Use a route where artifacts are created only by runtime submit handling.
+
+Learning:
+
+- Strict schema is real enforcement only where provider support and schema shape
+  are suitable.
+- Long refs need runtime allowed-set validation.
+- Each field needs one primary authority plus enough layered checks.
+
+## MCP-Projectable Schema Boundary
+
+Problem:
+
+- MCP/Claude tool surfaces need simple, directly valid object schemas.
+- Internal artifact schemas may benefit from richer JSON Schema composition.
+- Treating every repository schema as a tool schema can over-constrain internal
+  design, while exposing composed schemas can break tool hosts.
+
+Structural path:
+
+- Expose pattern-valid canonical tool names: use `namespace_verb` snake_case
+  such as `sheets_read`, matching `^[a-zA-Z0-9_-]{1,64}$`; reuse the catalog
+  name for dispatch, audit, and allowed-tool config, and enforce it in catalog
+  or seed validation.
+- Treat MCP tool `input_schema` values and schemas intended for MCP/Claude tool
+  projection as MCP-projectable schemas.
+- For MCP-projectable schemas, prefer direct object schemas with explicit
+  fields and avoid `oneOf`, `anyOf`, and `allOf`.
+- Put variant behavior behind operation enums, deterministic dispatch, runtime
+  validation, or explicit projection adapters.
+- Internal-only schemas may use composition when it materially reduces
+  complexity, but project them into compatible direct object schemas before
+  they reach an MCP/Claude tool surface.
+
+Learning:
+
+- The compatibility rule belongs at the tool projection boundary, not as a
+  universal ban on every internal schema.
+- Tools/code should own projection and validation so the LLM cannot accidentally
+  expose an incompatible schema shape.
+
+## Issue Stance Matrix Projection
+
+Problem:
+
+- A compact projection lacked action and dependency context needed by later LLM
+  units.
+- Asking later units to reread raw artifacts would increase latency and drift.
+
+Structural path:
+
+- Enrich the runtime projection with action, dependency, threshold, singleton,
+  shared-cause, and bounded-source-ref fields from authoritative upstream
+  artifacts.
+- Keep matrix merge deterministic.
+- Validate refs against allowed source variants.
+- Track projection coverage and fallback when omitted context may matter.
+
+Learning:
+
+- Projection-first enrichment is often better than expanding LLM context.
+- Add semantic context to deterministic projections when later judgment depends
+  on it.
+- Projection quality needs coverage checks, not only schema checks.