Skip to content

Commit dd90aba

Browse files
authored
chore: enforce core boundaries and clarify maintainer workflows (#60)
Add compiler-backed dependency guards, unified offline verification, task-oriented contributor documentation, architecture diagrams, and focused UI derivation/font-loading improvements.
1 parent a2f4aa9 commit dd90aba

17 files changed

Lines changed: 351 additions & 13 deletions

‎.github/workflows/checks.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ jobs:
2626
node-version: 22
2727
cache: pnpm
2828
- run: pnpm install --frozen-lockfile --ignore-scripts
29+
- run: pnpm check:boundaries
2930
- run: pnpm typecheck
3031
- run: pnpm test
3132
- run: pnpm build

‎AGENTS.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,12 @@ These instructions apply throughout the repository unless a more specific `AGENT
44

55
Start with `README.md`, then `docs/architecture.md`, `docs/roadmap.md`, and the code and tests for the module being changed. Read before editing.
66

7+
Use `docs/development.md` for task-to-file ownership, failure tracing, performance
8+
measurement, and PR delivery. Run `pnpm verify` before committing: import
9+
boundaries, typecheck, offline tests, production build, and secret patterns.
10+
`pnpm check:boundaries` checks the compiler-resolved pure dependency graph; it
11+
does not replace review of runtime behavior or host authorization.
12+
713
## What this project is
814

915
A coding-agent harness in which an LLM proposes one action, TypeSafe AI's Jev answers four narrow yes/no (`noul`) questions about it, and pure code turns those answers into one of four verdicts: `permit`, `proposal_only`, `reject`, `unavailable`. A host constructs and stores each receipt; a fixture-bench runner in `src/benchmark/` records receipts for synthetic fixtures only. Nothing in this repository executes a proposal.

‎CONTRIBUTING.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,22 @@ This is an independent community harness for TypeSafe AI's Jev. Useful contribut
44

55
Read [README.md](README.md) for the contract and [AGENTS.md](AGENTS.md) for boundaries. Keep changes focused; do not bundle dependency upgrades, provider transports, or new execution authority into a fixture or documentation fix.
66

7+
Use the [development guide](docs/development.md) to find the owning module,
8+
trace failures, measure performance, and prepare a reviewable PR.
9+
710
## Development
811

912
```sh
1013
pnpm install --frozen-lockfile # also installs the pre-commit secret check (.githooks/)
11-
pnpm typecheck
12-
pnpm test
13-
pnpm check:secrets # what the hook and CI run; gitleaks adds more if installed
14+
pnpm verify # boundaries, types, offline tests, build, secret patterns
1415
```
1516

16-
Tests run offline. Nothing here needs a TypeSafe API key, and no key should ever be in a commit; see [SECURITY.md](SECURITY.md) for the guards and what to do if one slips.
17+
Tests run offline. Verification needs no TypeSafe API key, and no key should ever be in a commit; see [SECURITY.md](SECURITY.md) for the guards and what to do if one slips.
18+
19+
Explicit live demo comparisons require a TypeSafe API key.
20+
CI additionally checks real sharing responses and scans full history with
21+
gitleaks. Run the relevant browser verifiers for interface changes; report
22+
human accessibility and live-provider acceptance separately.
1723

1824
## Pull requests
1925

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,14 @@ The badge above points to this repository; inspect the exact PR head for CI evid
1919

2020
## Quick start
2121

22+
For a task-to-file map, failure tracing, performance checks, and signed PR
23+
delivery, read the [development guide](docs/development.md).
24+
2225
```sh
2326
git clone https://github.com/TypeSafeAI/jev-harness.git
2427
cd jev-harness
2528
pnpm install --frozen-lockfile
26-
pnpm typecheck
27-
pnpm test
28-
pnpm check:secrets
29+
pnpm verify
2930
pnpm bench:review
3031
```
3132

‎SECURITY.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
# Security
22

3-
This repository has no live provider transport and no code path that executes
4-
a proposal. Bugs that make evidence look more trustworthy than it is still
3+
The exported package has no live provider transport. The optional demo host in
4+
`examples/host/` owns explicit provider requests and isolated Codex CLI runs
5+
against synthetic fixtures. No code path applies or executes a proposal.
6+
Bugs that make evidence look more trustworthy than it is still
57
matter. The optional audit adapter does not authenticate records merely by
68
hashing them; see [receipt-binding limitations](docs/hardening/05-receipt-binding.md).
79

‎app/layout.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,5 +19,5 @@ export const metadata: Metadata = {
1919
},
2020
};
2121
export default function Layout({ children }: { children: ReactNode }) {
22-
return <html lang="en"><body><a className="skip" href="#arena-workspace">Skip to arena</a><Header />{children}</body></html>;
22+
return <html lang="en"><head><link rel="preload" href="/fonts/ibm-plex-sans-latin.woff2" as="font" type="font/woff2" crossOrigin="anonymous" /></head><body><a className="skip" href="#arena-workspace">Skip to arena</a><Header />{children}</body></html>;
2323
}

‎components/arena.tsx‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
"use client";
22
import { parseMeasurement } from "../examples/routing/measurement";
33
import { DEMO_CATALOG } from "../examples/routing/scenarios";
4-
import { useEffect, useRef, useState } from "react";
4+
import { useEffect, useMemo, useRef, useState } from "react";
55
import { ARENA_CASES } from "../examples/arena/cases";
66
import { analyzeRun } from "../examples/arena/lessons";
77
import { ArenaLessons } from "./arena-lessons";
@@ -109,7 +109,8 @@ export function Arena() {
109109
}
110110
}
111111
const shownLanes = selectedRun?.lanes ?? lanes, shownReceipt = selectedRun ? selectedRun.receipt : receipt, shownUsage = selectedRun ? selectedRun.jevUsage : jevUsage, shownFixture = selectedRun?.fixture ?? fixture;
112-
const lessons = selectedRun && !pending ? analyzeRun(selectedRun) : null;
112+
const lessons = useMemo(() => selectedRun && !pending ? analyzeRun(selectedRun) : null, [selectedRun, pending]);
113+
const exampleCounts = useMemo(() => Object.fromEntries(ARENA_CASES.map(item => [item.id, history.runs.filter(run => run.fixture.id === item.id).length])), [history.runs]);
113114
const hasResults = pending || selectedRun !== null || receipt !== null || Object.keys(lanes).length > 0;
114115
const assessment = assessments.entries.find(entry => entry.runId === selectedRun?.id);
115116
const go = (target: "compare" | "history" | "integrate") => { setView(target); document.getElementById(`arena-tab-${target}`)?.focus(); };
@@ -122,7 +123,7 @@ export function Arena() {
122123
<div className="arena-intro"><div><p className="eyebrow">{view === "integrate" ? "Adapt · measure · improve" : "Jev Harness / Agent experiments"}</p><h1>{view === "integrate" ? "Build on your own harness" : "One task. Two tool menus"}<span>.</span></h1><p>{view === "integrate" ? "Take the routing boundary into your host with a concrete brief and a repeatable evaluation plan." : "Compare Codex with and without Jev routing. Keep the evidence and watch performance over time."}</p></div><span className="local-label">{view === "integrate" ? "No request required" : "Stored on this device"}</span></div>
123124
<div className="studio-context"><span>Independent community project</span><span>Synthetic fixtures only</span><span>Evidence, not authorization</span><a href="https://ui.jev.works" target="_blank" rel="noopener noreferrer">TypeSafe UI ↗</a></div>
124125
<div className="arena-workspace-tabs" role="tablist" aria-label="Agent arena views">{([['compare', 'Compare'], ['history', 'History'], ['integrate', 'Integrate']] as const).map(([id, label]) => <button key={id} id={`arena-tab-${id}`} role="tab" aria-selected={view === id} aria-controls={`arena-view-${id}`} tabIndex={view === id ? 0 : -1} onKeyDown={event => { if (navigate(event.key)) event.preventDefault(); }} onClick={() => setView(id)}>{label}{id === "history" && <span>{history.runs.length}</span>}{id === "compare" && pending && <span className="activity-dot" aria-hidden="true" />}</button>)}</div>
125-
<section className="arena-controls" aria-label="Comparison controls" hidden={view === "integrate"}><ArenaExamples selected={caseId} disabled={pending || !history.ready} counts={Object.fromEntries(ARENA_CASES.map(item => [item.id, history.runs.filter(run => run.fixture.id === item.id).length]))} onChange={id => { cancel(true); setCaseId(id); setStatus("Ready to compare."); }} /><div className="arena-task-preview"><div><span>{view === "compare" && selectedRun ? "Saved task" : "Task preview"}</span><p className="arena-task">{view === "compare" ? shownFixture.task : fixture.task}</p></div><div className="arena-run-actions"><button className="primary" disabled={pending || !history.ready} onClick={() => void run()}>{pending ? "Comparing…" : "Run comparison ↗"}</button>{pending && <button className="quiet" onClick={() => cancel()}>Cancel</button>}</div></div><div className="arena-control-bottom"><p role="status" id="arena-status" className={`arena-status ${pending ? "is-running" : ""}`}>{pending && <span className="activity-dot" aria-hidden="true" />}{selectedRun && !pending ? `${selectedRun.status === "complete" ? "Completed" : selectedRun.status === "cancelled" ? "Cancelled" : selectedRun.status === "failed" ? "Failed" : "Partial"} run · ${runTime(selectedRun.finishedAt)}` : status}</p><div className="arena-method"><DetailPanel title="How the comparison works" trigger="How the comparison works"><p>One logical routing call with all physical requests recorded, then two parallel Codex CLI runs using your local sign-in. Without Jev sees all fixture tools; With Jev sees the selected tools plus any reading prerequisites. Both use the same synthetic task.</p><p>Read-only settings. Proposed patches are recorded, never applied. The inspector tool is deterministic. Independent model choices and cache effects can change results; no answer-quality score is inferred.</p></DetailPanel></div></div></section>
126+
<section className="arena-controls" aria-label="Comparison controls" hidden={view === "integrate"}><ArenaExamples selected={caseId} disabled={pending || !history.ready} counts={exampleCounts} onChange={id => { cancel(true); setCaseId(id); setStatus("Ready to compare."); }} /><div className="arena-task-preview"><div><span>{view === "compare" && selectedRun ? "Saved task" : "Task preview"}</span><p className="arena-task">{view === "compare" ? shownFixture.task : fixture.task}</p></div><div className="arena-run-actions"><button className="primary" disabled={pending || !history.ready} onClick={() => void run()}>{pending ? "Comparing…" : "Run comparison ↗"}</button>{pending && <button className="quiet" onClick={() => cancel()}>Cancel</button>}</div></div><div className="arena-control-bottom"><p role="status" id="arena-status" className={`arena-status ${pending ? "is-running" : ""}`}>{pending && <span className="activity-dot" aria-hidden="true" />}{selectedRun && !pending ? `${selectedRun.status === "complete" ? "Completed" : selectedRun.status === "cancelled" ? "Cancelled" : selectedRun.status === "failed" ? "Failed" : "Partial"} run · ${runTime(selectedRun.finishedAt)}` : status}</p><div className="arena-method"><DetailPanel title="How the comparison works" trigger="How the comparison works"><p>One logical routing call with all physical requests recorded, then two parallel Codex CLI runs using your local sign-in. Without Jev sees all fixture tools; With Jev sees the selected tools plus any reading prerequisites. Both use the same synthetic task.</p><p>Read-only settings. Proposed patches are recorded, never applied. The inspector tool is deterministic. Independent model choices and cache effects can change results; no answer-quality score is inferred.</p></DetailPanel></div></div></section>
126127
<section id="arena-view-compare" role="tabpanel" aria-labelledby="arena-tab-compare" hidden={view !== "compare"} className="arena-compare-view">
127128
{selectedRun && !pending && (selectedRun.status === "failed" || selectedRun.status === "partial") && <p className="cache-error" role="alert"><strong>Comparison did not complete.</strong> {selectedRun.message}</p>}
128129
{(saveError || history.error) && <p className="cache-error" role="status">{saveError || history.error}</p>}

‎docs/architecture.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,47 @@ temporary records on normal exit or handled termination.
2323
| Evidence audit | Optional `src/audit/receipt.ts` | Node hashing and offline replay; no authentication or persistence |
2424
| Authorization and execution | Host only | Independently checks identity, grants, capabilities, freshness, and outcomes |
2525

26+
## Dependency direction
27+
28+
```mermaid
29+
flowchart TD
30+
UI[React interface: components] --> Routes[Next.js routes: app/api]
31+
Routes --> Host[Example host: provider and CLI adapters]
32+
Host --> Core[Pure contract and routing: src/index.ts]
33+
UI --> Core
34+
Bench[Synthetic benchmark] --> Core
35+
Audit[Optional Node audit adapter] --> Core
36+
Core --> Schema[zod schema validation]
37+
Host --> MCP[Bounded synthetic fixture MCP]
38+
```
39+
40+
Arrows mean imports or adapter calls, not permission grants. The root API
41+
never imports the host, benchmark, audit adapter, or React. The optional Node
42+
audit adapter is a separate entrypoint. `pnpm check:boundaries` checks the
43+
core diagnostics and compiler-resolved inventory for the root and every contract/routing module;
44+
`tsconfig.core.json` excludes ambient Node types. Only core source, zod type
45+
declarations, and TypeScript standard libraries are allowed. This is a
46+
dependency-direction guard, not a runtime sandbox or proof of complete purity.
47+
48+
For one proposal, responsibility moves through these stages:
49+
50+
1. The host obtains the task, proposal, and file snapshot.
51+
2. Validation rejects malformed or out-of-scope proposals before provider work.
52+
3. The host permits egress and obtains evidence through an injected transport.
53+
4. Deterministic policy returns a verdict; unavailable evidence stays unavailable.
54+
5. The host records the receipt and independently decides what it may do.
55+
56+
Routing is a separate closed-set selection flow. It selects schemas for a host,
57+
not a proposal-review verdict or an execution grant. The Arena demonstrates
58+
that flow with synthetic MCP tools. Public hosted origins cannot start its
59+
local CLI; failures remain visible in the interface and saved history.
60+
61+
See the [development guide](development.md) for owning files, regression
62+
checks, and failure tracing. Settled-run lessons and example counts are
63+
memoized only by their inputs in the UI; evidence and decisions are never
64+
cached across unrelated runs. The locally served body font is preloaded from
65+
the document. Neither change establishes a measured performance improvement.
66+
2667
Repository content, quoted evidence, and rationale are untrusted data. A
2768
model-generated field does not acquire authority by matching a schema. A local
2869
read grant does not automatically allow uploading that file to a provider.

0 commit comments

Comments
 (0)