Carrel Build

---
description: Boot the full autonomous Carrel build routine for one unattended work session.
allowed-tools: Read, Edit, Write, Bash, Agent, Skill, TodoWrite, Grep, Glob
---

# /carrel-build

Boot the autonomous Carrel build routine. This is the entry point for unattended overnight work on the Carrel macOS study app at `/Users/madu/Desktop/Codex`.

## Preflight: mandatory, before any code

Run these in parallel:

1. `cd /Users/madu/Desktop/Codex && git status --short` to confirm clean working tree
2. `cd /Users/madu/Desktop/Codex && git log --oneline -5` to anchor recent state
3. `cd /Users/madu/Desktop/Codex && git branch --show-current` to confirm not on main
4. Read `/Users/madu/Desktop/Codex/CLAUDE.md`, `/Users/madu/Desktop/Codex/AUTONOMOUS_WORK_PLAN.md` (canonical task queue), `/Users/madu/Desktop/Codex/.claude/RATER_RUBRIC.md` (100-point rubric), `/Users/madu/Desktop/Codex/.claude/AUTONOMOUS_SCOPE.md` (in-scope vs out-of-scope), `/Users/madu/Desktop/Codex/TODOS.md`, the latest plan in `/Users/madu/Desktop/Codex/docs/plans/`
5. `export CARREL_AUTONOMOUS=true` so the hooks activate

Halt and ask the operator if any of:
- current branch is `main` or `master`
- the most recent plan is older than 14 days (stale plan signals stale intent)
- working tree is dirty AND the dirty files do not share a directory or feature with the most recent commit (ambiguous in-flight state)

If the working tree is dirty but the dirty files clearly continue a recent commit's PR theme OR a current plan task's scope, do NOT halt. Instead:

1. Run `git diff --name-only` to list modified paths.
2. Run `git log -3 --format='%h %s'` to read the last three commit subjects, AND read the active plan file (most recent file under `docs/plans/`) to see what the next task is.
3. Match the modified paths against (a) any of the last 3 commits' touched directories, OR (b) the next plan task's named scope (e.g., "PR 6.2 touches StudyView.tsx and usage_events.py"). A match on either is sufficient.
4. If multiple distinct file groups are dirty (e.g., routine improvements under `.claude/` AND PR 6.x under `frontend/`), commit each group as a separate coherent commit before continuing. The audit-gate fires on each; the auditor's checkpoint-commit exception applies if the message uses `wip(routine): checkpoint` prefix.
5. Announce "continuing PR <name> from <hash>" or "committing routine improvements then resuming PR <name>" depending on what was found, and proceed.
6. Run the local test command, run lint, run typecheck. If green, the dirty state is closeable. If not green, finish the missing pieces, then commit.
7. Continue the normal loop from the next plan task.

## Checkpoint commit before any voluntary stop

Before the routine reports "done for now" (plan exhausted, time cap hit, voluntary stop), the implementer MUST commit whatever is on the working tree as a checkpoint commit so a chat-clear or session-end does not strand work:

git add -A git commit -m "wip(routine): checkpoint before stop

<one paragraph: what is in-flight, what state the tests are in, where the next implementing agent should resume>"

The audit-gate fires on this commit. Spawn the independent-auditor with the checkpoint context; the auditor's checkpoint-commit exception applies (abbreviated audit, approves liberally if the diff is coherent and tests are not regressed).

A chat-clear or HALT signal AFTER a checkpoint commit means the next /carrel-build session sees a clean tree at preflight and resumes from the next plan task naturally. A chat-clear BEFORE a checkpoint commit means 7+ in-flight files in the working tree and the dirty-tree continuation rule above kicks in.

## The loop

Repeat until a halt condition fires:

### 1. Pull the next task

**Canonical queue:** `/Users/madu/Desktop/Codex/AUTONOMOUS_WORK_PLAN.md`. Read it top-to-bottom. Pick the lowest-ID `pending` task whose `Deps:` line lists only `done` tasks (or `none`). Mark that task `Status: in_progress` by editing the work plan and committing the status flip on the feature branch before starting the implementation. The work plan's task entry tells you which master-plan section (`docs/plans/everything-to-100-2026-05-17.md`) carries the full implementation contract.

**Fallback:** if every `pending` task is currently `blocked` (e.g., depends on operator action) OR the work plan is exhausted, fall back to `TODOS.md` or the latest plan in `docs/plans/`. Pick the highest-leverage incomplete task. If both are empty, generate a 3-item shortlist from CLAUDE.md and the strategy memo, pick the highest-leverage item, and record the rationale in `.claude/logs/task-selection.jsonl`.

**Task announcement:** announce the chosen task by ID + title (e.g., `T01: Phase 3 slice β.1 — rename Citation chunk_id to node_id`) so the operator-visible log carries the queue reference.

### 2. Skill orchestration: pre-action routine (mandatory for non-trivial tasks)

Before writing any code or running any test for the chosen task, perform the skill-orchestration routine. The routine pays off in output quality by picking the right curated workflows for the task at hand. Skip ONLY for trivial mechanical work (formatting, status flips, doc reconciliation that adds no new claims, removing provably-dead code). Operator directive of 2026-05-19: this routine is now required at task start AND before any sub-decision that introduces or removes meaningful code logic.

Steps:

1. **State the desired outcome** in one sentence. Not "what am I doing" but "what does success look like." Example: "Success = the three scope-fallback queries read FROM nodes, return verbatim_text-populated HydratedNodeContext, the no-silent-fallback rule holds when translation produces zero rows, tests pin the regression, rater scores 100 first iteration." If you cannot write this sentence, you do not understand the task well enough to start coding; re-read the work plan + master plan + prior ADRs first.

2. **Scan the availabl