agent-bios 0.1.0

package/codex/guides/mock-realization-boundary.md

@@ -0,0 +1,275 @@
+---
+guide_id: mock-realization-boundary
+language: en
+status: active
+use_when:
+  - adding mocks, fakes, stubs, fixtures, or simulated providers
+  - deciding whether a mock-backed path counts as completion
+  - separating verification harnesses from production semantic paths
+  - centralizing mock payloads for later deletion or replacement
+  - reporting verification results that include mock-backed checks
+core_rules:
+  - mocks are verification realizations, not production semantic paths
+  - use mocks to verify wiring, schemas, artifact contracts, deterministic projections, failure handling, and harness stability
+  - use real semantic paths to verify product behavior, materiality judgment, causal reasoning, and semantic quality
+  - keep mock behavior behind explicit realization switches, fixture modules, or mock executors
+  - centralize mock payloads in a small deletion boundary so mock support can be removed or replaced together
+  - share validators and artifact contracts between mock and production paths
+  - report mock-backed verification separately from production-path verification
+completion_policy:
+  mock_backed_paths_support_verification: true
+  mock_backed_paths_count_as_product_completion: false
+  semantic_quality_from_mock: not_applicable
+verification_focus:
+  - mock paths exercise the same artifact contracts as production paths
+  - mock payloads are centralized and easy to delete
+  - mock execution is selected only through explicit realization config
+  - verification reports distinguish mock, fixture, and live paths
+  - production semantic gates run on real semantic paths
+---
+
+# Mock Realization Boundary Guide
+
+This guide is a scoped extension of the global Coding Guidelines. Use it when
+adding, reviewing, or cleaning up mocks, fakes, stubs, fixtures, simulated
+providers, or mock executors.
+
+The central rule is that a mock is a verification realization. It can prove that
+the harness, contract, validator, projection, or failure path works. It does not
+prove that the product semantic path works.
+
+## Core Distinction
+
+| Question | Mock path | Production semantic path |
+|---|---|---|
+| What does it prove? | Wiring, schemas, persistence, projections, failures | Real behavior, semantic judgment, user-visible quality |
+| Who owns semantics? | Fixture author | Real model, real service, real user input, or real runtime authority |
+| Completion credit | Verification support only | Product completion evidence |
+| Quality gate status | `not_applicable` or harness-only | Passed/failed against real semantic criteria |
+| Cleanup strategy | Central deletion boundary | Maintained product path |
+
+Use the same artifact contracts and validators whenever possible. The mock path
+should exercise the product contract, not create a parallel contract.
+
+## Appropriate Mock Uses
+
+Use mocks for:
+
+- wiring checks
+- schema and parser checks
+- artifact persistence checks
+- deterministic projection checks
+- retry and failure handling checks
+- timeout and cancellation checks
+- E2E harness stability
+- fixture-based regression tests
+- external dependency isolation when the dependency is not under test
+
+Use real paths for:
+
+- product behavior
+- materiality judgment
+- causal reasoning
+- semantic quality gates
+- user-visible recommendations
+- provider integration confidence
+- release evidence for high-risk flows
+
+## Structural Pattern
+
+1. Define an explicit realization selector such as `mock`, `fixture`, `live`, or
+   `direct`.
+2. Keep mock payloads in a fixture module or fixture directory.
+3. Keep mock executors as thin shells that route fixture payloads through the
+   same validators and artifact writers used by production.
+4. Mark semantic-quality evaluation as `not_applicable` for mock realization.
+5. Report mock-backed verification separately from live or production-path
+   verification.
+6. Keep the deletion boundary small enough that mock support can be removed or
+   replaced in one focused change.
+
+## Realization Selector
+
+Use explicit realization config so a mock cannot silently become the product
+path.
+
+Illustrative implementation:
+
+```ts
+type Realization = "mock" | "fixture" | "live";
+
+function parseRealization(value: string | undefined): Realization {
+  if (value === "mock" || value === "fixture" || value === "live") return value;
+  return "live";
+}
+
+function selectProvider(realization: Realization) {
+  if (realization === "mock") return createMockProvider();
+  if (realization === "fixture") return createFixtureProvider();
+  return createLiveProvider();
+}
+```
+
+## Central Fixture Boundary
+
+Centralize mock payloads. Runtime code that needs deterministic mock artifacts
+imports from this boundary instead of growing inline mock-specific payloads.
+
+Illustrative implementation:
+
+```ts
+export const reviewMockFixtures = {
+  findingLedger() {
+    return {
+      schema_version: 1,
+      findings: [
+        {
+          finding_id: "finding-001",
+          target: "fixture-target",
+          claim: "fixture finding",
+          severity: "low",
+        },
+      ],
+    };
+  },
+};
+```
+
+## Thin Mock Executor
+
+Keep the mock executor as an execution shell. It should not become the place
+where product behavior is reimplemented.
+
+Illustrative implementation:
+
+```ts
+async function runMockUnit(unit: Unit, ctx: RuntimeContext) {
+  const payload = reviewMockFixtures[unit.artifactKind]();
+  const artifact = validateArtifact(payload, unit.artifactKind);
+  await writeArtifact(ctx.outputPath, artifact);
+  return {
+    realization: "mock",
+    artifact_path: ctx.outputPath,
+    semantic_quality: "not_applicable",
+  };
+}
+```
+
+## Shared Validators
+
+The mock path should pass through the same validators as production. This makes
+mock tests useful for contract drift without letting mocks become product
+completion evidence.
+
+Illustrative implementation:
+
+```ts
+function writeArtifact(path: string, payload: unknown) {
+  const validated = validateCurrentArtifactContract(payload);
+  return writeYaml(path, validated);
+}
+
+await writeArtifact(outputPath, reviewMockFixtures.findingLedger());
+await writeArtifact(outputPath, liveModelArtifact);
+```
+
+## Semantic Quality Gate
+
+Mock-backed runs should make semantic quality explicitly not applicable. They
+can still verify the harness and artifact collection.
+
+Illustrative implementation:
+
+```ts
+function evaluateSemanticQuality(args: {
+  realization: Realization;
+  artifact: unknown;
+}) {
+  if (args.realization === "mock") {
+    return {
+      status: "not_applicable",
+      applicability: "real_semantic_path_only",
+      reason: "mock verifies harness and contracts, not product semantics",
+    };
+  }
+  return evaluateLiveSemanticQuality(args.artifact);
+}
+```
+
+## Verification Reporting
+
+Separate mock-backed checks from production-path checks in final reports.
+
+Preferred reporting shape:
+
+```ts
+type VerificationReport = {
+  mock_checks: CheckResult[];
+  fixture_checks: CheckResult[];
+  production_path_checks: CheckResult[];
+  unverified_risks: string[];
+};
+```
+
+Useful report language:
+
+- "Mock run passed artifact-contract checks."
+- "Mock run did not evaluate product semantic quality."
+- "Live semantic path remains unverified."
+- "Production path passed semantic quality gate."
+
+## Deletion Boundary
+
+Mock support should be easy to remove or replace. A good deletion boundary has:
+
+- one fixture module or fixture directory
+- one realization selector
+- one mock executor shell if needed
+- shared validators outside the mock boundary
+- tests that name the realization explicitly
+- no product runtime dependency on mock-only payloads
+
+When cleanup is needed, remove or replace the fixture module, realization route,
+and mock-only tests together.
+
+## Product Completion Rule
+
+Mock-backed paths can support verification but do not count as product
+completion.
+
+Examples:
+
+- A mock E2E can prove the pipeline writes all expected artifacts.
+- A mock E2E cannot prove the recommendation is semantically correct.
+- A fixture can prove a validator rejects malformed payloads.
+- A fixture cannot prove a live provider follows the intended reasoning path.
+- A mock provider can prove retry handling.
+- A mock provider cannot prove the real provider integration is production-ready.
+
+## Design Procedure
+
+Use this procedure before adding or extending mock behavior.
+
+1. Name what the mock is meant to verify.
+2. Name what the mock does not verify.
+3. Choose an explicit realization selector.
+4. Put mock payloads in one fixture boundary.
+5. Route mock outputs through shared validators and artifact writers.
+6. Keep mock executors thin.
+7. Mark semantic quality as not applicable for mock runs.
+8. Add reporting that separates mock checks from production-path checks.
+9. Add at least one real semantic-path check when product behavior is part of
+   the completion claim.
+10. Keep deletion or replacement possible in one focused change.
+
+## Verification Checklist
+
+- Mock use is explicitly selected.
+- Mock payloads are centralized.
+- Mock behavior is not embedded across production logic.
+- Mock output uses the current production artifact contract.
+- Shared validators run on mock output.
+- Mock-backed verification is reported separately.
+- Semantic quality is not claimed from mock-backed output.
+- Product completion has real semantic-path evidence.
+- Mock support has a clear deletion boundary.

package/codex/guides/svg-visualization-guide.md

@@ -0,0 +1,321 @@
+---
+guide_id: svg-visualization-guide
+language: en
+status: active
+use_when:
+  - creating SVG diagrams for architecture, pipelines, artifacts, runtime/LLM boundaries, or service blueprints
+  - adding a blueprint SVG to IMPLEMENTATION_MAP.html
+  - visualizing before/after structure, hot paths, postponed work, gates, quality checks, or artifact authority
+  - replacing prose-heavy implementation status with a compact visual decision aid
+core_rules:
+  - make each SVG answer one judgment question
+  - separate time flow from authority flow when they differ
+  - use stable role colors for input, runtime/tools, LLM, artifact, view/UI, gate, quality, postponed work, and downstream work
+  - label format and authority separately so canonical artifacts and projections are not confused
+  - keep hot-path work visually separate from postponed or excluded work
+  - prefer lanes, legends, short labels, explicit arrows, and compact nodes over dense prose
+  - validate SVG syntax and visual layout when practical
+verification_focus:
+  - the SVG has one clear question
+  - input and output are obvious
+  - runtime/tools and LLM responsibilities are visually distinct
+  - canonical artifacts and projections are labeled separately
+  - hot path and postponed work are separated
+  - gates and quality checks have different meanings
+  - text does not overlap and arrows remain readable
+---
+
+# SVG Visualization Guide
+
+Use this guide when a diagram needs more precision than a Markdown table or
+Mermaid diagram can provide. The goal is not decoration. The goal is to help a
+reader quickly decide what the system does, where authority lives, what is on
+the hot path, what is postponed, and what must be verified.
+
+For `IMPLEMENTATION_MAP.html`, include one self-contained SVG service blueprint
+that shows the whole service or implemented system at the right level of
+abstraction.
+
+## When To Use SVG
+
+Prefer SVG when the visual needs any of these:
+
+- before/after structure
+- sequential pipeline flow
+- multiple lanes or layers
+- artifact relationships
+- runtime/tools and LLM responsibility boundaries
+- canonical artifact versus projection distinction
+- gate, quality review, and UI projection in the same view
+- postponed or excluded work beside the hot path
+- a self-contained browser-readable visual artifact
+
+Prefer a Markdown table or Mermaid diagram when the structure is shallow, has
+five or fewer items, or the exact text diff matters more than layout.
+
+## Core Principles
+
+### One Judgment Question
+
+Each SVG should answer one clear question.
+
+Good questions:
+
+- How does source authority become a canonical artifact consumers trust?
+- Why does this pipeline need both a chunk pass and a bridge pass?
+- How did input authority change before and after this redesign?
+- What is the current service blueprint and where are the gates?
+
+The SVG may cover many nodes, but all nodes should support the same question.
+Detailed history, exhaustive task lists, and long explanations belong outside
+the SVG.
+
+### Time Flow And Authority Flow
+
+Separate time flow from authority flow when they differ.
+
+Time flow example:
+
+```text
+input -> stage 1 -> stage 2 -> stage N
+```
+
+Authority flow example:
+
+```text
+source/chat/decision/config
+  -> canonical JSON artifact
+  -> runtime projection
+  -> confirmed handoff
+```
+
+Use separate lanes or distinct arrow styles when the reader needs to see both.
+
+### Stable Role Colors
+
+Use the same role colors across diagrams so the reader does not relearn the
+legend.
+
+| Role | Color | Meaning |
+|---|---|---|
+| Input | Blue | User source, chat, decision, config snapshot |
+| Runtime/tools | Green | Deterministic parse, merge, projection, id/ref/digest creation |
+| LLM | Amber | Semantic interpretation, drafting, relation judgment |
+| Artifact | Slate/gray | Canonical or generated file |
+| View/UI | Purple | HTML review, confirmation UI, user-facing projection |
+| Gate | Red | Deterministic blocking check |
+| Quality | Cyan | Non-blocking quality report or competency question |
+| Postponed/excluded | Orange | Later decision, later collection, outside hot path |
+| Future/downstream | Dashed gray | Later phase, downstream system, future redesign |
+
+Color is not enough by itself. Use labels and legends too.
+
+### Format And Authority
+
+Each important node should show at least two of these:
+
+- human-readable name
+- artifact or concept id
+- format
+- owner
+- authority status
+
+Example:
+
+```text
+Confirmed Planning Input
+JSON canonical + YAML projection
+Runtime owns schema/ref/digest
+```
+
+YAML, Markdown, and HTML may be projections rather than canonical artifacts.
+Label that distinction directly.
+
+### Hot Path And Postponed Work
+
+Complexity reduction often depends on what the system leaves out. Show hot-path
+work and postponed or excluded work in the same SVG, but in separate lanes or
+side boxes.
+
+Examples:
+
+```text
+post_decision: fields resolved by a later decision
+post_collection: assets gathered in a later step
+placeholder_need: reserve context for later collection
+```
+
+Postponed items should not sit inside the main flow.
+
+## Recommended SVG Structure
+
+### Title And Subtitle
+
+Use a title that names the target and purpose. Use a subtitle for the single
+judgment question.
+
+```xml
+<text class="title" x="70" y="72">Input Authority Rebuild Plan</text>
+<text class="subtitle" x="72" y="108">How confirmed source authority becomes a canonical artifact</text>
+```
+
+### Legend
+
+Place a compact legend near the top. The legend should explain:
+
+- role colors
+- artifact formats
+- arrow meanings
+- hot path versus postponed work when relevant
+
+### Lanes
+
+Use lanes to make complex diagrams readable. Keep the lane count small.
+
+Recommended lanes:
+
+```text
+Inputs
+Runtime/tools
+LLM semantic work
+Canonical artifacts
+Views, gates, and quality
+Postponed or downstream work
+```
+
+For before/after comparisons, use two columns instead of many lanes.
+
+### Nodes
+
+Keep each node to three to five short lines.
+
+Recommended node shape:
+
+```text
+Node title
+Plain behavior
+Important constraint
+artifact_id or format
+```
+
+Use monospace-like styling for artifact ids when useful. Keep long prose in the
+surrounding document.
+
+### Arrows
+
+Use arrow meaning consistently.
+
+- Slate arrow: normal data flow
+- Green arrow: runtime-owned deterministic flow
+- Amber or blue arrow: LLM semantic submit/candidate flow
+- Red arrow: gate or blocking condition
+- Dashed gray arrow: optional, future, downstream, or projection-only flow
+
+When arrows cross too much, add a lane, hub node, or intermediate artifact.
+
+## Implementation Map Blueprint
+
+The `IMPLEMENTATION_MAP.html` blueprint SVG should explain the current service
+or implemented system, not every file and task.
+
+It should answer:
+
+- What enters the service?
+- What leaves the service?
+- Which steps are runtime/tools work?
+- Which steps are LLM semantic work?
+- Which artifacts are canonical?
+- Which views are generated projections?
+- Which gates block progress?
+- Which quality checks disclose risk without blocking?
+- Which items are postponed, excluded, downstream, or future work?
+
+Use the blueprint to support decisions. A reader should be able to understand
+the current architecture, hot path, authority boundaries, and main risks without
+reading a long progress log.
+
+## Layout Rules
+
+Recommended default:
+
+```xml
+<svg width="1900" height="1640" viewBox="0 0 1900 1640">
+```
+
+Use these layout defaults:
+
+- Width around 1800-1900px for complex blueprints
+- Lane gaps of at least 30-40px
+- Node gaps of at least 60-80px
+- Node width of at least 240px
+- Fixed font sizes
+- Letter spacing of 0 except tiny badge cases
+- Manual line breaks for long labels
+- Larger boxes when text could overflow
+- Hub nodes when arrows would cross heavily
+
+## Accessibility And Visual Hygiene
+
+Include `role`, `title`, and `desc`:
+
+```xml
+<svg role="img" aria-labelledby="title desc">
+  <title id="title">...</title>
+  <desc id="desc">...</desc>
+</svg>
+```
+
+Keep visuals plain and readable:
+
+- simple fill and stroke
+- wide margins
+- clear lanes
+- fixed color system
+- short labels
+- no text overflow
+- no decorative gradients, orbs, blobs, excessive shadows, or nested cards
+- no unnecessary icons
+
+## Procedure
+
+1. Write the judgment question in one sentence.
+2. Split concepts into up to five or six lanes.
+3. List three to five nodes per lane.
+4. Mark each node owner: input, runtime/tools, LLM, artifact, view, gate,
+   quality, postponed, downstream.
+5. Label machine-consumed outputs by format and authority.
+6. Put postponed or excluded work in a separate lane or side box.
+7. Draw arrows with consistent meanings.
+8. Validate syntax and inspect layout.
+
+## Verification
+
+Run syntax and diff checks when practical:
+
+```bash
+xmllint --noout path/to/file.svg
+git diff --check -- path/to/file.svg
+```
+
+If the SVG is embedded in HTML, inspect it in a browser or screenshot when
+layout matters. Check that:
+
+- text does not overlap
+- arrows do not obscure meaning
+- lane titles and node titles are easy to scan
+- hot path and postponed work are visually separate
+- runtime/tools, LLM, gate, quality, artifact, and view colors match the legend
+
+## Completion Criteria
+
+The SVG is complete when:
+
+- it answers one judgment question
+- input and output are clear
+- runtime/tools and LLM responsibilities are separated by label and color
+- canonical artifacts and projections are distinct
+- needed JSON/YAML/Markdown/HTML formats are labeled
+- hot path and postponed or downstream work are separate
+- gates and quality review have different visual meanings
+- text does not overlap
+- syntax and diff checks pass when available

package/config/agent-launch.toml

@@ -0,0 +1,94 @@
+schema_version = 1
+
+[backends.codex]
+command = "codex"
+passthrough_args = []
+
+[backends.claude]
+command = "claude"
+passthrough_args = ["--dangerously-skip-permissions"]
+
+[capabilities.onto]
+command = "onto"
+
+[capabilities.ultracode]
+command = "ultracode-for-codex"
+
+[hosts.codex]
+models = ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]
+# onto review seat used when a CROSS-family main (Claude) routes onto review to
+# this (gpt/codex) family; must be an onto review-role registered (provider, model).
+onto_review = { provider = "openai", model = "gpt-5.6-sol" }
+
+[hosts.codex.tiers.frontier]
+model = "gpt-5.6-sol"
+effort = "max"
+
+[hosts.codex.tiers.helm]
+model = "gpt-5.6-sol"
+effort = "xhigh"
+
+[hosts.codex.tiers.workhorse]
+model = "gpt-5.6-terra"
+effort = "high"
+
+[hosts.codex.tiers.sweep]
+model = "gpt-5.6-luna"
+effort = "low"
+
+[hosts.codex.agent_templates]
+frontier = "${CODEX_HOME}/agents/frontier.toml"
+workhorse = "${CODEX_HOME}/agents/workhorse.toml"
+sweep = "${CODEX_HOME}/agents/sweep.toml"
+
+[hosts.claude]
+models = ["claude-fable-5", "claude-opus-4-8", "claude-sonnet-5", "claude-haiku-4-5"]
+# onto review seat used when a CROSS-family main (Codex) routes onto review to
+# this (anthropic/claude) family; must be an onto review-role registered (provider, model).
+onto_review = { provider = "anthropic", model = "claude-fable-5" }
+
+[hosts.claude.tiers.frontier]
+model = "claude-fable-5"
+effort = "max"
+
+[hosts.claude.tiers.helm]
+model = "claude-opus-4-8"
+effort = "xhigh"
+
+[hosts.claude.tiers.workhorse]
+model = "claude-sonnet-5"
+effort = "high"
+
+[hosts.claude.tiers.sweep]
+model = "claude-haiku-4-5"
+effort = "low"
+
+[presets.balanced]
+label = "Balanced"
+description = "HELM default for everyday work with native multi-perspective review."
+main_tier = "helm"
+frontier_effort = "max"
+review_setup = "native-panel"
+delegation = true
+codex_execution_policy = "bypass"
+claude_permission_mode = "bypassPermissions"
+
+[presets.deep-review]
+label = "Deep review"
+description = "HELM with hybrid onto, native, and Ultracode review at deep FRONTIER effort."
+main_tier = "helm"
+frontier_effort = { codex = "ultra", claude = "max" }
+review_setup = "hybrid"
+delegation = true
+codex_execution_policy = "bypass"
+claude_permission_mode = "bypassPermissions"
+
+[presets.fast-batch]
+label = "Fast batch"
+description = "WORKHORSE default for high-volume, cost-conscious execution."
+main_tier = "workhorse"
+frontier_effort = "max"
+review_setup = "native-panel"
+delegation = true
+codex_execution_policy = "bypass"
+claude_permission_mode = "bypassPermissions"