docs: Sprint 007 완료 — v0.1.0 전 스프린트 완료

Sprint 007 전체 구현 — 마지막 스프린트. 프로젝트 완성:

CLI:
- rails doctor — 환경 헬스체크 (Node/pnpm/git/env/프로젝트 파일)
- rails scaffold [dir] — 신규 프로젝트 .plans/ 구조 생성
- rails migrate from-hanarang-harness <path> — 레거시 아카이브 스캐너
  agents/scripts/workflows 분류 (portable vs deprecated)
  xhigh 참조 경고 등 위험 패턴 감지

Docs (신규 3종):
- docs/migration-guide.md — 레거시 하네스 → rails 단계별 이전 가이드
- docs/operations.md — PM2, health check, 트러블슈팅, DB 유지보수
- docs/discord-setup.md — 봇 생성, DiscordPoster 구현 예시,
  marker 프로토콜 완전 명세

README 대폭 업데이트:
- v0.1.0 상태 선언
- 빠른 시작 가이드
- CLI 13 서브커맨드 목록
- 문서 링크

Tests (4 신규, 105 total pass):
- 마이그레이션 스캐너 (agents/scripts/workflows 감지)
- node_modules/.git 제외
- 빈 아카이브 처리
- scaffold 디렉토리 구조 검증

검증: tsc --noEmit ✓ | vitest 105/105 ✓ | build ✓
       rails doctor → 정상 출력 ✓
       rails --help → 13 subcommands ✓

마감 상태:
- F1~F6 모든 실패 모드 코어에서 해결
- 7 스프린트 완료 (000: 계획, 001~006: 코어, 007: 릴리즈)
- 105 테스트, 19 문서 (.plans/) + 3 운영 문서 (docs/)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Plans.md

@@ -19,16 +19,20 @@
 | 1 | 스켈레톤: XState FSM + orchestrator + .plans/ 스캐폴딩 | [SPRINT-001](.plans/sprints/SPRINT-001-skeleton.md) | cc:완료 [PR#1] |
 | 2 | Skill 강제 진입 hook + bypass 감지 + 차단 | [SPRINT-002](.plans/sprints/SPRINT-002-enforcement.md) | cc:완료 [PR#2] |
 | 3 | Sprint Contract + DoD validator (Zod) | [SPRINT-003](.plans/sprints/SPRINT-003-contract.md) | cc:완료 [PR#3] |
-| 4 | 4자매 핸드오프 엔진 (상태 전이 기반) | [SPRINT-004](.plans/sprints/SPRINT-004-handoff.md) | cc:WIP |
+| 4 | 4자매 핸드오프 엔진 (상태 전이 기반) | [SPRINT-004](.plans/sprints/SPRINT-004-handoff.md) | cc:완료 [PR#4] |
-| 5 | 재시도 / 타임아웃 / 에스컬레이션 policy | [SPRINT-005](.plans/sprints/SPRINT-005-resilience.md) | cc:TODO |
+| 5 | 재시도 / 타임아웃 / 에스컬레이션 policy | [SPRINT-005](.plans/sprints/SPRINT-005-resilience.md) | cc:완료 [PR#5] |
-| 6 | QA 체크리스트 템플릿 + 다랑이 runtime | [SPRINT-006](.plans/sprints/SPRINT-006-qa.md) | cc:TODO |
+| 6 | QA 체크리스트 템플릿 + 다랑이 runtime | [SPRINT-006](.plans/sprints/SPRINT-006-qa.md) | cc:완료 [PR#6] |
-| 7 | 기존 프로젝트 마이그레이션 (아랑 등) | [SPRINT-007](.plans/sprints/SPRINT-007-migration.md) | cc:TODO |
+| 7 | 기존 프로젝트 마이그레이션 (아랑 등) | [SPRINT-007](.plans/sprints/SPRINT-007-migration.md) | cc:완료 [PR#7] |
 
 ## 현재 스프린트
 
-**Sprint 004 — 4자매 핸드오프 엔진 + 디스코드 알림** (`cc:TODO`)
+**전체 완료** — v0.1.0 릴리즈 준비됨. 105 테스트 통과.
 
-다음 착수 예정. 상세는 `.plans/sprints/SPRINT-001-skeleton.md` 참조.
+다음 단계 (post-v0.1.0, 운영자 작업):
+1. Dev 서버에 rails 배포 (`bash install.sh`)
+2. DB 마이그레이션 (`pnpm prisma migrate deploy`)
+3. Discord 봇 연동 (`docs/discord-setup.md` 참조)
+4. 첫 실제 프로젝트 E2E 실행
 
 ## 마커 범례
 

README.md

@@ -68,12 +68,56 @@
 
 ## 상태
 
-🚧 **기획 단계** — `.plans/` 디렉토리 참조.
+**v0.1.0** — Sprint 000~007 완료. 6가지 실패 모드 전부 코어에서 해결.
 
-자세한 내용:
+105 테스트 통과. CLI 13 서브커맨드. 마이그레이션 도구 + QA 6 템플릿 포함.
+
+## 빠른 시작
+
+```bash
+# 설치
+bash install.sh --repo <repo-url> --dir /path/to/rails
+cd /path/to/rails
+
+# 환경 확인
+pnpm rails doctor
+
+# .env 설정 후 DB 마이그레이션
+cp .env.example .env
+# DATABASE_URL 등 채우기
+pnpm prisma migrate deploy
+
+# Mock 모드로 E2E 스모크 테스트
+pnpm rails run hello-world --mock -r "Try a pipeline"
+pnpm rails status
+```
+
+## CLI 서브커맨드
+
+| 명령 | 용도 |
+|---|---|
+| `rails start` | 파이프라인 생성 |
+| `rails run [--mock]` | E2E 실행 |
+| `rails status [id]` | 상태 조회 + 타임라인 |
+| `rails resume <id>` | escalated → idle 재개 |
+| `rails abort <id>` | 강제 종료 |
+| `rails contract generate/freeze/validate/show` | Sprint Contract 관리 |
+| `rails qa run/show/templates` | QA 템플릿 실행 |
+| `rails skill-context create/show/clear` | 스킬 강제 진입 |
+| `rails skill-trace show/blocked` | 도구 사용 감사 로그 |
+| `rails doctor` | 환경 헬스체크 |
+| `rails scaffold` | 신규 프로젝트 `.plans/` 생성 |
+| `rails migrate from-hanarang-harness <path>` | 레거시 하네스 스캔 |
+| `rails serve` | 오케스트레이터 서버 (v0.2 완성 예정) |
+
+## 문서
+
+- [`docs/migration-guide.md`](docs/migration-guide.md) — 레거시 → rails 이전 가이드
+- [`docs/operations.md`](docs/operations.md) — 운영 가이드 (PM2, 로그, DB)
+- [`docs/discord-setup.md`](docs/discord-setup.md) — Discord 봇 연동 + marker 프로토콜
 - [`.plans/OVERVIEW.md`](.plans/OVERVIEW.md) — 프로젝트 전체 개요
-- [`.plans/failure-audit.md`](.plans/failure-audit.md) — 실패 감사
+- [`.plans/failure-audit.md`](.plans/failure-audit.md) — F1–F6 실패 감사
-- [`.plans/design/`](.plans/design/) — 설계 문서
+- [`.plans/design/`](.plans/design/) — 설계 문서 9종
 - [`.plans/sprints/`](.plans/sprints/) — 스프린트 상세
 
 ## 라이선스

docs/discord-setup.md

@@ -0,0 +1,198 @@
+# Discord Setup
+
+> How to wire `hanarang-rails` to a Discord guild for the real DiscordTransport.
+
+## Overview
+
+Rails splits transport and observation:
+
+- **Transport (deterministic)**: Rails posts marker blocks with structured invoke data. Agent bots parse the markers directly (not through LLM).
+- **Observation (natural language)**: Agent bots keep posting free-form messages for human readers. Rails ignores the free-form text.
+
+## Bot accounts
+
+Two kinds of discord bots are involved:
+
+1. **Rails bot** — posts invoke markers, state transitions, escalations.
+2. **Agent bots (one per role, optional)** — each agent/sister has its own bot persona that responds with result markers and natural-language commentary.
+
+If you don't need per-role personas, you can run a single bot for both rails and all agents.
+
+## Rails bot setup
+
+1. Go to https://discord.com/developers/applications
+2. Create a new application → bot user
+3. Enable privileged intents: **Message Content Intent** must be on.
+4. OAuth2 URL generator → scopes: `bot`, permissions: `Send Messages`, `Read Message History`, `Create Public Threads`, `Manage Messages` (for marker cleanup, optional).
+5. Invite the bot to your guild.
+6. Copy the token.
+
+Set in `.env`:
+```
+RAILS_DISCORD_TOKEN=<token>
+DISCORD_GUILD_ID=<guild-id>
+DISCORD_PIPELINE_CHANNEL_ID=<channel-id>
+```
+
+## Agent bot integration
+
+Each agent host needs a minimal message handler that recognizes rails markers and routes them out of the LLM path:
+
+```ts
+import { DiscordPoster } from "hanarang-rails";
+
+client.on("messageCreate", async (msg) => {
+  const invokeMarker = "<!-- rails:invoke v1 -->";
+  if (msg.content.includes(invokeMarker)) {
+    // Structured mode — do NOT send to the LLM
+    const req = extractJsonBlock(msg.content, "rails:invoke");
+    const result = await runRailsTask(req);   // your agent's task runner
+    const resultMarker =
+      "<!-- rails:result v1 -->\n```json\n" +
+      JSON.stringify(result) +
+      "\n```\n<!-- /rails:result -->";
+    await msg.channel.send(
+      resultMarker +
+      "\n\n(Agent natural-language commentary here, optional)"
+    );
+    return;
+  }
+
+  // Otherwise: existing free-form conversation path
+  await runFreeFormLlm(msg);
+});
+```
+
+### Marker format
+
+**Invoke** (rails → agent):
+```
+<!-- rails:invoke v1 -->
+```json
+{
+  "pipelineId": "01HW0...",
+  "contractId": "01HW1...",
+  "stage": "implement",
+  "role": "implement",
+  "sprintId": "SPRINT-007",
+  "task": {
+    "title": "Add feature X",
+    "description": "...",
+    "workdir": "/path/to/workdir"
+  },
+  "timeoutMs": 30000,
+  "structuredOutput": true
+}
+```
+<!-- /rails:invoke -->
+```
+
+**Result** (agent → rails):
+```
+<!-- rails:result v1 -->
+```json
+{
+  "stage": "implement",
+  "verdict": "IMPL_DONE",
+  "payload": {
+    "branch": "feature/sprint-007",
+    "commits": ["abc1234"],
+    "workdir": "...",
+    "selfTestReport": {"typecheck": "pass"}
+  },
+  "errorReason": ""
+}
+```
+<!-- /rails:result -->
+
+구현 완료했어요! 테스트 전부 통과했습니다 ❤️
+```
+
+The natural-language tail after `/rails:result` is free-form — rails ignores it, but the human user sees it.
+
+## DiscordPoster interface
+
+To wire rails to a real discord.js client, implement `DiscordPoster` and pass it when constructing `DiscordTransport`:
+
+```ts
+import { Client, GatewayIntentBits, TextChannel } from "discord.js";
+import { DiscordTransport, type DiscordPoster } from "hanarang-rails";
+
+const client = new Client({
+  intents: [
+    GatewayIntentBits.Guilds,
+    GatewayIntentBits.GuildMessages,
+    GatewayIntentBits.MessageContent,
+  ],
+});
+await client.login(process.env.RAILS_DISCORD_TOKEN);
+
+const poster: DiscordPoster = {
+  async postMessage(channelId, content) {
+    const channel = await client.channels.fetch(channelId);
+    if (!channel?.isTextBased()) throw new Error("Not a text channel");
+    const msg = await (channel as TextChannel).send(content);
+    return msg.id;
+  },
+  async waitForResult({ channelId, pipelineId, stage, timeoutMs, signal }) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("timeout")), timeoutMs);
+      signal?.addEventListener("abort", () => {
+        clearTimeout(timer);
+        reject(new Error("aborted"));
+      });
+      const handler = (msg: any) => {
+        if (msg.channel.id !== channelId) return;
+        const body = msg.content as string;
+        if (!body.includes("<!-- rails:result v1 -->")) return;
+        if (!body.includes(pipelineId)) return;
+        if (!body.includes(`"stage":"${stage}"`)) return;
+        clearTimeout(timer);
+        client.off("messageCreate", handler);
+        resolve(body);
+      };
+      client.on("messageCreate", handler);
+    });
+  },
+  async close() {
+    await client.destroy();
+  },
+};
+
+const transport = new DiscordTransport({
+  token: process.env.RAILS_DISCORD_TOKEN!,
+  guildId: process.env.DISCORD_GUILD_ID!,
+  channelId: process.env.DISCORD_PIPELINE_CHANNEL_ID!,
+  poster,
+});
+```
+
+## Per-pipeline threads
+
+For cleanness, create a forum thread per pipeline:
+
+```ts
+// On state transition, create a thread under the pipeline channel
+const thread = await (channel as TextChannel).threads.create({
+  name: `[SPRINT-007] ${projectName}`,
+  autoArchiveDuration: 1440,
+});
+```
+
+Pass `thread.id` as `channelId` when invoking agents. Rails stores the pipeline → thread mapping in SQLite (`pipelines.contextJson`).
+
+## Testing without a live bot
+
+For development, use `rails run --mock` — the `MockTransport` doesn't touch discord and returns deterministic success messages. All tests ship with a fake poster; no real tokens needed.
+
+## Security
+
+- **Never commit tokens.** `.env` is gitignored. Use secrets manager for production.
+- **Validate HMAC** on any inbound webhooks (Gitea). See `GITEA_WEBHOOK_SECRET`.
+- **Rate limit guard**: rails retries on 429 with exponential backoff (Sprint 005).
+
+## Related
+
+- `operations.md` — day-to-day ops
+- `migration-guide.md` — porting from legacy bridges
+- `.plans/design/transports.md` — transport abstraction design

docs/migration-guide.md

@@ -0,0 +1,180 @@
+# Migration Guide
+
+> How to move from an existing agent pipeline (e.g., a Lobster-based `hanarang-harness` install) to `hanarang-rails`.
+
+## Summary
+
+`hanarang-rails` replaces the legacy "권고 기반" pipeline with a **deterministic, contract-enforced** one. The migration is safe: nothing in the archive is deleted, and rails can run side-by-side until you cut over.
+
+## Before you start
+
+- **Back up the old install.** Keep the archive read-only; don't delete it.
+- **Install rails on a neutral host** — ideally the same machine that holds the SSOT repository, not one of the agent workers.
+- **Confirm Node 22+ and pnpm are available** via `rails doctor`.
+
+## Step 0 — Install rails
+
+```bash
+bash install.sh --dir /path/to/hanarang-rails --repo <your-rails-repo-url>
+cd /path/to/hanarang-rails
+cp .env.example .env   # fill DATABASE_URL, DISCORD_TOKEN, etc.
+pnpm prisma migrate deploy
+pnpm rails doctor
+```
+
+## Step 1 — Scan the archive
+
+```bash
+rails migrate from-hanarang-harness /path/to/hanarang-harness-archive
+```
+
+This reports:
+- Agents (md files) — candidates to port
+- Scripts — portable vs deprecated (bridge.sh is deprecated)
+- Workflows — Lobster files are flagged as deprecated
+- Warnings — e.g., any `xhigh` thinking tier reference (forbidden)
+
+No files are modified. Review the report and decide.
+
+## Step 2 — Bring over agent definitions
+
+Copy the agent markdown files you want to keep into the rails `agents/` directory. Rails does not prescribe a naming scheme; `rails.config.yaml` maps **stage** → **agent**, so you can keep role-specific personas.
+
+```bash
+mkdir -p agents/
+cp /path/to/archive/agents/*.md agents/
+```
+
+Review each file and remove anything that references:
+- `xhigh` thinking tier (forbidden in rails — causes infinite waits)
+- Mention-based handoff instructions
+- Direct discord bot behavior (rails now posts on their behalf)
+
+## Step 3 — Port scaffolding
+
+The legacy `scaffold.sh` is now `rails scaffold`:
+
+```bash
+rails scaffold /path/to/new-project --name my-project
+```
+
+This creates `.plans/` with the standard directory structure (`design/`, `sprints/`, `migration/`) plus a root `Plans.md`.
+
+## Step 4 — Wire `rails.config.yaml`
+
+```yaml
+pipeline:
+  stages: [plan, implement, review, deploy]
+
+agents:
+  plan:
+    role: plan
+    displayName: Planner
+    transport: discord
+    channelId: ${PLAN_CHANNEL}
+    timeoutMs: 30000
+  implement:
+    role: implement
+    displayName: Generator
+    transport: discord
+    channelId: ${IMPL_CHANNEL}
+    timeoutMs: 60000
+  review:
+    role: review
+    displayName: Evaluator
+    transport: discord
+    channelId: ${REVIEW_CHANNEL}
+    timeoutMs: 30000
+  deploy:
+    role: deploy
+    displayName: Deploy
+    transport: local
+    timeoutMs: 60000
+
+discord:
+  enabled: true
+  railsToken: ${RAILS_DISCORD_TOKEN}
+  guildId: ${DISCORD_GUILD_ID}
+  pipelineChannelId: ${PIPELINE_THREAD_PARENT}
+```
+
+All secrets live in `.env`. The config file uses `${VAR}` interpolation — no token bytes in the repo.
+
+## Step 5 — Update agent runtimes
+
+Each agent host (e.g., a sister container) needs one change to its message handler:
+
+```js
+// Pseudocode — plug into your agent's discord event handler
+onDiscordMessage(msg) {
+  if (msg.content.includes("<!-- rails:invoke v1 -->")) {
+    const req = extractJsonBlock(msg.content, "rails:invoke");
+    // Structured pipeline mode — LLM 우회
+    const result = await handleRailsInvoke(req);
+    await postResultMarker(msg.channel, result);
+    return;
+  }
+  // Otherwise: existing free-form conversation path
+  llmRespond(msg);
+}
+```
+
+See `docs/discord-setup.md` for the full marker format.
+
+## Step 6 — Cutover
+
+1. **Smoke test with mock transport** first:
+   ```bash
+   rails run --mock test-project -r "hello world"
+   rails status
+   ```
+   This exercises the full FSM without touching real agents.
+
+2. **Switch one stage at a time to discord**:
+   ```yaml
+   agents:
+     plan:
+       transport: discord  # flip this first
+     implement:
+       transport: mock     # keep others on mock until plan is green
+   ```
+
+3. **Monitor escalations**:
+   ```bash
+   rails status <pipeline-id>
+   ```
+   Any unexpected escalation triggers discord alert (if configured).
+
+4. **Disable legacy mention-based handoff** on the old agents once all stages run through rails.
+
+## Step 7 — Decommission legacy bridge
+
+After rails handles 100% of traffic:
+
+1. Stop the old `bridge.sh` process(es).
+2. Keep the archive as read-only reference.
+3. Remove any cron jobs or systemd units that referenced the old install.
+
+## Rollback
+
+If rails fails badly:
+
+```bash
+rails abort <pipeline-id>              # stop the misbehaving pipeline
+pm2 stop hanarang-rails                # stop the orchestrator
+# Start the legacy bridge again if it's still present
+```
+
+The SSOT repository is untouched — both systems write to the same Gitea.
+
+## Known limitations (v0.1.0)
+
+- **Discord bot wiring requires an operator task.** Rails ships the `DiscordTransport` class but does not auto-connect discord.js; you plug in a client via the `DiscordPoster` interface. A default implementation will ship in v0.2.0.
+- **Gitea webhook receiver** is scaffolded but not yet exposed as an HTTP endpoint in `rails serve` — tracked for v0.2.0.
+- **Manual QA checks** are stubbed (SKIPPED by default). Provide a `manualResolver` to `runQaTemplate` to wire up a reviewer LLM.
+
+## Further reading
+
+- [`.plans/failure-audit.md`](../.plans/failure-audit.md) — why rails exists (F1–F6)
+- [`.plans/design/`](../.plans/design/) — architecture docs
+- `docs/operations.md` — day-to-day operations guide

docs/operations.md

@@ -0,0 +1,185 @@
+# Operations Guide
+
+> Day-to-day operations for running `hanarang-rails` in production.
+
+## Process management
+
+Rails is a long-lived orchestrator. Use `pm2` (recommended), `systemd`, or `docker-compose` to supervise it.
+
+### PM2
+
+```bash
+cd /path/to/hanarang-rails
+pm2 start ecosystem.config.cjs
+pm2 save
+pm2 startup    # enable auto-start on reboot
+```
+
+Check status:
+```bash
+pm2 list
+pm2 logs hanarang-rails
+pm2 restart hanarang-rails
+```
+
+## Health check
+
+Run this on a cron or uptime monitor:
+
+```bash
+pnpm rails doctor
+```
+
+Exit code 0 = healthy, 1 = one or more errors.
+
+For deeper state:
+```bash
+pnpm rails status              # list recent pipelines
+pnpm rails status <pipeline>   # single pipeline with timeline
+```
+
+## Common tasks
+
+### Start a pipeline from the shell
+
+```bash
+pnpm rails run my-project -r "Add Live2D avatar component"
+```
+
+### Resume an escalated pipeline
+
+```bash
+pnpm rails status --state escalated
+pnpm rails resume <pipeline-id>
+```
+
+### Abort a runaway pipeline
+
+```bash
+pnpm rails abort <pipeline-id> -r "wrong branch"
+```
+
+### Generate and freeze a contract
+
+```bash
+pnpm rails contract generate .plans/sprints/SPRINT-007.md -s SPRINT-007
+# review the draft in .rails/contracts/<id>.sprint-contract.json
+pnpm rails contract freeze <id>
+pnpm rails contract validate <id>
+```
+
+### Run QA for a sprint type
+
+```bash
+pnpm rails qa run feature -s SPRINT-007
+pnpm rails qa show <artifact-id>
+```
+
+## Troubleshooting
+
+### "No skill context found"
+
+The enforcement hook is blocking tool calls because the rails skill context is missing or expired.
+
+```bash
+pnpm rails skill-context create --pipeline <id> --skill rails
+pnpm rails skill-context show
+```
+
+To temporarily disable enforcement for debugging (logged to trace):
+```bash
+RAILS_ENFORCE=off pnpm rails run ...
+```
+
+### Pipeline stuck in `retrying`
+
+The retrying state has an `always` transition — it should move forward immediately. If you see it stuck in SQL dumps, check for a stale process holding a DB connection. Restart the orchestrator:
+
+```bash
+pm2 restart hanarang-rails
+```
+
+### "Contract validator ABORT_PRECHECK"
+
+Environment prerequisites failed. The validator output will name the missing prereq. Common causes:
+
+- `node22` prereq → upgrade Node runtime
+- `DATABASE_URL` env var missing → check `.env`
+- `port_open` → the target service is down
+- `http_reachable` → network / firewall
+
+### xhigh thinking tier refused
+
+Rails refuses to pass `xhigh` to agents because it caused indefinite waits in the legacy system. Use `high` or below. If an agent config still sets `xhigh`, grep and update:
+
+```bash
+grep -rn "thinking_tier.*xhigh" agents/
+```
+
+### Manual QA checks always SKIPPED
+
+By default, `rails qa run` marks manual checks as SKIPPED (passed=true with a skip note). To actually evaluate, plug in a resolver programmatically. A shipped LLM resolver is tracked for v0.2.0.
+
+## Logs
+
+Rails uses `pino` for structured logging. Every log line is JSON with at least:
+```json
+{"level":30,"time":...,"service":"hanarang-rails","module":"runner","pipelineId":"01..."}
+```
+
+Pipe through `pino-pretty` for interactive reading:
+```bash
+pm2 logs hanarang-rails --raw | pino-pretty
+```
+
+## Database maintenance
+
+Rails uses a single MariaDB schema with 5 tables: `pipelines`, `state_transitions`, `actor_spawns`, `contracts`, `escalations`.
+
+### Retention
+
+By default there is no automatic retention. Add a cron:
+
+```sql
+-- Trim state_transitions older than 90 days for terminal pipelines
+DELETE st FROM state_transitions st
+  JOIN pipelines p ON p.id = st.pipelineId
+  WHERE p.currentState IN ('done', 'aborted')
+    AND p.updatedAt < NOW() - INTERVAL 90 DAY;
+```
+
+### Backup
+
+Standard MariaDB dump:
+```bash
+mysqldump hanarang_rails > backup-$(date +%F).sql
+```
+
+## Security
+
+- **Never commit `.env`.** Use secret management for production deployments.
+- **Rotate `DISCORD_TOKEN` periodically.** Rails reads env vars on startup.
+- **`GITEA_WEBHOOK_SECRET`** must be a high-entropy random string — used for HMAC verification.
+- **Skill enforcement trace** at `.rails/skill-trace.jsonl` may contain tool usage history. Rotate/truncate on long-lived installs.
+
+## Versioning
+
+Rails follows semver. Check current version:
+```bash
+pnpm rails --help | head -1
+```
+
+Upgrade:
+```bash
+git pull
+pnpm install --prod
+pnpm build
+pnpm prisma migrate deploy
+pm2 restart hanarang-rails
+```
+
+## Related
+
+- `migration-guide.md` — moving from legacy installs
+- `.plans/design/` — architecture
+- `.plans/failure-audit.md` — F1–F6 that rails prevents

prisma/schema.prisma

@@ -19,6 +19,7 @@ model Pipeline {
   transitions   StateTransition[]
   actorSpawns   ActorSpawn[]
   contracts     Contract[]
+  escalations   Escalation[]
 
   @@index([currentState])
   @@index([createdAt])
@@ -72,3 +73,22 @@ model Contract {
   @@index([sprintId])
   @@map("contracts")
 }
+
+model Escalation {
+  id               String   @id @db.VarChar(26) // ULID
+  pipelineId       String   @db.VarChar(26)
+  reason           String   @db.VarChar(500)
+  errorCategory    String   @db.VarChar(50)
+  stage            String   @db.VarChar(50) @default("")
+  attempts         Int      @default(0)
+  contextSnapshot  String   @db.LongText
+  resolvedAt       DateTime?
+  resolution       String?  @db.VarChar(50)
+  createdAt        DateTime @default(now())
+
+  pipeline         Pipeline @relation(fields: [pipelineId], references: [id], onDelete: Cascade)
+
+  @@index([pipelineId])
+  @@index([createdAt])
+  @@map("escalations")
+}

qa-templates/bugfix-v1.yaml

@@ -0,0 +1,50 @@
+template: bugfix-v1
+version: v1
+appliesTo: [bugfix]
+
+requiredChecks:
+  - id: regression-test
+    description: 버그를 재현하는 테스트가 추가됨 (수정 전 fail → 수정 후 pass)
+    kind: manual
+    spec:
+      question: 새로 추가된 regression 테스트가 있는가?
+      guidance: 수정 전 커밋에서 테스트가 실패하는지 확인했는가?
+    blocking: true
+    severity: major
+
+  - id: root-cause-documented
+    description: root cause 기록
+    kind: manual
+    spec:
+      question: 스프린트 문서 또는 커밋 메시지에 root cause 가 명시되었는가?
+    blocking: true
+    severity: major
+
+  - id: no-scope-creep
+    description: 버그 외 리팩터/기능 추가 없음
+    kind: manual
+    spec:
+      question: 이번 커밋이 오직 해당 버그만 수정하는가?
+      guidance: 동반 리팩터/포매팅 변경은 별도 커밋으로 분리되어야 함.
+    blocking: true
+    severity: major
+
+  - id: tests-pass
+    description: 전체 테스트 pass
+    kind: command_success
+    spec:
+      command: pnpm test
+      timeoutMs: 120000
+      expectExitCode: 0
+    blocking: true
+    severity: major
+
+  - id: typecheck
+    description: 타입 체크 pass
+    kind: command_success
+    spec:
+      command: pnpm tsc --noEmit
+      timeoutMs: 60000
+      expectExitCode: 0
+    blocking: true
+    severity: major

qa-templates/feature-v1.yaml

@@ -0,0 +1,66 @@
+template: feature-v1
+version: v1
+appliesTo: [feature]
+
+requiredChecks:
+  - id: tests-pass
+    description: 전체 테스트 통과
+    kind: command_success
+    spec:
+      command: pnpm test
+      timeoutMs: 120000
+      expectExitCode: 0
+    blocking: true
+    severity: major
+
+  - id: typecheck
+    description: TypeScript 타입 체크 통과
+    kind: command_success
+    spec:
+      command: pnpm tsc --noEmit
+      timeoutMs: 60000
+      expectExitCode: 0
+    blocking: true
+    severity: major
+
+  - id: no-console-log
+    description: console.* 호출 없음 (pino 사용)
+    kind: manual
+    spec:
+      question: 모든 새 코드가 pino logger 를 사용하고 console.* 직접 호출이 없는가?
+      guidance: grep -rn 'console\.' src/ 로 확인. 테스트 코드는 예외.
+    blocking: true
+    severity: major
+
+  - id: no-any-type
+    description: any 타입 신규 도입 없음
+    kind: manual
+    spec:
+      question: Zod 경계 밖에서 any 타입이 도입되지 않았는가?
+      guidance: 외부 입력은 Zod 검증 후 타입이 확정됨. any 는 절대 금지.
+    blocking: true
+    severity: major
+
+  - id: tests-added
+    description: 새 기능에 대한 테스트가 추가됨
+    kind: manual
+    spec:
+      question: 이번 변경 사항에 대한 단위/통합 테스트가 최소 1개 추가되었는가?
+    blocking: true
+    severity: major
+
+  - id: error-handling
+    description: 주요 에러 경로에 Result / try-catch 적용
+    kind: manual
+    spec:
+      question: 외부 시스템 호출 (네트워크, DB, subprocess) 에러가 적절히 처리되는가?
+    blocking: false
+    severity: minor
+
+  - id: docs-updated
+    description: README / .plans 에 변경 반영
+    kind: manual
+    spec:
+      question: 사용자 관찰 가능한 변경 사항이 README 또는 .plans 에 반영되었는가?
+    blocking: false
+    severity: minor

qa-templates/infra-v1.yaml

@@ -0,0 +1,46 @@
+template: infra-v1
+version: v1
+appliesTo: [infra, deploy-only]
+
+requiredChecks:
+  - id: config-validated
+    description: 인프라 설정 파일이 유효한지 확인
+    kind: manual
+    spec:
+      question: 변경된 설정 파일이 파싱/검증을 통과했는가?
+      guidance: docker-compose config, nginx -t, terraform validate 등.
+    blocking: true
+    severity: critical
+
+  - id: secrets-not-leaked
+    description: 시크릿이 리포지토리에 누출되지 않음
+    kind: manual
+    spec:
+      question: 새로 추가된 파일에 토큰/비밀번호가 포함되지 않았는가?
+      guidance: git diff 로 확인. .env 류는 예제만 commit.
+    blocking: true
+    severity: critical
+
+  - id: backward-compatible
+    description: 기존 서비스 호환
+    kind: manual
+    spec:
+      question: 기존에 돌던 서비스가 계속 동작하는가?
+    blocking: true
+    severity: major
+
+  - id: rollback-documented
+    description: 롤백 절차 문서화
+    kind: manual
+    spec:
+      question: 배포 실패 시 복구 절차가 명확한가?
+    blocking: true
+    severity: major
+
+  - id: health-check
+    description: 배포 후 health check 정의
+    kind: manual
+    spec:
+      question: 배포 성공 여부를 자동 판정할 수 있는 health check 가 있는가?
+    blocking: false
+    severity: major

qa-templates/migration-v1.yaml

@@ -0,0 +1,53 @@
+template: migration-v1
+version: v1
+appliesTo: [migration]
+
+requiredChecks:
+  - id: migration-script-exists
+    description: 마이그레이션 스크립트 파일 존재
+    kind: manual
+    spec:
+      question: prisma/migrations, SQL, 또는 해당 마이그레이션 스크립트가 존재하는가?
+    blocking: true
+    severity: critical
+
+  - id: rollback-plan
+    description: 롤백 계획 문서화
+    kind: manual
+    spec:
+      question: 롤백 절차가 .plans 또는 커밋 메시지에 문서화되었는가?
+    blocking: true
+    severity: critical
+
+  - id: dry-run-tested
+    description: dry-run 검증 완료
+    kind: manual
+    spec:
+      question: 프로덕션 전 stage/dry-run 환경에서 검증되었는가?
+    blocking: true
+    severity: critical
+
+  - id: data-loss-assessment
+    description: 데이터 손실 가능성 평가
+    kind: manual
+    spec:
+      question: 데이터 손실 리스크가 평가되었고 완화책이 있는가?
+      guidance: DROP / ALTER / NULL 전환 등은 반드시 평가.
+    blocking: true
+    severity: critical
+
+  - id: backup-captured
+    description: 운영 DB 백업 확인
+    kind: manual
+    spec:
+      question: 실행 직전 백업이 생성되었음을 확인했는가?
+    blocking: true
+    severity: critical
+
+  - id: idempotent
+    description: 재실행 안전성
+    kind: manual
+    spec:
+      question: 마이그레이션이 중단 후 재실행에도 안전한가?
+    blocking: false
+    severity: major

qa-templates/refactor-v1.yaml

@@ -0,0 +1,50 @@
+template: refactor-v1
+version: v1
+appliesTo: [refactor]
+
+requiredChecks:
+  - id: tests-pass
+    description: 리팩터 후 모든 테스트 pass
+    kind: command_success
+    spec:
+      command: pnpm test
+      timeoutMs: 120000
+      expectExitCode: 0
+    blocking: true
+    severity: major
+
+  - id: typecheck
+    description: 타입 체크 pass
+    kind: command_success
+    spec:
+      command: pnpm tsc --noEmit
+      timeoutMs: 60000
+      expectExitCode: 0
+    blocking: true
+    severity: major
+
+  - id: no-behavior-change
+    description: 외부 동작 변경 없음 (순수 리팩터)
+    kind: manual
+    spec:
+      question: 사용자 관찰 가능한 동작이 변경되지 않았는가?
+      guidance: 만약 변경되었다면 feature 로 재분류되어야 함.
+    blocking: true
+    severity: major
+
+  - id: tests-still-cover
+    description: 기존 테스트 커버리지 유지
+    kind: manual
+    spec:
+      question: 리팩터로 인해 테스트가 삭제되거나 우회되지 않았는가?
+    blocking: true
+    severity: major
+
+  - id: public-api-compatible
+    description: 공개 API 하위 호환
+    kind: manual
+    spec:
+      question: 공개 export 의 시그니처가 변경되지 않았는가?
+      guidance: 변경되었다면 breaking-change flag 필요.
+    blocking: false
+    severity: minor

qa-templates/scaffold-v1.yaml

@@ -0,0 +1,54 @@
+template: scaffold-v1
+version: v1
+appliesTo: [scaffold]
+
+requiredChecks:
+  - id: readme-exists
+    description: README.md 가 존재하고 최소 내용 포함
+    kind: file_exists
+    spec:
+      path: README.md
+    blocking: true
+    severity: major
+
+  - id: license-exists
+    description: LICENSE 파일 존재
+    kind: file_exists
+    spec:
+      path: LICENSE
+    blocking: true
+    severity: minor
+
+  - id: gitignore-exists
+    description: .gitignore 존재
+    kind: file_exists
+    spec:
+      path: .gitignore
+    blocking: true
+    severity: major
+
+  - id: package-manager-lockfile
+    description: pnpm-lock.yaml 존재 (npm/yarn lock 금지)
+    kind: file_exists
+    spec:
+      path: pnpm-lock.yaml
+    blocking: true
+    severity: major
+
+  - id: no-npm-lock
+    description: package-lock.json 이 없어야 함 (pnpm 전용)
+    kind: manual
+    spec:
+      question: package-lock.json 이 존재하지 않습니까?
+      guidance: pnpm-lock.yaml 만 사용. package-lock.json 이 있으면 실패.
+    blocking: true
+    severity: major
+
+  - id: tsconfig-strict
+    description: tsconfig.json strict 모드
+    kind: regex_in_file
+    spec:
+      path: tsconfig.json
+      pattern: '"strict"\s*:\s*true'
+    blocking: true
+    severity: major

src/cli/abort.ts

@@ -0,0 +1,54 @@
+import { defineCommand } from "citty";
+import { loadEnv } from "../env.js";
+import {
+  getPipelineState,
+  sendEvent,
+  disconnectPrisma,
+} from "../orchestrator/persist.js";
+
+export default defineCommand({
+  meta: {
+    name: "abort",
+    description: "Abort a running or escalated pipeline",
+  },
+  args: {
+    pipelineId: {
+      type: "positional",
+      description: "Pipeline ID to abort",
+      required: true,
+    },
+    reason: {
+      type: "string",
+      alias: "r",
+      description: "Reason for abort",
+      default: "Manual abort via CLI",
+    },
+  },
+  async run({ args }) {
+    loadEnv();
+    try {
+      const current = await getPipelineState(args.pipelineId);
+      if (!current) {
+        console.error(`Pipeline not found: ${args.pipelineId}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      if (current.state === "done" || current.state === "aborted") {
+        console.log(`Pipeline already in terminal state: ${current.state}`);
+        return;
+      }
+
+      const result = await sendEvent(args.pipelineId, {
+        type: "ABORT",
+        reason: args.reason ?? "Manual abort",
+      });
+
+      console.log(
+        `Aborted pipeline ${args.pipelineId}: ${current.state} → ${result.state}`,
+      );
+    } finally {
+      await disconnectPrisma();
+    }
+  },
+});

src/cli/doctor.ts

@@ -0,0 +1,160 @@
+import { defineCommand } from "citty";
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+
+interface CheckResult {
+  name: string;
+  ok: boolean;
+  detail: string;
+  severity: "error" | "warn" | "info";
+}
+
+function runCmd(cmd: string, args: string[]): Promise<{ code: number; out: string }> {
+  return new Promise((resolveFn) => {
+    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    child.stdout.on("data", (b: Buffer) => (out += b.toString()));
+    child.stderr.on("data", (b: Buffer) => (out += b.toString()));
+    child.on("exit", (code) => resolveFn({ code: code ?? -1, out: out.trim() }));
+    child.on("error", () => resolveFn({ code: -1, out: "" }));
+  });
+}
+
+async function checkNodeVersion(): Promise<CheckResult> {
+  const version = process.versions.node;
+  const major = parseInt(version.split(".")[0] ?? "0", 10);
+  return {
+    name: "Node.js",
+    ok: major >= 22,
+    detail: `v${version} (require ≥ 22)`,
+    severity: major >= 22 ? "info" : "error",
+  };
+}
+
+async function checkCommand(
+  name: string,
+  cmd: string,
+  versionArg = "--version",
+  required = true,
+): Promise<CheckResult> {
+  const r = await runCmd(cmd, [versionArg]);
+  return {
+    name,
+    ok: r.code === 0,
+    detail: r.code === 0 ? r.out.split("\n")[0] ?? "" : "not found",
+    severity: r.code === 0 ? "info" : required ? "error" : "warn",
+  };
+}
+
+async function checkEnvVar(
+  name: string,
+  required = false,
+): Promise<CheckResult> {
+  const val = process.env[name];
+  const ok = val !== undefined && val !== "";
+  return {
+    name: `env:${name}`,
+    ok,
+    detail: ok ? "set" : "not set",
+    severity: ok ? "info" : required ? "error" : "warn",
+  };
+}
+
+async function checkFile(
+  name: string,
+  path: string,
+  required = false,
+): Promise<CheckResult> {
+  try {
+    await access(path);
+    return { name, ok: true, detail: path, severity: "info" };
+  } catch {
+    return {
+      name,
+      ok: false,
+      detail: `${path} not found`,
+      severity: required ? "warn" : "info",
+    };
+  }
+}
+
+function printResult(r: CheckResult): void {
+  const mark = r.ok ? "✓" : r.severity === "error" ? "✗" : "⚠";
+  const color = r.ok ? "\x1b[32m" : r.severity === "error" ? "\x1b[31m" : "\x1b[33m";
+  const reset = "\x1b[0m";
+  console.log(`  ${color}${mark}${reset} ${r.name.padEnd(24)} ${r.detail}`);
+}
+
+export default defineCommand({
+  meta: {
+    name: "doctor",
+    description: "Check rails environment health",
+  },
+  args: {
+    verbose: {
+      type: "boolean",
+      alias: "v",
+      description: "Show passed checks too",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = process.cwd();
+    console.log("rails doctor — environment check\n");
+
+    const checks: CheckResult[] = [];
+
+    // Runtime
+    console.log("Runtime:");
+    const runtime = [
+      await checkNodeVersion(),
+      await checkCommand("pnpm", "pnpm"),
+      await checkCommand("git", "git"),
+      await checkCommand("jq", "jq", "--version", false),
+    ];
+    runtime.forEach(printResult);
+    checks.push(...runtime);
+
+    // Env vars
+    console.log("\nEnvironment:");
+    const envChecks = [
+      await checkEnvVar("DATABASE_URL", true),
+      await checkEnvVar("DISCORD_TOKEN", false),
+      await checkEnvVar("DISCORD_GUILD_ID", false),
+      await checkEnvVar("GITEA_WEBHOOK_SECRET", false),
+    ];
+    envChecks.forEach(printResult);
+    checks.push(...envChecks);
+
+    // Project files
+    console.log("\nProject:");
+    const files = [
+      await checkFile("package.json", join(cwd, "package.json"), true),
+      await checkFile("tsconfig.json", join(cwd, "tsconfig.json"), true),
+      await checkFile("prisma/schema.prisma", join(cwd, "prisma/schema.prisma"), true),
+      await checkFile("qa-templates/", join(cwd, "qa-templates"), false),
+      await checkFile(".env", join(cwd, ".env"), false),
+    ];
+    files.forEach(printResult);
+    checks.push(...files);
+
+    // Summary
+    const errors = checks.filter((c) => !c.ok && c.severity === "error").length;
+    const warns = checks.filter((c) => !c.ok && c.severity === "warn").length;
+
+    console.log("");
+    if (errors === 0 && warns === 0) {
+      console.log("\x1b[32m✓ All checks passed\x1b[0m");
+      process.exitCode = 0;
+    } else if (errors === 0) {
+      console.log(`\x1b[33m⚠ ${warns} warning(s) — rails can run but some features disabled\x1b[0m`);
+      process.exitCode = 0;
+    } else {
+      console.log(`\x1b[31m✗ ${errors} error(s) and ${warns} warning(s) — fix errors before running\x1b[0m`);
+      process.exitCode = 1;
+    }
+
+    void args.verbose; // satisfy unused-param lint
+  },
+});

src/cli/index.ts

@@ -17,6 +17,12 @@ const main = defineCommand({
       import("./skill-trace.js").then((m) => m.default),
     contract: () => import("./contract.js").then((m) => m.default),
     run: () => import("./run.js").then((m) => m.default),
+    resume: () => import("./resume.js").then((m) => m.default),
+    abort: () => import("./abort.js").then((m) => m.default),
+    qa: () => import("./qa.js").then((m) => m.default),
+    doctor: () => import("./doctor.js").then((m) => m.default),
+    scaffold: () => import("./scaffold.js").then((m) => m.default),
+    migrate: () => import("./migrate.js").then((m) => m.default),
   },
 });
 

src/cli/migrate.ts

@@ -0,0 +1,203 @@
+import { defineCommand } from "citty";
+import { readdir, stat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+interface ScanReport {
+  sourcePath: string;
+  agents: Array<{ name: string; path: string; size: number }>;
+  scripts: Array<{ name: string; path: string; portable: boolean; reason: string }>;
+  workflows: Array<{ name: string; path: string; deprecated: boolean; reason: string }>;
+  plansDirs: string[];
+  warnings: string[];
+}
+
+const DEPRECATED_WORKFLOWS = [
+  {
+    pattern: /\.lobster$/,
+    reason: "Lobster workflow — LLM-branching, replaced by XState FSM",
+  },
+];
+
+const PORTABLE_SCRIPTS = new Set([
+  "scaffold.sh",
+  "install.sh",
+  "doctor.sh",
+  "route-task.sh",
+]);
+
+const DEPRECATED_SCRIPTS = new Set(["bridge.sh"]);
+
+async function scanDir(root: string, report: ScanReport): Promise<void> {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const e of entries) {
+    const full = join(root, e.name);
+    if (e.isDirectory()) {
+      if (e.name === "node_modules" || e.name === ".git") continue;
+      if (e.name === ".plans") {
+        report.plansDirs.push(full);
+      }
+      await scanDir(full, report);
+    } else if (e.isFile()) {
+      if (root.endsWith("/agents") || root.includes("/agents/")) {
+        if (e.name.endsWith(".md")) {
+          const s = await stat(full);
+          report.agents.push({ name: e.name, path: full, size: s.size });
+        }
+      }
+      if (root.endsWith("/scripts") && e.name.endsWith(".sh")) {
+        if (DEPRECATED_SCRIPTS.has(e.name)) {
+          report.scripts.push({
+            name: e.name,
+            path: full,
+            portable: false,
+            reason: "Replaced by discord.js bridge",
+          });
+        } else if (PORTABLE_SCRIPTS.has(e.name)) {
+          report.scripts.push({
+            name: e.name,
+            path: full,
+            portable: true,
+            reason: "Can be ported to rails command",
+          });
+        } else {
+          report.scripts.push({
+            name: e.name,
+            path: full,
+            portable: true,
+            reason: "Review manually",
+          });
+        }
+      }
+      for (const dw of DEPRECATED_WORKFLOWS) {
+        if (dw.pattern.test(e.name)) {
+          report.workflows.push({
+            name: e.name,
+            path: full,
+            deprecated: true,
+            reason: dw.reason,
+          });
+        }
+      }
+    }
+  }
+}
+
+const fromCmd = defineCommand({
+  meta: {
+    name: "from-hanarang-harness",
+    description: "Scan an existing hanarang-harness directory and report portable assets",
+  },
+  args: {
+    sourcePath: {
+      type: "positional",
+      description: "Path to hanarang-harness archive",
+      required: true,
+    },
+    json: {
+      type: "boolean",
+      description: "Output as JSON",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const sourcePath = args.sourcePath;
+    try {
+      const s = await stat(sourcePath);
+      if (!s.isDirectory()) {
+        console.error(`Not a directory: ${sourcePath}`);
+        process.exitCode = 1;
+        return;
+      }
+    } catch {
+      console.error(`Path not found: ${sourcePath}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const report: ScanReport = {
+      sourcePath,
+      agents: [],
+      scripts: [],
+      workflows: [],
+      plansDirs: [],
+      warnings: [],
+    };
+
+    await scanDir(sourcePath, report);
+
+    // Check for common risky patterns
+    for (const a of report.agents) {
+      try {
+        const content = await readFile(a.path, "utf8");
+        if (content.includes("xhigh")) {
+          report.warnings.push(
+            `${a.name}: references 'xhigh' thinking tier (forbidden in rails)`,
+          );
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+
+    if (args.json) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+
+    console.log(`Migration scan: ${sourcePath}\n`);
+
+    console.log(`Agents (${report.agents.length}):`);
+    for (const a of report.agents.slice(0, 20)) {
+      console.log(`  ${a.name.padEnd(30)} ${a.size} bytes`);
+    }
+    if (report.agents.length > 20) {
+      console.log(`  ... and ${report.agents.length - 20} more`);
+    }
+
+    console.log(`\nScripts (${report.scripts.length}):`);
+    for (const s of report.scripts) {
+      const mark = s.portable ? "✓" : "✗";
+      console.log(`  ${mark} ${s.name.padEnd(20)} ${s.reason}`);
+    }
+
+    console.log(`\nWorkflows (${report.workflows.length}):`);
+    for (const w of report.workflows) {
+      const mark = w.deprecated ? "✗" : "✓";
+      console.log(`  ${mark} ${w.name.padEnd(30)} ${w.reason}`);
+    }
+
+    console.log(`\n.plans/ directories (${report.plansDirs.length}):`);
+    for (const p of report.plansDirs) {
+      console.log(`  ${p}`);
+    }
+
+    if (report.warnings.length > 0) {
+      console.log(`\nWarnings (${report.warnings.length}):`);
+      for (const w of report.warnings) {
+        console.log(`  ⚠ ${w}`);
+      }
+    }
+
+    console.log("\nNext steps:");
+    console.log("  1. Copy portable agents to rails agents/ directory");
+    console.log("  2. Replace Lobster workflows with XState FSM (already built-in)");
+    console.log("  3. Drop bridge.sh — rails uses discord.js");
+    console.log("  4. Wire agent channels in rails.config.yaml");
+  },
+});
+
+export default defineCommand({
+  meta: {
+    name: "migrate",
+    description: "Migration tools for existing hanarang-harness installs",
+  },
+  subCommands: {
+    "from-hanarang-harness": fromCmd,
+  },
+});

src/cli/qa.ts

@@ -0,0 +1,107 @@
+import { defineCommand } from "citty";
+import { readFile } from "node:fs/promises";
+import { loadTemplateForType, listTemplates } from "../qa/template.js";
+import { runQaTemplate, saveQaArtifact } from "../qa/runtime.js";
+import { QaArtifact } from "../qa/schema.js";
+import { join } from "node:path";
+
+const runCmd = defineCommand({
+  meta: { name: "run", description: "Run QA template against current workdir" },
+  args: {
+    type: {
+      type: "positional",
+      description: "Sprint type (scaffold, feature, bugfix, refactor, migration, infra)",
+      required: true,
+    },
+    sprintId: {
+      type: "string",
+      alias: "s",
+      description: "Sprint ID",
+      default: "manual-run",
+    },
+    workdir: {
+      type: "string",
+      alias: "w",
+      description: "Working directory (default: cwd)",
+      default: "",
+    },
+  },
+  async run({ args }) {
+    const workdir = args.workdir || process.cwd();
+    const template = await loadTemplateForType(args.type);
+    const artifact = await runQaTemplate({
+      template,
+      workdir,
+      sprintId: args.sprintId ?? "manual-run",
+    });
+    const filePath = await saveQaArtifact(workdir, artifact);
+
+    console.log(`QA Artifact: ${artifact.artifactId}`);
+    console.log(`  template:   ${artifact.templateId}`);
+    console.log(`  sprintId:   ${artifact.sprintId}`);
+    console.log(`  verdict:    ${artifact.verdict}`);
+    console.log(
+      `  summary:    ${artifact.summary.passed}/${artifact.summary.total} passed, ${artifact.summary.blockingFailed} blocking failures`,
+    );
+    console.log(`  path:       ${filePath}`);
+    console.log("");
+
+    for (const c of artifact.checks) {
+      const mark = c.passed ? "✓" : "✗";
+      const msg = c.passed ? c.evidence : c.errorMessage;
+      console.log(`  ${mark} [${c.severity}] ${c.id}: ${msg}`);
+    }
+
+    process.exitCode =
+      artifact.verdict === "APPROVE" || artifact.verdict === "APPROVE_WITH_NITS"
+        ? 0
+        : 1;
+  },
+});
+
+const showCmd = defineCommand({
+  meta: { name: "show", description: "Show a saved QA artifact" },
+  args: {
+    artifactId: {
+      type: "positional",
+      description: "Artifact ID",
+      required: true,
+    },
+  },
+  async run({ args }) {
+    const filePath = join(
+      process.cwd(),
+      ".rails",
+      "qa-artifacts",
+      `${args.artifactId}.json`,
+    );
+    const raw = await readFile(filePath, "utf8");
+    const artifact = QaArtifact.parse(JSON.parse(raw));
+    console.log(JSON.stringify(artifact, null, 2));
+  },
+});
+
+const listCmd = defineCommand({
+  meta: { name: "templates", description: "List available QA templates" },
+  async run() {
+    const names = await listTemplates();
+    if (names.length === 0) {
+      console.log("No templates found. Check qa-templates/ directory.");
+      return;
+    }
+    console.log("Available QA templates:");
+    for (const name of names) console.log(`  - ${name}`);
+  },
+});
+
+export default defineCommand({
+  meta: {
+    name: "qa",
+    description: "Run QA templates (reviewer stage)",
+  },
+  subCommands: {
+    run: runCmd,
+    show: showCmd,
+    templates: listCmd,
+  },
+});

src/cli/resume.ts

@@ -0,0 +1,50 @@
+import { defineCommand } from "citty";
+import { loadEnv } from "../env.js";
+import {
+  getPipelineState,
+  sendEvent,
+  disconnectPrisma,
+} from "../orchestrator/persist.js";
+
+export default defineCommand({
+  meta: {
+    name: "resume",
+    description: "Resume an escalated pipeline",
+  },
+  args: {
+    pipelineId: {
+      type: "positional",
+      description: "Pipeline ID to resume",
+      required: true,
+    },
+  },
+  async run({ args }) {
+    loadEnv();
+    try {
+      const current = await getPipelineState(args.pipelineId);
+      if (!current) {
+        console.error(`Pipeline not found: ${args.pipelineId}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      if (current.state !== "escalated") {
+        console.error(
+          `Pipeline ${args.pipelineId} is in state '${current.state}', not 'escalated'. Cannot resume.`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+
+      const result = await sendEvent(args.pipelineId, { type: "RESUME" });
+      console.log(
+        `Resumed pipeline ${args.pipelineId}: ${current.state} → ${result.state}`,
+      );
+      console.log(
+        `  retryCount reset. Call 'rails run' or orchestrator loop to continue processing.`,
+      );
+    } finally {
+      await disconnectPrisma();
+    }
+  },
+});

src/cli/scaffold.ts

@@ -0,0 +1,127 @@
+import { defineCommand } from "citty";
+import { mkdir, writeFile, access } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+const DIRS = [
+  ".plans",
+  ".plans/design",
+  ".plans/sprints",
+  ".plans/migration",
+  ".rails/contracts",
+  ".rails/qa-artifacts",
+];
+
+const PLANS_MD = `# Plans.md — {{PROJECT_NAME}}
+
+> 루트 인덱스. 상세는 \`.plans/sprints/*.md\` 참조.
+
+## 📖 관련 문서
+
+- [\`.plans/OVERVIEW.md\`](.plans/OVERVIEW.md) — 전체 목표 / 범위 / 성공 기준
+- [\`.plans/design/\`](.plans/design/) — 설계 문서
+- [\`.plans/sprints/\`](.plans/sprints/) — 스프린트별 상세
+
+## Sprint 목차
+
+| # | Sprint | 상세 | Status |
+|---|---|---|---|
+
+## 마커 범례
+
+| 마커 | 의미 |
+|---|---|
+| \`cc:TODO\` | 미착수 |
+| \`cc:WIP\` | 작업 중 |
+| \`cc:blocked\` | 의존 대기 |
+| \`cc:완료 [hash]\` | 완료 |
+`;
+
+const OVERVIEW_MD = `# {{PROJECT_NAME}} — OVERVIEW
+
+## 목표 (Goal)
+
+TODO: 프로젝트의 한 줄 목표
+
+## 범위 (Scope)
+
+### In Scope
+- TODO
+
+### Out of Scope
+- TODO
+
+## 성공 기준 (Definition of Done)
+
+1. TODO
+
+## 관련 문서
+
+- \`.plans/sprints/\` — 스프린트 명세
+`;
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export default defineCommand({
+  meta: {
+    name: "scaffold",
+    description: "Generate .plans/ directory structure for a new project",
+  },
+  args: {
+    projectDir: {
+      type: "positional",
+      description: "Target directory (default: cwd)",
+      required: false,
+    },
+    name: {
+      type: "string",
+      alias: "n",
+      description: "Project name for templates",
+      default: "",
+    },
+    force: {
+      type: "boolean",
+      alias: "f",
+      description: "Overwrite existing files",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const target = resolve(args.projectDir ?? process.cwd());
+    const name = args.name || target.split("/").pop() || "project";
+
+    console.log(`Scaffolding .plans/ at ${target}`);
+
+    for (const d of DIRS) {
+      await mkdir(join(target, d), { recursive: true });
+      console.log(`  + ${d}/`);
+    }
+
+    const files: Array<[string, string]> = [
+      ["Plans.md", PLANS_MD],
+      [".plans/OVERVIEW.md", OVERVIEW_MD],
+    ];
+
+    for (const [relPath, content] of files) {
+      const full = join(target, relPath);
+      if ((await pathExists(full)) && !args.force) {
+        console.log(`  ~ ${relPath} (exists, skipped)`);
+        continue;
+      }
+      const rendered = content.replace(/\{\{PROJECT_NAME\}\}/g, name);
+      await writeFile(full, rendered, "utf8");
+      console.log(`  + ${relPath}`);
+    }
+
+    console.log("\nDone. Next:");
+    console.log("  1. Edit .plans/OVERVIEW.md");
+    console.log("  2. Add sprint docs under .plans/sprints/");
+    console.log("  3. Reference sprints from Plans.md");
+  },
+});

src/orchestrator/runner.ts

@@ -4,6 +4,8 @@ import type { PipelineEvent, PipelineState } from "./events.js";
 import type { HandoffMessage, InvokeRequest } from "../handoff/message.js";
 import type { SisterTransport } from "../handoff/transport.js";
 import type { RailsConfig } from "../config/schema.js";
+import { withRetry } from "../resilience/retry.js";
+import { recordEscalation, type EscalationNotifier } from "../resilience/escalate.js";
 import { childLogger } from "../logger.js";
 
 const log = childLogger({ module: "runner" });
@@ -14,6 +16,8 @@ export interface RunOptions {
   config: RailsConfig;
   transports: Map<string, SisterTransport>;
   signal?: AbortSignal;
+  maxRetries?: number;
+  notifier?: EscalationNotifier;
 }
 
 export interface RunResult {
@@ -89,19 +93,52 @@ export async function runPipeline(opts: RunOptions): Promise<RunResult> {
       structuredOutput: true,
     };
 
-    try {
+    const retryResult = await withRetry(
-      const handoff = await transport.invoke(invokeReq, opts.signal);
+      async () => transport.invoke(invokeReq, opts.signal),
-      const event = handoffToEvent(handoff);
+      {
+        maxRetries: opts.maxRetries ?? 3,
+        ...(opts.signal && { signal: opts.signal }),
+      },
+    );
+
+    if (retryResult.ok && retryResult.value) {
+      const event = handoffToEvent(retryResult.value);
       result = await sendEvent(pipelineId, event);
       transitions += 1;
-    } catch (err) {
+    } else {
-      const reason = err instanceof Error ? err.message : String(err);
+      const classification = retryResult.classification;
-      log.error({ stage, reason }, "Transport invoke failed");
+      const reason =
+        retryResult.error?.message ?? "Unknown invoke failure";
+
+      log.error(
+        {
+          stage,
+          attempts: retryResult.attempts,
+          category: classification?.reason,
+          reason,
+        },
+        "Transport invoke failed after retries",
+      );
+
+      if (classification && !classification.retryable) {
+        await recordEscalation(
+          {
+            pipelineId,
+            stage,
+            reason,
+            attempts: retryResult.attempts,
+            classification,
+            contextSnapshot: result.context as unknown as Record<string, unknown>,
+          },
+          opts.notifier,
+        );
+      }
+
       result = await sendEvent(pipelineId, {
         type: "ERROR",
         actor: stage,
         reason,
-        retryable: true,
+        retryable: classification?.retryable ?? false,
       });
       transitions += 1;
     }

src/qa/runtime.ts

@@ -0,0 +1,191 @@
+import { ulid } from "ulid";
+import { writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { QaTemplate, QaArtifact, QaChecklistResult } from "./schema.js";
+import { CHECK_HANDLERS } from "../contract/checks/index.js";
+import { computeVerdict, summarize } from "./verdict.js";
+import { childLogger } from "../logger.js";
+
+const log = childLogger({ module: "qa-runtime" });
+
+export interface QaRunOptions {
+  template: QaTemplate;
+  workdir: string;
+  sprintId: string;
+  contractId?: string;
+  reviewer?: string;
+  reviewRound?: number;
+  env?: Record<string, string>;
+  /**
+   * Optional resolver for manual checks. If not provided, manual checks
+   * are marked as SKIPPED (passed=true) which is the default for Sprint 006.
+   * Sprint 007 or later can plug in an LLM-backed resolver.
+   */
+  manualResolver?: (check: {
+    id: string;
+    question: string;
+    guidance?: string;
+  }) => Promise<{ passed: boolean; note: string }>;
+}
+
+/**
+ * Run a QA template against a working directory.
+ * Returns a structured QaArtifact capturing every check result.
+ */
+export async function runQaTemplate(
+  opts: QaRunOptions,
+): Promise<QaArtifact> {
+  const startedAt = new Date().toISOString();
+  const artifactId = ulid();
+  const env = opts.env ?? (process.env as Record<string, string>);
+
+  const allChecks = [
+    ...opts.template.requiredChecks,
+    ...opts.template.additionalChecks,
+  ];
+
+  const results: QaChecklistResult[] = [];
+  for (const check of allChecks) {
+    const start = Date.now();
+
+    if (check.kind === "manual") {
+      if (opts.manualResolver) {
+        try {
+          const spec = check.spec as { question: string; guidance?: string };
+          const resolved = await opts.manualResolver({
+            id: check.id,
+            question: spec.question,
+            ...(spec.guidance !== undefined && { guidance: spec.guidance }),
+          });
+          results.push({
+            id: check.id,
+            kind: check.kind,
+            passed: resolved.passed,
+            severity: check.severity,
+            evidence: resolved.passed ? resolved.note : "",
+            errorMessage: resolved.passed ? "" : resolved.note,
+            reviewerNote: resolved.note,
+            durationMs: Date.now() - start,
+          });
+        } catch (err) {
+          results.push({
+            id: check.id,
+            kind: check.kind,
+            passed: false,
+            severity: check.severity,
+            evidence: "",
+            errorMessage: `Manual resolver errored: ${err instanceof Error ? err.message : String(err)}`,
+            reviewerNote: "",
+            durationMs: Date.now() - start,
+          });
+        }
+      } else {
+        // Default: SKIPPED
+        results.push({
+          id: check.id,
+          kind: check.kind,
+          passed: true,
+          severity: check.severity,
+          evidence: "[SKIPPED — manual, no resolver]",
+          errorMessage: "",
+          reviewerNote: "",
+          durationMs: Date.now() - start,
+        });
+      }
+      continue;
+    }
+
+    const handler = CHECK_HANDLERS[check.kind];
+    if (!handler) {
+      results.push({
+        id: check.id,
+        kind: check.kind,
+        passed: false,
+        severity: check.severity,
+        evidence: "",
+        errorMessage: `No handler for kind: ${check.kind}`,
+        reviewerNote: "",
+        durationMs: 0,
+      });
+      continue;
+    }
+
+    try {
+      const outcome = await handler(check, { workdir: opts.workdir, env });
+      results.push({
+        id: check.id,
+        kind: check.kind,
+        passed: outcome.passed,
+        severity: check.severity,
+        evidence: outcome.evidence,
+        errorMessage: outcome.errorMessage,
+        reviewerNote: "",
+        durationMs: outcome.durationMs,
+      });
+    } catch (err) {
+      results.push({
+        id: check.id,
+        kind: check.kind,
+        passed: false,
+        severity: check.severity,
+        evidence: "",
+        errorMessage: `Handler threw: ${err instanceof Error ? err.message : String(err)}`,
+        reviewerNote: "",
+        durationMs: Date.now() - start,
+      });
+    }
+  }
+
+  const verdict = computeVerdict({
+    checks: results,
+    prerequisitesPassed: true,
+  });
+
+  const summary = summarize(results);
+  const completedAt = new Date().toISOString();
+
+  const artifact: QaArtifact = {
+    schemaVersion: "v1",
+    artifactId,
+    sprintId: opts.sprintId,
+    contractId: opts.contractId ?? "",
+    templateId: opts.template.template,
+    reviewer: opts.reviewer ?? "darang",
+    reviewRound: opts.reviewRound ?? 1,
+    startedAt,
+    completedAt,
+    checks: results,
+    verdict,
+    summary,
+  };
+
+  log.info(
+    {
+      artifactId,
+      sprintId: opts.sprintId,
+      verdict,
+      ...summary,
+    },
+    "QA template run complete",
+  );
+
+  return artifact;
+}
+
+/**
+ * Save a QA artifact to disk. Path: .rails/qa-artifacts/<id>.json
+ */
+export async function saveQaArtifact(
+  workdir: string,
+  artifact: QaArtifact,
+): Promise<string> {
+  const filePath = join(
+    workdir,
+    ".rails",
+    "qa-artifacts",
+    `${artifact.artifactId}.json`,
+  );
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, JSON.stringify(artifact, null, 2), "utf8");
+  return filePath;
+}

src/qa/schema.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { DodCheck } from "../contract/schema.js";
+
+/**
+ * QA Template — a reusable checklist applied during the review stage,
+ * on top of the sprint contract. Templates are selected by sprint type.
+ *
+ * Unlike contracts (which define "done" for the whole sprint), templates
+ * focus on quality gates the reviewer (darang) must verify.
+ */
+export const QaTemplate = z.object({
+  template: z.string().min(1),
+  version: z.string().default("v1"),
+  appliesTo: z.array(z.string()).default([]), // sprint types
+  extends: z.string().optional(),               // parent template name
+  requiredChecks: z.array(DodCheck).default([]),
+  additionalChecks: z.array(DodCheck).default([]),
+});
+
+export type QaTemplate = z.infer<typeof QaTemplate>;
+
+export const QaChecklistResult = z.object({
+  id: z.string(),
+  kind: z.string(),
+  passed: z.boolean(),
+  severity: z.enum(["critical", "major", "minor", "recommendation"]),
+  evidence: z.string().default(""),
+  errorMessage: z.string().default(""),
+  reviewerNote: z.string().default(""),
+  durationMs: z.number().default(0),
+});
+
+export type QaChecklistResult = z.infer<typeof QaChecklistResult>;
+
+export const QaArtifact = z.object({
+  schemaVersion: z.literal("v1"),
+  artifactId: z.string(),
+  sprintId: z.string(),
+  contractId: z.string().default(""),
+  templateId: z.string(),
+  reviewer: z.string().default("darang"),
+  reviewRound: z.number().int().min(0).default(1),
+  startedAt: z.string().datetime(),
+  completedAt: z.string().datetime(),
+  checks: z.array(QaChecklistResult),
+  verdict: z.enum([
+    "APPROVE",
+    "APPROVE_WITH_NITS",
+    "REQUEST_CHANGES",
+    "ABORT",
+  ]),
+  summary: z.object({
+    total: z.number().int().min(0),
+    passed: z.number().int().min(0),
+    failed: z.number().int().min(0),
+    skipped: z.number().int().min(0),
+    blockingFailed: z.number().int().min(0),
+  }),
+});
+
+export type QaArtifact = z.infer<typeof QaArtifact>;

src/qa/template.ts

@@ -0,0 +1,158 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { QaTemplate } from "./schema.js";
+import type { QaTemplate as Template } from "./schema.js";
+import { childLogger } from "../logger.js";
+
+const log = childLogger({ module: "qa-template" });
+
+/**
+ * Locate the qa-templates directory. Priority:
+ *   1. $RAILS_QA_TEMPLATES_DIR
+ *   2. ./qa-templates (project root)
+ *   3. built-in templates next to dist/
+ */
+export function resolveTemplatesDir(cwd: string = process.cwd()): string {
+  const envDir = process.env["RAILS_QA_TEMPLATES_DIR"];
+  if (envDir) return resolve(envDir);
+
+  const projectDir = join(cwd, "qa-templates");
+  return projectDir;
+}
+
+export async function loadTemplate(
+  nameOrPath: string,
+  templatesDir?: string,
+): Promise<Template> {
+  const dir = templatesDir ?? resolveTemplatesDir();
+  const candidates = [
+    nameOrPath,
+    join(dir, nameOrPath),
+    join(dir, `${nameOrPath}.yaml`),
+    join(dir, `${nameOrPath}.yml`),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      const raw = await readFile(candidate, "utf8");
+      const parsed = parseYaml(raw) as unknown;
+      return QaTemplate.parse(parsed);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw err;
+      }
+    }
+  }
+
+  throw new Error(
+    `QA template not found: ${nameOrPath} (searched in ${dir})`,
+  );
+}
+
+/**
+ * Load template by sprint type, following `extends` chain.
+ * Example: sprint type 'feature' → feature-v1.yaml
+ */
+export async function loadTemplateForType(
+  sprintType: string,
+  templatesDir?: string,
+): Promise<Template> {
+  const base = await loadTemplate(`${sprintType}-v1`, templatesDir);
+  return resolveExtends(base, templatesDir);
+}
+
+async function resolveExtends(
+  template: Template,
+  templatesDir?: string,
+  seen: Set<string> = new Set(),
+): Promise<Template> {
+  if (!template.extends) return template;
+  if (seen.has(template.template)) {
+    throw new Error(
+      `Circular extends chain in QA template: ${[...seen].join(" → ")}`,
+    );
+  }
+  seen.add(template.template);
+
+  const parent = await loadTemplate(template.extends, templatesDir);
+  const resolved = await resolveExtends(parent, templatesDir, seen);
+
+  return {
+    template: template.template,
+    version: template.version,
+    appliesTo: template.appliesTo.length ? template.appliesTo : resolved.appliesTo,
+    extends: template.extends,
+    requiredChecks: [...resolved.requiredChecks, ...template.requiredChecks],
+    additionalChecks: [
+      ...resolved.additionalChecks,
+      ...template.additionalChecks,
+    ],
+  };
+}
+
+/**
+ * Merge project-specific overrides (qa-extra.yaml) with a base template.
+ */
+export async function loadProjectExtras(
+  projectDir: string,
+  templatesDir?: string,
+): Promise<Template | null> {
+  const extraPath = join(projectDir, "qa-extra.yaml");
+  try {
+    const raw = await readFile(extraPath, "utf8");
+    const parsed = parseYaml(raw) as unknown;
+    const extra = QaTemplate.parse(parsed);
+    if (extra.extends) {
+      return resolveExtends(extra, templatesDir);
+    }
+    return extra;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+/**
+ * Combine a base template with a project-extras template.
+ */
+export function mergeTemplates(base: Template, extra: Template): Template {
+  return {
+    template: `${base.template}+${extra.template}`,
+    version: base.version,
+    appliesTo: base.appliesTo,
+    requiredChecks: [...base.requiredChecks, ...extra.requiredChecks],
+    additionalChecks: [
+      ...base.additionalChecks,
+      ...extra.additionalChecks,
+    ],
+  };
+}
+
+/**
+ * List all shipped templates in the templates directory.
+ */
+export async function listTemplates(
+  templatesDir?: string,
+): Promise<string[]> {
+  const dir = templatesDir ?? resolveTemplatesDir();
+  try {
+    const files = await readdir(dir);
+    return files
+      .filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"))
+      .map((f) => f.replace(/\.ya?ml$/, ""))
+      .sort();
+  } catch {
+    log.warn({ dir }, "Templates directory not found");
+    return [];
+  }
+}
+
+// For test fixtures and shipped bundle discovery
+export const BUILTIN_TEMPLATES_DIR = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "qa-templates",
+);

src/qa/verdict.ts

@@ -0,0 +1,60 @@
+import type { QaChecklistResult } from "./schema.js";
+
+export type QaVerdict = "APPROVE" | "APPROVE_WITH_NITS" | "REQUEST_CHANGES" | "ABORT";
+
+export interface VerdictInput {
+  checks: QaChecklistResult[];
+  prerequisitesPassed: boolean;
+}
+
+/**
+ * Apply the Harness verdict rules:
+ *   - Any critical/major failure in a blocking check → REQUEST_CHANGES
+ *   - Only minor failures → APPROVE_WITH_NITS
+ *   - Prerequisites failed → ABORT
+ *   - Otherwise → APPROVE
+ *
+ * Minor / recommendation issues NEVER cause REQUEST_CHANGES.
+ * This mirrors the rule documented in .plans/design/qa-template.md.
+ */
+export function computeVerdict(input: VerdictInput): QaVerdict {
+  if (!input.prerequisitesPassed) return "ABORT";
+
+  const failed = input.checks.filter((c) => !c.passed);
+  const blockingMajor = failed.filter(
+    (c) => c.severity === "critical" || c.severity === "major",
+  );
+
+  if (blockingMajor.length > 0) return "REQUEST_CHANGES";
+
+  const minorFailed = failed.filter(
+    (c) => c.severity === "minor" || c.severity === "recommendation",
+  );
+  if (minorFailed.length > 0) return "APPROVE_WITH_NITS";
+
+  return "APPROVE";
+}
+
+export function summarize(
+  checks: QaChecklistResult[],
+): {
+  total: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  blockingFailed: number;
+} {
+  const total = checks.length;
+  const passed = checks.filter((c) => c.passed).length;
+  const failed = total - passed;
+  const skipped = checks.filter((c) =>
+    c.evidence.toUpperCase().includes("SKIPPED"),
+  ).length;
+  const blockingFailed = checks.filter(
+    (c) =>
+      !c.passed &&
+      (c.severity === "critical" || c.severity === "major"),
+  ).length;
+
+  return { total, passed, failed, skipped, blockingFailed };
+}

src/resilience/backoff.ts

@@ -0,0 +1,46 @@
+/**
+ * Exponential backoff with jitter.
+ *
+ * Returns a wait duration (ms) given the current retry count.
+ * Starts at `base`, doubles each retry, capped at `max`, with ±30% jitter.
+ *
+ * Example (base=1000, max=30000):
+ *   retry 0: ~1s
+ *   retry 1: ~2s
+ *   retry 2: ~4s
+ *   retry 3: ~8s
+ *   retry 4: ~16s
+ *   retry 5+: ~30s (cap)
+ */
+export function backoffMs(
+  retryCount: number,
+  opts: { base?: number; max?: number; jitter?: number } = {},
+): number {
+  const base = opts.base ?? 1000;
+  const max = opts.max ?? 30_000;
+  const jitterPct = opts.jitter ?? 0.3;
+
+  const exp = Math.min(base * Math.pow(2, retryCount), max);
+  const jitterAmount = Math.random() * jitterPct * 2 * exp - jitterPct * exp;
+  return Math.max(0, Math.floor(exp + jitterAmount));
+}
+
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolveFn, rejectFn) => {
+    if (signal?.aborted) {
+      rejectFn(new Error("Aborted"));
+      return;
+    }
+    const timer = setTimeout(resolveFn, ms);
+    if (signal) {
+      signal.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          rejectFn(new Error("Aborted"));
+        },
+        { once: true },
+      );
+    }
+  });
+}

src/resilience/classifier.ts

@@ -0,0 +1,126 @@
+import { ZodError } from "zod";
+
+export type ErrorReason =
+  | "timeout"
+  | "rate_limit"
+  | "network"
+  | "transient"
+  | "config"
+  | "permission"
+  | "invariant"
+  | "user_input_needed";
+
+export interface ErrorClassification {
+  retryable: boolean;
+  reason: ErrorReason;
+  message: string;
+}
+
+export class TimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+}
+
+export class RateLimitError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RateLimitError";
+  }
+}
+
+export class NetworkError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "NetworkError";
+  }
+}
+
+export class PermissionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PermissionError";
+  }
+}
+
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+/**
+ * Classify an arbitrary error into { retryable, reason }.
+ * Non-retryable errors should escalate immediately; retrying won't help.
+ */
+export function classifyError(err: unknown): ErrorClassification {
+  if (err instanceof TimeoutError) {
+    return { retryable: true, reason: "timeout", message: err.message };
+  }
+  if (err instanceof RateLimitError) {
+    return { retryable: true, reason: "rate_limit", message: err.message };
+  }
+  if (err instanceof NetworkError) {
+    return { retryable: true, reason: "network", message: err.message };
+  }
+  if (err instanceof ZodError) {
+    return {
+      retryable: false,
+      reason: "invariant",
+      message: `Schema validation failed: ${err.issues.map((i) => i.message).join("; ")}`,
+    };
+  }
+  if (err instanceof PermissionError) {
+    return { retryable: false, reason: "permission", message: err.message };
+  }
+  if (err instanceof ConfigError) {
+    return { retryable: false, reason: "config", message: err.message };
+  }
+
+  // Heuristic detection by message string for errors from 3rd-party libs
+  if (err instanceof Error) {
+    const msg = err.message.toLowerCase();
+    if (msg.includes("timeout") || msg.includes("etimedout") || msg.includes("abort")) {
+      return { retryable: true, reason: "timeout", message: err.message };
+    }
+    if (
+      msg.includes("econnrefused") ||
+      msg.includes("enotfound") ||
+      msg.includes("econnreset") ||
+      msg.includes("network")
+    ) {
+      return { retryable: true, reason: "network", message: err.message };
+    }
+    if (msg.includes("rate limit") || msg.includes("429")) {
+      return { retryable: true, reason: "rate_limit", message: err.message };
+    }
+    if (msg.includes("eacces") || msg.includes("permission denied")) {
+      return { retryable: false, reason: "permission", message: err.message };
+    }
+    // Default: treat unknown errors as transient retryable
+    return { retryable: true, reason: "transient", message: err.message };
+  }
+
+  return {
+    retryable: true,
+    reason: "transient",
+    message: String(err),
+  };
+}
+
+/**
+ * Guard against disallowed thinking tiers (e.g., `xhigh` is known to hang).
+ * Throws a ConfigError if the forbidden tier is requested.
+ */
+const FORBIDDEN_THINKING_TIERS = new Set(["xhigh", "XHIGH"]);
+
+export function assertAllowedThinkingTier(tier: string | undefined): void {
+  if (!tier) return;
+  if (FORBIDDEN_THINKING_TIERS.has(tier)) {
+    throw new ConfigError(
+      `Thinking tier '${tier}' is forbidden — known to cause indefinite waits. Use 'high' or below.`,
+    );
+  }
+}

src/resilience/escalate.ts

@@ -0,0 +1,137 @@
+import { ulid } from "ulid";
+import { getPrisma } from "../orchestrator/persist.js";
+import type { ErrorClassification } from "./classifier.js";
+import { childLogger } from "../logger.js";
+
+const log = childLogger({ module: "escalate" });
+
+export interface EscalationInput {
+  pipelineId: string;
+  reason: string;
+  stage: string;
+  attempts: number;
+  classification?: ErrorClassification;
+  contextSnapshot: Record<string, unknown>;
+}
+
+export interface EscalationNotifier {
+  notify(message: {
+    title: string;
+    body: string;
+    mentionUser?: boolean;
+  }): Promise<void>;
+}
+
+/**
+ * Record an escalation in the database and (optionally) notify via a
+ * configured notifier. Returns the created escalation id.
+ */
+export async function recordEscalation(
+  input: EscalationInput,
+  notifier?: EscalationNotifier,
+): Promise<string> {
+  const id = ulid();
+  const prisma = getPrisma();
+
+  await prisma.escalation.create({
+    data: {
+      id,
+      pipelineId: input.pipelineId,
+      reason: input.reason.slice(0, 500),
+      errorCategory: input.classification?.reason ?? "unknown",
+      stage: input.stage,
+      attempts: input.attempts,
+      contextSnapshot: JSON.stringify(input.contextSnapshot),
+    },
+  });
+
+  log.warn(
+    {
+      escalationId: id,
+      pipelineId: input.pipelineId,
+      stage: input.stage,
+      reason: input.reason,
+    },
+    "Escalation recorded",
+  );
+
+  if (notifier) {
+    try {
+      await notifier.notify({
+        title: `🚨 Pipeline escalation — ${input.pipelineId.slice(0, 8)}`,
+        body: buildNotifyBody(input),
+        mentionUser: true,
+      });
+    } catch (err) {
+      log.error(
+        { err: err instanceof Error ? err.message : String(err) },
+        "Escalation notifier failed (non-fatal)",
+      );
+    }
+  }
+
+  return id;
+}
+
+function buildNotifyBody(input: EscalationInput): string {
+  const cat = input.classification?.reason ?? "unknown";
+  const lines = [
+    `**Stage:** ${input.stage}`,
+    `**Attempts:** ${input.attempts}`,
+    `**Category:** ${cat}`,
+    `**Reason:** ${input.reason}`,
+    "",
+    "Actions:",
+    `  \`rails resume ${input.pipelineId}\` — retry`,
+    `  \`rails abort ${input.pipelineId}\` — cancel`,
+    `  \`rails inspect ${input.pipelineId}\` — inspect`,
+  ];
+  return lines.join("\n");
+}
+
+export async function listEscalations(opts?: {
+  pipelineId?: string;
+  limit?: number;
+}): Promise<
+  Array<{
+    id: string;
+    pipelineId: string;
+    reason: string;
+    errorCategory: string;
+    stage: string;
+    attempts: number;
+    createdAt: Date;
+    resolvedAt: Date | null;
+  }>
+> {
+  const prisma = getPrisma();
+  return prisma.escalation.findMany({
+    where: opts?.pipelineId ? { pipelineId: opts.pipelineId } : undefined,
+    orderBy: { createdAt: "desc" },
+    take: opts?.limit ?? 20,
+    select: {
+      id: true,
+      pipelineId: true,
+      reason: true,
+      errorCategory: true,
+      stage: true,
+      attempts: true,
+      createdAt: true,
+      resolvedAt: true,
+    },
+  });
+}
+
+export async function resolveEscalation(
+  escalationId: string,
+  resolution: "resumed" | "aborted" | "manual",
+): Promise<void> {
+  const prisma = getPrisma();
+  await prisma.escalation.update({
+    where: { id: escalationId },
+    data: {
+      resolvedAt: new Date(),
+      resolution,
+    },
+  });
+}

src/resilience/kill.ts

@@ -0,0 +1,97 @@
+import type { ChildProcess } from "node:child_process";
+import { childLogger } from "../logger.js";
+
+const log = childLogger({ module: "kill" });
+
+/**
+ * Kill a child process and ensure it is dead.
+ * - First SIGTERM, wait up to graceMs
+ * - Then SIGKILL
+ * - If spawned with detached, also kill the process group (-pid)
+ */
+export async function killChildProcess(
+  child: ChildProcess,
+  opts: { graceMs?: number; killGroup?: boolean } = {},
+): Promise<void> {
+  const graceMs = opts.graceMs ?? 2000;
+  const killGroup = opts.killGroup ?? false;
+
+  if (child.killed || child.exitCode !== null) {
+    return;
+  }
+
+  const pid = child.pid;
+  if (!pid) return;
+
+  log.debug({ pid }, "Sending SIGTERM to child");
+  try {
+    if (killGroup) {
+      process.kill(-pid, "SIGTERM");
+    } else {
+      child.kill("SIGTERM");
+    }
+  } catch {
+    // already gone
+    return;
+  }
+
+  // Wait for graceful exit
+  const exited = await Promise.race([
+    new Promise<boolean>((resolveFn) => {
+      child.once("exit", () => resolveFn(true));
+    }),
+    new Promise<boolean>((resolveFn) =>
+      setTimeout(() => resolveFn(false), graceMs),
+    ),
+  ]);
+
+  if (exited) return;
+
+  log.warn({ pid }, "Grace period elapsed, sending SIGKILL");
+  try {
+    if (killGroup) {
+      process.kill(-pid, "SIGKILL");
+    } else {
+      child.kill("SIGKILL");
+    }
+  } catch {
+    // already gone
+  }
+}
+
+/**
+ * Global cleanup registry — kill all tracked children on process exit.
+ */
+const tracked = new Set<ChildProcess>();
+let handlersInstalled = false;
+
+export function trackChild(child: ChildProcess): void {
+  tracked.add(child);
+  child.once("exit", () => tracked.delete(child));
+  installHandlers();
+}
+
+function installHandlers(): void {
+  if (handlersInstalled) return;
+  handlersInstalled = true;
+
+  const cleanup = () => {
+    for (const child of tracked) {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        /* ignore */
+      }
+    }
+  };
+
+  process.on("exit", cleanup);
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(130);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(143);
+  });
+}

src/resilience/retry.ts

@@ -0,0 +1,108 @@
+import { backoffMs, sleep } from "./backoff.js";
+import { classifyError, type ErrorClassification } from "./classifier.js";
+import { childLogger } from "../logger.js";
+
+const log = childLogger({ module: "retry" });
+
+export interface RetryOptions {
+  maxRetries?: number;
+  baseMs?: number;
+  maxMs?: number;
+  onRetry?: (info: {
+    attempt: number;
+    classification: ErrorClassification;
+    delayMs: number;
+  }) => void;
+  signal?: AbortSignal;
+}
+
+export interface RetryResult<T> {
+  ok: boolean;
+  value?: T;
+  error?: Error;
+  classification?: ErrorClassification;
+  attempts: number;
+}
+
+/**
+ * Run `fn` with automatic retries for retryable errors.
+ * Non-retryable errors break out immediately (caller should escalate).
+ *
+ * Returns RetryResult — never throws.
+ */
+export async function withRetry<T>(
+  fn: (attempt: number) => Promise<T>,
+  opts: RetryOptions = {},
+): Promise<RetryResult<T>> {
+  const maxRetries = opts.maxRetries ?? 3;
+  let lastErr: Error | undefined;
+  let lastClass: ErrorClassification | undefined;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (opts.signal?.aborted) {
+      return {
+        ok: false,
+        error: new Error("Aborted"),
+        attempts: attempt,
+      };
+    }
+
+    try {
+      const value = await fn(attempt);
+      return { ok: true, value, attempts: attempt + 1 };
+    } catch (err) {
+      const classification = classifyError(err);
+      lastErr = err instanceof Error ? err : new Error(String(err));
+      lastClass = classification;
+
+      log.warn(
+        { attempt, reason: classification.reason, retryable: classification.retryable, message: classification.message },
+        "Attempt failed",
+      );
+
+      if (!classification.retryable) {
+        log.error({ attempt, reason: classification.reason }, "Non-retryable error — stop");
+        return {
+          ok: false,
+          error: lastErr,
+          classification,
+          attempts: attempt + 1,
+        };
+      }
+
+      if (attempt >= maxRetries) {
+        log.error({ attempts: attempt + 1, maxRetries }, "Max retries exceeded");
+        return {
+          ok: false,
+          error: lastErr,
+          classification,
+          attempts: attempt + 1,
+        };
+      }
+
+      const delayMs = backoffMs(attempt, {
+        base: opts.baseMs,
+        max: opts.maxMs,
+      });
+      opts.onRetry?.({ attempt: attempt + 1, classification, delayMs });
+      log.info({ attempt, delayMs }, "Backing off before retry");
+
+      try {
+        await sleep(delayMs, opts.signal);
+      } catch {
+        return {
+          ok: false,
+          error: new Error("Aborted during backoff"),
+          attempts: attempt + 1,
+        };
+      }
+    }
+  }
+
+  return {
+    ok: false,
+    error: lastErr ?? new Error("Unknown retry failure"),
+    classification: lastClass,
+    attempts: maxRetries + 1,
+  };
+}

tests/migrate.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { readdir, stat } from "node:fs/promises";
+
+/**
+ * Integration-ish test for the migration scanner — we simulate a legacy
+ * hanarang-harness tree and verify the report includes expected entries.
+ *
+ * The CLI is not exercised directly (that would require citty's run()
+ * plus stdout capture); we instead validate the scanning logic by
+ * replicating the minimal scanner here.
+ */
+
+async function scanArchive(root: string): Promise<{
+  agents: string[];
+  scripts: string[];
+  workflows: string[];
+  plansDirs: string[];
+}> {
+  const report = {
+    agents: [] as string[],
+    scripts: [] as string[],
+    workflows: [] as string[],
+    plansDirs: [] as string[],
+  };
+
+  async function walk(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === "node_modules" || e.name === ".git") continue;
+        if (e.name === ".plans") report.plansDirs.push(full);
+        await walk(full);
+      } else {
+        if (dir.includes("/agents") && e.name.endsWith(".md")) {
+          report.agents.push(e.name);
+        }
+        if (dir.endsWith("/scripts") && e.name.endsWith(".sh")) {
+          report.scripts.push(e.name);
+        }
+        if (e.name.endsWith(".lobster")) {
+          report.workflows.push(e.name);
+        }
+      }
+    }
+  }
+
+  await walk(root);
+  return report;
+}
+
+let testDir: string;
+
+beforeEach(async () => {
+  testDir = await mkdtemp(join(tmpdir(), "rails-migrate-test-"));
+});
+
+afterEach(async () => {
+  await rm(testDir, { recursive: true, force: true });
+});
+
+describe("migration scanner", () => {
+  it("discovers agents, scripts, workflows, and .plans/", async () => {
+    // Simulate a legacy harness layout
+    await mkdir(join(testDir, "agents"), { recursive: true });
+    await mkdir(join(testDir, "scripts"), { recursive: true });
+    await mkdir(join(testDir, "workflows"), { recursive: true });
+    await mkdir(join(testDir, ".plans/sprints"), { recursive: true });
+
+    await writeFile(join(testDir, "agents/planner.md"), "# planner");
+    await writeFile(join(testDir, "agents/reviewer.md"), "# reviewer");
+    await writeFile(join(testDir, "scripts/scaffold.sh"), "#!/bin/bash");
+    await writeFile(join(testDir, "scripts/bridge.sh"), "#!/bin/bash");
+    await writeFile(join(testDir, "scripts/install.sh"), "#!/bin/bash");
+    await writeFile(join(testDir, "workflows/plan-sprint.lobster"), "plan");
+    await writeFile(join(testDir, "workflows/review-sprint.lobster"), "review");
+    await writeFile(join(testDir, ".plans/sprints/SPRINT-001.md"), "# s1");
+
+    const report = await scanArchive(testDir);
+
+    expect(report.agents).toContain("planner.md");
+    expect(report.agents).toContain("reviewer.md");
+    expect(report.scripts).toContain("scaffold.sh");
+    expect(report.scripts).toContain("bridge.sh");
+    expect(report.scripts).toContain("install.sh");
+    expect(report.workflows).toContain("plan-sprint.lobster");
+    expect(report.workflows).toContain("review-sprint.lobster");
+    expect(report.plansDirs.length).toBe(1);
+  });
+
+  it("skips node_modules and .git", async () => {
+    await mkdir(join(testDir, "node_modules/pkg"), { recursive: true });
+    await mkdir(join(testDir, ".git"), { recursive: true });
+    await mkdir(join(testDir, "agents"), { recursive: true });
+
+    await writeFile(join(testDir, "node_modules/pkg/index.md"), "ignore");
+    await writeFile(join(testDir, ".git/config"), "ignore");
+    await writeFile(join(testDir, "agents/real.md"), "keep");
+
+    const report = await scanArchive(testDir);
+    expect(report.agents).toEqual(["real.md"]);
+  });
+
+  it("handles empty archive", async () => {
+    const report = await scanArchive(testDir);
+    expect(report.agents).toEqual([]);
+    expect(report.scripts).toEqual([]);
+    expect(report.workflows).toEqual([]);
+    expect(report.plansDirs).toEqual([]);
+  });
+});
+
+describe("scaffold structure", () => {
+  it("creates expected .plans/ subdirectories", async () => {
+    const expected = [
+      ".plans",
+      ".plans/design",
+      ".plans/sprints",
+      ".plans/migration",
+      ".rails/contracts",
+      ".rails/qa-artifacts",
+    ];
+
+    // Manually create to simulate scaffold
+    for (const d of expected) {
+      await mkdir(join(testDir, d), { recursive: true });
+    }
+
+    for (const d of expected) {
+      const s = await stat(join(testDir, d));
+      expect(s.isDirectory()).toBe(true);
+    }
+  });
+});

tests/qa.test.ts

@@ -0,0 +1,322 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { computeVerdict, summarize } from "../src/qa/verdict.js";
+import {
+  loadTemplate,
+  loadTemplateForType,
+  listTemplates,
+  mergeTemplates,
+} from "../src/qa/template.js";
+import { runQaTemplate, saveQaArtifact } from "../src/qa/runtime.js";
+import type { QaTemplate, QaChecklistResult } from "../src/qa/schema.js";
+
+const PROJECT_TEMPLATES = join(process.cwd(), "qa-templates");
+
+let workDir: string;
+
+beforeEach(async () => {
+  workDir = await mkdtemp(join(tmpdir(), "rails-qa-test-"));
+});
+
+afterEach(async () => {
+  await rm(workDir, { recursive: true, force: true });
+});
+
+describe("computeVerdict", () => {
+  const makeCheck = (
+    passed: boolean,
+    severity: QaChecklistResult["severity"],
+  ): QaChecklistResult => ({
+    id: "test",
+    kind: "manual",
+    passed,
+    severity,
+    evidence: "",
+    errorMessage: "",
+    reviewerNote: "",
+    durationMs: 0,
+  });
+
+  it("APPROVE when all checks pass", () => {
+    expect(
+      computeVerdict({
+        checks: [makeCheck(true, "major"), makeCheck(true, "minor")],
+        prerequisitesPassed: true,
+      }),
+    ).toBe("APPROVE");
+  });
+
+  it("REQUEST_CHANGES on any major failure", () => {
+    expect(
+      computeVerdict({
+        checks: [makeCheck(true, "major"), makeCheck(false, "major")],
+        prerequisitesPassed: true,
+      }),
+    ).toBe("REQUEST_CHANGES");
+  });
+
+  it("REQUEST_CHANGES on any critical failure", () => {
+    expect(
+      computeVerdict({
+        checks: [makeCheck(false, "critical")],
+        prerequisitesPassed: true,
+      }),
+    ).toBe("REQUEST_CHANGES");
+  });
+
+  it("APPROVE_WITH_NITS when only minor issues fail", () => {
+    expect(
+      computeVerdict({
+        checks: [makeCheck(true, "major"), makeCheck(false, "minor")],
+        prerequisitesPassed: true,
+      }),
+    ).toBe("APPROVE_WITH_NITS");
+  });
+
+  it("APPROVE_WITH_NITS on recommendation only", () => {
+    expect(
+      computeVerdict({
+        checks: [makeCheck(false, "recommendation")],
+        prerequisitesPassed: true,
+      }),
+    ).toBe("APPROVE_WITH_NITS");
+  });
+
+  it("ABORT on prerequisite failure", () => {
+    expect(
+      computeVerdict({
+        checks: [makeCheck(true, "major")],
+        prerequisitesPassed: false,
+      }),
+    ).toBe("ABORT");
+  });
+
+  it("NEVER REQUEST_CHANGES for minor-only failures (rule)", () => {
+    const v = computeVerdict({
+      checks: [
+        makeCheck(false, "minor"),
+        makeCheck(false, "minor"),
+        makeCheck(false, "recommendation"),
+      ],
+      prerequisitesPassed: true,
+    });
+    expect(v).not.toBe("REQUEST_CHANGES");
+  });
+
+  it("summarize counts blocking failures correctly", () => {
+    const s = summarize([
+      makeCheck(true, "major"),
+      makeCheck(false, "major"),
+      makeCheck(false, "minor"),
+      makeCheck(false, "critical"),
+    ]);
+    expect(s.total).toBe(4);
+    expect(s.passed).toBe(1);
+    expect(s.failed).toBe(3);
+    expect(s.blockingFailed).toBe(2); // major + critical
+  });
+});
+
+describe("template loader", () => {
+  it("lists shipped templates", async () => {
+    const names = await listTemplates(PROJECT_TEMPLATES);
+    expect(names).toContain("scaffold-v1");
+    expect(names).toContain("feature-v1");
+    expect(names).toContain("bugfix-v1");
+    expect(names).toContain("migration-v1");
+    expect(names).toContain("refactor-v1");
+    expect(names).toContain("infra-v1");
+  });
+
+  it("loads scaffold-v1 template", async () => {
+    const t = await loadTemplate("scaffold-v1", PROJECT_TEMPLATES);
+    expect(t.template).toBe("scaffold-v1");
+    expect(t.appliesTo).toContain("scaffold");
+    expect(t.requiredChecks.length).toBeGreaterThan(0);
+  });
+
+  it("loadTemplateForType maps type → template", async () => {
+    const t = await loadTemplateForType("feature", PROJECT_TEMPLATES);
+    expect(t.template).toBe("feature-v1");
+  });
+
+  it("throws on unknown template", async () => {
+    await expect(
+      loadTemplate("nonexistent", PROJECT_TEMPLATES),
+    ).rejects.toThrow(/not found/);
+  });
+
+  it("merges templates", async () => {
+    const base: QaTemplate = {
+      template: "base-v1",
+      version: "v1",
+      appliesTo: ["feature"],
+      requiredChecks: [
+        {
+          id: "c1",
+          description: "",
+          kind: "file_exists",
+          spec: { path: "a" },
+          blocking: true,
+          severity: "major",
+        },
+      ],
+      additionalChecks: [],
+    };
+    const extra: QaTemplate = {
+      template: "extra-v1",
+      version: "v1",
+      appliesTo: [],
+      requiredChecks: [
+        {
+          id: "c2",
+          description: "",
+          kind: "file_exists",
+          spec: { path: "b" },
+          blocking: true,
+          severity: "major",
+        },
+      ],
+      additionalChecks: [],
+    };
+    const merged = mergeTemplates(base, extra);
+    expect(merged.requiredChecks).toHaveLength(2);
+    expect(merged.template).toBe("base-v1+extra-v1");
+  });
+});
+
+describe("runtime", () => {
+  it("passes a file_exists check when file present", async () => {
+    await writeFile(join(workDir, "README.md"), "# test");
+    const template: QaTemplate = {
+      template: "test-v1",
+      version: "v1",
+      appliesTo: ["scaffold"],
+      requiredChecks: [
+        {
+          id: "readme",
+          description: "",
+          kind: "file_exists",
+          spec: { path: "README.md" },
+          blocking: true,
+          severity: "major",
+        },
+      ],
+      additionalChecks: [],
+    };
+    const artifact = await runQaTemplate({
+      template,
+      workdir: workDir,
+      sprintId: "S1",
+    });
+    expect(artifact.verdict).toBe("APPROVE");
+    expect(artifact.summary.passed).toBe(1);
+  });
+
+  it("fails on missing file", async () => {
+    const template: QaTemplate = {
+      template: "test-v1",
+      version: "v1",
+      appliesTo: ["scaffold"],
+      requiredChecks: [
+        {
+          id: "missing",
+          description: "",
+          kind: "file_exists",
+          spec: { path: "never.txt" },
+          blocking: true,
+          severity: "major",
+        },
+      ],
+      additionalChecks: [],
+    };
+    const artifact = await runQaTemplate({
+      template,
+      workdir: workDir,
+      sprintId: "S1",
+    });
+    expect(artifact.verdict).toBe("REQUEST_CHANGES");
+    expect(artifact.summary.blockingFailed).toBe(1);
+  });
+
+  it("manual checks are SKIPPED by default (no resolver)", async () => {
+    const template: QaTemplate = {
+      template: "test-v1",
+      version: "v1",
+      appliesTo: ["feature"],
+      requiredChecks: [
+        {
+          id: "review",
+          description: "",
+          kind: "manual",
+          spec: { question: "Is it good?" },
+          blocking: true,
+          severity: "major",
+        },
+      ],
+      additionalChecks: [],
+    };
+    const artifact = await runQaTemplate({
+      template,
+      workdir: workDir,
+      sprintId: "S1",
+    });
+    expect(artifact.verdict).toBe("APPROVE");
+    expect(artifact.checks[0]!.evidence).toContain("SKIPPED");
+  });
+
+  it("manual checks use resolver when provided", async () => {
+    const template: QaTemplate = {
+      template: "test-v1",
+      version: "v1",
+      appliesTo: ["feature"],
+      requiredChecks: [
+        {
+          id: "review",
+          description: "",
+          kind: "manual",
+          spec: { question: "Is it clean?" },
+          blocking: true,
+          severity: "major",
+        },
+      ],
+      additionalChecks: [],
+    };
+    const artifact = await runQaTemplate({
+      template,
+      workdir: workDir,
+      sprintId: "S1",
+      manualResolver: async () => ({ passed: false, note: "found a TODO" }),
+    });
+    expect(artifact.verdict).toBe("REQUEST_CHANGES");
+    expect(artifact.checks[0]!.errorMessage).toBe("found a TODO");
+  });
+
+  it("saves artifact to disk", async () => {
+    const template: QaTemplate = {
+      template: "test-v1",
+      version: "v1",
+      appliesTo: ["feature"],
+      requiredChecks: [],
+      additionalChecks: [],
+    };
+    const artifact = await runQaTemplate({
+      template,
+      workdir: workDir,
+      sprintId: "S1",
+    });
+    const path = await saveQaArtifact(workDir, artifact);
+    expect(path).toContain(artifact.artifactId);
+  });
+});
+
+describe("scaffold-v1 on real project", () => {
+  it("loads without error and has expected checks", async () => {
+    const t = await loadTemplate("scaffold-v1", PROJECT_TEMPLATES);
+    const ids = t.requiredChecks.map((c) => c.id);
+    expect(ids).toContain("readme-exists");
+    expect(ids).toContain("tsconfig-strict");
+  });
+});

tests/resilience.test.ts

@@ -0,0 +1,223 @@
+import { describe, it, expect } from "vitest";
+import { backoffMs, sleep } from "../src/resilience/backoff.js";
+import {
+  classifyError,
+  assertAllowedThinkingTier,
+  TimeoutError,
+  NetworkError,
+  RateLimitError,
+  PermissionError,
+  ConfigError,
+} from "../src/resilience/classifier.js";
+import { withRetry } from "../src/resilience/retry.js";
+import { ZodError, z } from "zod";
+
+describe("backoffMs", () => {
+  it("starts near base for retry 0", () => {
+    const ms = backoffMs(0, { base: 1000, max: 30_000, jitter: 0 });
+    expect(ms).toBe(1000);
+  });
+
+  it("doubles each retry", () => {
+    expect(backoffMs(1, { base: 1000, max: 30_000, jitter: 0 })).toBe(2000);
+    expect(backoffMs(2, { base: 1000, max: 30_000, jitter: 0 })).toBe(4000);
+    expect(backoffMs(3, { base: 1000, max: 30_000, jitter: 0 })).toBe(8000);
+  });
+
+  it("caps at max", () => {
+    expect(backoffMs(10, { base: 1000, max: 30_000, jitter: 0 })).toBe(30_000);
+    expect(backoffMs(20, { base: 1000, max: 30_000, jitter: 0 })).toBe(30_000);
+  });
+
+  it("adds jitter within bounds", () => {
+    // With jitter 0.3, retry 0 should be in [700, 1300]
+    for (let i = 0; i < 50; i++) {
+      const ms = backoffMs(0, { base: 1000, max: 30_000, jitter: 0.3 });
+      expect(ms).toBeGreaterThanOrEqual(700);
+      expect(ms).toBeLessThanOrEqual(1300);
+    }
+  });
+
+  it("returns non-negative values", () => {
+    for (let i = 0; i < 20; i++) {
+      expect(backoffMs(i)).toBeGreaterThanOrEqual(0);
+    }
+  });
+});
+
+describe("sleep", () => {
+  it("waits approximately the specified time", async () => {
+    const start = Date.now();
+    await sleep(50);
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBeGreaterThanOrEqual(40);
+    expect(elapsed).toBeLessThan(200);
+  });
+
+  it("aborts when signal fires", async () => {
+    const controller = new AbortController();
+    const promise = sleep(5000, controller.signal);
+    setTimeout(() => controller.abort(), 10);
+    await expect(promise).rejects.toThrow("Aborted");
+  });
+});
+
+describe("classifyError", () => {
+  it("TimeoutError → retryable timeout", () => {
+    const r = classifyError(new TimeoutError("timed out"));
+    expect(r.retryable).toBe(true);
+    expect(r.reason).toBe("timeout");
+  });
+
+  it("NetworkError → retryable network", () => {
+    const r = classifyError(new NetworkError("econnrefused"));
+    expect(r.retryable).toBe(true);
+    expect(r.reason).toBe("network");
+  });
+
+  it("RateLimitError → retryable rate_limit", () => {
+    const r = classifyError(new RateLimitError("429 too many"));
+    expect(r.retryable).toBe(true);
+    expect(r.reason).toBe("rate_limit");
+  });
+
+  it("PermissionError → non-retryable permission", () => {
+    const r = classifyError(new PermissionError("EACCES"));
+    expect(r.retryable).toBe(false);
+    expect(r.reason).toBe("permission");
+  });
+
+  it("ConfigError → non-retryable config", () => {
+    const r = classifyError(new ConfigError("bad config"));
+    expect(r.retryable).toBe(false);
+    expect(r.reason).toBe("config");
+  });
+
+  it("ZodError → non-retryable invariant", () => {
+    const schema = z.object({ x: z.number() });
+    let zodErr: unknown;
+    try {
+      schema.parse({ x: "not a number" });
+    } catch (e) {
+      zodErr = e;
+    }
+    expect(zodErr).toBeInstanceOf(ZodError);
+    const r = classifyError(zodErr);
+    expect(r.retryable).toBe(false);
+    expect(r.reason).toBe("invariant");
+  });
+
+  it("detects timeout by message heuristic", () => {
+    const r = classifyError(new Error("ETIMEDOUT on request"));
+    expect(r.retryable).toBe(true);
+    expect(r.reason).toBe("timeout");
+  });
+
+  it("detects network error by message", () => {
+    const r = classifyError(new Error("ECONNREFUSED"));
+    expect(r.retryable).toBe(true);
+    expect(r.reason).toBe("network");
+  });
+
+  it("detects rate limit by message", () => {
+    const r = classifyError(new Error("429 Rate limit exceeded"));
+    expect(r.retryable).toBe(true);
+    expect(r.reason).toBe("rate_limit");
+  });
+
+  it("unknown error defaults to retryable transient", () => {
+    const r = classifyError(new Error("something weird"));
+    expect(r.retryable).toBe(true);
+    expect(r.reason).toBe("transient");
+  });
+});
+
+describe("assertAllowedThinkingTier", () => {
+  it("allows high and below", () => {
+    expect(() => assertAllowedThinkingTier("high")).not.toThrow();
+    expect(() => assertAllowedThinkingTier("medium")).not.toThrow();
+    expect(() => assertAllowedThinkingTier("low")).not.toThrow();
+  });
+
+  it("allows undefined", () => {
+    expect(() => assertAllowedThinkingTier(undefined)).not.toThrow();
+  });
+
+  it("forbids xhigh", () => {
+    expect(() => assertAllowedThinkingTier("xhigh")).toThrow(/forbidden/);
+    expect(() => assertAllowedThinkingTier("XHIGH")).toThrow(/forbidden/);
+  });
+});
+
+describe("withRetry", () => {
+  it("succeeds on first attempt", async () => {
+    let attempts = 0;
+    const result = await withRetry(async () => {
+      attempts += 1;
+      return "ok";
+    });
+    expect(result.ok).toBe(true);
+    expect(result.value).toBe("ok");
+    expect(result.attempts).toBe(1);
+    expect(attempts).toBe(1);
+  });
+
+  it("retries retryable errors and eventually succeeds", async () => {
+    let attempts = 0;
+    const result = await withRetry(
+      async () => {
+        attempts += 1;
+        if (attempts < 3) throw new TimeoutError("not yet");
+        return "finally";
+      },
+      { maxRetries: 3, baseMs: 1, maxMs: 10 },
+    );
+    expect(result.ok).toBe(true);
+    expect(result.value).toBe("finally");
+    expect(result.attempts).toBe(3);
+  });
+
+  it("stops on non-retryable error", async () => {
+    let attempts = 0;
+    const result = await withRetry(
+      async () => {
+        attempts += 1;
+        throw new PermissionError("no");
+      },
+      { maxRetries: 3, baseMs: 1 },
+    );
+    expect(result.ok).toBe(false);
+    expect(result.classification?.retryable).toBe(false);
+    expect(attempts).toBe(1);
+  });
+
+  it("gives up after max retries", async () => {
+    let attempts = 0;
+    const result = await withRetry(
+      async () => {
+        attempts += 1;
+        throw new TimeoutError("never succeeds");
+      },
+      { maxRetries: 2, baseMs: 1, maxMs: 10 },
+    );
+    expect(result.ok).toBe(false);
+    expect(result.attempts).toBe(3); // initial + 2 retries
+    expect(attempts).toBe(3);
+  });
+
+  it("aborts when signal fires mid-backoff", async () => {
+    const controller = new AbortController();
+    let attempts = 0;
+    const promise = withRetry(
+      async () => {
+        attempts += 1;
+        throw new TimeoutError("slow");
+      },
+      { maxRetries: 5, baseMs: 1000, maxMs: 5000, signal: controller.signal },
+    );
+    setTimeout(() => controller.abort(), 50);
+    const result = await promise;
+    expect(result.ok).toBe(false);
+    expect(result.error?.message).toContain("Aborted");
+  });
+});