How jeromyjsmith/fre-meta-harness works
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: 01_inbox_intake Inbox Intake · contracts Contracts · schemas Schemas · scripts Scripts
Components 20
Authority Layer
Canonical doctrine and operating rules for the parent harness.
- README · Top-level repository intent and operating summary.
README.md - Doctrine 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 · Primary contract definitions for inbox, routing, delegation, triad, observability, peer mesh, and promotion.
contracts - Schemas · Machine-readable schema layer used to validate governed artifacts and runtime outputs.
schemas - Examples · Valid and invalid examples used to exercise contract behavior.
examples - Expected Failures · Known-bad cases that define rejection boundaries.
expected-failures - Validator · 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 · Front-door intake, packet normalization, and delegation decision entry.
stages/01_inbox_intake - Research Harvest · Capability harvesting, gap mapping, and research packet production.
stages/02_research_harvest - Semantic Cartography · Maps subsystem boundaries and harness topology from harvested evidence.
stages/03_semantic_cartography - Triad Review · Governed review against the three-agent topology and gap strength.
stages/04_triad_review - Wrapper Synthesis · 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 · Python orchestration and runtime service surface.
service/main.py - TypeScript App · App-facing runtime surface implemented in TypeScript.
app/server.ts
Ops and Evaluation
Automation, probes, scoring, evaluation, and evidence generation.
- Scripts · Main local-first automation for probes, ratchets, scoring, ingestion, and visualization.
scripts - Evaluation · Dashboards, metrics, probe results, strengthening reports, and benchmark artifacts.
evaluation - Inbox Router · 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 · 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 · Claude agents, hooks, and skills that constrain and structure agent behavior.
.claude - External Corpora · Imported reference corpora and upstream authorities used as comparative or governing inputs.
external
Connections 22
- 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.