# jeromyjsmith/fre-meta-harness architecture

> Architecture diagram of the GitHub repository jeromyjsmith/fre-meta-harness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jeromyjsmith/fre-meta-harness
- Repository: https://github.com/jeromyjsmith/fre-meta-harness

## Overview

1. **Repository role**
   - This is a **portable parent wrapper / meta-harness** repo for the `VW_iTwin_Bridge` body cell. It is not a single app; it is a governed framework for ingesting work, routing it through staged agents, validating artifacts, and promoting outputs.

2. **Canonical authority layer**
   - The main “source of truth” lives in `README.md`, `GOAL.md`, `program.md`, `domain_spec.md`, `GOLDENPATH.md`, `MEMORY.md`, and `source/parent-operational-doctrine.md`.
   - These files define the operating doctrine, scope boundaries, and the execution protocol that the rest of the repo must conform to.

3. **Contract-first architecture**
   - `contracts/`, `schemas/`, `examples/`, and `expected-failures/` form the validation boundary.
   - The repo uses explicit YAML/JSON schemas for packets, routing, delegation, peer mesh, observability, capability matrices, and promotion artifacts.
   - `tests/` and `scripts/validate_parent_wrapper_contract.py` enforce these contracts against valid and invalid examples.

4. **Stage pipeline**
   - `stages/01_inbox_intake` through `stages/05_wrapper_synthesis` define the main processing path.
   - The intended flow is: **inbox intake → research harvest → semantic cartography → triad review → wrapper synthesis**.
   - Each stage has a `CONTEXT.md`, references, and an output area, which makes the pipeline boundary explicit and inspectable.

5. **Front-door and delegation flow**
   - The inbox/front-door layer is modeled by `contracts/inbox-packet.yaml`, `contracts/inbox-routing-decision.yaml`, `contracts/delegation-bundle.yaml`, and `contracts/front-door-runtime-topology.yaml`.
   - Operationally, incoming governed packets are routed, converted into delegation bundles, and then dispatched into stage or runtime lanes rather than being handled ad hoc.

6. **Subsystem and triad governance**
   - The repo distinguishes **governed parent roles** from runtime mesh roles.
   - `contracts/three-agent-topology.yaml`, `contracts/agent-extension-request.yaml`, and `schemas/governed-agent-profile.schema.json` formalize the triad governance layer.
   - `source/subsystems/` and `contracts/subsystem-*.yaml` describe subsystem boundaries such as intake ETL, research harvest, semantic cartography, and wrapper synthesis without claiming they are always active.

7. **Runtime surfaces**
   - There is a small application/runtime surface under `service/` and `app/`:
     - `service/main.py`
     - `service/inbox_runtime.py`
     - `app/server.ts`
   - The repo is therefore **polyglot**: Python for orchestration, validation, probes, and runtime services; TypeScript for at least one app-facing surface.

8. **Evaluation, proof, and observability**
   - `evaluation/` is a major subsystem, not just test output.
   - It contains dashboards, metrics, probe results, tool-health reports, agent-eval fixtures, research compilations, and strengthening reports.
   - `scripts/run-*.sh` and the probe scripts produce bounded evidence for runtime truth, capability harvests, peer mesh behavior, and subsystem proof families.

9. **Operational tooling and automation**
   - `scripts/` contains the main automation entry points: ratchet runs, peer-mesh local runs, ingestion, probing, scoring, visualization, and capability harvesting.
   - `scripts/watchers/inbox_router.py` is the clearest long-lived routing automation surface.
   - These scripts connect the contract layer to the generated evidence and local runtime checks.

10. **Agent and prompt governance**
   - `.claude/agents/`, `.claude/skills/`, and `.claude/hooks/` define the Claude Code operating environment.
   - Prompt schemas and templates in `agent-heavy-run-prompt-*` and `architect-review-handoff-prompt-*` govern structured handoffs and review flows.
   - This repo treats agent behavior as a governed interface, not as free-form prompting.

11. **Imported upstream authorities**
   - `external/` contains imported reference corpora and upstream authorities such as `goal-md`, `meta-harness`, `autoresearch-mlx`, and prompt/tooling research.
   - The `README` also notes `lib/` as a restoreable, gitignored dependency area for third-party repositories used by the harness.

12. **Artifact lifecycle**
   - `outbox/`, `promotion/`, `runs/`, `memory/`, `cache/`, `graph/`, `relationships/`, and `inbox/` represent the durable and semi-durable working surfaces.
   - The typical lifecycle is: input packet enters inbox → gets routed and staged → produces outbox/processed artifacts → feeds evaluation and promotion readiness → lands in run logs and metrics.

13. **Dependency and execution model**
   - The repo expects local tooling like `uv`, `bun`, and `just`, and uses `pyproject.toml`, `uv.lock`, and `package.json` to anchor the Python and JS tooling.
   - Validation and scoring are intentionally local-first and bounded; external analysis services like InfraNodus are represented by repository artifacts and scripts, with optional runtime integration rather than hard dependency.

14. **Architecture in one sentence**
   - This repository is a **contract-driven, stage-based parent harness** that ingests governed work, routes it through validated agent and subsystem boundaries, and emits reproducible proofs, metrics, and promotion artifacts.

Main entry points: [`stages/01_inbox_intake`](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/stages/01_inbox_intake) (Inbox Intake), [`contracts`](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/contracts) (Contracts), [`schemas`](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/schemas) (Schemas), [`scripts`](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/scripts) (Scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authority["Authority Layer"]
  node_readme["README<br/>authority doc<br/>[README.md]"]
  node_governance_docs["Doctrine Docs<br/>authority docs"]
end

subgraph group_contracts["Contract Boundary"]
  node_contracts_bundle[("Contracts<br/>schema set")]
  node_schemas_bundle[("Schemas<br/>schema set")]
  node_examples_bundle["Examples<br/>fixtures"]
  node_failures_bundle["Expected Failures<br/>negative fixtures"]
  node_tests_validator["Validator<br/>test harness"]
end

subgraph group_pipeline["Stage Pipeline"]
  node_stage_intake["Inbox Intake<br/>stage 01"]
  node_stage_research["Research Harvest<br/>stage 02"]
  node_stage_cartography["Semantic Cartography<br/>stage 03"]
  node_stage_triad["Triad Review<br/>stage 04"]
  node_stage_synthesis["Wrapper Synthesis<br/>stage 05"]
end

subgraph group_runtime["Runtime Surfaces"]
  node_service_runtime["Python Service<br/>python runtime<br/>[main.py]"]
  node_app_runtime["TypeScript App<br/>ts runtime<br/>[server.ts]"]
end

subgraph group_ops["Ops and Evaluation"]
  node_scripts_ops["Scripts<br/>automation"]
  node_evaluation_repo[("Evaluation<br/>evidence store")]
  node_watcher_router["Inbox Router<br/>watcher<br/>[inbox_router.py]"]
end

subgraph group_artifacts["Working Artifacts"]
  node_working_surfaces[("Working Surfaces<br/>artifact areas")]
end

subgraph group_governance["Agent Governance"]
  node_claude_env["Claude Env<br/>agent governance<br/>[.claude]"]
  node_external_auth["External Corpora<br/>upstream refs"]
end

node_readme -->|"defines"| node_governance_docs
node_governance_docs -->|"governs"| node_contracts_bundle
node_contracts_bundle -->|"formalized by"| node_schemas_bundle
node_schemas_bundle -->|"validated by"| node_examples_bundle
node_schemas_bundle -->|"rejects"| node_failures_bundle
node_tests_validator -->|"checks"| node_contracts_bundle
node_stage_intake -->|"consumes"| node_contracts_bundle
node_stage_intake -->|"writes"| node_working_surfaces
node_stage_intake -->|"hands off to"| node_stage_research
node_stage_research -->|"feeds"| node_stage_cartography
node_stage_cartography -->|"feeds"| node_stage_triad
node_stage_triad -->|"approves for"| node_stage_synthesis
node_stage_synthesis -->|"promotes"| node_working_surfaces
node_scripts_ops -->|"hosts"| node_watcher_router
node_watcher_router -->|"routes"| node_stage_intake
node_scripts_ops -->|"produces"| node_evaluation_repo
node_evaluation_repo -->|"reflects"| node_tests_validator
node_claude_env -->|"constrains"| node_stage_triad
node_claude_env -->|"orchestrates"| node_scripts_ops
node_external_auth -.->|"informs"| node_governance_docs
node_service_runtime -->|"implements"| node_stage_intake
node_app_runtime -.->|"interfaces with"| node_service_runtime

click node_readme "https://github.com/jeromyjsmith/fre-meta-harness/blob/main/README.md"
click node_governance_docs "https://github.com/jeromyjsmith/fre-meta-harness/blob/main/source/parent-operational-doctrine.md"
click node_contracts_bundle "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/contracts"
click node_schemas_bundle "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/schemas"
click node_examples_bundle "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/examples"
click node_failures_bundle "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/expected-failures"
click node_tests_validator "https://github.com/jeromyjsmith/fre-meta-harness/blob/main/tests/validate_parent_wrapper_contract.py"
click node_stage_intake "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/stages/01_inbox_intake"
click node_stage_research "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/stages/02_research_harvest"
click node_stage_cartography "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/stages/03_semantic_cartography"
click node_stage_triad "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/stages/04_triad_review"
click node_stage_synthesis "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/stages/05_wrapper_synthesis"
click node_service_runtime "https://github.com/jeromyjsmith/fre-meta-harness/blob/main/service/main.py"
click node_app_runtime "https://github.com/jeromyjsmith/fre-meta-harness/blob/main/app/server.ts"
click node_scripts_ops "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/scripts"
click node_evaluation_repo "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/evaluation"
click node_watcher_router "https://github.com/jeromyjsmith/fre-meta-harness/blob/main/scripts/watchers/inbox_router.py"
click node_working_surfaces "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/outbox"
click node_claude_env "https://github.com/jeromyjsmith/fre-meta-harness/blob/main/.claude"
click node_external_auth "https://github.com/jeromyjsmith/fre-meta-harness/tree/main/external"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_governance_docs,node_claude_env,node_external_auth toneBlue
class node_contracts_bundle,node_schemas_bundle,node_examples_bundle,node_failures_bundle,node_tests_validator toneAmber
class node_stage_intake,node_stage_research,node_stage_cartography,node_stage_triad,node_stage_synthesis toneMint
class node_service_runtime,node_app_runtime toneRose
class node_scripts_ops,node_evaluation_repo,node_watcher_router toneIndigo
class node_working_surfaces toneTeal
```

## Components

### Authority Layer

Canonical doctrine and operating rules for the parent harness.

- [README](https://github.com/jeromyjsmith/fre-meta-harness/blob/main/README.md): authority doc · Top-level repository intent and operating summary. · `README.md`
- [Doctrine Docs](https://github.com/jeromyjsmith/fre-meta-harness/blob/main/source/parent-operational-doctrine.md): authority docs · Core governing docs such as goal, program, domain spec, golden path, memory, and operational doctrine. · `source/parent-operational-doctrine.md`

### Contract Boundary

Schemas, examples, and failure cases that define valid governed artifacts.

- [Contracts](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/contracts): schema set · Primary contract definitions for inbox, routing, delegation, triad, observability, peer mesh, and promotion. · `contracts`
- [Schemas](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/schemas): schema set · Machine-readable schema layer used to validate governed artifacts and runtime outputs. · `schemas`
- [Examples](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/examples): fixtures · Valid and invalid examples used to exercise contract behavior. · `examples`
- [Expected Failures](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/expected-failures): negative fixtures · Known-bad cases that define rejection boundaries. · `expected-failures`
- [Validator](https://github.com/jeromyjsmith/fre-meta-harness/blob/main/tests/validate_parent_wrapper_contract.py): test harness · Contract and runtime validation entrypoints, including the parent wrapper contract checker. · `tests/validate_parent_wrapper_contract.py`

### Stage Pipeline

The main staged processing path from intake to wrapper synthesis.

- [Inbox Intake](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/stages/01_inbox_intake): stage 01 · Front-door intake, packet normalization, and delegation decision entry. · `stages/01_inbox_intake`
- [Research Harvest](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/stages/02_research_harvest): stage 02 · Capability harvesting, gap mapping, and research packet production. · `stages/02_research_harvest`
- [Semantic Cartography](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/stages/03_semantic_cartography): stage 03 · Maps subsystem boundaries and harness topology from harvested evidence. · `stages/03_semantic_cartography`
- [Triad Review](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/stages/04_triad_review): stage 04 · Governed review against the three-agent topology and gap strength. · `stages/04_triad_review`
- [Wrapper Synthesis](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/stages/05_wrapper_synthesis): stage 05 · Produces the promoted wrapper-facing outputs and final delegation artifacts. · `stages/05_wrapper_synthesis`

### Runtime Surfaces

Executable entrypoints for orchestration and app-facing runtime.

- [Python Service](https://github.com/jeromyjsmith/fre-meta-harness/blob/main/service/main.py): python runtime · Python orchestration and runtime service surface. · `service/main.py`
- [TypeScript App](https://github.com/jeromyjsmith/fre-meta-harness/blob/main/app/server.ts): ts runtime · App-facing runtime surface implemented in TypeScript. · `app/server.ts`

### Ops and Evaluation

Automation, probes, scoring, evaluation, and evidence generation.

- [Scripts](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/scripts): automation · Main local-first automation for probes, ratchets, scoring, ingestion, and visualization. · `scripts`
- [Evaluation](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/evaluation): evidence store · Dashboards, metrics, probe results, strengthening reports, and benchmark artifacts. · `evaluation`
- [Inbox Router](https://github.com/jeromyjsmith/fre-meta-harness/blob/main/scripts/watchers/inbox_router.py): watcher · Long-lived routing automation that watches and dispatches governed inbox work. · `scripts/watchers/inbox_router.py`

### Working Artifacts

Durable or semi-durable repo surfaces for packets, runs, promotion, and memory.

- [Working Surfaces](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/outbox): artifact areas · Inbox, outbox, runs, promotion, memory, cache, graph, and relationships used across the lifecycle. · `outbox`

### Agent Governance

Claude Code agents, hooks, and skills that constrain behavior.

- [Claude Env](https://github.com/jeromyjsmith/fre-meta-harness/blob/main/.claude): agent governance · Claude agents, hooks, and skills that constrain and structure agent behavior. · `.claude`
- [External Corpora](https://github.com/jeromyjsmith/fre-meta-harness/tree/main/external): upstream refs · Imported reference corpora and upstream authorities used as comparative or governing inputs. · `external`

## Connections

- README → Doctrine Docs: defines · Repository doctrine is grounded in the canonical operating docs.
- Doctrine Docs → Contracts: governs · Doctrine sets the rules for contract and artifact shape.
- Contracts → Schemas: formalized by · Contracts are represented as explicit machine-readable schemas.
- Schemas → Examples: validated by · Schemas are exercised against valid examples.
- Schemas → Expected Failures: rejects · Negative fixtures define expected validation failures.
- Validator → Contracts: checks · Validator enforces the contract boundary.
- Inbox Intake → Contracts: consumes · Intake begins with governed packet and routing contracts.
- Inbox Intake → Working Surfaces: writes · Intake emits routed artifacts into durable working areas.
- Inbox Intake → Research Harvest: hands off to · Validated intake results move into research harvest.
- Research Harvest → Semantic Cartography: feeds · Research harvest produces evidence for topology mapping.
- Semantic Cartography → Triad Review: feeds · Topology and subsystem maps are reviewed by the triad lane.
- Triad Review → Wrapper Synthesis: approves for · Triad review gates wrapper synthesis.
- Wrapper Synthesis → Working Surfaces: promotes · Final outputs land in outbox, promotion, and run surfaces.
- Scripts → Inbox Router: hosts · Automation includes the inbox routing watcher.
- Inbox Router → Inbox Intake: routes · Incoming packets are dispatched into the intake stage.
- Scripts → Evaluation: produces · Scripts generate probes, dashboards, reports, and metrics.
- Evaluation → Validator: reflects · Evaluation captures validation and proof outcomes.
- Claude Env → Triad Review: constrains · Agent roles and hooks shape governed review behavior.
- Claude Env → Scripts: orchestrates · Agent environment supports scripted automation and handoffs.
- External Corpora → Doctrine Docs: informs · Imported authorities supplement the repo's canonical doctrine.
- Python Service → Inbox Intake: implements · Python runtime exposes intake and orchestration behavior.
- TypeScript App → Python Service: interfaces with · TypeScript surface complements the Python runtime boundary.