## Edison in `happy-local` (Happy Stacks)

This doc explains **what Edison is**, **how it works**, and **how we use it in Happy Stacks** to reliably manage feature work across multiple Happy components (`happy`, `happy-cli`, `happy-server-light`, `happy-server`) while enforcing **stacks + worktrees** discipline.

This is intended to be handed to **any human or LLM** and be sufficient to work correctly in this repo.

---

## What Edison is (in one sentence)

**Edison is a task + QA + evidence + validation workflow layer** that standardizes how work is planned, executed, and verified, with generated role prompts (agents/validators/orchestrator) and trusted evidence capture.

In `happy-local`, Edison is **integrated** but **not responsible for isolation**; isolation is provided by **Happy Stacks** (component worktrees + stacks).

---

## Big picture: what provides isolation here

In `happy-local`:

- **Isolation is provided by Happy Stacks**
  - **Component worktrees** live under `components/.worktrees/<component>/<owner>/<branch...>`
  - **Stacks** live under `~/.happy/stacks/<stack>/...` and each stack has its own ports/db/cli-home/etc.
- **Edison worktrees are disabled**
  - We do **not** use Edison session worktrees in this repo; they would conflict with Happy Stacks’ worktree model.

This means:

- You must **never edit** default checkouts under `components/<component>` (treat as read-only “launcher defaults”).
- All work must happen in **component worktrees** and be tested/validated inside the correct **stack**.

---

## Sessions in `happy-local` (important)

Edison “sessions” still exist in `happy-local`, but **they do not create git worktrees** here because Edison worktrees are disabled (`.edison/config/worktrees.yml`).

Think of sessions in this repo as:

- **Ownership + safety gating** for task lifecycle transitions (claim/done)
- **Optional context** for validation bundling and session-scoped task queues

### What sessions do (and don’t) do here

- **Sessions do**:
  - allow safely claiming tasks into a session (`task claim`)
  - gate completing tasks (`task done` requires a session)
  - optionally move tasks/QA into session-scoped directories under `.project/sessions/...`
- **Sessions do not**:
  - create/manage git worktrees (Happy Stacks handles worktrees)
  - persist “current session” via `.project/.session-id` (Edison only writes that inside a git worktree)
    - Outside worktrees, prefer passing `--session <id>` or setting `AGENTS_SESSION=<id>` for your shell.

### Commands that require a session vs not

- **Requires a session**:
  - `happys edison -- task claim <task-id> --session <session-id>`
  - `happys edison -- task done <task-id> --session <session-id>`
- **Does NOT require a session**:
  - Evidence capture: `happys edison --stack=<stack> -- evidence capture <task-id>`
  - Validation: `happys edison --stack=<stack> -- qa validate <task-id> --execute`

### Recommended flow (implementation)

Use sessions for ownership, and Happy Stacks for isolation:

- Create a session (no worktree will be created in this repo):
  - `happys edison -- session create --id <session-id>`
- Claim **component** tasks into that session:
  - `happys edison -- task claim <task-id> --session <session-id>`
- Implement only in the stack’s pinned component worktrees.
- Mark done when finished:
  - `happys edison -- task done <task-id> --session <session-id>`

### Recommended flow (validation-only)

If you’re only validating existing tasks, you generally **do not need to create a session**:

- `happys edison --stack=<stack> -- evidence capture <task-id>`
- `happys edison --stack=<stack> -- qa validate <task-id> --execute`

Note: a **parent task is not a session**. Parent tasks are planning umbrellas; sessions are for “who is working on what right now” and guarded claim/done transitions.

---

## The one correct entrypoint: `happys edison`

**Do not run `edison ...` directly** in `happy-local`.

Use:

- `happys edison -- <edison args...>`
- `happys edison --stack=<stack> -- <edison args...>` (recommended)

Why this wrapper is mandatory:

- **Stack-scoped execution**: exports `HAPPY_STACKS_STACK` + loads the stack env file
- **Multi-repo evidence fingerprinting**: evidence is keyed off the actual component repos the stack points at
- **Fail-closed guardrails**: happy-stacks guards require the right stack + task metadata
- **Convenience**: **stack auto-inference** from task/QA frontmatter when a task/QA id is present

Reference:

- `.edison/guidelines/agents/HAPPY_STACKS_EDISON_WRAPPER.md`

---

## Where Edison stores things in this repo

- **Config + overlays**: `.edison/`
  - Project config: `.edison/config/*.yml`
  - Project validator overlays: `.edison/validators/overlays/*.md`
  - Happy Stacks pack: `.edison/packs/happy-stacks/`
- **Generated content** (do not edit): `.edison/_generated/`
  - Agents/validators/constitutions/guidelines/start prompts, etc.
- **Tasks/QA state** (gitignored here):
  - Global tasks: `.project/tasks/<state>/*.md`
  - Global QA: `.project/qa/<state>/*.md`
  - Session-scoped tasks/QA (optional): `.project/sessions/**/{tasks|qa}/...`

Note: `.project/` is gitignored in this repo by design (task/QA state is local for now).

---

## Happy Stacks task model (MANDATORY)

We enforce a strict structure so stacks/worktrees are never “forgotten”:

### Parent → Track → Component

- **Parent task** (`hs_kind: parent`)
  - Planning umbrella for a feature
  - Declares: `components: [...]`
  - **Not claimable**
- **Track task** (`hs_kind: track`)
  - Child of a parent
  - Owns exactly **one stack** (one stack per track)
  - Declares: `track: upstream|fork|integration`, `stack: <name>`, `components: [...]`, `base_task: <parent-id>`
- **Component task** (`hs_kind: component`)
  - Child of a track
  - Targets exactly **one component**: `component: happy` (or `happy-cli`, etc.)
  - Declares: `stack: <same as track>`, `base_task`, `base_worktree`

This is enforced by happy-stacks guards:

- `.edison/packs/happy-stacks/guards/task.py`

---

## Planning a feature (recommended workflow)

### 1) Read the “planning slash command”

Use:

- `happys edison -- read START_PLAN_FEATURE --type start`

### 2) Create a parent task

Create the task, then fill mandatory frontmatter:

- `happys edison -- task new --id <id> --slug <slug>`

Edit the created task file to set:

- `hs_kind: parent`
- `components: [...]`

### 3) Scaffold everything (preferred)

Use:

- `happys edison task:scaffold <parent-task-id> --mode=upstream|fork|both --yes`

This will (idempotently):

- create track + component subtasks
- create stacks for tracks
- create component worktrees
- pin the stack to those worktrees

---

## Implementing a component task (agent workflow)

### Non-negotiables

- Work only inside `components/.worktrees/...`
- Run validation/evidence **stack-scoped**
- Use `happys` commands (not raw `pnpm/yarn/expo/docker`)

### Evidence capture (trusted runner)

Evidence must be captured via Edison (snapshot-based, fingerprinted):

- `happys edison --stack=<stack> -- evidence capture <task-id>`

For reviewing evidence, prefer the CLI (it is staleness-aware):

- `happys edison --stack=<stack> -- evidence status <task-id> --preset <preset>`
- `happys edison --stack=<stack> -- evidence show <task-id> --command <ci-command>`

Evidence commands are configured in:

- `.edison/config/ci.yml`

They call stack-scoped commands like:

- `happys stack typecheck <stack> [components...]`
- `happys stack lint <stack> [components...]`
- `happys stack build <stack>`
- `happys stack test <stack> [components...]`

### Validation presets (project policy)

Configured in:

- `.edison/config/validation.yml`

Presets:

- **fast**: typecheck + build + lint + **track drift review**
- **standard**: typecheck + build + lint + tests + **track drift review** (implementation evidence)
- **standard-validate**: **standard** + **CodeRabbit review evidence** (validation-only)
- **fast-ui**: fast + **browser UI validation** + **track drift review** (for tasks that include component `happy`)
- **standard-ui**: standard + **browser UI validation** + **track drift review** (implementation evidence)
- **standard-ui-validate**: **standard-ui** + **CodeRabbit review evidence** (validation-only)
- **quick**: docs-only (no command evidence)

#### CodeRabbit evidence policy (Happy Stacks)

- CodeRabbit runs as **command evidence** (`command-coderabbit.txt`), not as an Edison validator.
- It is **mandatory for execute-mode task validation**:
  - `happys edison --stack=<stack> -- qa validate <task-id> --execute --preset standard-validate`
- It **does not run automatically**. When preflight reports it missing, capture it explicitly:

```bash
happys edison --stack=<stack> -- evidence capture <task-id> --preset standard-validate --only coderabbit
```

Note: `qa run` (single-validator execution) also enforces validation-only evidence in happy-local:

- `happys edison --stack=<stack> -- qa run <validator> <task-id>`
- If required evidence (including CodeRabbit for the `*-validate` presets) is missing, the wrapper will refuse and tell you exactly which `evidence capture` command to run.

Track drift review is intentionally fast:

- `track:coherence` is captured as **command evidence** (`command-track-coherence.txt`).
- The `track-drift-review` validator should **read that evidence** and should not re-run `track:coherence` unless evidence is missing/broken.

Additionally, for “what changed?” review:

- `command-task-diff.txt` captures the **full per-component diff** computed inside the stack-pinned component repos.
  - It detects the correct base ref per repo (using the stack’s configured remote default branch, e.g. `upstream/<defaultBranch>`).
  - Validators should treat this as the canonical “PR diff” view for code review.

---

## Browser “E2E” validator (MCP-driven UI validation)

In this repo, the `browser-e2e` validator is **not** “run Playwright test files”.

It is:

- **Start stack if needed** (Edison web server lifecycle)
- **Navigate the real UI** and validate flows using **Playwright MCP browser tools**

Key wiring:

- Validator prompt is composed from the core `e2e-web` pack plus a Happy overlay:
  - Overlay: `.edison/validators/overlays/browser-e2e.md`
- Stack lifecycle config:
  - `.edison/config/validation.yml`:
    - `validation.web_servers.happy-stack` (and alias `browser-e2e`)
    - `validation.validators.browser-e2e.web_server.ref: browser-e2e`

Important behavior:

- Edison probes the stack URL (`/health`) and starts the stack if unreachable.
- Edison stops the stack **only if Edison started it**.

---

## Validation workflow (validators / humans)

Start with:

- `happys edison -- read START_VALIDATE_TASK --type start`

Common commands:

- **Show task / QA**:
  - `happys edison -- task show <task-id>`
  - `happys edison -- qa show <qa-id>`
- **Evidence status**:
  - `happys edison --stack=<stack> -- evidence status <task-id>`
- **Run validators**:
  - `happys edison --stack=<stack> -- qa validate <task-id> --execute --preset fast|standard`

---

## How stack auto-inference works (wrapper convenience)

If you run `happys edison -- ... <task-id-or-qa-id> ...` without `--stack`,
the wrapper will try to infer `stack:` from frontmatter by searching:

- `.project/tasks/**`
- `.project/qa/**`
- `.project/sessions/**/{tasks|qa}/**`

If inference fails, prefer explicit `--stack=<stack>`.

---

## Operational commands you’ll use a lot (Happy Stacks)

- **Pick worktrees**:
  - `happys wt new ...`
  - `happys wt pr ... --use`
  - `happys stack wt <stack> -- use <component> <owner/branch>`
- **Health / diagnosis**:
  - `happys stack doctor <stack>`
- **Auth repair (non-interactive)**:
  - `happys stack auth <stack> copy-from <seed>`

- **Dev UI login key (agents should only consume, not create)**:
  - `happys auth dev-key --print`
- **Stop stacks (safe)**:
  - `happys stop --except-stacks=main --yes`

See `AGENTS.md` for the full, canonical Happy Stacks discipline.

---

## Customization points (where to change behavior safely)

### Project configuration

- Evidence commands: `.edison/config/ci.yml`
- Validation presets + web server profiles: `.edison/config/validation.yml`
- Enabled packs: `.edison/config/packs.yml`
- Edison worktrees disabled: `.edison/config/worktrees.yml`
- Task/QA templates used for creation (project-owned): `.edison/config/tasks.yml`

### Project templates (task/QA creation)

These are used by Edison when creating new task/QA markdown files:

- `.edison/templates/happy-stacks/TASK.md`
- `.edison/templates/happy-stacks/QA.md`

### Happy-local overlays

- Validator overlay (adds Happy-specific rules): `.edison/validators/overlays/browser-e2e.md`
- Happy Stacks pack overlays + guards: `.edison/packs/happy-stacks/**`

---

## Common failure modes (and what to do)

- **“Do not run `edison ...` directly”**
  - Fix: use `happys edison -- ...` (or `--stack=<stack>`)
- **Auth missing / machine not registered**
  - Fix: `happys stack auth <stack> copy-from <seed>` (recommended seed: `dev-auth`)
- **Stack port collisions / foreign component paths**
  - Fix: `happys stack audit --fix-workspace --fix-paths --fix-ports`
- **Browser validator can’t reach server**
  - Fix: run stack doctor, ensure you’re in the correct stack context, and re-run validation:
    - `happys stack doctor <stack>`
    - `happys edison --stack=<stack> -- qa validate <task-id> --execute`

---

## Appendix: quick “start here” for an LLM

1. Read repo discipline: `AGENTS.md`
2. Start prompt: `happys edison -- read START_HAPPY_STACKS_NEW_SESSION --type start`
3. Plan feature: `happys edison -- read START_PLAN_FEATURE --type start`
4. Scaffold: `happys edison task:scaffold <parent-task-id> --mode=upstream|fork|both --yes`
5. Implement only in component worktrees + validate via stack-scoped evidence:
   - `happys edison --stack=<stack> -- evidence capture <task-id>`