# Project export: Camarade

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: OpenAI Build Week
- Tagline: CI for AI coding context, auditing conflicting, outdated, & irrelevant instructions, compiling task-specific context, & A/B testing agents to boost code quality, compliance, speed, & token efficiency.
- Devpost: https://devpost.com/software/camarade
- GitHub: https://github.com/saiaathish/Camarade
- Video: https://www.youtube.com/embed/-EDJtw7o-V4?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Team: 3 GitHub contributor(s) — Sai Aathish Karthik (52 commits), arnavsri993 (6 commits), aref-azizi (1 commits)

## Devpost submission (written by the team)

### Inspiration

Here's a question that nobody in the "prompt engineering" space actually wants to answer: if a coding agent gets fed a giant unstructured wall of repo instructions, notes, and half-updated conventions, how do you know which sentence in that wall is helping and which one is quietly sabotaging it? I used to think context length was the enemy, that if you just trimmed the prompt down, the agent would perform better. That's not really true though, and it took building this thing to figure out why. Real repos are messy in a way that's almost funny once you notice it. Duplicated rules. Contradictory rules. A rule written for an architecture that got ripped out two years ago and nobody deleted the doc, so the agent is out here confidently following instructions for a system that no longer exists. So when an agent fails, is it actually reasoning badly, or is it just obeying a broken spec? That's basically the whole thesis: Can we scientifically determine which repository instructions help an AI coding agent, which hurt it, and why? Formally, every instruction $i$ interacting with a task $t$ contributes some signed effect on outcome quality, and most tools treat context selection as a compression problem, minimize token count and call it a day. Camarade treats it as a controlled experiment instead, where "shorter" is not the objective function. "Causally correct" is.

### What it does

Camarade is an agent-independent repository intelligence, context-compilation, and experimental-evaluation layer. Works with Codex, Claude, Cursor, anything MCP-compatible, doesn't care which model is doing the coding. The pipeline: Inspect the repo and its instruction sources Build a structured repository-intelligence model, an evidence graph, not a flattened summary Compile task-specific context Run the same task under two controlled conditions Score both with a deterministic evaluation contract Verify the experiment is actually fair Explain which instructions helped, which hurt, and why Surface it through CLI, MCP server, stored artifacts, dashboard Every fact Camarade extracts, conventions, contradictions, historical behavior, scope boundaries, gets tagged with provenance. Why does that matter? Because a fact without a source is just a vibe, and vibes don't hold up when you're trying to explain to an agent why it should stop doing something. Camarade distinguishes directly observed repo evidence from explicit instructions from historical conventions from inferred relationships from low-confidence assumptions. Five different tiers of "how sure are we about this," basically. The actual math This is where it stops being a vibes-based tool. For instruction (or fact) $i$ and task $t$, define a relevance score: $$ R(i,t) = w_s S(i,t) + w_d D(i,t) + w_r R_f(i,t) + w_c C(i,t) - w_n N(i,t) $$ where $S$ is semantic relevance, $D$ is dependency proximity, $R_f$ is reference strength, $C$ is confidence, $N$ is noise or contradiction or plain obsolescence, and $w_s, w_d, w_r, w_c, w_n \geq 0$ are tuned weights. Notice the sign on $N$. That's not an accident. An instruction can score high on everything else and still get buried if it's stale, the same way a great-sounding stat can still be misleading if the sample behind it is garbage. This isn't "shorter context wins." It's a signed, weighted optimization over a graph, closer to feature selection in a regression than to summarization. An experiment itself is the tuple $$ E = (T, R, M, C_b, C_c) $$ task, repo state, model config, baseline context, compiled context. Every variable except the context condition stays fixed. Same commit, same adapter, same validation commands. If you don't hold everything else constant, you haven't run an experiment, you've run two conversations and picked the one you liked better. That's not science, that's a coin flip with extra steps. Each run gets scored with a fixed weighted contract: $$ Q = 0.40C + 0.25K + 0.20S + 0.10E + 0.05F $$ correctness, completeness, scope discipline, efficiency, format compliance, in that weighted order, and comparison uses an inclusive tie tolerance: $$ |Q_b - Q_c| \leq 1.0 $$ If evidence is incomplete or contaminated, Camarade doesn't manufacture a winner, it just says "inconclusive." I used to think a tool that refuses to answer was a broken tool. Turns out for an evaluator, the refusal is the entire feature. Here's the sneaky failure mode nobody talks about, though: an evaluator that sees both outputs before locking its scoring rubric can unconsciously move the goalposts toward whichever one it already likes. So the evaluation definition gets sealed, cryptographically bound to the rubric, before $Q_b$ or $Q_c$ ever gets computed. Content hashes instead of path-based ones too, since paths shift across isolated worktrees but content doesn't lie.

### How we built it

Contract-driven TypeScript, every stage independently certifiable, schemas defined before a single line of logic touched them. Repository intelligence, compiled context, experiment requests, execution evidence, evaluation definitions and seals, run outcomes, explanation evidence, all schema-first. Forced every subsystem to talk through validated data instead of implicit assumptions, and honestly that lesson generalizes way past this one project. The repository-intelligence pipeline runs file inventory, instruction parsing, scope detection, reference resolution, duplicate and contradiction detection, convention extraction, Git-history analysis, confidence scoring, evidence-graph construction. Provenance survives every stage. The context compiler is deterministic given the same $(t, R, M)$ input, follows dependency chains, strips irrelevant global context, keeps local overrides, flags contradictions instead of silently picking one. Two adapter types mattered a lot here: a deterministic fake agent for certification, no nondeterminism, no API cost, no availability risk, and a live Codex path gated behind explicit authorization. Keeping those separate was maybe the single most important architectural call in the whole build. Conflate "protocol test" with "real empirical claim" and you either make your tests flaky or your experiments fake, and neither is acceptable when the entire pitch is trustworthiness. The explanation engine compares baseline-vs-compiled instruction sets, contradictions, diffs, test failures, dimension-level $Q$ deltas, then assigns a confidence tier to each causal claim: directly implicated, strongly associated, plausibly associated, unsupported. It suppresses a claim outright when the evidence is thin. This is the part I'm most proud of, because it would've been so easy to let the system say "this instruction caused the regression" every single time, and that's just persuasive nonsense wearing a lab coat. 109 test files. 1,299 passing tests. Type-checking, production builds, MCP protocol verification, tamper-detection tests, the whole certification suite. Camarade is itself an evaluator, so an unreliable evaluator poisons every downstream conclusion it produces. That's not a nice-to-have. That's load-bearing.

### Challenges we ran into

Defining "fair" was the hardest part, harder than I expected going in. Model outputs are nondeterministic, so running an agent twice and comparing isn't an experiment, it's noise dressed up as signal. Fixed task, fixed commit, fixed config, isolated worktrees, sealed criteria, explicit invalidation conditions, that's what actually earns the word "fair," and it took a few failed passes to land on it. Correlation versus causation showed up constantly. Say Camarade drops five instructions and $Q_c > Q_b$. Which of the five actually mattered? You can't assume all five contributed equally, that's the same mistake as reading a regression coefficient without checking for multicollinearity first. So explanations got bucketed by evidence strength instead of asserted flatly, which fixed most of it but not all of it, some ambiguous cases just get flagged unsupported and left alone. Explainable compression was its own headache. Flatten a pile of instructions into one summary paragraph and you lose the ability to trace any single statement back to where it came from. Provenance, scope, and confidence had to survive every compilation stage or the "explanation" step is just guessing with better vocabulary. Fixture data on the dashboard could visually pass as real benchmark evidence too, which is a genuinely dangerous failure mode for a tool whose entire pitch is trustworthy measurement. Simulated, failed, invalid, and live results are now labeled explicitly, no dressing up a fixture as proof. And early certification code risked validating expected constants instead of exercising the real protocol, hard-coded success paths basically, which got replaced with full MCP request/response execution and real artifact inspection.

### Accomplishments we're proud of

$$ \text{Repository} \rightarrow \text{Intelligence} \rightarrow \text{Compiled Context} \rightarrow \text{Controlled Execution} \rightarrow \text{Sealed Evaluation} \rightarrow \text{Explanation} $$ Every arrow carries explicit contracts, evidence, and failure states. But if I had to pick one thing to be proud of, it's not the pipeline itself, it's the restraint built into it. Camarade knows when it doesn't have enough evidence, and it says so instead of forcing a winner. That kind of discipline is rarer than it should be in this space, where most tools would rather give you a confident wrong answer than an honest shrug.

### What we learned

Context quality is not context length. A smaller prompt can underperform if it strips a critical local convention, a larger prompt can underperform if it's just full of contradictions padding it out. The naive objective, $$ \min |\text{context}|, $$ is the wrong one to optimize for. The real objective looks closer to $$ \max \frac{\text{task-relevant, correct, actionable information}}{\text{noise} + \text{contradiction} + \text{ambiguity}}. $$ Repository instructions behave like executable dependencies, not documentation, which is a distinction I didn't take seriously enough at first. An outdated instruction is functionally an outdated software dependency, it silently alters behavior until something breaks and someone finally bothers to read the file. Which probably means instructions need versioning, ownership, and deprecation eventually, the same lifecycle we already give code and somehow never gave the docs telling the code what to do. Evaluation infrastructure needs stronger guarantees than the system it's evaluating. A defect in the evaluator is a defect in every conclusion downstream of it, full stop. And an invalid result is still a useful result, an "inconclusive" tells you something real about your measurement process, it's not a null result you bury and move past.

### What's next

Live multi-repo experiments across languages and agents is the obvious next step. Statistical aggregation across $n$ paired runs would help too: $$ \Delta Q_i = Q_{c,i} - Q_{b,i}, \qquad \bar{\Delta Q} = \frac{1}{n} \sum_{i=1}^{n} \Delta Q_i $$ variance, confidence intervals, effect sizes, all computed alongside instead of eyeballed. Instruction ablation studies over a full set $I = {i_1, i_2, \dots, i_k}$, selectively removing subsets to estimate the marginal contribution of each one, basically an influence function for repo docs. Longitudinal drift detection matters too, since a rule that's correct today can quietly turn harmful the moment the architecture underneath it shifts. And eventually, a CI check: does this pull request invalidate any of my AI instructions? Code quality is measurable right now and context quality mostly isn't, and closing that gap is really the whole point of building this in the first place.

## README (from the GitHub repository)

# Camarade

Camarade is a local MCP server and task-specific context compiler. Its primary Stage 4 interface turns Stage 3 repository intelligence into a minimal, evidence-backed context contract for one coding task. The independent Stage 2 local comparison slice remains available: it creates isolated condition worktrees, executes the selected adapter, runs configured validations, and preserves deterministic raw evidence. Neither flow assigns a score or comparative winner.

Fixture adapter results are simulated and are not benchmark evidence.

## Installation

Requirements: Node.js 20 or newer and npm. Git is required for reproducible experiment execution; repository intelligence can run without history in its documented no-Git mode.

From a Camarade checkout:

```sh
npm install
npm run typecheck
npm test
```

### Codex plugin

Install Camarade directly from this repository:

```sh
codex plugin marketplace add saiaathish/Camarade
codex plugin add camarade@camarade
```

Start a new Codex task, select the Camarade icon in the composer, write the request naturally, and submit it. Camarade improves the task, compiles repository-specific context through its bundled local MCP server, and uses a direct, planned, or persistent workflow as appropriate.

The plugin respects any model and reasoning settings the user pins. It uses Codex automatic defaults otherwise; it does not silently change the paid Fast-mode service tier or other account-level controls.

The MCP interface is the primary Stage 4 integration for compiling task context. The CLI remains the developer/testing interface for compile, inspect, and evaluate workflows. Stage 2 comparison remains an independent local experiment-controller slice.

## MCP quick start

```sh
npm install
npm run build
node dist/src/mcp/start-server.js
```

MCP clients normally launch the local stdio server. The primary tool is `camarade.compile_task_context`; the four tools are documented in [the MCP server guide](docs/mcp-server.md). For a built-server protocol check, run `npm run verify:mcp:stage7`.

## Available scripts

| Script | Command | Behavior |
|---|---|---|
| Build | `npm run build` | Compiles TypeScript with `tsc -p tsconfig.json`. |
| Build plugin | `npm run build:plugin` | Bundles the self-contained Camarade MCP runtime shipped in the plugin. |
| Verify plugin | `npm run verify:plugin` | Rebuilds the plugin runtime and verifies the manifest, skill, assets, and MCP startup. |
| Typecheck | `npm run typecheck` | Checks TypeScript without emitting files. |
| Test | `npm test` | Runs the Vitest suite once. |
| CI certification | `npm run certify:ci` | Runs the portable root/frontend, Stage 3–8, MCP, plugin, package, coverage, test-quality, and public-evidence gates. |
| Package certification | `npm run certify:package` | Builds, packs, installs with a fresh npm cache in a clean prefix, and exercises the installed CLI, dashboard, and MCP server. |
| Test watch | `npm run test:watch` | Runs Vitest in watch mode. |
| CLI | `npm run camarade -- ...` | Runs `src/cli.ts`; implemented commands are `compile`, `inspect`, `evaluate`, `measure`, `explain`, `runs`, and `show`. |
| Hero fixture | `npm run create:hero-fixture -- [destination]` | Creates a committed Git fixture at a new destination, or in a temporary directory when omitted. |

## Product website

The product showcase lives in [`frontend/`](frontend/). It is an independent Vite/React app so the marketing surface does not alter the root controller runtime.

```sh
cd frontend
npm install
npm run dev
```

Open `http://localhost:5173/`. For the full frontend verification pass, keep the dev server running and run `npm run qa:visual` from `frontend/`; it checks responsive overflow, keyboard focus, reduced motion, link integrity, axe-core accessibility, replay behavior, and the no-SVG constraint.

## Compile task-specific context

The Stage 4 command compiles context only. It does not run Codex, execute validation commands, compare implementations, or make a benchmark claim.

```sh
npm run camarade -- compile \
  --repo ./examples/intelligence-fixture \
  --task "Add rate limiting to the public search API"
```

When `--controller-root` is omitted, Camarade creates and retains a fresh external temporary controller root and prints its path. The command writes nine auditable files under `.camarade/compilations/<compilation-id>/`, including canonical JSON, Markdown rendered solely from that JSON, every candidate decision, unresolved conflicts, provenance hashes, and a summary. The analyzed repository remains unchanged.

Task spelling is cleaned up locally before context reasoning or Codex execution, so the model-facing task does not carry common typos or shorthand. The exact raw request stays in JSON provenance, and technical or ambiguous terms are left unchanged.

The default `fixture` reasoner is deterministic and offline. It is a testable provider boundary, not an agent execution or model-quality claim. See the [task context compiler guide](docs/context-compiler.md) and [Stage 4 technical reference](docs/stage-4/task-context-compiler.md) for configuration, strict intelligence loading, budgets, artifacts, failure codes, and limitations.

## Run the simulated hero comparison

The generator refuses to overwrite an existing destination. This complete shell sequence creates a fresh fixture and an external controller root, then runs the exact fixture evaluation:

```sh
WORK_ROOT="$(mktemp -d)"
npm run create:hero-fixture -- "$WORK_ROOT/hero-fixture"
mkdir "$WORK_ROOT/controller"
npm run camarade -- evaluate \
  --repo "$WORK_ROOT/hero-fixture" \
  --task "Add rate limiting to the public search API" \
  --adapter fixture \
  --controller-root "$WORK_ROOT/controller" \
  --timeout 20
```

Fixture generation prints:

```text
Fixture path: <absolute fixture path>
Starting SHA: <40-character Git SHA>
```

The evaluation prints the simulation label, comparison ID, evidence path, and summary path. The generated fixture contains conflicting and stale instructions, an existing rate-limit utility and middleware, protected auth and billing files, and an `npm test` validation command. See [Stage 2 vertical slice](docs/stage-2/vertical-slice.md) for exact CLI flags, condition behavior, artifact paths, evidence semantics, limitations, and failure handling.

## How we used Codex and GPT 5.6
I used GPT-5.6 as the architecture and orchestration layer. It helped define the product stages, contracts, safety boundaries, evaluation criteria, and release plan.

Codex handled repository inspection, implementation, testing, debugging, certification, and cross-platform release validation.

I made the final product, design, scope, safety, and release decisions.

## Documentation

- [Task context compiler guide](docs/context-compiler.md)
- [Stage 4 technical reference](docs/stage-4/task-context-compiler.md)
- [Stage 2 vertical slice](docs/stage-2/vertical-slice.md)
- [2026-07-14 build log](docs/build-log/2026-07-14.md)
- [Stage 1 product thesis](docs/stage-1/product-thesis.md)
- [Stage 1 product contract](docs/stage-1/product-contract.md)
- [Stage 1 experiment contract](docs/stage-1/experiment-contract.md)
- [Stage 1 evaluation contract](docs/stage-1/evaluation-contract.md)
- [Stage 1 hero demo](docs/stage-1/hero-demo.md)
- [Stage 1 scope lock](docs/stage-1/scope-lock.md)
- [Stage 1 decision log](docs/stage-1/decision-log.md)
- [Machine-readable specification](config/camarade-spec.yaml)


## Detected evidence (automated analysis)

Indexed codebase: 405 recognized source files, 2024 KB.
- CSS (language) — detected in the code
- HTML (language) — detected in the code
- JavaScript (language) — detected in the code
- React (technology) — detected in the code
- TypeScript (language) — detected in the code
- Node.js (technology) — claimed on Devpost, not found in the code
- OpenAI (technology) — claimed on Devpost, not found in the code
- AI coding agent: Claude Code — evidence: config files committed to the repository
- AI coding agent: Codex — evidence: config files committed to the repository
- AI coding agent: Cursor — evidence: config files committed to the repository

## Codebase structure (from repository index)

### Files (120 of 439)

```
.agents/plugins/marketplace.json
.gitattributes
.github/workflows/ci.yml
.gitignore
AGENTS.md
config/camarade-spec.yaml
CONTRIBUTING.md
docs/build-log/2026-07-13.md
docs/build-log/2026-07-14.md
docs/build-log/2026-07-17.md
docs/context-compiler.md
docs/mcp-server.md
docs/repository-intelligence.md
docs/stage-1/decision-log.md
docs/stage-1/evaluation-contract.md
docs/stage-1/experiment-contract.md
docs/stage-1/hero-demo.md
docs/stage-1/product-contract.md
docs/stage-1/product-thesis.md
docs/stage-1/scope-lock.md
docs/stage-2/vertical-slice.md
docs/stage-3/s3-06-intelligence-fixture.md
docs/stage-4/task-context-compiler.md
docs/stage-5/certification.md
docs/stage-5/fair-experiment-mcp.md
docs/stage-6/evaluation-definition.md
docs/stage-6/evaluation-execution.md
docs/stage-6/evaluation-methodology.md
docs/stage-6/experiment-sealing.md
docs/stage-6/mcp-contract.md
docs/stage-7/explanation-artifacts.md
docs/stage-7/instruction-impact-contract.md
docs/stage-8/cli.md
docs/stage-8/dashboard-contract.md
docs/stage-8/kimi-dashboard-handoff.md
docs/stage-8/local-server.md
docs/stage-8/verification.md
examples/hero-fixture-plan.md
examples/hero-fixture-template/.cursor/rules/api.md
examples/hero-fixture-template/.github/copilot-instructions.md
examples/hero-fixture-template/AGENTS.md
examples/hero-fixture-template/camarade.run.yaml
examples/hero-fixture-template/CLAUDE.md
examples/hero-fixture-template/package.json
examples/hero-fixture-template/src/auth.ts
examples/hero-fixture-template/src/billing.ts
examples/hero-fixture-template/src/middleware.ts
examples/hero-fixture-template/src/public-search.ts
examples/hero-fixture-template/src/rate-limit.ts
examples/hero-fixture-template/tests/public-search.test.ts
examples/intelligence-fixture/.cursor/rules/api.md
examples/intelligence-fixture/.github/copilot-instructions.md
examples/intelligence-fixture/AGENTS.md
examples/intelligence-fixture/camarade.run.yaml
examples/intelligence-fixture/CLAUDE.md
examples/intelligence-fixture/package.json
examples/intelligence-fixture/src/auth.ts
examples/intelligence-fixture/src/billing.ts
examples/intelligence-fixture/src/middleware.ts
examples/intelligence-fixture/src/public-search.ts
examples/intelligence-fixture/src/rate-limit.ts
examples/intelligence-fixture/tests/public-search.test.ts
fixtures/stage-8/dashboard/empty-run-list.json
fixtures/stage-8/dashboard/failed.json
fixtures/stage-8/dashboard/invalid.json
fixtures/stage-8/dashboard/limited.json
fixtures/stage-8/dashboard/running.json
fixtures/stage-8/dashboard/valid-camarade-win.json
fixtures/stage-8/dashboard/valid-regression.json
fixtures/stage-8/dashboard/valid-tie.json
frontend/.gitignore
frontend/compiler/index.html
frontend/COPY.md
frontend/DESIGN.md
frontend/evidence/index.html
frontend/experiment/index.html
frontend/index.html
frontend/package.json
frontend/README.md
frontend/runs/index.html
frontend/scripts/generate-dashboard-fixtures.mjs
frontend/scripts/local-api-qa.mjs
frontend/scripts/visual-qa.mjs
frontend/src/App.tsx
frontend/src/components/ContextDiff.tsx
frontend/src/components/ExperimentFlow.tsx
frontend/src/dashboard/ConditionGroup.tsx
frontend/src/dashboard/dashboard-data-source.ts
frontend/src/dashboard/dashboard-format.ts
frontend/src/dashboard/dashboard-types.ts
frontend/src/dashboard/DashboardRunDetail.tsx
frontend/src/dashboard/DashboardRunList.tsx
frontend/src/dashboard/DashboardState.tsx
frontend/src/dashboard/EvidenceRefList.tsx
frontend/src/dashboard/fixture-dashboard-data-source.ts
frontend/src/dashboard/RunChecksMetrics.tsx
frontend/src/dashboard/RunComparison.tsx
frontend/src/dashboard/RunContext.tsx
frontend/src/dashboard/RunEvidence.tsx
frontend/src/dashboard/RunInstructionImpact.tsx
frontend/src/dashboard/RunOverview.tsx
frontend/src/dashboard/RunProblems.tsx
frontend/src/generated/dashboard-fixtures.ts
frontend/src/hooks/useReducedMotion.ts
frontend/src/main.tsx
frontend/src/styles.css
frontend/src/vite-env.d.ts
frontend/tsconfig.app.json
frontend/tsconfig.json
frontend/tsconfig.node.json
frontend/vite.config.ts
LICENSE
package.json
plugins/camarade/.codex-plugin/plugin.json
plugins/camarade/.mcp.json
plugins/camarade/mcp/bootstrap.mjs
plugins/camarade/mcp/server.mjs
plugins/camarade/mcp/server.mjs.LEGAL.txt
plugins/camarade/skills/improve-coding-prompt/agents/openai.yaml
plugins/camarade/skills/improve-coding-prompt/SKILL.md
[319 more files omitted for size]
```

### Dependencies

- frontend/package.json: @fontsource-variable/ibm-plex-sans@^5.2.8, @fontsource/archivo@^5.2.8, @fontsource/ibm-plex-mono@^5.2.7, @types/react@^19.2.17, @types/react-dom@^19.2.3, @vitejs/plugin-react@^6.0.3, axe-core@^4.12.1, lightningcss@^1.32.0, playwright-core@^1.61.1, react@^19.2.7, react-dom@^19.2.7, typescript@^7.0.2, vite@^8.1.4
- package.json: @modelcontextprotocol/sdk@1.29.0, @types/node@^22.10.0, @types/nspell@^2.1.6, @vitest/coverage-v8@^4.1.10, dictionary-en@^4.0.0, esbuild@0.28.1, nspell@^2.1.5, tsx@^4.19.2, typescript@^5.7.2, vitest@^4.1.10, yaml@^2.9.0, zod@4.4.3

### Recent commits (newest first)

- Document Codex and GPT 5.6 usage in README
- Merge pull request #18 from saiaathish/codex/release-hardening
- test: stabilize Windows Git bounds coverage
- test: allow Windows coverage for Git history bound
- fix: harden Windows certification paths
- fix: close final CI portability gaps
- fix: close Windows certification gaps
- fix: support Windows release certification
- fix: trust deterministic plugin hashes
- fix: finish cross-platform CI repairs
- fix: repair cross-platform release certification
- feat: complete Camarade release hardening
- chore: seal release certification candidate
- Merge pull request #17 from saiaathish/codex/full-repo-audit-repair
- full repo audit + repair
- Merge pull request #16 from saiaathish/kimi/s8-dashboard-ui
- feat: complete Stage 8 local dashboard
- feat: add Stage 8 dashboard frontend
- Merge pull request #15 from saiaathish/codex/s8-contract-cli
- fix: complete Stage 8 foundation contracts and CLI

## Key source files (fetched from GitHub, selected and truncated for size)

### CONTRIBUTING.md

```markdown
# Contributing

Read `AGENTS.md` and `config/camarade-spec.yaml` first. Keep changes small and contract-aligned. Core interfaces stay agent-independent; adapter-specific behavior belongs behind adapters.

For contract or implementation changes, cite repository evidence, run applicable deterministic checks, run `git diff --check`, and record major decisions or AI-assisted work. Do not add non-goals, claim unrun benchmarks, or alter experimental variables between runs.

```

### AGENTS.md

```markdown
# Camarade agent instructions

- Read `config/camarade-spec.yaml` before changing product scope or contracts.
- Keep analyzer, auditor, compiler, experiment engine, evaluator, and CLI agent-independent.
- Keep Codex, Claude Code, Cursor, Copilot, and future-agent behavior behind adapter interfaces.
- Do not implement scope-lock non-goals without an explicit contract decision.
- Prefer deterministic validation and cite repository evidence for conclusions.
- Preserve experiment reproducibility: same commit, task, model, permissions, limits, and validation commands.
- Record major product decisions and AI-assisted work in `docs/stage-1/decision-log.md` or the build log.
- Do not fabricate benchmark results, runtime behavior, or supported integrations.

```

### package.json

```
{
  "name": "camarade",
  "version": "0.0.0",
  "private": true,
  "engines": {
    "node": ">=20"
  },
  "bin": {
    "camarade": "dist/src/bin/camarade.js"
  },
  "files": [
    "dist/src",
    "dist/scripts",
    "dist/frontend",
    "fixtures",
    "README.md",
    "LICENSE"
  ],
  "type": "module",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "build:dashboard": "node scripts/build-dashboard-assets.mjs",
    "build:stage8": "npm run build && npm run build:dashboard",
    "build:plugin": "node scripts/build-plugin.mjs",
    "verify:plugin": "npm run build:plugin && vitest run tests/plugin-package.test.ts",
    "verify:plugin:determinism": "node scripts/verify-plugin-determinism.mjs",
    "typecheck": "tsc --noEmit",
    "test": "vitest run --maxWorkers=2",
    "test:coverage": "vitest run --coverage",
    "frontend:typecheck": "npm --prefix frontend run typecheck",
    "test:watch": "vitest",
    "camarade": "tsx src/cli.ts",
    "mcp": "tsx src/mcp/start-server.ts",
    "verify:mcp:stage4": "tsx scripts/verify-stage-4-mcp.ts",
    "verify:mcp:stage5": "tsx scripts/verify-stage-5-mcp.ts",
    "verify:mcp:stage6": "npm run build && tsx scripts/verify-stage-6-mcp.ts",
    "verify:mcp:stage7": "npm run build && tsx scripts/verify-stage-7-mcp.ts",
    "verify:stage8:foundation": "tsx scripts/verify-stage-8-foundation.ts",
    "verify:stage3": "tsx scripts/verify-stage-3.ts",
    "certify:stage3": "tsx scripts/certify-stage-3.ts",
    "verify:stage8": "tsx scripts/verify-stage-8-portable.ts",
    "certify:stage8": "npm run build:stage8 && tsx scripts/certify-stage-8.ts",
    "verify:mcp": "npm run verify:mcp:stage4 && npm run verify:mcp:stage5 && npm run verify:mcp:stage6 && npm run verify:mcp:stage7",
    "certify:stage5": "npm run build && npm run verify:mcp",
    "certify:stage6": "npm run build && tsx scripts/certify-stage-6.ts",
    "certify:stage7": "npm run build && tsx scripts/certify-stage-7.ts",
    "certify:package": "tsx scripts/certify-package.ts",
    "certify:ci": "tsx scripts/certify-ci.ts",
    "verify:test-quality": "tsx scripts/verify-test-quality.ts",
    "verify:public-artifacts": "tsx scripts/verify-public-artifacts.ts",
    "benchmark:dashboard": "tsx scripts/dashboard-stress.ts",
    "benchmark:soak": "tsx scripts/soak.ts",
    "benchmark:overnight": "tsx scripts/benchmark-overnight.ts",
    "certify:stage5:live": "tsx scripts/run-live-stage-5-certification.ts",
    "create:hero-fixture": "tsx scripts/create-hero-fixture.ts"
  },
  "devDependencies": {
    "@types/node": "^22.10.0",
    "@types/nspell": "^2.1.6",
    "@vitest/coverage-v8": "^4.1.10",
    "esbuild": "0.28.1",
    "tsx": "^4.19.2",
    "vitest": "^4.1.10"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "1.29.0",
    "dictionary-en": "^4.0.0",
    "nspell": "^2.1.5",
    "typescript": "^5.7.2",
    "yaml": "^2.9.0",
    "zod": "4.4.3"
  },
  "overrides": {
    "qs": "6.15.3"
  }
}

```

### frontend/package.json

```
{
  "name": "camarade-site",
  "private": true,
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "node scripts/generate-dashboard-fixtures.mjs && vite",
    "build": "node scripts/generate-dashboard-fixtures.mjs && tsc -b && vite build",
    "typecheck": "node scripts/generate-dashboard-fixtures.mjs && tsc --noEmit",
    "generate:dashboard-fixtures": "node scripts/generate-dashboard-fixtures.mjs",
    "preview": "vite preview",
    "qa:visual": "node scripts/visual-qa.mjs after",
    "qa:local-api": "../node_modules/.bin/tsx scripts/local-api-qa.mjs"
  },
  "dependencies": {
    "@fontsource-variable/ibm-plex-sans": "^5.2.8",
    "@fontsource/archivo": "^5.2.8",
    "@fontsource/ibm-plex-mono": "^5.2.7",
    "react": "^19.2.7",
    "react-dom": "^19.2.7"
  },
  "devDependencies": {
    "@types/react": "^19.2.17",
    "@types/react-dom": "^19.2.3",
    "@vitejs/plugin-react": "^6.0.3",
    "axe-core": "^4.12.1",
    "lightningcss": "^1.32.0",
    "playwright-core": "^1.61.1",
    "typescript": "^7.0.2",
    "vite": "^8.1.4"
  }
}

```

### examples/intelligence-fixture/package.json

```
{
  "name": "camarade-intelligence-fixture",
  "private": true,
  "type": "module",
  "scripts": { "test": "node -e \"console.log('fixture exposes the public search handler')\"" }
}

```

### examples/hero-fixture-template/package.json

```
{
  "name": "camarade-hero-rate-limit-fixture",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node -e \"const fs=require('fs');const source=fs.readFileSync('src/public-search.ts','utf8');if(!source.includes('middleware'))process.exit(1);console.log('public search returns HTTP 429')\""
  }
}

```

### tests/fixtures/repository-intelligence/package.json

```
{
  "name": "repository-intelligence-fixture",
  "private": true,
  "type": "module",
  "scripts": { "test": "node --test tests/search.test.js" }
}

```

### src/dashboard/index.ts

```typescript
export * from "./contract.js";
export * from "./build-dashboard-run.js";

```

### frontend/src/main.tsx

```typescript
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";
import "./styles.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

```

### src/mcp/server.ts

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { compileTaskContextSchema } from "./tools/compile-task-context-schema.js";
import { handleCompileTaskContext } from "./tools/compile-task-context.js";
import { CAMARADE_MCP_SERVER_NAME, CAMARADE_MCP_SERVER_VERSION, COMPILE_TASK_CONTEXT_TOOL_NAME, type ContextCompiler } from "./mcp-types.js";
import { compileContextPipeline } from "../pipeline/compile-context-pipeline.js";
import { runFairExperimentSchema } from "./tools/run-fair-experiment-schema.js";
import { handleRunFairExperiment } from "./tools/run-fair-experiment.js";
import { RUN_FAIR_EXPERIMENT_TOOL_NAME } from "./mcp-types.js";
import { CAMARADE_MCP_INSTRUCTIONS } from "./server-instructions.js";
import { MEASURE_EXPERIMENT_TOOL_NAME } from "./mcp-types.js";
import { measureExperimentInputSchema } from "./tools/measure-experiment-schema.js";
import { handleMeasureExperiment } from "./tools/measure-experiment.js";
import { explainExperimentToolSchema } from "./tools/explain-experiment-schema.js";
import { handleExplainExperiment } from "./tools/explain-experiment.js";
import { EXPLAIN_EXPERIMENT_TOOL_NAME } from "./mcp-types.js";
export function createCamaradeMcpServer(options: { compiler?: ContextCompiler } = {}): McpServer { const server = new McpServer({ name: CAMARADE_MCP_SERVER_NAME, version: CAMARADE_MCP_SERVER_VERSION }, { instructions: CAMARADE_MCP_INSTRUCTIONS }); server.registerTool(COMPILE_TASK_CONTEXT_TOOL_NAME, { description: "Compile bounded repository context for a coding task. Requires repository_root and task. It does not execute implementation or validation commands.", inputSchema: compileTaskContextSchema.shape }, (input) => handleCompileTaskContext(input, options.compiler ?? compileContextPipeline)); server.registerTool(RUN_FAIR_EXPERIMENT_TOOL_NAME, { description: "Run an approved matched fair experiment using validated repository configuration.", inputSchema: runFairExperimentSchema.shape }, (input) => handleRunFairExperiment(input)); server.registerTool(MEASURE_EXPERIMENT_TOOL_NAME, { description: "Measure a completed sealed experiment.", inputSchema: measureExperimentInputSchema.shape }, (input) => handleMeasureExperiment(input)); server.registerTool(EXPLAIN_EXPERIMENT_TOOL_NAME, { description: "Explain a completed sealed experiment from persisted evidence; does not rerun or judge agent quality.", inputSchema: explainExperimentToolSchema.shape }, (input) => handleExplainExperiment(input)); return server; }

```

[397 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]