sandcastle-drain 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Downeys
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# sandcastle-drain
+
+A wrapper around [`@ai-hero/sandcastle`](https://github.com/mattpocock/sandcastle) that drains a queue of GitHub issues labeled `sandcastle`, runs Claude Code against each in an isolated Docker worktree, and posts results back to the issue. Ships an opinionated set of engineering principles and a reviewer rubric that enforces them.
+
+## Prerequisites
+
+The wrapper relies on the host machine to supply these. None of them are installed for you.
+
+- **Docker installed and running.** The agent runs inside the container declared in `docker/Dockerfile` (Node 22 + git + gh + Claude Code CLI + Playwright + Chromium).
+- **Node.js 20+** on the host (the wrapper itself is a Node CLI).
+- **`gh` CLI installed and `gh auth login` complete.** The wrapper shells out to `gh issue list / edit / comment / create` and `gh pr create / merge`.
+- **Claude Code CLI installed locally**, with OAuth credentials persisted to `~/.config/sandcastle-claude-creds/`. The wrapper bind-mounts that directory into every sandbox so the agent reuses your Pro/Max subscription. Bootstrap once with:
+  ```sh
+  mkdir -p ~/.config/sandcastle-claude-creds
+  docker run -it --rm \
+    --entrypoint claude \
+    -v ~/.config/sandcastle-claude-creds:/home/agent/.claude \
+    sandcastle:<your-image-name> \
+    login
+  ```
+  `--entrypoint claude` overrides the base image's `sleep infinity` so the device-code flow runs. Re-run if a drain reports auth errors mid-flight.
+- **Matt Pocock's `tdd` and `diagnose` skills** installed at `<host>/.claude/skills/{tdd,diagnose}/` via:
+  ```sh
+  npx skills@latest add mattpocock/skills/tdd mattpocock/skills/diagnose
+  ```
+  The wrapper probes for these at startup and refuses to drain without them.
+- **A GitHub repo with the canonical labels.** The wrapper auto-creates any missing labels (`sandcastle`, `in-progress`, `needs-review`, `blocked`, `retry`, `priority`, `oversized`, `skipped-this-run`, `needs-info`) on first run.
+
+## Install
+
+```sh
+npm install --save-dev sandcastle-drain
+```
+
+The package exposes a single binary, `sandcastle-drain`. Invoke it via `npx`:
+
+```sh
+npx sandcastle-drain <subcommand>
+```
+
+## Usage
+
+| Command                 | What it does                                                                                            |
+| ----------------------- | ------------------------------------------------------------------------------------------------------- |
+| `npx sandcastle-drain drain`  | Process every open issue labeled `sandcastle`. One agent run per issue, on a branch `agent/issue-N`.    |
+| `npx sandcastle-drain ship N` | Push `agent/issue-N`, open a PR with `Closes #N`, squash-merge it, and delete the remote branch.       |
+| `npx sandcastle-drain sweep N`| Post-merge cleanup: pull main, remove the worktree directory, prune git's worktree metadata, delete the local branch. Refuses to run unless a MERGED PR exists for the branch. |
+
+All paths resolve relative to the host working directory where you ran `npx sandcastle-drain`. The wrapper writes runtime artifacts to `<host-cwd>/.sandcastle-drain/` (logs, worktrees, staged content, optional `splits.json`).
+
+## What the wrapper enforces
+
+Two layers run on every implementer commit: a fixed set of **development principles** the implementer must follow, and a four-category **reviewer rubric** that audits the diff after the commits land.
+
+The principle files ship inside the package at `dist/content/principles/` and are staged into `<host-cwd>/.sandcastle-drain/staged/principles/` before each drain so the agent can read them from inside the sandbox. Twelve files cover language and types, architecture (onion layers), CQRS, frontend organization, domain modeling, testing, linting and tooling, clean code, personal-use trade-offs, context-budget discipline (100k target / 150k ceiling), Claude Code interactive-vs-autonomous mode deltas, and a README that indexes the rest. Both the implementer and the reviewer eager-load the relevant files.
+
+The reviewer rubric is four categories. **Domain integrity** flags anemic-model violations and any aggregate-specific invariants the host has written into `CONTEXT.md` or an ADR. **Test discipline** enforces the behavior-required test rule (every commit that introduces testable behavior ships with tests), property-based testing on state machines, and integration tests that hit real infrastructure rather than mocks. **Architecture intent** rejects inheritance of domain classes, impurity in the domain layer, and cross-layer imports that violate the onion direction. **Glossary & ADR alignment** checks that new names match `CONTEXT.md` verbatim and that diffs don't contradict any ADR under `docs/adr/`.
+
+## Reviewer-gating behavior
+
+The reviewer is **gating in the success path** and emits findings advisorily on the rejection path — it is not "advisory only." `handleRejection` in `dist/orchestrator/main.ts` is the load-bearing function; the flow is:
+
+1. After the implementer commits and the CI gate passes, the reviewer sub-agent runs read-only against the worktree and emits a JSON verdict (`PASS` or `FAIL`) with a structured findings array.
+2. **`PASS` + CI green** → the wrapper auto-ships and sweeps: push, open a PR with `Closes #N`, squash-merge, delete the remote branch. The issue auto-closes via the squash-merge body.
+3. **`FAIL`** → `handleRejection` tags the branch tip as `rejected/issue-N-attempt-K` (preserving the work), discards the local branch, files a new GitHub issue titled `[follow-up #N] <original title>` labeled `sandcastle` + `priority` whose body carries the reviewer findings + the list of changed files + commit titles, comments on the original linking the follow-up, and closes the original. The next drain cycle picks up the `priority`-labeled follow-up first, combined with auto-ship this prevents the rejected branch from merging until a follow-up passes.
+4. **Reviewer parse error or throw** → the wrapper posts an error comment on the issue, labels it `needs-review`, and leaves the branch in place for the human to inspect.
+
+So `PASS` is required for auto-merge, and `FAIL` actively gates the merge by closing the original issue out and queueing a follow-up. The reviewer's findings remain advisory only in the sense that the wrapper does not modify the rejected diff for you — the next implementer run on the follow-up is what addresses them.
+
+## Optional host content
+
+Two host artifacts deepen the reviewer rubric. Both are optional; the wrapper degrades gracefully when they're absent.
+
+- **`CONTEXT.md`** is the canonical domain glossary. If populated, the reviewer enforces nomenclature binding — every new type / table / file path / UI label in a diff must use the exact names defined in `CONTEXT.md`. If `CONTEXT.md` is still the empty stub, the nomenclature check is silently dropped (per the conditional rubric).
+- **`docs/adr/`** holds architectural decision records. If populated, the reviewer reads the ADR index and flags any diff that contradicts a written decision. If the directory is empty, the ADR-alignment check is silently dropped.
+
+Both files / directories live in the **host project's** working directory, not inside the installed library. The reviewer prompt template eager-loads them from the worktree at review time.
+
+## Configuration knobs that exist today
+
+None, intentionally. The wrapper is opinionated:
+
+- Model is pinned to `claude-opus-4-7`.
+- Label set is fixed (`sandcastle`, `in-progress`, `needs-review`, `blocked`, `retry`, `priority`, `oversized`, `skipped-this-run`, `needs-info`).
+- Paths are fixed (`<host-cwd>/.sandcastle-drain/staged/`, `<host-cwd>/.sandcastle-drain/worktrees/`, `<host-cwd>/.sandcastle-drain/logs/`).
+- Idle timeout: 10 minutes per run. Wall-clock cap: 90 minutes per run. One auto-retry on idle / wall-clock timeout.
+- Reviewer budget: 5 minute idle, 30 minute wall-clock.
+
+If you need different values, fork the wrapper or open an issue. Future versions may expose a `sandcastle.config.ts` if users need it; today there is no escape hatch beyond editing source.
+
+## Versioning discipline
+
+This package follows semver with two specific contracts:
+
+- **Principle file changes are minor.** Renaming a rule, adding a new principle file, tightening guidance — the host's `^x.y.z` range picks them up automatically and the next drain enforces them.
+- **Reviewer rubric changes and reviewer JSON output schema changes are major.** Hosts may parse the verdict comment, and the set of review outcomes hosts see is part of the public contract. A new severity level, a renamed category, or a changed field shape bumps the major version. Pin the major version (`~x.y.z` or `x.y.x`) if you depend on a specific rubric shape.
+
+Other public-API changes (CLI subcommand names, the staged-content layout under `dist/content/`, the orchestrator's exit codes) also bump major.
+
+## Limitations
+
+- **Windows worktree teardown.** pnpm's `node_modules/.pnpm/` symlink farm defeats standard recursive deletion on Windows; `git worktree remove` surfaces `Function not implemented`. The wrapper ships `removeWorktreeDir` in `dist/orchestrator/worktree-cleanup.ts` (uses `robocopy /MIR` against an empty source) and runs it before every drain to clean up orphans. Sandcastle's own internal teardown still throws on Windows after a successful agent run — the wrapper recovers commits via `tryRecoverCommits` and labels the run `ok (windows-teardown)`. This is the documented success path on Windows, not a failure mode.
+- **No CI / GitHub Actions variant in v1.** The wrapper runs locally only. Authentication uses your volume-mounted Pro/Max OAuth credentials, which Sandcastle upstream does not first-class — don't deploy this to a cloud VM. See [issue #191 on mattpocock/sandcastle](https://github.com/mattpocock/sandcastle/issues/191) for upstream context.
+- **Sandcastle is pinned to an exact version** in this package's dependencies. Treat upstream upgrades as breaking until you've re-tested the auth path and the worktree lifecycle.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * `sandcastle-drain` CLI — the single entry point users invoke via `npx sandcastle-drain
+ * <subcommand>`. Three subcommands route to the existing orchestrators:
+ *
+ *   sandcastle-drain drain          — drain the GitHub issue queue
+ *   sandcastle-drain ship <issue>   — push, PR, squash-merge an `agent/issue-N` branch
+ *   sandcastle-drain sweep <issue>  — post-merge worktree/branch cleanup
+ *
+ * Startup probes (`probeSkills`, `probeAuth`, `probeGhAuth`, `probeLabels`) run
+ * once up-front regardless of subcommand so the user gets an actionable error
+ * before any work begins. Paths inside the orchestrators resolve relative to
+ * `process.cwd()` — the host project where `npx sandcastle-drain` was invoked — not
+ * the installed library's directory.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runDrain } from './orchestrator/main.js';
+import { runAllPrereqs } from './orchestrator/prereqs.js';
+import { ShipError, shipBranch } from './orchestrator/ship.js';
+import { SweepError, sweepBranch } from './orchestrator/sweep.js';
+import { stage } from './stage.js';
+const HELP_TEXT = `Usage: sandcastle-drain <command> [args]
+
+Commands:
+  drain               Drain the queue of \`sandcastle\`-labeled GitHub issues
+  ship <issue>        Push, open a PR, and squash-merge \`agent/issue-<N>\`
+  sweep <issue>       Post-merge cleanup: remove worktree, delete local branch
+
+Options:
+  -h, --help          Show this help message
+
+All paths resolve relative to the current working directory.`;
+function printHelp() {
+    console.log(HELP_TEXT);
+}
+function fail(msg, opts = {}) {
+    console.error(msg);
+    if (opts.showHelp) {
+        console.error('');
+        console.error(HELP_TEXT);
+    }
+    process.exit(1);
+}
+function parseIssueArg(subcommand, arg) {
+    if (!arg || !/^\d+$/.test(arg)) {
+        fail(`Usage: sandcastle-drain ${subcommand} <issue-number>  (e.g. \`sandcastle-drain ${subcommand} 3\`)`);
+    }
+    return Number(arg);
+}
+function reportUnexpectedError(when, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const stack = err instanceof Error && err.stack ? err.stack : String(err);
+    const logPath = join(process.cwd(), '.sandcastle-drain', 'logs', 'sandcastle-startup.log');
+    let logRef = logPath;
+    try {
+        mkdirSync(join(process.cwd(), '.sandcastle-drain', 'logs'), { recursive: true });
+        writeFileSync(logPath, `${new Date().toISOString()}\n${stack}\n`);
+    }
+    catch {
+        logRef = '(could not write log file)';
+    }
+    console.error(`sandcastle-drain: unexpected error ${when}: ${message}`);
+    console.error(`See ${logRef} for details.`);
+    process.exit(1);
+}
+async function main() {
+    const [, , subcommand, ...rest] = process.argv;
+    if (!subcommand || subcommand === '-h' || subcommand === '--help') {
+        printHelp();
+        return;
+    }
+    // Validate args before running prereqs so usage errors don't depend on
+    // `gh` being authed — a missing issue number should fail fast with help text.
+    let issue;
+    switch (subcommand) {
+        case 'drain':
+            break;
+        case 'ship':
+        case 'sweep':
+            issue = parseIssueArg(subcommand, rest[0]);
+            break;
+        default:
+            fail(`Unknown command: ${subcommand}`, { showHelp: true });
+    }
+    // Prereqs run once before any subcommand. The probes are cheap (a few exec
+    // calls + a single `gh label list`), and surfacing a missing skill or
+    // expired token up-front beats failing mid-drain. Wrap in a try/catch so an
+    // unexpected throw (e.g. `gh` returning unparseable JSON, an EACCES on the
+    // skills check) becomes a clean one-liner with a log file pointer instead
+    // of a raw stack trace.
+    let token;
+    try {
+        ({ token } = await runAllPrereqs());
+    }
+    catch (err) {
+        reportUnexpectedError('during startup', err);
+    }
+    switch (subcommand) {
+        case 'drain':
+            // Stage library content (principles, agent-docs) into
+            // <host-cwd>/.sandcastle-drain/staged/ before the drain begins, so the
+            // per-issue worktrees can copy it in via `copyToWorktree`. Prompts are
+            // rendered in memory by `src/render-prompt.ts` and never materialize on
+            // the host filesystem.
+            await stage(process.cwd());
+            await runDrain({ token });
+            return;
+        case 'ship':
+            try {
+                await shipBranch({ issue: issue });
+            }
+            catch (err) {
+                if (err instanceof ShipError)
+                    fail(`[ship] ${err.message}`);
+                throw err;
+            }
+            return;
+        case 'sweep':
+            try {
+                await sweepBranch({ issue: issue });
+            }
+            catch (err) {
+                if (err instanceof SweepError)
+                    fail(`[sweep] ${err.message}`);
+                throw err;
+            }
+            return;
+    }
+}
+try {
+    await main();
+}
+catch (err) {
+    // Catches anything that escaped the subcommand handlers (the prereq path
+    // has its own wrapper that adds "during startup" context).
+    reportUnexpectedError('after startup', err);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/content/agent-docs/issue-tracker.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations. `gh` infers the repo from `git remote -v` — verify that `origin` points at the right GitHub repository before running `gh` commands.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

package/dist/content/agent-docs/sandcastle-windows-cleanup.md

@@ -0,0 +1,45 @@
+# Sandcastle on Windows: worktree teardown is the success path
+
+## Behavior
+
+On Windows, `sandcastle.run()` throws `error: failed to delete '.sandcastle-drain/worktrees/agent-issue-N': Function not implemented` _after_ the agent has committed. This is the **expected** exit path for any drain that runs `pnpm install`, not a failure mode. The wrapper:
+
+1. Catches the throw, recording `runError`. `result` is undefined.
+2. Reads `git log main..agent/issue-N` (via [`src/orchestrator/teardown.ts`](../../orchestrator/teardown.ts)) to recover the commit list directly from the branch.
+3. Labels the run `ok (windows-teardown)` in [`src/orchestrator/status.ts`](../../orchestrator/status.ts) — a success-tier status that sits alongside `completed` and `partial-work` under needs-review.
+
+The teardown throw and the wrapper's post-hoc recovery are now considered routine Windows behavior. The status name makes it visible in the per-run GitHub comment so reviewers know what happened, without implying anything went wrong.
+
+## Cause
+
+pnpm's `node_modules/.pnpm/` symlink farm defeats Windows recursive deletion (Node's `fs.rm`, `Remove-Item`, `rmdir /s`, and git's own worktree teardown — git surfaces `Function not implemented` from the kernel). Sandcastle's internal `WorktreeManager.remove` runs in the success path and trips this.
+
+The wrapper's own `removeWorktreeDir` mitigation (`robocopy /MIR` in [`src/orchestrator/worktree-cleanup.ts`](../../orchestrator/worktree-cleanup.ts)) handles the same root cause for the _next-run_ orphan cleanup — but it cannot run inside sandcastle's lifecycle, because sandcastle owns its own worktree teardown.
+
+## What we tried (for context)
+
+Probed sandcastle 0.5.7's public API for a way to disable internal worktree cleanup so the wrapper could own it:
+
+- `RunOptions` in `node_modules/@ai-hero/sandcastle/dist/run.d.ts` — no `cleanupWorktree`, `keepWorktree`, or equivalent flag.
+- `SandboxHooks` in `dist/SandboxLifecycle.d.ts` — only `onWorktreeReady` / `onSandboxReady` setup hooks; no teardown hook.
+- `WorktreeManager.remove` exists in `dist/WorktreeManager.d.ts` but is internal — not callable from the wrapper without forking.
+- One escape hatch: `RunOptions.signal` docs say "The worktree is preserved on disk after abort (error-path behavior)." Aborting works, but defeats the purpose — we want a normal completion that doesn't tear down.
+
+## Decision
+
+We accept the throw-then-read flow as the durable Windows path until sandcastle exposes a cleanup-ownership hook. It is the success path, not an error path. The pre-run cleanup at `processIssue` step (b.5) calls `removeWorktreeDir` against any orphaned dir from a prior drain so the symlink farm doesn't accumulate.
+
+## When to revisit
+
+When sandcastle ships a release that:
+
+- Adds a `cleanupWorktree: false` (or similarly-named) option to `RunOptions`, **or**
+- Adds a `beforeWorktreeRemove` / `onTeardown` hook to `SandboxHooks`, **or**
+- Switches its own teardown to use long-path-aware Win32 APIs (e.g. invokes our same `robocopy /MIR` trick or `RemoveDirectoryW` with `FILE_FLAG_BACKUP_SEMANTICS`).
+
+At that point, take ownership of cleanup in the wrapper and remove the `ok (windows-teardown)` status — runs will exit cleanly as `completed`.
+
+## Do not
+
+- Fork sandcastle to add the option (per memory `sandcastle_api_drift_v0_5_7.md`).
+- Pre-empt sandcastle's cleanup by deleting `node_modules/.pnpm/` ourselves before `run()` returns — that races sandcastle's lifecycle and corrupts the agent's workspace.

package/dist/content/agent-docs/triage-labels.md

@@ -0,0 +1,101 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker, plus the workflow labels the sandcastle-drain wrapper auto-manages.
+
+## Triage state labels
+
+Used by the `triage` skill's state machine.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                 |
+| -------------------------- | -------------------- | --------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue |
+| `needs-info`               | `needs-info`         | Waiting for more information (see note) |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation           |
+| `wontfix`                  | `wontfix`            | Will not be actioned                    |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+> **Note on `needs-info`:** the sandcastle-drain wrapper at `src/orchestrator/main.ts` also writes this label automatically whenever a run produces 0 commits — bail-out, timeout, or hard error. See the workflow section below. Same label, two writers (you, manually, and the wrapper).
+
+## sandcastle-drain workflow labels
+
+Eight labels that exist only for the sandcastle-drain wrapper at `src/orchestrator/main.ts`. `sandcastle`, `blocked`, and `retry` are user-applied; `in-progress`, `needs-review`, `priority`, `oversized`, and `skipped-this-run` are wrapper-managed — don't touch them by hand unless you're recovering from a crashed run.
+
+| Label          | Applied when                                                                                                                                                                                                                      | Removed when                                                                                                        |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `sandcastle`   | Issue is queued for the agent. Apply manually.                                                                                                                                                                                    | Wrapper transitions the issue to `needs-review` or `needs-info`.                                                    |
+| `in-progress`  | Wrapper picks up the issue at the start of a run.                                                                                                                                                                                 | Wrapper finishes the run (any outcome).                                                                             |
+| `needs-review` | Wrapper finishes a run that produced commits — success OR partial work after timeout/abort, both go here.                                                                                                                         | Manually, after review.                                                                                             |
+| `blocked`      | Skip this issue. Apply manually when blocked.                                                                                                                                                                                     | Manually, once unblocked.                                                                                           |
+| `retry`        | You apply alongside `sandcastle` to discard a prior agent attempt and re-run.                                                                                                                                                     | Wrapper removes it as part of the retry handling on the next drain.                                                 |
+| `priority`     | Wrapper applies to a rejection-loop follow-up issue (alongside `sandcastle`). The drain serves `priority`-labeled issues before unflagged ones, then by issue number. May also be applied manually to jump-the-queue urgent work. | Manually, after the issue is resolved or no longer urgent.                                                          |
+| `oversized`    | Wrapper applies to a parent issue when its implementer wrote `.sandcastle-drain/splits.json` during the run and the wrapper filed the listed follow-ups. Audit trail signal — see the **split protocol** section below.                 | Manually, when the follow-ups have all landed and the parent can be closed (or kept open as a tracker — your call). |
+| `skipped-this-run` | Wrapper applies when a drain bypassed the issue without running the agent — blocked-by-failed-sibling, an existing `agent/issue-N` branch already in place, or the rate-limit tail of a curtailed drain. The accompanying comment names the reason. | Wrapper removes it at the start of the next outcome block so a successful run never carries a stale breadcrumb.       |
+
+The wrapper also writes the triage-state `needs-info` label as one of the run outcomes — see the state machine below.
+
+The wrapper drains in this order: `priority`-labeled `sandcastle` issues first (oldest by issue number), then unflagged `sandcastle` issues (oldest by issue number). Issues with `in-progress` or `blocked` are skipped at queue-fetch time.
+
+## Outcome state machine
+
+After every `sandcastle.run()`, the wrapper:
+
+1. Posts a status comment on the issue containing the run's status string, branch name, commit count + SHAs, last ~50 lines of agent stdout in a `<details>` block, and the host-side log file path. This is best-effort; if `gh` fails, the run still proceeds.
+2. Runs the CI gate, then the advisory reviewer sub-agent. Both produce comments on the issue.
+3. Applies labels:
+
+   | Run outcome                                                        | Label change                                                                                                                                                                                                                                    |
+   | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | Commits + CI green + reviewer `PASS` → wrapper auto-ships + sweeps | remove `in-progress` + `sandcastle` (issue auto-closed by squash-merge `Closes #N`)                                                                                                                                                             |
+   | Commits + reviewer `FAIL` → rejection loop                         | remove `in-progress` + `sandcastle`; tag `rejected/issue-N-attempt-K`; discard branch; open a follow-up issue with `sandcastle` + `priority`; comment on the original. The original gets no new label — the follow-up carries the work forward. |
+   | Commits + CI green + reviewer parse error / throw                  | remove `in-progress` + `sandcastle`, add `needs-review` (branch and worktree remain)                                                                                                                                                            |
+   | Commits + CI red                                                   | remove `in-progress` + `sandcastle`, add `needs-info`                                                                                                                                                                                           |
+   | No commits (bail-out, timeout, hard error — any 0-commit outcome)  | remove `in-progress` + `sandcastle`, add `needs-info`                                                                                                                                                                                           |
+
+   The wrapper never leaves `sandcastle` on the issue after a run — silent re-queue is a footgun. To re-run, you re-apply `sandcastle` (with `retry` to discard the prior branch) explicitly.
+
+   **Auto-merge fallback.** If `npm run ship <N>` itself errors out (merge conflict, missing main protection, gh auth lapse), the wrapper logs the failure and falls back to the `needs-review` path so the slice is recoverable by hand. If ship succeeded but sweep failed, the merge is on main and the issue auto-closed — only the local worktree / branch leaks, and `npm run sweep <N>` cleans them up.
+
+4. Defensive check: verifies the agent didn't push the branch (`git rev-parse --verify origin/agent/issue-<N>` should fail). If it succeeded, flags a warning in the status comment but doesn't fail the run. The auto-merge path at step 3 pushes from the wrapper, not the agent — `gh pr merge` runs _after_ `git push -u origin <branch>` and is unrelated to this defensive check.
+
+## The reviewer-rejection flow
+
+When the reviewer returns `FAIL` on commits, the wrapper closes out the run automatically rather than parking the issue for human review:
+
+1. Tags the branch tip as `rejected/issue-N-attempt-K`. `K` increments per rejection on the same issue — `git tag --list 'rejected/issue-N-attempt-*'` counts the prior attempts.
+2. Discards the local branch (`git branch -D agent/issue-N`).
+3. Files a new issue titled `[follow-up #N] <original title>` with labels `sandcastle` + `priority`. The body links back to the original, includes the reviewer's findings as a checklist, lists the files and commit titles from the prior attempt, and points at the `rejected/issue-N-attempt-K` tag so the next implementer can `git diff main..rejected/issue-N-attempt-K` for context.
+4. Comments on the original issue with a pointer to the follow-up.
+
+The next drain iteration picks up the follow-up first (because of `priority`). To inspect a rejected attempt: `git show rejected/issue-N-attempt-K` for the annotated message, or `git diff main..rejected/issue-N-attempt-K` for the full diff.
+
+## The `retry` flow
+
+When the agent's branch is wrong-headed and you want a fresh attempt:
+
+1. Comment on the issue explaining what was wrong (this comment becomes input to the next agent run, since the prompt pulls all comments).
+2. Swap `needs-review` for `sandcastle` AND add `retry`.
+3. Next drain: the wrapper sees `sandcastle` + `retry`, runs `git branch -D agent/issue-<N>`, removes `retry`, and processes the issue normally.
+
+The wrapper only honors `retry` alongside `sandcastle`, never on `needs-review`. Adding `retry` to a `needs-review` issue does nothing destructive.
+
+If the branch is mostly right but needs only minor tweaks, **don't use `retry`** — just `git checkout agent/issue-<N>`, edit, commit, push, and open a PR yourself. No agent involvement, no label changes needed. The agent has no memory between runs anyway, so a retry starts fresh from `main` with only the issue body and comments as feedback — re-running for small tweaks is much more expensive than fixing them by hand.
+
+## The split protocol
+
+When the implementer realises mid-run that an issue's acceptance criteria don't fit under the 150k context ceiling, it commits what does fit and writes a list of follow-up issues into `.sandcastle-drain/splits.json` at the worktree root. The wrapper acts on the file after the implementer run completes:
+
+1. Reads + validates the file (array of `{ title, body }`, 1 to 10 entries).
+2. Files each entry as a new GitHub issue with `sandcastle` + `priority` labels. The next drain iteration picks them up before unflagged work — matching the rejection-loop precedent.
+3. Comments on the parent issue with a checklist linking the follow-ups.
+4. Applies the `oversized` label to the parent.
+5. Refetches the drain queue so the new follow-ups land at the front of the remaining queue.
+
+The parent issue's foundation commits still flow through the normal `needs-review` / auto-merge / rejection path — splitting does not throw away the work the implementer did finish. Rejection takes precedence: if the reviewer FAILs on the run, the rejection-loop follow-up subsumes any split intent and the split flow is skipped.
+
+The implementer prompt (`src/prompts/implementer.md.tpl`) documents the file shape and rules. `.sandcastle-drain/splits.json` is gitignored so a sloppy `git add -A` doesn't capture it.
+
+---
+
+Edit any of these tables to match whatever vocabulary you actually use. If you change a label string, also update the wrapper at [`src/orchestrator/main.ts`](../../orchestrator/main.ts) and any references in [`README.md`](../../../README.md).

package/dist/content/principles/README.md

@@ -0,0 +1,39 @@
+# Development principles
+
+The rules Claude Code (interactive + sandcastle-drain-autonomous) follows when building code in this repo, plus the architectural constraints those rules force the _product code_ to take.
+
+These principles serve two readers:
+
+- **Claude Code** — what to enforce when writing TypeScript, when to skip ceremony, how to size sandcastle-drain issues, what's relaxed because this is personal-use, what is not.
+- **The product code itself** — what shape the codebase must take to remain testable, maintainable, and faithful to the domain.
+
+The product itself — its lifecycle, domain types, workflows — is **out of scope** here. Those decisions land in [CONTEXT.md](../../../CONTEXT.md) and [docs/adr/](../../../docs/adr/) as they crystallise.
+
+## Index
+
+| File                                                   | Scope            | Topic                                                                                                                                                                      |
+| ------------------------------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [language-and-types.md](language-and-types.md)         | Dev              | TypeScript strict mode, Zod at boundaries, branded types, tagged-union results, no-Effect rationale                                                                        |
+| [architecture.md](architecture.md)                     | Dev + Product    | Onion layers (Domain / Application / External / Presentation), package layout, dependency direction                                                                        |
+| [cqrs.md](cqrs.md)                                     | Dev + Product    | Read/write port separation at the Application boundary; one `<Aggregate>CommandRepository` + one `<Aggregate>QueryRepository` per new aggregate                            |
+| [frontend-organization.md](frontend-organization.md)   | Dev              | Co-locate at the lowest level shared; per-component folders with `Component.{tsx,test,hook,util,mock,module.scss}`; feature folders; `shared/` for cross-feature            |
+| [domain-modeling.md](domain-modeling.md)               | Dev + Product    | DDD ceremony rule (wrong-if-violated), anemic-model ban, reified-association pattern, decomposed-display values, nomenclature binding to CONTEXT.md                        |
+| [testing.md](testing.md)                               | Dev              | Vitest + Playwright, per-layer coverage, property-based for domain, testcontainers + recorded fixtures, behavior-required test rule                                        |
+| [linting-and-tooling.md](linting-and-tooling.md)       | Dev              | ESLint + plugins, three custom rules, Husky + lint-staged + pre-commit, no `--no-verify` ever                                                                              |
+| [clean-code.md](clean-code.md)                         | Dev              | DRY / YAGNI / KISS, small focused functions with lint-enforced max-depth and complexity, composition over inheritance, pure functions and immutability in the domain layer |
+| [personal-use-tradeoffs.md](personal-use-tradeoffs.md) | Dev + Product    | What's relaxed (UI, auth, ops), what's not (domain correctness, types, backups), tech-selection rule with paid-service ADR requirement                                     |
+| [context-budget.md](context-budget.md)                 | Dev (sandcastle-drain) | 100k target / 150k ceiling, BUDGET config location, mechanical post-run measurement, summarize-don't-paste                                                                 |
+| [claude-code-modes.md](claude-code-modes.md)           | Dev              | Universal rules + sandcastle-drain-only deltas (token budget, summarize-don't-paste, no-push, no-clarification)                                                                  |
+
+## How to use this folder
+
+- **Read [CLAUDE.md](../../../CLAUDE.md) first** — it links here and to the other agent-skill docs in [src/content/agent-docs/](../agent-docs/).
+- **Then read the file relevant to what you're about to do.** Don't load the whole folder unless you're auditing.
+- **If two files contradict, the more specific one wins** (e.g. `claude-code-modes.md` overrides general guidance for autonomous runs).
+- **If a principle conflicts with what you're being asked to do**, surface the conflict in the issue or session — don't silently override.
+
+## What's deliberately _not_ here
+
+- The product's lifecycle, workflow, domain types — those go in CONTEXT.md and ADRs once decided.
+- Tooling enforcement (lint config, tsconfig flags, pre-commit hook wiring) — those are queued as separate sandcastle-drain issues; principles describe the rules, follow-up issues implement them.
+- Scaffolded package folders — created when the first product issue needs them.