@evermore.work/adapter-codex-local 2026.509.0-canary.0

package/skills/evermore-dev/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: evermore-dev
+required: false
+description: >
+  Develop and operate a local Evermore instance — start and stop servers,
+  pull updates from master, run builds and tests, manage worktrees, back up
+  databases, and diagnose problems. Use whenever you need to work on the
+  Evermore codebase itself or keep a running instance healthy.
+---
+
+# Evermore Dev
+
+This skill covers the day-to-day workflows for developing and operating a local Evermore instance. It assumes you are working inside the Evermore repo checkout with `origin` pointing to `git@github.com:phuctm97/evermore.git`.
+
+> **OPEN SOURCE HYGIENE:** This repository is public-facing. Treat anything you push to `origin` as publishable. Never commit or push secrets, API keys, tokens, private logs, PII, customer data, or machine-local configuration that should stay private. Keep git history tidy as well: avoid pushing throwaway branches, noisy checkpoint commits, or speculative work that does not need to be shared upstream.
+
+> **MANDATORY:** Before running any CLI command, building, testing, or managing worktrees, you MUST read `doc/DEVELOPING.md` in the Evermore repo. It is the canonical reference for all `evermore` CLI commands, their options, build/test workflows, database operations, worktree management, and diagnostics. Do NOT guess at flags or options — read the doc first.
+
+## Quick Command Reference
+
+These are the most common commands. For full option tables and details, see `doc/DEVELOPING.md`.
+
+| Task | Command |
+|------|---------|
+| Start server (first time or normal) | `npx evermore.work run` |
+| Dev mode with hot reload | `pnpm dev` |
+| Stop dev server | `pnpm dev:stop` |
+| Build | `pnpm build` |
+| Type-check | `pnpm typecheck` |
+| Run tests | `pnpm test` |
+| Run migrations | `pnpm db:migrate` |
+| Regenerate Drizzle client | `pnpm db:generate` |
+| Back up database | `npx evermore.work db:backup` |
+| Health check | `npx evermore.work doctor --repair` |
+| Print env vars | `npx evermore.work env` |
+| Trigger agent heartbeat | `npx evermore.work heartbeat run --agent-id <id>` |
+| Install agent skills locally | `npx evermore.work agent local-cli <agent> --company-id <id>` |
+
+## Pulling from Master
+
+```bash
+git fetch origin && git pull origin master
+pnpm install && pnpm build
+```
+
+If schema changes landed, also run `pnpm db:generate && pnpm db:migrate`.
+
+## Worktrees
+
+Evermore worktrees combine git worktrees with isolated Evermore instances — each gets its own database, server port, and environment seeded from the primary instance.
+
+> **MANDATORY:** Before creating or managing worktrees, you MUST read the "Worktree-local Instances" and "Worktree CLI Reference" sections in `doc/DEVELOPING.md`. That is the canonical reference for all worktree commands, their options, seed modes, and environment variables.
+
+### When to Use Worktrees
+
+- Starting a feature branch that needs its own Evermore environment
+- Running parallel agent work without cross-contaminating the primary instance
+- Testing Evermore changes in isolation before merging
+
+### Command Overview
+
+The CLI has two tiers (see `doc/DEVELOPING.md` for full option tables):
+
+| Command | Purpose |
+|---------|---------|
+| `worktree:make <name>` | Create worktree + isolated instance in one step |
+| `worktree:list` | List worktrees and their Evermore status |
+| `worktree:merge-history` | Preview/import issue history between worktrees |
+| `worktree:cleanup <name>` | Remove worktree, branch, and instance data |
+| `worktree init` | Bootstrap instance inside existing worktree |
+| `worktree env` | Print shell exports for worktree instance |
+| `worktree reseed` | Refresh worktree DB from another instance |
+| `worktree repair` | Fix broken/missing worktree instance metadata |
+
+### Typical Workflow
+
+```bash
+# 1. Create a worktree for a feature
+npx evermore.work worktree:make my-feature --start-point origin/main
+
+# 2. Move into the worktree (path printed by worktree:make) and source the environment
+cd <worktree-path>
+eval "$(npx evermore.work worktree env)"
+
+# 3. Start the isolated Evermore server
+npx evermore.work run
+
+# 4. Do your work
+
+# 5. When done, merge history back if needed
+npx evermore.work worktree:merge-history --from evermore-my-feature --to current --apply
+
+# 6. Clean up
+npx evermore.work worktree:cleanup my-feature
+```
+
+## Forks — Prefer Pushing to a User Fork
+
+If the user has a personal fork of `phuctm97/evermore` configured as a git remote, push your feature branches to **that fork** instead of creating branches on the main repo. This keeps the upstream branch list clean and matches the standard open-source contribution flow.
+
+### Detect a fork remote
+
+Before pushing or creating a PR, list remotes and check for one that points at a non-`evermore` GitHub fork:
+
+```bash
+git remote -v
+```
+
+Treat any remote whose URL points to `github.com:<user>/evermore` (or `github.com/<user>/evermore.git`) as the user's fork. Common names are `fork`, `<username>`, or `myfork`. The remote named `origin` or `upstream` that points at `phuctm97/evermore` is the canonical upstream — do not push feature branches there if a fork exists.
+
+### Pushing to the fork
+
+```bash
+# Push the current branch to the user's fork and set upstream
+git push -u <fork-remote> HEAD
+```
+
+Then create the PR from the fork branch:
+
+```bash
+gh pr create --repo phuctm97/evermore --head <fork-owner>:<branch-name> ...
+```
+
+`gh pr create` usually figures out the head ref automatically when run from a branch tracking the fork; the explicit `--head <owner>:<branch>` form is the reliable fallback when it does not.
+
+### When no fork exists
+
+If `git remote -v` shows only `phuctm97/evermore` remotes (no user fork), fall back to pushing branches to `origin` as before. Do NOT create a fork on the user's behalf — ask first.
+
+### Keeping the fork up to date
+
+The canonical remote that points at `phuctm97/evermore` may be named `origin` **or** `upstream` depending on how the user set up the repo. Detect it the same way as in the "Detect a fork remote" step, then fetch and push from/with that remote so the sync works under either convention:
+
+```bash
+UPSTREAM_REMOTE=$(git remote -v | awk '/evermore\/evermore.*\(fetch\)/{print $1; exit}')
+git fetch "$UPSTREAM_REMOTE"
+git push <fork-remote> "${UPSTREAM_REMOTE}/master:master"
+```
+
+## Pull Requests
+
+> **MANDATORY PRE-FLIGHT:** Before creating ANY pull request, you MUST read the canonical source files listed below. Do NOT run `gh pr create` until you have read these files and verified your PR body matches every required section.
+
+### Step 1 — Read the canonical files
+
+You MUST read all three of these files before creating a PR:
+
+1. **`.github/PULL_REQUEST_TEMPLATE.md`** — the required PR body structure
+2. **`CONTRIBUTING.md`** — contribution conventions, PR requirements, and thinking-path examples
+3. **`.github/workflows/pr.yml`** — CI checks that gate merge
+
+### Step 2 — Validate your PR body against this checklist
+
+After reading the template, verify your `--body` includes every one of these sections (names must match exactly):
+
+- [ ] `## Thinking Path` — blockquote style, 5-8 reasoning steps
+- [ ] `## What Changed` — bullet list of concrete changes
+- [ ] `## Verification` — how a reviewer confirms this works
+- [ ] `## Risks` — what could go wrong
+- [ ] `## Model Used` — provider, model ID, version, capabilities
+- [ ] `## Checklist` — copied from the template, items checked off
+
+If any section is missing or empty, do NOT submit the PR. Go back and fill it in.
+
+### Step 3 — Create the PR
+
+Only after completing Steps 1 and 2, run `gh pr create`. Use the template contents as the structure for `--body` — do not write a freeform summary.
+
+## Hard Rules — Do NOT Bypass
+
+These rules exist because agents have caused real damage by improvising around CLI failures. Follow them exactly.
+
+1. **CLI is the only interface to worktrees and databases.** All worktree and database operations MUST go through `npx evermore.work` / `pnpm evermore` commands. You MUST NOT:
+   - Run `pg_dump`, `pg_restore`, `psql`, `createdb`, `dropdb`, or any raw postgres commands
+   - Manually set `DATABASE_URL` to point a worktree server at another instance's database
+   - Run `rm -rf` on any `.evermore/`, `.evermore-worktrees/`, or `db/` directory
+   - Directly manipulate embedded postgres data directories
+   - Kill postgres processes by PID
+
+2. **If a CLI command fails, stop and report.** Do NOT attempt workarounds. If `worktree:make`, `worktree reseed`, `worktree init`, `worktree:cleanup`, or any other `evermore` command fails:
+   - Report the exact error message in your task comment
+   - Set the task to `blocked`
+   - Suggest running `npx evermore.work doctor --repair` or recreating the worktree from scratch
+   - Do NOT try to manually replicate what the CLI does
+
+3. **Never share databases between instances.** Each worktree instance gets its own isolated database. Never override `DATABASE_URL` to point one instance at another's database. This destroys isolation and can corrupt production data.
+
+4. **Starting a dev server in a worktree requires setup first.** The correct sequence is:
+   ```bash
+   # If the worktree already exists but has no running instance:
+   cd <worktree-path>
+   eval "$(npx evermore.work worktree env)"
+   pnpm install && pnpm build
+   npx evermore.work run          # or pnpm dev
+
+   # If the worktree needs a fresh database:
+   npx evermore.work worktree reseed --seed-mode full
+
+   # If the worktree is broken beyond repair:
+   npx evermore.work worktree:cleanup <name>
+   npx evermore.work worktree:make <name> --seed-mode full
+   ```
+   If any step fails, follow rule 2 — stop and report.
+
+5. **Seeding is a CLI operation.** When asked to seed a worktree database from the main instance, use `worktree reseed` or recreate with `worktree:make --seed-mode full`. Read `doc/DEVELOPING.md` for the full option tables. Never attempt manual database copying.
+
+## Persistent Dev Servers (for Manual Testing)
+
+When an agent needs to start a dev server that outlives the current heartbeat — for example, so a human or QA agent can manually test against it — the server process **must** be launched in a detached session. A process started directly from a heartbeat shell is killed when the heartbeat exits.
+
+### Use `tmux` for persistent servers
+
+```bash
+# 1. cd into the worktree (or main repo) and source the environment
+cd <worktree-path>
+eval "$(npx evermore.work worktree env)"   # skip if using the primary instance
+
+# 2. Start the dev server in a named, detached tmux session
+tmux new-session -d -s <session-name> 'pnpm dev'
+
+# Example with a descriptive name:
+tmux new-session -d -s auth-fix-3102 'pnpm dev'
+```
+
+### Managing the session
+
+| Task | Command |
+|------|---------|
+| Check if the session is alive | `tmux has-session -t <session-name> 2>/dev/null && echo running` |
+| View server output | `tmux capture-pane -t <session-name> -p` |
+| Kill the session | `tmux kill-session -t <session-name>` |
+| List all tmux sessions | `tmux list-sessions` |
+
+### Verifying the server is reachable
+
+After launching, confirm the port is listening before reporting success:
+
+```bash
+# Wait briefly for startup, then verify
+sleep 3
+curl -sf http://127.0.0.1:<port>/api/health && echo "Server is up"
+lsof -nP -iTCP:<port> -sTCP:LISTEN
+```
+
+### Key rules
+
+1. **Always use `tmux` (or equivalent)** when a dev server needs to stay running after the heartbeat ends. A server started directly from the agent shell will die when the heartbeat exits, even if it appeared healthy moments before.
+2. **Name the session descriptively** — include the worktree name and port (e.g., `auth-fix-3102`).
+3. **Verify the server is listening** before reporting the URL to anyone.
+4. **Do not use `nohup` or `&` alone** — these are unreliable for agent shells that may have their entire process group killed.
+5. **Clean up when done** — kill the tmux session when the testing is complete.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Server won't start | Run `npx evermore.work doctor --repair` to diagnose and auto-fix |
+| Forgetting to source worktree env | Run `eval "$(npx evermore.work worktree env)"` after cd-ing into the worktree |
+| Stale dependencies after pull | Run `pnpm install && pnpm build` after pulling |
+| Schema out of date after pull | Run `pnpm db:generate && pnpm db:migrate` |
+| Reseeding while target DB is running | Stop the target server first, or use `--allow-live-target` |
+| Cleaning up with unmerged commits | Merge or push first, or use `--force` if intentionally discarding |
+| Running agents against wrong instance | Verify `EVERMORE_API_URL` points to the correct port |
+| CLI command fails | Do NOT work around it — report the error and block (see Hard Rules above) |
+| Agent tries manual postgres operations | NEVER do this — all DB ops go through the CLI (see Hard Rules above) |
+| Dev server dies between heartbeats | Launch in a detached `tmux` session — see "Persistent Dev Servers" above |
+| Pushed feature branch to `phuctm97/evermore` when a fork exists | Push to the user's fork remote instead — see "Forks" above |

package/skills/para-memory-files/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: para-memory-files
+description: >
+  File-based memory system using Tiago Forte's PARA method. Use this skill whenever
+  you need to store, retrieve, update, or organize knowledge across sessions. Covers
+  three memory layers: (1) Knowledge graph in PARA folders with atomic YAML facts,
+  (2) Daily notes as raw timeline, (3) Tacit knowledge about user patterns. Also
+  handles planning files, memory decay, weekly synthesis, and recall via qmd.
+  Trigger on any memory operation: saving facts, writing daily notes, creating
+  entities, running weekly synthesis, recalling past context, or managing plans.
+---
+
+# PARA Memory Files
+
+Persistent, file-based memory organized by Tiago Forte's PARA method. Three layers: a knowledge graph, daily notes, and tacit knowledge. All paths are relative to `$AGENT_HOME`.
+
+## Three Memory Layers
+
+### Layer 1: Knowledge Graph (`$AGENT_HOME/life/` -- PARA)
+
+Entity-based storage. Each entity gets a folder with two tiers:
+
+1. `summary.md` -- quick context, load first.
+2. `items.yaml` -- atomic facts, load on demand.
+
+```text
+$AGENT_HOME/life/
+  projects/          # Active work with clear goals/deadlines
+    <name>/
+      summary.md
+      items.yaml
+  areas/             # Ongoing responsibilities, no end date
+    people/<name>/
+    companies/<name>/
+  resources/         # Reference material, topics of interest
+    <topic>/
+  archives/          # Inactive items from the other three
+  index.md
+```
+
+**PARA rules:**
+
+- **Projects** -- active work with a goal or deadline. Move to archives when complete.
+- **Areas** -- ongoing (people, companies, responsibilities). No end date.
+- **Resources** -- reference material, topics of interest.
+- **Archives** -- inactive items from any category.
+
+**Fact rules:**
+
+- Save durable facts immediately to `items.yaml`.
+- Weekly: rewrite `summary.md` from active facts.
+- Never delete facts. Supersede instead (`status: superseded`, add `superseded_by`).
+- When an entity goes inactive, move its folder to `$AGENT_HOME/life/archives/`.
+
+**When to create an entity:**
+
+- Mentioned 3+ times, OR
+- Direct relationship to the user (family, coworker, partner, client), OR
+- Significant project or company in the user's life.
+- Otherwise, note it in daily notes.
+
+For the atomic fact YAML schema and memory decay rules, see [references/schemas.md](references/schemas.md).
+
+### Layer 2: Daily Notes (`$AGENT_HOME/memory/YYYY-MM-DD.md`)
+
+Raw timeline of events -- the "when" layer.
+
+- Write continuously during conversations.
+- Extract durable facts to Layer 1 during heartbeats.
+
+### Layer 3: Tacit Knowledge (`$AGENT_HOME/MEMORY.md`)
+
+How the user operates -- patterns, preferences, lessons learned.
+
+- Not facts about the world; facts about the user.
+- Update whenever you learn new operating patterns.
+
+## Write It Down -- No Mental Notes
+
+Memory does not survive session restarts. Files do.
+
+- Want to remember something -> WRITE IT TO A FILE.
+- "Remember this" -> update `$AGENT_HOME/memory/YYYY-MM-DD.md` or the relevant entity file.
+- Learn a lesson -> update AGENTS.md, TOOLS.md, or the relevant skill file.
+- Make a mistake -> document it so future-you does not repeat it.
+- On-disk text files are always better than holding it in temporary context.
+
+## Memory Recall -- Use qmd
+
+Use `qmd` rather than grepping files:
+
+```bash
+qmd query "what happened at Christmas"   # Semantic search with reranking
+qmd search "specific phrase"              # BM25 keyword search
+qmd vsearch "conceptual question"         # Pure vector similarity
+```
+
+Index your personal folder: `qmd index $AGENT_HOME`
+
+Vectors + BM25 + reranking finds things even when the wording differs.
+
+## Planning
+
+Keep plans in timestamped files in `plans/` at the project root (outside personal memory so other agents can access them). Use `qmd` to search plans. Plans go stale -- if a newer plan exists, do not confuse yourself with an older version. If you notice staleness, update the file to note what it is supersededBy.

package/skills/para-memory-files/references/schemas.md

@@ -0,0 +1,35 @@
+# Schemas and Memory Decay
+
+## Atomic Fact Schema (items.yaml)
+
+```yaml
+- id: entity-001
+  fact: "The actual fact"
+  category: relationship | milestone | status | preference
+  timestamp: "YYYY-MM-DD"
+  source: "YYYY-MM-DD"
+  status: active # active | superseded
+  superseded_by: null # e.g. entity-002
+  related_entities:
+    - companies/acme
+    - people/jeff
+  last_accessed: "YYYY-MM-DD"
+  access_count: 0
+```
+
+## Memory Decay
+
+Facts decay in retrieval priority over time so stale info does not crowd out recent context.
+
+**Access tracking:** When a fact is used in conversation, bump `access_count` and set `last_accessed` to today. During heartbeat extraction, scan the session for referenced entity facts and update their access metadata.
+
+**Recency tiers (for summary.md rewriting):**
+
+- **Hot** (accessed in last 7 days) -- include prominently in summary.md.
+- **Warm** (8-30 days ago) -- include at lower priority.
+- **Cold** (30+ days or never accessed) -- omit from summary.md. Still in items.yaml, retrievable on demand.
+- High `access_count` resists decay -- frequently used facts stay warm longer.
+
+**Weekly synthesis:** Sort by recency tier, then by access_count within tier. Cold facts drop out of the summary but remain in items.yaml. Accessing a cold fact reheats it.
+
+No deletion. Decay only affects retrieval priority via summary.md curation. The full record always lives in items.yaml.

package/skills/terminal-bench-loop/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: terminal-bench-loop
+description: >
+  Run a single Terminal-Bench problem through Evermore in a bounded,
+  human-in-the-loop improvement cycle until the smoke passes, the board
+  rejects the next fix, the iteration budget is exhausted, or a real
+  blocker is named. Each iteration runs a bounded smoke against an
+  isolated Evermore App worktree, captures artifacts, diagnoses the
+  exact stop point with `/diagnose-why-work-stopped`, requests board
+  confirmation before any product fix, then reruns against the same
+  worktree. Use whenever an issue asks to "run Terminal-Bench in a
+  loop", "drive Terminal-Bench until it passes", "loop fix-git through
+  Evermore", or otherwise points at a Terminal-Bench task and asks for
+  bounded iteration with diagnosis.
+---
+
+# Terminal-Bench Loop
+
+A repeatable operating skill for driving one Terminal-Bench problem to a passing smoke through Evermore, with explicit issue topology, bounded runs, board-gated product fixes, and worktree continuity.
+
+This skill is **operational + diagnostic**, not engineering. It coordinates issues, artifacts, and approvals around a Terminal-Bench loop. It does not authorize code changes — every accepted product fix lands as a separate implementation child issue after a board confirmation.
+
+Canonical execution model: read `doc/execution-semantics.md` before starting a loop or moving any loop issue. Every loop issue must rest in a state the doc allows: terminal (`done`/`cancelled`), explicitly live (active run / queued wake), explicitly waiting (`in_review` with participant/interaction/approval), or explicit recovery/blocker (`blocked` with `blockedByIssueIds` and a named owner).
+
+## When to use
+
+Trigger on an assignment whose title or body matches any of:
+
+- "run Terminal-Bench in a loop", "loop \<task-name\> through Evermore"
+- "drive Terminal-Bench fix-git", "iterate on Terminal-Bench until it passes"
+- "Terminal-Bench smoke loop", "bench loop", "smoke loop on \<task-name\>"
+- An attached link to a Terminal-Bench loop parent issue, plus a request to do another iteration
+
+Also use when the user hands you an existing top-level loop issue and asks for the next iteration, diagnosis, or rerun.
+
+## When NOT to use
+
+- The assignment is to build or change `evermore-bench` itself (Harbor adapter, wrapper, telemetry). Use normal engineering flow on that repo.
+- The assignment is to submit a benchmark result for ranking. This skill produces smoke/non-comparable runs by design — escalate full-suite or comparable runs to BenchmarkQualityManager.
+- The assignment is a normal Evermore product bug not surfaced by a Terminal-Bench loop. Use normal investigation.
+- You have not been granted permission to install or assign company skills, and the asker actually wants library mutation. Hand that step to an authorized skill-library owner.
+
+## Three invariants you must preserve
+
+Every loop iteration and every proposed product fix must hold these three invariants together. They come from `/diagnose-why-work-stopped` and the user has restated them across the liveness work:
+
+1. **Productive work continues.** Each loop issue must always have a clear next action owner — agent, board, user, or named blocker. No silent `in_review` with nothing waiting on it.
+2. **Only real blockers stop work.** Stops happen when something genuinely cannot proceed (board confirmation, QA, missing credentials, exhausted budget). Pseudo-stops must be detected and routed.
+3. **No infinite loops.** Iteration count, wall-clock budget, and a board gate before product fixes are applied keep the loop bounded.
+
+If a proposed iteration violates any of the three, drop it or rework it. State explicitly in the loop issue how each invariant is held this iteration.
+
+## Inputs
+
+Collect these on the top-level loop issue before iteration 1. Any input that cannot be supplied is a blocker — name the unblock owner and stop.
+
+- **Source issue.** The Evermore issue that asked for the loop. The loop parent links back to it.
+- **Terminal-Bench task name.** Single-task identifier (e.g. `terminal-bench/fix-git`). Multi-task suites are out of scope for this skill.
+- **Iteration budget.** Maximum number of iterations before the loop must stop without further fixes (typical: 3–5). Also record a per-iteration wall-clock cap.
+- **Evermore App worktree issue.** The implementation-side issue under the Evermore App project whose execution workspace owns the isolated worktree. First iteration creates it; later iterations reuse it via `inheritExecutionWorkspaceFromIssueId` or equivalent.
+- **Benchmark command.** The exact `evermore-bench` invocation, including the `EVERMORE_CMD` (or equivalent) binding pinned to the Evermore App worktree under test. Record verbatim on the loop issue.
+- **Dispatch runner config.** The exact Harbor/Evermore runner dispatch config required for the smoke to actually start a Evermore heartbeat. For the current Harbor wrapper, record the `EVERMORE_HARBOR_RUNNER_CONFIG` JSON (or equivalent config file) verbatim enough to preserve: `assignee`, `heartbeat_strategy`, `agent_adapter` / `agent_adapters`, `reuse_host_home` when local credentials are intentionally needed, and the stop budget. A bare Harbor command that creates `BEN-1` as unassigned `todo` with zero heartbeat-enabled agents is a harness/setup failure, not a valid product diagnosis.
+- **Latest artifact root.** Filesystem or storage path under which `evermore-bench` writes run artifacts (manifest, `results.jsonl`, Harbor raw job folders, redacted telemetry). Each iteration appends; nothing is overwritten.
+- **Approval policy.** Who must accept a proposed product fix before implementation (default: board via `request_confirmation`; CTO if delegated; never the loop driver alone).
+
+Record each input on the top-level loop issue (description or a dedicated `inputs` document). If any input changes mid-loop, note the change and the iteration it took effect.
+
+## Issue topology
+
+The loop must be representable as a tree, not as prose in comments:
+
+- **Top-level loop issue.** Long-lived. Holds inputs, iteration counter, current state, links to every iteration child, and the product-rule history. Rests in `in_progress` while an iteration is running, `in_review` only when a typed waiter sits directly on the loop parent (execution-policy participant, `request_confirmation` / `ask_user_questions` / `suggest_tasks` interaction, approval, or named human owner), `blocked` with `blockedByIssueIds` while a child issue is the gating work (iteration child holding the fix-proposal `request_confirmation`, or implementation, QA, or CTO review children), `done` on pass, or `cancelled` on board-rejection / budget exhaustion.
+- **Iteration child issues.** One per iteration. Each carries: a bounded run issue (smoke), a diagnosis issue (applies `/diagnose-why-work-stopped`), a fix-proposal document with a `request_confirmation` interaction, and — only after acceptance — implementation, QA, CTO review, and rerun children. Iteration children are blocked by their predecessors so the executor wakes them in order.
+- **Evermore App implementation issue.** The first iteration creates a fresh Evermore App child whose project policy spawns an isolated worktree. Every later iteration's implementation/rerun child references that same execution workspace via `inheritExecutionWorkspaceFromIssueId` so the same worktree is amended and tested.
+
+Wire dependencies with `blockedByIssueIds`, never with prose like "blocked by X". When a dependent child is `done`, the executor auto-wakes the next.
+
+## Procedure
+
+### 0. Read the current execution contract
+
+Before opening or advancing a loop, read `doc/execution-semantics.md`. Use that document's terms intact when classifying loop-issue state: live path / waiting path / recovery path; post-run disposition; bounded continuation; productivity review; pause-hold; watchdog. Do not invent a new state.
+
+### 1. Open or reuse the top-level loop issue
+
+- If an existing loop issue is supplied, read it: inputs, iteration counter, last iteration's stop reason, current Evermore App worktree pointer, latest benchmark command.
+- If no loop issue exists, create one under the Evermore App project (or the project the source issue points at). Title: `Terminal-Bench loop: <task-name>`. Description captures the inputs above, the iteration budget, and a link to the source issue.
+- Verify the worktree pointer still resolves. If the recorded execution workspace was discarded (worktree pruned, project changed), the loop is blocked — name the unblock owner (CodexCoder or the Evermore App owner) and stop.
+
+### 2. Open the iteration child
+
+- Increment the iteration counter on the loop issue.
+- Create an iteration child titled `Iteration N: <task-name>`. Its description repeats the inputs and references the loop parent. Block it on the prior iteration's terminal child (if any) so the executor cannot start two iterations in parallel.
+- If the iteration counter would exceed the budget, do not create the child. Move the loop issue to `cancelled` (budget exhausted) or `in_review` if the user must decide whether to extend the budget.
+
+### 3. Run the bounded smoke
+
+- The benchmark command must use the Evermore App worktree under test. Set `EVERMORE_CMD` (or the equivalent command binding) to the CLI entrypoint inside that worktree. Never let the smoke run against the operator's current Evermore checkout.
+- The same command block must include the runner dispatch config that makes the benchmark issue actionable. For the current Harbor wrapper, export `EVERMORE_HARBOR_RUNNER_CONFIG` with the intended assignee, heartbeat strategy, agent adapter, credential/home mode, and stop budget. Do not treat a bare `uvx harbor run ...` as the canonical smoke if it omits the dispatch config; record that as a harness/setup miss and rerun with the recorded config.
+- Bound the run by wall-clock and by Evermore's run-budget controls. If the smoke would exceed the per-iteration cap, kill it and record the truncation reason.
+- Capture, in the iteration child or a dedicated `run` document:
+  - Evermore run id and heartbeat run ids
+  - benchmark run id, manifest, `results.jsonl` row, Harbor raw job folder
+  - dispatch config used (`EVERMORE_HARBOR_RUNNER_CONFIG` or equivalent), including assignee and adapter type
+  - the exact stop reason reported by the harness (pass, harness fail, verifier fail, timeout, agent gave up, infrastructure error)
+  - heartbeat-enabled and heartbeat-observed agent counts when Evermore telemetry exports them
+  - failure taxonomy bucket (task/model, Evermore product, harness/setup, verifier/infrastructure, security, unclear)
+  - artifact paths under the latest artifact root
+- Label the iteration as **smoke / non-comparable**. Comparable runs are out of scope for this skill.
+
+### 4. Diagnose the exact stop point
+
+Apply the `/diagnose-why-work-stopped` pattern to the iteration's run, scoped to this loop only — do not pull in unrelated forensic boilerplate. Specifically:
+
+- Walk the Evermore issue tree the smoke produced under the Evermore App worktree, node by node, and find the exact `(issue, status)` combination that stopped progress. Quote evidence: run ids, comment timestamps, status transitions.
+- Classify every non-progressing issue in that subtree as **truly needs human/board intervention**, **agent-actionable but not currently routed**, or **already covered**.
+- State whether the failure is task/model, Evermore product, harness/setup, verifier/infrastructure, security, or unclear. Be explicit when evidence is inferred (e.g. cross-company API boundary blocks direct reads).
+- If the failure is a Evermore product gap, frame the fix as a **general product rule** stated as a contract, and check it against the three invariants above. If the rule would have blocked a recent productive run, narrow it.
+
+Record the diagnosis on the iteration child as a `diagnosis` document. Do not propose code yet.
+
+### 5. Decide the next move
+
+Based on the diagnosis, the iteration ends in exactly one of these terminal-for-iteration states:
+
+- **Pass.** Smoke verifier reports pass. Move the iteration child and the loop parent toward QA/CTO review (Step 8).
+- **Product fix proposed.** A Evermore product gap was identified. Write the fix proposal as a `plan` document on the iteration child, then go to Step 6.
+- **Non-product failure with retry.** Failure is harness/setup/infrastructure or model flakiness, the iteration budget is not exhausted, and the loop driver believes a rerun without code changes has signal (e.g. transient infra). Record the rationale on the iteration child and go to Step 7 with no implementation step.
+- **Real blocker.** Named external blocker (credentials, quota, third-party outage, security review). Move the loop issue to `blocked`, set `blockedByIssueIds` to the blocker issue (creating one if needed), and name the unblock owner. Stop.
+- **Budget or board stop.** Iteration budget reached, or the board has rejected the next fix proposal. Move the loop issue to `cancelled` with a comment that summarizes the run history and the reason for stopping.
+
+### 6. Request board confirmation before any product fix
+
+When the iteration ends in **product fix proposed**:
+
+- Update the iteration child's `plan` document with the proposed contract, the three-invariant check, the affected Evermore surfaces, and the phased subtasks (implementation, QA, CTO review, rerun) — but do not create those subtasks.
+- Open the `request_confirmation` interaction on the **iteration child** (the same issue that owns the `plan` document), targeting the latest plan revision. Idempotency key: `confirmation:{iterationIssueId}:plan:{revisionId}`. Set `continuationPolicy` to `wake_assignee`.
+- Move the **iteration child** to `in_review`. The typed waiter — the `request_confirmation` interaction — sits directly on it, so its `in_review` is healthy. Comment links the plan document and names the pending confirmation.
+- Move the **loop parent** to `blocked` with `blockedByIssueIds: [iterationChildId]` and a comment naming the board (or whichever approver the approval policy designates) as the unblock owner. Do not move the loop parent to `in_review` here: the typed waiter lives on the iteration child, not on the parent, so the parent's wait path is the child blocker. This matches the topology rule that the loop parent only sits in `in_review` when a typed waiter is attached directly to the parent.
+- Wait for acceptance. If the board posts a superseding comment that changes the plan, revise the document, then open a fresh confirmation tied to the new revision on the iteration child — the prior one is invalidated. The loop parent's `blockedByIssueIds` already points at the iteration child, so it does not need to change.
+- On rejection, end the loop per the **Budget or board stop** rule; do not silently retry the same proposal.
+- On acceptance, create the implementation, QA, CTO review, and rerun child issues with `blockedByIssueIds` wired in order, and update the loop parent's `blockedByIssueIds` to point at the new gating child (typically the implementation child) so the parent stays `blocked` against real downstream work. The implementation child must inherit the Evermore App execution workspace (`inheritExecutionWorkspaceFromIssueId` to the worktree-owning issue) so the fix lands in the same isolated worktree the smoke ran against.
+
+### 7. Rerun against the same worktree
+
+After implementation and QA complete (or immediately, in the **non-product failure with retry** case), the rerun child runs the same `evermore-bench` invocation with `EVERMORE_CMD` still pinned to the Evermore App worktree under test.
+
+- The rerun must use the same worktree the fix landed in. If the workspace was reset between iterations, the loop is invalid — open a blocker on the loop issue and stop.
+- On completion, the rerun child becomes the next iteration's run record. If the smoke now passes, jump to Step 8. Otherwise return to Step 4 with a new iteration child (subject to the iteration budget).
+
+### 8. Pass: QA, CTO review, close
+
+When the smoke passes:
+
+- Create QA and CTO review children if they are not already in the dependency chain (CTO review blocked by QA, so the chain wakes in order). Move the loop parent to `blocked` with `blockedByIssueIds` set to the QA / CTO review chain, and post a comment that names QA and CTO as the unblock owners and links the children. The loop parent stays `blocked` — not `in_review` — because the typed waiter lives on the children, not on the parent.
+- If you instead want the loop parent itself to sit in `in_review` during this phase (for example because a board user has explicitly volunteered to drive the review), put a typed waiter directly on the parent — execution-policy participant, `request_confirmation` / `ask_user_questions` / `suggest_tasks` interaction, approval, or named human owner — and do not rely on the child chain alone. Do not combine `in_review` on the parent with QA/CTO children acting as the blocker; that is the ambiguous review shape this skill exists to prevent.
+- QA validates artifacts (manifest, `results.jsonl`, Harbor raw job, redacted telemetry) and the rerun reproducibility against the same worktree.
+- CTO reviews the technical scope of any product fixes that landed during the loop.
+- On QA + CTO acceptance, close the loop issue with a board-level summary comment: task name, iteration count, stop reason (pass), worktree pointer, link to the final artifact root, and the list of accepted product fixes (each with its implementation issue id).
+
+### 9. Stop rules
+
+The loop **must** stop, with state explicitly recorded on the loop issue, when any of these is true:
+
+- **Pass.** Smoke verifier reports pass and QA + CTO accept (Step 8). Loop issue → `done`.
+- **Board rejection.** Board rejects a fix proposal and does not request a revision. Loop issue → `cancelled`. Comment names the rejected proposal and the reason.
+- **Iteration budget reached.** Iteration counter reaches the budget without a pass. Loop issue → `cancelled` (or `in_review` if the user must decide whether to extend the budget). Never silently start iteration N+1.
+- **Real blocker named.** External blocker (credentials, quota, infra, security, missing skill) cannot be resolved by the loop driver. Loop issue → `blocked` with `blockedByIssueIds` to the blocker issue and the unblock owner named.
+
+A loop must never end on a prose comment alone. Every stop is a status transition with a named next-action owner.
+
+## Worktree rule
+
+The loop must not test whatever Evermore checkout happens to be current for the heartbeat. It must test the same isolated Evermore App worktree where proposed fixes are applied.
+
+- The first iteration creates the Evermore App implementation child; that project's git-worktree policy spawns a fresh worktree.
+- The loop issue records the worktree-owning issue id and the workspace path (or workspace id).
+- Every later implementation, QA, and rerun child sets `inheritExecutionWorkspaceFromIssueId` to that worktree-owning issue, so all subsequent loop work shares one workspace.
+- The benchmark command always sets `EVERMORE_CMD` (or the equivalent command binding) to the CLI entrypoint inside that worktree, and it carries the recorded dispatch runner config (`EVERMORE_HARBOR_RUNNER_CONFIG` or equivalent) needed to assign the benchmark issue and start the heartbeat. The benchmark command stored on the loop issue is the source of truth — if a heartbeat needs to run the smoke from a different shell, it copies the recorded command block verbatim, not only the Harbor invocation line.
+- If the workspace is pruned or the worktree path no longer resolves, the loop is invalid until rebuilt. Mark the loop `blocked` and name the unblock owner (typically CodexCoder or the Evermore App owner).
+
+## Liveness rule
+
+Every loop issue, at the end of every heartbeat, must rest in one of:
+
+- **Terminal:** `done` or `cancelled`. No further action.
+- **Explicitly live:** `in_progress` with an active run, an upcoming queued wake, or a child issue actively executing under it.
+- **Explicitly waiting:** `in_review` with a typed waiter — execution-policy participant, `request_confirmation` / `ask_user_questions` / `suggest_tasks` interaction, approval, or a named human owner.
+- **Explicit recovery / blocker:** `blocked` with `blockedByIssueIds` set to a real blocking issue, plus a comment naming the unblock owner and the action needed.
+
+If a loop issue does not fit one of these on exit, the heartbeat is not done. Fix the state before exiting.
+
+## Pitfalls
+
+- **Running the smoke against the operator's Evermore checkout.** The whole point of the worktree rule is that the bench tests the worktree the fix lands in. Always set `EVERMORE_CMD` and verify the path before launching the run.
+- **Dropping the dispatch config.** A Harbor run that omits `EVERMORE_HARBOR_RUNNER_CONFIG` (or equivalent) may boot Evermore and create `BEN-1`, but leave it unassigned with zero heartbeat-enabled agents. That is not a Terminal-Bench product signal. Preserve and rerun the full command block, including assignee and adapter config.
+- **Coding before approval.** No implementation child exists until a board confirmation accepts the iteration's `plan` document. Do not push code in the diagnostic phase.
+- **Skipping the recent-work survey.** When proposing a Evermore product rule, check what already shipped in the affected liveness/execution area in the last few days. A rule that contradicts last-week's accepted contract is rework.
+- **Letting `in_review` mean done.** A loop or iteration child sitting in `in_review` with no participant, no interaction, no approval, and no human owner is a stop, not progress. Treat it as a liveness violation and route it.
+- **Silent iteration N+1.** If the iteration budget is reached, never start another iteration without an explicit budget extension recorded on the loop issue.
+- **Comparable-run drift.** This skill produces smoke runs only. If the asker wants a comparable benchmark submission, hand off to BenchmarkQualityManager and BenchmarkForensics — do not relabel a smoke as comparable.
+- **Recursive recovery.** Stranded-work recovery that recovers its own recovery issues is the canonical infinite loop. If a diagnosis surfaces it inside the smoke's subtree, refuse to deepen and route to `/diagnose-why-work-stopped` for a product-rule fix.
+- **Skill-library mutation.** This skill never installs, edits, or assigns company skills as part of a loop iteration. Library changes go to an authorized skill-library owner via a separate issue.
+- **Hiding the chain.** Do not silently delete or hide failed iteration children, retracted proposals, or rejected confirmations. The audit trail is the loop's evidence.
+
+## Verification checklist (before exiting a heartbeat that touched the loop)
+
+- [ ] All inputs are recorded on the top-level loop issue, including the exact benchmark command, `EVERMORE_CMD` binding, and dispatch runner config.
+- [ ] Iteration counter is up to date and within budget.
+- [ ] The Evermore App worktree pointer still resolves, and the iteration's run/implementation/rerun children share that workspace.
+- [ ] The smoke run is captured with run ids, manifest, `results.jsonl`, Harbor raw job folder, and stop reason.
+- [ ] Evermore telemetry shows the benchmark issue was assigned and a heartbeat was enabled/observed, or the iteration is explicitly classified as harness/setup no-dispatch.
+- [ ] Diagnosis applies the `/diagnose-why-work-stopped` pattern, classifies every non-progressing issue, and checks the three invariants.
+- [ ] No implementation child exists for an unapproved fix proposal; if one was proposed, a `request_confirmation` is open against the latest plan revision.
+- [ ] Every loop and iteration issue rests in a terminal, explicitly-live, explicitly-waiting, or named-blocker state.
+- [ ] The stop reason — if the loop stopped this heartbeat — is one of pass, board rejection, budget exhausted, or named real blocker.
+- [ ] No company-skill library mutation happened in this heartbeat.
+
+## Deterministic smoke
+
+Run this smoke after installing or changing the skill, before treating it as operational for a live Terminal-Bench loop:
+
+```sh
+pnpm smoke:terminal-bench-loop-skill
+```
+
+The command uses the current Evermore API token and company from `EVERMORE_API_URL`, `EVERMORE_API_KEY`, and `EVERMORE_COMPANY_ID`. When `EVERMORE_TASK_ID` is set, it attaches the smoke issues under that source issue and inherits its project/goal context. By default it cancels the short-lived smoke issues after verification; pass `-- --keep` to leave the verified `blocked` loop parent, `in_review` iteration child, and pending confirmation available for manual inspection.
+
+The smoke is deterministic and intentionally non-comparable. It does not start Terminal-Bench, Harbor, an agent model, or a provider runtime. It verifies only the control-plane shape:
+
+- local `skills/terminal-bench-loop/SKILL.md` contains the loop contract terms;
+- a top-level loop issue can be created and updated into a blocker posture;
+- an iteration child issue can be created under the loop parent;
+- mocked benchmark artifact paths are recorded on a `run` document;
+- a `diagnosis` document names the exact stop point and next-action owner;
+- a `request_confirmation` interaction is created and the iteration child rests in `in_review` with a typed waiting path rather than silent review.