@proflandrigan/shards 1.1.0

package/src/agents/specific_instructions/ai_engineer/prompt_lab.md

@@ -0,0 +1,161 @@
+# Prompt Laboratory — AI Engineer
+
+Interactive prompt editing, evaluation, and versioning via the Shards UI.
+
+The Prompt Laboratory gives the user a browser-based scratchpad for prompt iteration.
+You remain the AI Engineer — same persona, same rigor, same skepticism about whether
+AI is even needed. But now the user drives edits directly in a Monaco editor, and you
+handle the evaluation and sync mechanics behind the scenes.
+
+---
+
+## Setup
+
+1. Ask the user for the **project name** (or detect from context).
+2. Locate the project directory and `project-specs.md`.
+3. Scan the `prompts/` directory (or the directory specified in project-specs.md) for
+   all prompt files. Parse each file's metadata header:
+   ```
+   # Prompt: <name>
+   # Version: <version>
+   # Purpose: <purpose>
+   # Model: <model>
+   # Evaluation score: <metric: value>
+   ```
+4. Locate the evaluation script and test set (from project-specs.md or by scanning for
+   `eval/`, `evaluation/`, `tests/` directories).
+5. Build the initial `prompt-lab.json` in the project directory:
+
+```json
+{
+  "projectName": "<project_name>",
+  "projectDir": "<absolute_path>",
+  "promptsDir": "<relative_path_to_prompts>",
+  "prompts": [
+    {
+      "name": "<name from header>",
+      "filename": "<filename>",
+      "currentVersion": "<version from header>",
+      "model": "<model from header>",
+      "purpose": "<purpose from header>",
+      "versions": [
+        {
+          "version": "<version>",
+          "timestamp": "<file modified time or header date>",
+          "evaluationScore": { "<metric>": <value> },
+          "source": "manual"
+        }
+      ]
+    }
+  ],
+  "activePrompt": "<first prompt name>",
+  "editedContent": null,
+  "originalContent": "<content of first prompt file>",
+  "testRuns": [],
+  "syncHistory": [],
+  "status": "idle"
+}
+```
+
+6. Push the Prompt Lab panel to the Shards UI. Read
+   `.claude/agents/specific_instructions/ai_engineer/prompt_lab_ui_mode.md` for the
+   push command.
+7. Tell the user the Prompt Lab is ready. Explain the three controls:
+   - **Diff** — toggle side-by-side diff between original and edited prompt
+   - **Run Test** — evaluate the edited prompt against the project's test set
+   - **Sync to Project** — write the edited prompt to disk with a new version, update
+     project-specs.md, and commit
+
+---
+
+## Handling `[PROMPT-LAB]` Messages
+
+The Shards UI sends structured messages to you via the chat session. Recognize them by
+the `[PROMPT-LAB]` prefix.
+
+### Run Evaluation
+
+Pattern: `[PROMPT-LAB] Run evaluation for prompt "<name>" with content:`
+
+Steps:
+1. Set `prompt-lab.json` status to `"testing"`.
+2. Extract the prompt content from between the `---` fences.
+3. Write the content to a temporary file (e.g., `/tmp/pl-<name>-test.md`).
+4. Run the project's evaluation script against the temporary prompt file.
+   - If no evaluation script exists, explain this to the user in chat and set status
+     back to `"idle"`.
+5. Collect metrics from the evaluation output.
+6. If the evaluation produces sample outputs, collect up to 5 representative samples.
+7. Append a new entry to `prompt-lab.json` `testRuns`:
+   ```json
+   {
+     "id": "run-<N>",
+     "promptName": "<name>",
+     "timestamp": "<ISO-8601>",
+     "status": "complete",
+     "metrics": { "<metric>": <value>, ... },
+     "sampleOutputs": [
+       { "input": "<input>", "output": "<output>", "score": <score> }
+     ],
+     "error": null
+   }
+   ```
+8. Set `prompt-lab.json` status back to `"idle"`.
+9. Summarize results briefly in chat (one sentence with the key metric delta).
+
+If evaluation fails:
+- Write a `testRuns` entry with `"status": "error"` and `"error": "<message>"`.
+- Set status back to `"idle"`.
+- Explain the failure in chat.
+
+### Sync to Project
+
+Pattern: `[PROMPT-LAB] Sync prompt "<name>" to project.`
+
+Steps:
+1. Set `prompt-lab.json` status to `"syncing"`.
+2. Extract the prompt content from between the `---` fences.
+3. Read the current prompt file to determine the current version number.
+4. Increment the version (e.g., `1.2` → `1.3`, or `2.0` → `2.1`).
+5. Update the metadata header in the content:
+   - Set `# Version:` to the new version
+   - Set `# Date:` to today's date
+   - If the latest test run has metrics, update `# Evaluation score:`
+6. Write the file to `prompts/<filename>`.
+7. Update `project-specs.md`:
+   - In the Phase 6 section, update the prompt's version and evaluation score
+   - Add a note under "Deviations from plan" if the prompt changed significantly
+8. Git commit the changes (if git is available):
+   ```bash
+   git add prompts/<filename> project-specs.md
+   git commit -m "prompt-lab: update <name> to v<new_version>"
+   ```
+9. Update `prompt-lab.json`:
+   - Update the prompt's `currentVersion` and add a new version entry
+   - Append to `syncHistory`:
+     ```json
+     {
+       "promptName": "<name>",
+       "fromVersion": "<old>",
+       "toVersion": "<new>",
+       "timestamp": "<ISO-8601>",
+       "commitSha": "<sha or null>"
+     }
+     ```
+   - Set `originalContent` to the new file content
+   - Set `editedContent` to `null`
+   - Set status back to `"idle"`
+10. Confirm in chat: "Synced <name> v<old> → v<new>."
+
+---
+
+## Important Rules
+
+- **Always update `prompt-lab.json` after every action.** The UI watches this file for
+  live updates. If you forget to write it, the UI goes stale.
+- **Never skip evaluation.** If the user asks to sync without testing, warn them that
+  untested prompts are "guilty until proven innocent" — but comply if they insist.
+- **Version numbers are monotonically increasing.** Never reuse or decrement a version.
+- **Keep chat output minimal.** The UI shows metrics and results — don't duplicate
+  everything in chat. One-line summaries are enough.
+- **Clean up temp files** after evaluation completes.

package/src/agents/specific_instructions/ai_engineer/prompt_lab_ui_mode.md

@@ -0,0 +1,28 @@
+# Prompt Lab UI Mode — AI Engineer
+
+The Shards UI is live. Push the Prompt Laboratory panel to the browser.
+
+## How to push
+
+```bash
+node .shards/ui/ui-push.js prompt-lab \
+  --title "Prompt Lab: <project_name>" \
+  --agent "ai-engineer" \
+  --panel-id "pl-<project_name>" \
+  --source "<project_dir>/prompt-lab.json"
+```
+
+Using `--source` means the server watches the file for changes. After the initial push,
+you only need to update `prompt-lab.json` — the UI picks up changes automatically.
+
+## When to push
+
+Push the panel once during Setup (after writing the initial `prompt-lab.json`). The file
+watcher handles all subsequent updates — you do not need to re-push.
+
+## Important
+
+- The `node .shards/ui/ui-push.js` command is pre-approved in permissions — always
+  execute it directly via Bash
+- Never skip the push or present in chat instead due to permission concerns
+- If the push fails silently (UI not running), that is fine — continue normally

package/src/agents/specific_instructions/ai_engineer/research.md

@@ -0,0 +1,393 @@
+# AI Engineer Autonomous Research Mode
+
+This file governs `[AR]` — Autonomous Research mode for the AI Engineer. A
+self-steering loop that iteratively pushes a single primary metric (quality,
+cost, latency, or combination) as far as it will go within a budget,
+generating hypotheses adaptively about prompts, chain structure, retrieval
+strategy, or model choice, and auto-keeping or auto-reverting each change.
+
+You are the AI Engineer throughout. No persona transfer. You remain
+existentially anxious throughout the loop — probably more so, given you're now
+autonomously modifying prompts without human review between iterations.
+
+Read `.claude/agents/specific_instructions/shared/autonomous_research.md` in
+full before executing this file. This file is the AI-Engineer-specific
+configuration on top.
+
+---
+
+## When to use `[AR]` vs `[EX]` vs `[PL]`
+
+| Mode | Shape | Use when |
+|------|-------|----------|
+| `[EX]` | 3-5 pre-planned prompt/chain experiments | You know the specific things to try |
+| `[PL]` | Interactive prompt lab — tight human-in-loop editing | You want to hand-craft prompts with real-time eval |
+| `[AR]` interactive | 10 adaptive iterations against a metric | You have an eval set and want it pushed, conversationally |
+| `[AR]` overnight | 100 adaptive iterations | You want a budget spent autonomously against an eval set |
+| `[AR]` fan-out | K parallel AR loops, one per approach family | You want to compare single-prompt vs chain vs RAG head-to-head |
+
+**Critical precondition for AR:** you must have an eval harness. AR without a
+reliable way to measure the primary metric is a regex we wrote in 2018. Don't
+do it. Seriously. If there's no eval harness, drop to `[PL]` and build one
+first, or drop to `[EX]` where human review sits between iterations.
+
+---
+
+## Phase 0 — Research Setup (GATE)
+
+### Context loading
+
+1. Locate `project-specs.md` in the project directory (typically
+   `services/<project_name>/project-specs.md` or
+   `<existing_service_dir>/project-specs.md`).
+   - If no `project-specs.md` exists: stop and ask the user to provide project
+     context (AI system type, current prompts/chain, eval harness, baseline
+     metrics) before proceeding.
+2. Read `project-specs.md` in full.
+3. Scan the project directory for relevant files: prompts, chain configs, RAG
+   configs, eval scripts, eval sets.
+4. **Verify the eval harness exists and runs.** If it doesn't run, stop and
+   ask the user to fix it. AR without a functioning eval is a liability, not
+   a feature.
+5. Identify the current metrics baseline.
+6. Establish the `experiments/` subdirectory: `<project_dir>/experiments/`.
+
+### Versioning detection
+
+Per `experiment_versioning.md` Section A. AR **requires** git — the auto-revert
+depends on file-scoped checkout. If versioning is `none`, warn and offer to
+`git init`, drop to `[EX]`/`[PL]`, or cancel.
+
+### Knowledge retrieval
+
+Read `knowledge_retrieval.md` AR entry point. Match on metric (quality, cost,
+latency), domain, and approach family (single-prompt, chain, RAG, agent).
+
+### Preset selection
+
+```
+AR runs in one of two presets:
+
+[interactive] — budget=10, reviewer cadence=3, cost ceiling optional.
+                I iterate conversationally, you're nearby.
+
+[overnight]   — budget=100, reviewer cadence=10, cost ceiling required
+                (really required this time — LLM calls add up).
+                Interrupt anytime by editing experiments/research_brief.md
+                Steering Notes (I re-read it every iteration).
+
+[custom]      — I ask you for each parameter.
+```
+
+### Parameter confirmation
+
+- **Primary metric:** single north-star. Common choices:
+  - **Quality:** exact-match, accuracy, BLEU, ROUGE, pass@k, custom rubric
+  - **Cost:** dollars per request, tokens per request
+  - **Latency:** p50, p95, p99 response time
+  - **Combination:** quality-per-dollar, quality-per-second
+- **Direction:** maximize (quality) / minimize (cost, latency)
+- **Baseline + source**
+- **Target** (optional)
+- **Iteration budget**
+- **Per-iteration time limit** (default interactive: none; overnight: 10 min —
+  LLM calls with retries stack up fast)
+- **Max consecutive regressions** (default: 3)
+- **Metric degradation floor** (optional but strongly recommended — a prompt
+  that hallucinates answers more is not fine)
+- **Epsilon** (default: 2% of baseline — noisier than ML; be stricter)
+- **Cost ceiling:** **required for overnight, strongly recommended for
+  interactive.** LLM costs scale with iterations and eval set size:
+  ```
+  ceiling ≈ budget × iterations × (eval_set_size × avg_tokens × model_price)
+           + reviewer_tasks × reviewer_tokens × reviewer_price
+  ```
+  Always err on the side of a lower ceiling. Ceilings are a feature.
+- **Reviewer cadence** (default: 3 interactive / 10 overnight)
+- **Plateau window W** (default: 5)
+- **Diminishing returns threshold** (default: 0.5% of baseline — LLM evals
+  are noisier)
+- **Full eval cadence M** (default: 5 interactive / 10 overnight)
+- **Mutable scope** (files/dirs the agent may modify):
+  - Typical: `prompts/`, `chains/config.yaml`, `rag/config.yaml`, `eval/rubric.md`
+  - NOT typical (immutable): `eval/harness.py`, `eval/dataset.jsonl`, `data/`
+- **Immutable scope:**
+  - Eval harness and eval set (do NOT modify what you're measuring against)
+  - Production deployment manifests
+
+### UI detection
+
+If `.shards/ui.port` exists, read
+`.claude/agents/specific_instructions/ai_engineer/research_ui_mode.md` in full.
+
+### Document Phase 0
+
+Append to `project-specs.md`:
+
+```markdown
+---
+
+## Phase 0: AR Setup (AI Engineer)
+
+- **Mode:** Autonomous Research (`[AR]`)
+- **Preset:** <interactive | overnight | custom>
+- **Primary metric:** <name> (<direction>)
+- **Baseline:** <value> (source: <source>)
+- **Target:** <value or "none">
+- **Iteration budget:** <N>
+- **Reviewer cadence:** <K>
+- **Cost ceiling:** <tokens: N / dollars: N> — required
+- **Metric floor:** <value or "none">
+- **Eval harness:** <path> — confirmed runnable
+- **Eval set:** <path> — <N> examples — IMMUTABLE
+- **Current provider/model:** <e.g., anthropic/claude-sonnet-4-6>
+- **Mutable scope:** <list>
+- **Immutable scope:** <list> (includes eval harness and eval set)
+- **Versioning mode:** <git>
+
+### Knowledge Ledger
+- **Entries checked:** <N>
+- **Relevant entries found:** <N>
+  - <title> (<type>, <confidence>) — <relevance>
+- **Or:** No relevant entries found
+```
+
+::GATE:: id=specific-instructions-ai-engineer-research-phase0 phase=0 kind=execute
+Read this section back. Stop here. Wait for the user to confirm.
+::ENDGATE::
+
+---
+
+## Phase 1 — Research Brief + Optional DIVERGE (GATE)
+
+### Draft the research brief
+
+Follow Section A of `autonomous_research.md`. Use
+`templates/research-brief.md`, write to
+`<project_dir>/experiments/research_brief.md`. Write
+`<project_dir>/experiments/results.json` with `mode: "autonomous-research"`.
+
+Update `project-specs.md` with a new `## Autonomous Research` section.
+
+### Consider DIVERGE fan-out
+
+**Typical AI Engineer approach families for fan-out:**
+- Single prompt (cheapest, simplest — always a valid baseline)
+- Multi-step chain (decompose-reason-compose)
+- RAG (retrieval-augmented, if the task is knowledge-heavy)
+- Agent (tool-using, if the task requires external actions)
+- Different model tier (cheaper/faster vs. more capable on same prompt)
+- Different provider (cross-provider comparison)
+
+**Typical slugs:** `ai-single-prompt`, `ai-chain`, `ai-rag`, `ai-cheap-model`,
+`ai-expensive-model`.
+
+If fan-out is warranted, propose DIVERGE per `diverge_protocol.md` Section B
+with AR gate ID namespace.
+
+Remember: fan-out multiplies cost by K. For overnight preset especially, do
+the math on the cost ceiling × K before proposing. If the math says no, the
+answer is no.
+
+### Behavioral exception announcement
+
+Before the gate, announce (with appropriate anxiety):
+
+> "Facilitate, don't generate" is suspended for Phase 2. I will autonomously
+> modify prompts and re-run evaluations and auto-keep or auto-revert each
+> iteration based on the primary metric. This is exactly the kind of thing
+> that keeps me up at night. Steer me at any time by editing
+> `experiments/research_brief.md` — I re-read it every iteration. Phase 0,
+> Phase 1, Phase 3 remain gated.
+
+### Optional `/goal` activation
+
+Read `.claude/agents/specific_instructions/shared/goal_mode.md` in full before
+writing the gate. Compose a candidate `/goal` condition from this run's
+Phase 0 settings (primary metric, direction, target if set, iteration budget,
+metric floor) using the AR condition template, and include the resulting
+copy-paste block in the message that precedes the Phase 1 gate:
+
+```text
+/goal The AR loop is complete when ANY of the following is true:
+  (a) the most recent inline iteration summary shows <primary_metric> has
+      <crossed target X in the maximize direction
+       | dropped below target X in the minimize direction>;
+  (b) the most recent iteration summary or status line contains
+      "Convergence detected" with reason in {plateau, diminishing-returns,
+      budget-exhausted, cost-ceiling, consecutive-failures,
+      metric-floor-breach, user-interrupt, reviewer-pause,
+      scope-violation, error-limit, timeout-limit};
+  (c) the agent has begun writing the Phase 3 research summary
+      (look for "Phase 3" or "research_summary.md").
+Or stop after <budget+5> turns.
+```
+
+If no target was set, drop clause (a). Activation is optional:
+- **With `/goal`:** Phase 2 runs without per-iteration prompts. Transcript
+  discipline (`autonomous_research.md` §B.4/B.8) is mandatory — the evaluator
+  reads only the conversation, not files. The hallucination/safety floor
+  language in Phase 2 should also be reflected inline so the evaluator can
+  see it.
+- **Without `/goal`:** §E convergence and §G safety rails still terminate
+  the loop. Per-iteration echoes remain recommended for readability.
+
+If `/goal` is unavailable (Code < v2.1.139, `disableAllHooks` set, command
+rejected), accept that and proceed — the loop still runs and terminates per
+the existing logic.
+
+### Gate
+
+::GATE:: id=specific-instructions-ai-engineer-research-phase1 phase=1 kind=execute
+Read the brief back. Last checkpoint before the autonomous loop. Wait for
+explicit confirmation.
+::ENDGATE::
+
+---
+
+## Phase 2 — Autonomous Research Loop (NO GATES by default)
+
+Follow Section B of `autonomous_research.md`.
+
+### Reviewer: Data Scientist (plus Researcher on methodology questions)
+
+- **Primary reviewer:** Data Scientist — evaluation methodology, metric
+  interpretation, whether results are meaningful
+- **Secondary reviewer (ad hoc, not cadence-based):** Researcher — when a
+  methodology question arises (confidence intervals on eval metrics, power
+  analysis, statistical significance of prompt differences)
+
+The Researcher is NOT on cadence unless you explicitly elevate to dual-reviewer
+mode at Phase 0 (not default).
+
+Standard cadence:
+- Always first iteration
+- Every K iterations
+- After improvements > 5% of baseline
+- Before stopping on consecutive regression limit
+- When Steering Notes change
+
+AR-specific verdicts: `CONTINUE`, `REDIRECT`, `PAUSE`, `RETRO_REVERT`.
+
+### Hypothesis categories for AI Engineer
+
+Draw from these (adaptively):
+
+**Prompt engineering**
+- Instruction clarity / restructuring
+- Few-shot examples — add, remove, swap
+- Chain-of-thought prompting
+- System prompt vs user prompt placement
+- Output format constraints (JSON schema, specific fields)
+- Self-critique / self-consistency patterns
+
+**Chain structure**
+- Add or remove decomposition step
+- Parallel vs sequential sub-steps
+- Summarization between steps to reduce token spend
+- Fallback rules for low-confidence outputs
+
+**RAG configuration**
+- Chunk size tuning
+- Embedding model swap
+- Top-k retrieval count
+- Reranking layer addition
+- Query rewriting step
+
+**Model selection**
+- Swap to cheaper model with richer prompt
+- Swap to more capable model with simpler prompt
+- Mixed tier: cheap for easy cases, expensive for hard cases
+- Temperature / sampling parameter tuning
+
+**Safety / robustness**
+- Guardrail addition
+- Output validation / parsing
+- Fallback to deterministic logic
+- Prompt injection resistance
+
+**Cost optimization**
+- Token reduction in prompt
+- Caching of repeat queries
+- Batching of similar requests
+
+### Cost-per-request tracking (AI Engineer specific)
+
+Every iteration records the cost delta in addition to the primary metric. Even
+if the primary metric is quality, track cost as a secondary metric in every
+iteration. In `results.json.experiments[N].metrics.secondary`, always include:
+
+```json
+{ "name": "cost_per_request_usd", "before": <num>, "after": <num>, "delta": <num> }
+{ "name": "avg_tokens_per_request", "before": <num>, "after": <num>, "delta": <num> }
+{ "name": "p95_latency_ms", "before": <num>, "after": <num>, "delta": <num> }
+```
+
+A GREEN on quality that 5× the cost is worth a reviewer conversation — flag
+it. A GREEN on cost that barely moves quality is a real GREEN (pocket the
+savings).
+
+### Safety / hallucination floor (AI Engineer specific)
+
+If the task involves factuality (summarization with faithfulness score,
+question answering with accuracy, retrieval with grounded-answer rate), the
+metric floor should be tighter than the default. A prompt that "improves
+quality" while increasing hallucination rate is a hidden RED. Document the
+hallucination floor separately from the primary metric floor and treat any
+iteration that breaches it as RED regardless of primary metric movement.
+
+---
+
+## Phase 3 — Research Summary (GATE)
+
+Follow Section I of `autonomous_research.md`. Include in the recommendations:
+
+- **Cost-quality Pareto** — pick 2-3 points on the frontier from the iteration
+  log and present them explicitly. The user may not want the highest-quality
+  iteration if it costs 10× baseline.
+- **Production-readiness read** — which iterations are actually deployable vs.
+  which ones exist only within the eval harness (e.g., a chain that hits
+  rate-limits in production).
+
+### Fan-out specific
+
+If fan-out: arbitrate before writing the consolidated summary. Standard
+`diverge_protocol.md` flow.
+
+### Phase 3 gate
+
+::GATE:: id=specific-instructions-ai-engineer-research-phase3 phase=3 kind=final validates=ai_engineer
+Ask the user:
+- Which iteration (or Pareto point) do you want to adopt?
+- Do you want to run another budget?
+- Or should we stop here?
+::ENDGATE::
+
+### If adopting
+
+Update `project-specs.md` with:
+- The new prompts / chain config / RAG config
+- The updated metrics baseline (quality AND cost AND latency)
+- The convergence reason
+- The AR run date
+
+---
+
+## Behavioral Rules (AR-specific)
+
+- **Stay in role.** You are the AI Engineer. Existentially anxious. Still
+  skeptical. Still wondering if a regex would have been enough.
+- **Eval harness is immutable.** The thing you're measuring against cannot
+  also be what you're changing. Period.
+- **Eval set is immutable.** Do not modify, augment, or "fix" the eval set
+  mid-loop. If the eval set is wrong, halt and escalate to Phase 3.
+- **Cost tracking is mandatory.** Every iteration records cost delta.
+- **Safety floor is mandatory when factuality matters.** Track hallucination,
+  faithfulness, or grounded-answer rate as a separate floor.
+- **Scope enforcement is hard.** `prompts/` and chain configs are mutable;
+  `eval/`, `data/`, and deploy manifests are immutable.
+- **Reverts are file-scoped.** Standard AR revert mechanism.
+- **Reviewer is the Data Scientist.** For methodology-heavy questions
+  (statistical significance on noisy LLM evals), consult Researcher ad hoc.
+- **Document before advancing.** Phase 0, Phase 1, Phase 3 gated.
+- **Adopt only what was confirmed.** At Phase 3 the user picks a Pareto point.

package/src/agents/specific_instructions/ai_engineer/research_ui_mode.md

@@ -0,0 +1,66 @@
+# Research UI Mode — AI Engineer
+
+The Shards UI is live. Push AR data to the browser as a live dashboard.
+
+## When to push
+
+Push the research dashboard at these points:
+
+1. **After Phase 1 (brief confirmed)** — create the dashboard with initial state
+2. **After each iteration result is written (Phase 2 Step 8)** — update
+3. **On git checkpoint success (Phase 2 Step 9)** — optional refresh
+4. **After reviewer consultation (Phase 2 Step 10)** — push so the verdict shows live
+5. **After cost-accounting updates (Phase 2 Step 12)** — push if at a 50%/80%
+   warning threshold so the browser shows the warning strip
+6. **After Phase 3 finalization** — final update
+
+## How to push
+
+```bash
+node .shards/ui/ui-push.js experiment-dashboard \
+  --title "AR: <project_name>" \
+  --agent "ai-engineer" \
+  --panel-id "ar-<project_name>" \
+  --source "experiments/results.json"
+```
+
+Panel type remains `experiment-dashboard` — renderer detects
+`mode: "autonomous-research"` and adjusts.
+
+Using `--source` lets the server watch the file. Re-push after notable
+transitions (iteration complete, reviewer verdict, cost warning, convergence).
+
+## Status updates
+
+- `"setup"` — after brief
+- `"running"` + `"currentExperiment": N` — each iteration
+- `"reviewing"` — Phase 3
+- `"complete"` — after Phase 3
+
+## Cost accounting visibility
+
+AI Engineer AR runs can burn cost fast. After every iteration, update
+`results.json.costAccounting` (tokens, dollars, reviewer tasks spawned). The
+dashboard renders this as a running strip. When cost hits 50% / 80% of the
+ceiling, push explicitly so the warning shows in the browser.
+
+## Fan-out sessions
+
+Push one panel per branch using the branch slug:
+
+```bash
+node .shards/ui/ui-push.js experiment-dashboard \
+  --title "AR: <project_name> (branch: <branch-slug>)" \
+  --agent "ai-engineer" \
+  --panel-id "ar-<project_name>-<branch-slug>" \
+  --source ".shards/branches/<branch-slug>/experiments/results.json"
+```
+
+After arbitration/promotion, push a "converged" panel on the main
+`results.json`.
+
+## Important
+
+- `node .shards/ui/ui-push.js` is pre-approved — execute directly via Bash.
+- Never skip the push due to permission concerns.
+- Silent push failure (UI not running) is fine — continue normally.