midi2-gpu-fabric.git · AGENTS.md

revision 6c640405a953073e82e6144206cea1aadea5fabd · complete file

# MIDI2 GPU Fabric — Agent Guide

Scope: MIDI 2.0 + GPU workspace. The MIDI backplane IDL is the sole contract. No OpenAPI.

## Proof-Bounded Development (mandatory)

PBD is the default implementation discipline. Before substantial work, define a finite observable acceptance proof
for the requested capability. Use the existing Swift Kits, MIDI2 IDL, FountainStore APIs, and declared host adapters
first. Change architecture only when a proof condition fails and the existing seam cannot satisfy it safely; state
the failed condition, the reason, and the smallest necessary change.

The required lifecycle is:

`capability → acceptance proof → minimal implementation → verification → STOP`

New concerns must be classified as proof-required, proof-invalidating defects, or unrelated follow-up. Only the first
two may expand the current scope. When the proof passes, stop implementation and report `COMPLETE`; otherwise report
`BLOCKED — <concrete reason>`. Every completion report must include the requested capability, exact proof, evidence,
necessary changes, and deferred observations. See [`docs/proof-bounded-development.md`](docs/proof-bounded-development.md).

Invariants
- Repository-native execution is mandatory. Before acting, the implementing agent MUST read this guide, the
applicable scoped `AGENTS.md`, the resolved governance chapters, and the named procedure skill. The repository's
Swift Kits, MIDI2 IDL, FountainStore APIs, and declared Swift host adapters are the only authority for runtime,
preview, synchronization, publication, and acceptance. Do not substitute Python, Ruby, ad-hoc static servers,
generic HTTP wrappers, shell launchers, guessed paths, or remembered procedures. If the declared repository-native
path is missing or cannot be verified, stop and report that exact seam; do not fall back. Python or other tools may
be used only when the applicable repository skill explicitly names them as a non-runtime validator or generator,
and their output must not be presented as Swift runtime, Store sync, edge, or acceptance evidence.
- Normative capability ownership: every Reframe skill MUST be defined in the
Swift `ReframeSkillKit`, and every Fountain Coach maintenance operation MUST
be defined in the Swift `FountainCoachMaintenanceKit`, before implementation
begins. `.codex/skills` and `.claude/skills` are agent procedures, never
runtime authority. `ReframeCore` MUST resolve the kit contract and route
through an explicit MIDI2 instrument or Swift host adapter; no Python-backed
fallback may satisfy a kit-owned capability. See Governance Chapter 112.
- Contract and telemetry come from `@fountain-coach/midi-backplane@v1.0.0`.
- Facts derive only from the IDL and are seeded into FountainStore.
- Runtime loops must emit telemetry; chunk tracker and budget checks remain enabled.
- Telemetry follows `schema/telemetry.yaml` (errors, jitter, resource).
- Resume tokens, chunk rules, and budgets are enforced by the runtime.
- When native Store access is available, do not use HTTP for backplane access.
- MIDI2 adapters must mirror topics without changing the IDL.
- MCP is optional capability only; repo correctness must not depend on MCP.
- Chapter 94 infrastructure authorization is provider-neutral at the MIDI2/FCIS boundary. Provider credentials
remain in SecretStore-backed host adapters; the current admitted implementation is mock-only read-only validation.
Owner-controlled operational production is a distinct, explicitly recorded mode: it still requires a named
provider-specific adapter, SecretStore custody, exact target, signed/pinned artifact, TLS/host handoff where
applicable, rollback/revocation evidence, and bounded acceptance before mutation. Independent external security
review is desirable and must remain a later gate for security-reviewed or public production claims; it is not by
itself a blocker to owner-controlled operational use. Never claim that a review occurred when it did not, and never
promote the mock adapter into a real provider authorization claim.
- The runtime repository is private by publication policy; public Book projections may contain only sanitized,
evidence-backed contracts, release boundaries, and AX/VRT proof. Never publish source, private store data, secrets,
manuscript material, or deployment credentials. The public policy is
`docs/publication-policy.md` and Reframe governance Chapter 44.
- User-facing interfaces follow the org **FCIS-AX Standard** (accessibility is the machine-readable UI layer): every view — including custom-drawn CALayer/Canvas views — exposes its content to the accessibility tree (role/label/value/actions); an agent may not claim or offer state the AX tree does not expose; UI is driven and verified through accessibility, not pixel coordinates or screenshot-only inspection (VRT covers visual fidelity, AX covers semantic truth — see `FCIS-AX-05`). Canonical text: Fountain-Coach `.github` → `docs/FCIS-AX-Standard.md`.
- Live GUI acceptance is a stateful drive: first inspect the existing app; when a fresh launch is needed, place its window on the attached external display and enter full-screen there before the scenario. Resolve and capture that window by CoreGraphics window ID, never by display number or guessed coordinates. AX is the interaction and semantic-state authority; the persisted FountainStore artifacts are behavioural truth; window-ID screenshots establish visual truth; logs are telemetry only. Coordinate input is a documented, temporary bridge only for a current AX gap.
- For Reframe runtime or user-facing implementation changes, use a governed implementation loop by default: implement a bounded slice, run focused tests, live-drive the affected behavior through AX, capture the matching window-ID evidence, read the matching FountainStore artifacts, report observed versus unestablished results, and correct the implementation before declaring the slice complete. Bind every drive to one PID, CoreGraphics window ID, managed Store path, executable path, and source commit; an isolated run must never be reported as the writer's current UI. Documentation-only, schema-only, and non-Reframe changes may use their applicable validation without a GUI drive, but must state that the live loop was excluded and why.
- Build provenance is an acceptance prerequisite: never drive or publish a SwiftPM executable from an unverified cache. Resolve from the committed manifest/lockfile, report the exact package revisions and executable path, and run the repository's negative deprecated-surface check (`apps/modernization-studio/Scripts/verify-reader-ui-surface.sh`). A current source tree plus an older transitive UI package is a failed build, not a valid version.
- FountainStore selection is governed by the released `FountainStoreSessionKit` Swift API. Reframe launches carry one explicit store intent and canonical path; callers must not scan, guess, or recreate leases in shell code. The persisted receipt and owner-safe lease are the admission authority.
- **Estate publication default:** every Fountain Coach publication domain and subdomain is published through the
Swift Store-to-Store operation `estate.publication.sync`: the explicit local FountainStore is the source, the
authenticated remote FountainStore is the destination, and typed remote read-back plus the persisted sync receipt
are the publication proof. Do not select a site generator, static-directory deployment, Caddy copy, generic HTTP
wrapper, or ad-hoc script as the publication path. Domain rendering and hosting remain projections of the remote
Store; they must not become a second publication authority.
- **Bounded publication routing:** when the request names one chapter, page, or domain route, invoke the native
`ReframeEstateSync` host adapter with the canonical `--host` and normalized `--path-prefix`; never begin with a
whole-estate sync. Whole-estate synchronization requires explicit whole-estate intent. Before mutation, establish
the selected local Store route, authenticated remote readiness, SecretStore credential availability, destination
capacity, and exactly one active publication process. Report `COMPLETE` only when the correlated receipt proves the
route patch, typed manifest and selected-path read-back, public HTTPS, and a matching digest; otherwise stop at the
concrete failed seam without changing publication mechanisms.

MIDI2 port authority norm — non-negotiable
- `auto` is the only accepted port input. The Swift `ReframeLaunch` coordinator allocates the peer port, Reframe
binds its target listener, and the resulting `ReframeLaunchReadiness` record is the sole authority for both
resolved ports. The process environment is pre-bind configuration, not readiness; its target value may be `0`.
- Every MIDI2 peer, scenario runner, and acceptance adapter MUST consume and validate the typed readiness record
against the bound Reframe PID, executable, managed Store, and source revision before opening transport. No peer
may read, infer, override, or accept numeric ports from another source. Missing, stale, mismatched, unresolved,
or non-distinct readiness is a bounded failure and ends the run.
- This is a transport admission invariant, not a convenience implementation. A run without the validated record
cannot claim MIDI2 discovery, scenario execution, AX evidence, or terminal proof.

Canonical Reframe launch procedure — mandatory
- For every Reframe live drive, scenario run, or GUI acceptance, launch only through the Swift `ReframeLaunch`
product. Never launch `ReframeApp` directly, through `apps/modernization-studio/Scripts/modernization-studio-one-click.command`,
through `swift run`, or through an ad-hoc shell/background wrapper. The shell launcher is retired from the protocol
path.
- Build the three products from the current manifest before launching:
`swift build --package-path apps/modernization-studio --product ReframeApp`,
`swift build --package-path apps/modernization-studio --product ReframeLaunch`, and
`swift build --package-path apps/modernization-studio --product ReframeScenarioRunner`.
- Prepare the fresh managed Store and typed scenario proof with `ReframeScenarioRunner --prepare`. The scenario
YAML is authoring authority; its checked JSON projection is the runner input. Require both
`scenario-validation: PASS` and `scenario-preparation: COMPLETE`.
- Launch with the exact built executable, canonical managed Store path, `--store-intent` matching the scenario,
scenario JSON, source revision, and two distinct MIDI2 ports:

```sh
apps/modernization-studio/.build/arm64-apple-macosx/debug/ReframeLaunch \
--executable apps/modernization-studio/.build/arm64-apple-macosx/debug/ReframeApp \
--store /absolute/run-dir/store.fountainstore --store-intent explicit \
--scenario-file apps/modernization-studio/LiveScenarios/<scenario>.json \
--midi2-listen-port auto --midi2-peer-port auto \
--source-revision <source-commit>
```

- `ReframeLaunch` must print `swift_ready=true` before any scenario runner, MIDI2 peer, AX action, or acceptance
claim. Process creation is not readiness. Record the Swift launcher PID, Reframe child PID, executable, Store,
scenario, source revision, readiness proof, and both resolved ports. `auto` is the only accepted launch value:
Swift allocates the peer port, Reframe binds its target listener, and the typed readiness record is the sole port
authority consumed by `ReframePeer`. Numeric ports supplied by callers are rejected as guessed transport state.
- After `swift_ready=true`, place the printed Reframe PID with
`swift apps/modernization-studio/Scripts/place-bound-reframe-on-external-display.swift --pid <pid>` and require
`verified: true` (and the governed fullscreen/display gate) before any interaction. Bind all evidence to the same
PID, CoreGraphics window ID, Store path, executable, and source revision.
- If the coordinator, readiness file, AX window, display admission, Store receipt, or MIDI2 terminal event is
missing, stop and report the bounded blocker. Do not substitute another launcher, Store, PID, port, or guessed
window, and do not repair a stalled run with ad-hoc polling or relaunch.

AI reasoning contract
- Operational reasoning precedence is: `schema/idl.yaml` and `schema/facts.json`; live FountainStore state; root `AGENTS.md`; scoped app `AGENTS.md`; generated reasoning manifest; docs and `PLANS.md` as citations only.
- The generated reasoning manifest is the model-facing orientation layer. Handwritten docs may explain naming, history, or UX intent, but they must not override operational contract or state truth.
- Codex is the governing agent operating this repository and, when communicating with Reframe, is a MIDI2 peer. Codex MUST address Reframe through the Swift `ReframePeer` and Reframe's named Composer MIDI2 instrument (`fountaincoach.composer@0.1.0`), using the repository-native RTP-MIDI2 transport. The Composer forwards the request into Reframe's existing intent-mediation boundary; Codex does not become Reframe, impersonate its UI, or create a parallel command language.
- Codex identity is fixed before every Reframe exchange: `Codex / companion agent / codex.peer / reasoning`. The user intention remains a separate peer and Reframe remains the runtime authority. A Composer request with a substituted or collapsed Codex identity is rejected at the Swift ingress boundary.
- When Codex needs Reframe to act, Codex MUST send the natural-language request through that Composer peer and allow Reframe to resolve it against its live command surface and state. AX is for governed UI observation and acceptance evidence only; it is not Codex's Composer transport. Python, Node, direct HTTP, shell launchers, guessed endpoints, and manual UI text injection are not substitutes for the MIDI2 peer path.
- Reframe command reasoning is status-quo grounded: first obtain the existing command surface through Reframe's `/commands` command, then reason over the actual returned entries exactly as presented—using their names, usage, descriptions, availability, and live Reframe/FountainStore state, without assuming an additional schema. Semantically compare what each entry says it does with the user's intent, select an existing command only when that fit is established, and otherwise report that the status quo is insufficient. Never invent command fields, redefine command semantics, infer an unexposed effect, or modify the command system merely to make a selection fit.
- For operational work, Codex may ask Reframe in natural language to perform the requested task on Codex's behalf. Reframe's own intent mediation must then resolve that request against its live command surface and state; Codex must not bypass that mediation by manually inventing or selecting a command from memory.
- Command-driven work must be direct and bounded: obtain the command catalog once, extract only the relevant command entries, invoke the selected existing command once, and perform targeted terminal verification. Do not repeatedly dump the full AX tree, re-search already-resolved source, wait on unrelated build output, or treat exploratory inspection as reasoning progress.
- Token budget is decided by reasoning, never by numeric fit. Clamping, capping, shrinking, truncating, or byte/token-fit selection of prompt context or model output is not allowed anywhere (runtime or tests). Only the model's reasoning about semantic need may decide what context is included and how much output is required. Numeric measurements (token/byte counts) may be observed for telemetry only — they must never decide semantic inclusion or output allowance. A provider API's required maximum is a transport constraint only (e.g. the physical context window): honor it as transport, document it as such, and never use it to shape semantic content.
- Reasoning context must be selected by reasoned semantic relevance for the current phase. Do not assemble full transcript, full manifest, full toolset, and full runtime state by default — but when context cannot be safely selected by reasoning, ask for clarification or retrieve more targeted state rather than truncating or dropping by position/size.
- Freeform user turns must pass through an intent-mediation boundary before any execution planner or tool/action router. Mediation decides whether the turn is actionable, needs clarification, or should stay conversational.
- Natural-language meaning must be resolved by grounded reasoning over contract and live state. Do not decide user intent from exact wording, phrase lists, regex heuristics, or transcript prose matching.
- Phrase or pattern matching is allowed only for explicit machine-facing grammars such as slash commands, IDs, or other deliberately structured inputs; it must not be the authority for operational meaning on chat-native surfaces.
- If a turn can be satisfied from explicit structured references or grounded deterministic controls, do that before spending model budget.
- If grounded contract or state context is insufficient, ask or retrieve. Do not improvise from outdated documentation or default onboarding prose.
- When `schema/idl.yaml`, `schema/facts.json`, roles, AGENTS guidance, or the reasoning-manifest overlay changes, regenerate the tracked reasoning manifest artifacts before considering the repo consistent again.

Routing
- For Modernization Studio work, follow `apps/modernization-studio/AGENTS.md`.
- For Stage Native work, follow `apps/stage-native/AGENTS.md`.
- For Teatro Stage web work, follow `apps/teatro-stage-web/AGENTS.md`.
- For multi-step or high-risk changes, create or update `PLANS.md` before edits.
- Use skills for procedures: `.codex/skills/*/SKILL.md`.

References
- `docs/midi-backplane.md` (IDL contract and telemetry)
- `docs/fountainstore-instrument.md` (FountainStore handler surface)
- `docs/ollama-driver.md` (LLM driver + eval harness)
- `docs/instrument-template.md` (instrument namespace checklist)
- `docs/status-performance.md` (state and scale notes)