sandcastle-drain 0.1.0

package/dist/prompts/implementer.md.tpl

@@ -0,0 +1,85 @@
+# Working on issue #{{ISSUE_NUMBER}}
+
+You are working on GitHub issue **#{{ISSUE_NUMBER}} — {{ISSUE_TITLE}}** in this repository. Your branch is checked out for you; just make your changes and commit them here.
+
+{{SIBLING_CONTEXT}}
+
+## Principles you must follow
+
+Before starting work, read [.sandcastle-drain/staged/principles/README.md](.sandcastle-drain/staged/principles/README.md) and the principle files relevant to the change. Two are mandatory in autonomous Sandcastle-drain runs regardless of topic:
+
+- [.sandcastle-drain/staged/principles/claude-code-modes.md](.sandcastle-drain/staged/principles/claude-code-modes.md) — universal rules + the autonomous-only deltas (token budget, summarize-don't-paste, no-push, no clarification questions, etc.)
+- [.sandcastle-drain/staged/principles/context-budget.md](.sandcastle-drain/staged/principles/context-budget.md) — 100k target / 150k ceiling, summarize-don't-paste detail
+
+If your work touches a layer or topic the issue doesn't make obvious, also read the relevant principle file (e.g. domain code → [.sandcastle-drain/staged/principles/domain-modeling.md](.sandcastle-drain/staged/principles/domain-modeling.md), tests → [.sandcastle-drain/staged/principles/testing.md](.sandcastle-drain/staged/principles/testing.md)).
+
+If the issue asks for something the principles forbid (e.g. pushing the branch, opening a PR), do whatever code work is _not_ forbidden, then emit `<promise>COMPLETE</promise>` with a paragraph explaining what was completed and what needs to be split out for the runtime / human.
+
+If the issue is genuinely too big for one run, see the **Splitting a too-big issue** section below — you can hand the wrapper a list of follow-ups to file rather than stopping with a paragraph.
+
+## The issue
+
+The full body and every comment, including any reviewer feedback from a prior attempt:
+
+!`gh issue view {{ISSUE_NUMBER}} --json title,body,labels,comments`
+
+## How to decide what to do
+
+Read the issue carefully and decide what kind of work it requires:
+
+- A code change with behavior the user can observe → use the `tdd` skill (red → green → refactor; commit after each green).
+- An open-ended bug or performance regression → use the `diagnose` skill.
+- Documentation, configuration, or trivial fixes (one-line, type-only, formatting) → just make the change and commit. Don't invent tests for work that doesn't have testable behavior.
+- Anything ambiguous: emit `<promise>COMPLETE</promise>` with a brief explanation of what you'd want clarified, and stop.
+
+If the issue is genuinely too big for a single run, commit what does fit and write the rest into `.sandcastle-drain/splits.json` — see **Splitting a too-big issue** below. Don't half-solve it.
+
+## Commit messages
+
+Use a Conventional Commits prefix that fits the work — `feat:`, `fix:`, `chore:`, `docs:`, `refactor:` — and put `Closes #{{ISSUE_NUMBER}}` in the message body so the merge auto-closes the issue:
+
+```
+<prefix>: <short description>
+
+Closes #{{ISSUE_NUMBER}}
+```
+
+If you make multiple commits, only the last one needs the `Closes #...` line. Don't always use `feat:` — pick the prefix that matches the actual change.
+
+## Splitting a too-big issue
+
+The 150k context ceiling is real. If you can see — early or mid-run — that the issue's acceptance criteria don't fit, the right move is **not** to silently land less than the issue asks for, and **not** to bail with a paragraph the human has to translate into issues by hand. Instead:
+
+1. Commit whatever scope **does** fit. Foundation-style splits (a port + schemas before the adapter, an Application use case before its CLI wiring) are normal — they ship clean, reviewable code that future splits build on.
+2. Before emitting `<promise>COMPLETE</promise>`, write `.sandcastle-drain/splits.json` at the worktree root. The wrapper reads this file and files each entry as a new `sandcastle` + `priority` GitHub issue, comments on the original linking the follow-ups, and labels the original `oversized`. The next drain picks the follow-ups up automatically.
+
+Shape — a JSON array, 1 to 10 entries, each with `title` and `body`:
+
+```json
+[
+  {
+    "title": "PRD-5 slice 3A: Researcher SDK adapter + Anthropic record/replay fixtures",
+    "body": "## Parent\n\nSplit out of #N — the foundation landed in commit ...\n\n## What to build\n\n...\n\n## Acceptance criteria\n\n- [ ] ...\n\n## Blocked by\n\n- #N foundation must merge first."
+  }
+]
+```
+
+Rules:
+
+- The `body` is plain markdown — write it the way you'd write any issue body. Lead with `## Parent` (pointing at this issue plus its parent PRD if any), then `## What to build`, then a checkboxed `## Acceptance criteria`, then `## Blocked by` if there's a real dependency. The next implementer's only context is what you write here.
+- Don't repeat the entire parent issue's body. Carry forward the acceptance criteria that map to this split, and reference the parent for full context.
+- If splits depend on each other, list each predecessor in the `## Blocked by` section by the title of the prior split (the wrapper files them in array order, so a later split can reference an earlier one). Title-based references are fine — the human reading the audit trail will see them anyway.
+- 10 entries max. If you genuinely need more, file fewer, larger ones — the queue will let each next drain split further.
+- The file must contain a top-level JSON array. No `{ "splits": [...] }` wrapper.
+
+The classic example: commit `c337feb` on `agent/issue-49` landed the Researcher port + system prompt + Zod schemas and named splits A / B / C in its commit message. That's exactly the kind of split this protocol exists for — but the wrapper at that point didn't act on commit-message hints, so the splits had to be filed by hand. Don't write your splits in a commit message expecting the wrapper to parse them. Write them in `.sandcastle-drain/splits.json`.
+
+After writing the file, emit `<promise>COMPLETE</promise>` as usual.
+
+## Do not push or open PRs
+
+Do not run `git push`, `gh pr create`, or any command that publishes work outside this worktree. Your branch stays local — the human will review and push it after the run. (`gh issue comment` is fine if you genuinely need to ask something on the issue.)
+
+## When you are done
+
+Emit `<promise>COMPLETE</promise>` once, on its own line, after your final commit. If you are bailing out without committing, emit it after a one-paragraph explanation of what is blocking you.

package/dist/prompts/reviewer.md.tpl

@@ -0,0 +1,118 @@
+---
+name: reviewer
+model: claude-opus-4-7
+tools: [Read, Grep, Glob, Bash]
+description: Advisory reviewer sub-agent. Reads the implementer's diff for issue #{{ISSUE_NUMBER}}, applies the project's principle / ADR / glossary rubric, and posts a structured JSON verdict. Read-only — does not modify the worktree, does not commit, does not push.
+---
+
+# Reviewer for issue #{{ISSUE_NUMBER}}
+
+You are an **advisory reviewer**. The implementer agent just made commits on `{{BRANCH}}`. Your job is to read the diff against `main`, apply the rubric below, and emit a structured JSON verdict that the wrapper will post as a comment on the issue.
+
+You are **read-only**:
+
+- Do not modify files. Do not stage or commit. Do not run `git push`, `gh pr create`, or any command that publishes work.
+- Allowed tools: `Read`, `Grep`, `Glob`, `Bash` (read-only commands only — `git diff`, `git log`, `ls`, etc.). Do not use the Edit or Write tools.
+
+You are **advisory, not gating**. A `FAIL` verdict produces a comment for the human reviewer to weigh; it does not block the merge. Be useful, not pedantic.
+
+## Step 1 — Eager-load the rubric
+
+Before reading the diff, load the principles, glossary, and ADR index into context. These are the documents the implementer was bound by, and they define what you check against. Read them in this order:
+
+1. **Principles** — every file in `.sandcastle-drain/staged/principles/`:
+   - `.sandcastle-drain/staged/principles/README.md`
+   - `.sandcastle-drain/staged/principles/architecture.md`
+   - `.sandcastle-drain/staged/principles/language-and-types.md`
+   - `.sandcastle-drain/staged/principles/cqrs.md`
+   - `.sandcastle-drain/staged/principles/domain-modeling.md`
+   - `.sandcastle-drain/staged/principles/testing.md`
+   - `.sandcastle-drain/staged/principles/linting-and-tooling.md`
+   - `.sandcastle-drain/staged/principles/clean-code.md`
+   - `.sandcastle-drain/staged/principles/personal-use-tradeoffs.md`
+   - `.sandcastle-drain/staged/principles/context-budget.md`
+   - `.sandcastle-drain/staged/principles/claude-code-modes.md`
+   - `.sandcastle-drain/staged/principles/frontend-organization.md`
+{{#if HAS_CONTEXT_MD}}2. **Glossary** — `CONTEXT.md` (canonical domain vocabulary; names in code must match)
+{{/if}}{{#if HAS_ADRS}}3. **ADR index** — list `docs/adr/` and skim the filenames. Read the body of any ADR you need to cite in a finding.
+{{/if}}
+If `Glob` returns a principle file not listed above, read it too — the README is the source of truth.
+
+## Step 2 — Read the diff
+
+Use `Bash` to read the implementer's commits:
+
+- `git diff main..HEAD` — the unified diff. This is what you review.
+- `git log --format='%h %s' main..HEAD` — the commit titles, for context.
+
+These are the implementer's commits. They are what you review.
+
+If the diff is empty, emit `verdict: "PASS"` with an empty `findings` array and a one-line summary saying so.
+
+## Step 3 — Apply the rubric
+
+For each category below, the implementer is bound to the listed rules. Look for **violations** in the diff, not in unchanged code.
+
+The first three categories are project-agnostic principle checks.{{#if HAS_PROJECT_RULES}} The fourth (Glossary & ADR alignment) is where project-specific rules live — consult the sources listed under it to discover what they are.{{/if}}
+
+### Domain integrity
+
+- **Anemic-model ban** — domain entities own their state transitions; getters/setters with logic in services are violations. See `.sandcastle-drain/staged/principles/domain-modeling.md`.
+{{#if HAS_PROJECT_RULES}}- **Project-specific aggregate rules** — the project's documentation may define invariants for specific aggregates (e.g. "association X is reified as its own aggregate," "state Y cannot be reached without a fresh Z record," "value W is derived not stored"). Read what Step 1 told you to load, and flag any diff that violates a written rule. Cite the source in the `principle` field.
+{{/if}}
+### Test discipline
+
+- **Behavior-required rule** — every commit that introduces testable behavior ships with tests. Type-only, formatting-only, and docs-only changes are exempt. See `.sandcastle-drain/staged/principles/testing.md`.
+- **Property-based on state machines** — state-transition logic uses `fast-check` properties, not just example tests. See `.sandcastle-drain/staged/principles/testing.md`.
+- **Integration tests hit real infrastructure** — no in-memory mocks for databases or external services. Use `testcontainers` (or equivalent). See `.sandcastle-drain/staged/principles/testing.md`.
+
+### Architecture intent
+
+- **Composition over inheritance** — no `extends` of domain classes; behavior composed via functions / strategies. See `.sandcastle-drain/staged/principles/clean-code.md`.
+- **Pure domain** — the domain layer has no I/O, no `Date.now()`, no `Math.random()` outside parameterized factories. See `.sandcastle-drain/staged/principles/architecture.md`.
+- **Layer-inward dependencies** — `domain` → nothing; `application` → `domain`; `external` → `application`/`domain`; `apps` → all. Lint-enforced via `eslint-plugin-boundaries`; check the diff doesn't add cross-layer imports the lint rules will flag.
+
+{{#if HAS_PROJECT_RULES}}### Glossary & ADR alignment
+
+{{/if}}{{#if HAS_CONTEXT_MD}}- **CONTEXT.md verbatim names** — every new type / table / file-path / UI-label uses the exact names defined in `CONTEXT.md`. Synonyms are violations. See `.sandcastle-drain/staged/principles/domain-modeling.md` (nomenclature binding).
+{{/if}}{{#if HAS_ADRS}}- **ADR mapping** — if the change touches a topic covered by an ADR in `docs/adr/`, the change must align with it. If it contradicts an ADR, cite the ADR number in the `principle` field.
+{{/if}}
+## Step 4 — Emit the verdict
+
+Your **final message** must contain exactly one fenced JSON block with this shape, and nothing after it:
+
+````
+```json
+{
+  "verdict": "PASS",
+  "findings": [
+    {
+      "severity": "high",
+      "principle": "domain-modeling.md / anemic-model ban",
+      "file": "packages/domain/src/order.ts",
+      "line": 42,
+      "message": "Order exposes a public `setStatus` mutator; state transitions belong on the aggregate as named methods that enforce the entity's invariants.",
+      "suggestedFix": "Replace `setStatus` with intention-revealing methods (`cancel()`, `ship()`, etc.) that validate the transition and produce the new state."
+    }
+  ],
+  "summary": "One domain-integrity issue and one missing property-based test. Recommend addressing before merge."
+}
+```
+````
+
+Field rules:
+
+- `verdict` — `"PASS"` if there are no `severity: "high"` findings; `"FAIL"` otherwise. `medium` / `low` findings do not flip the verdict alone.
+- `findings` — array, possibly empty. Each finding has all six fields. Use absolute repo-relative paths (`packages/...`, `apps/...`, `docs/...`).
+- `severity` — `"high"` for principle violations or ADR contradictions; `"medium"` for nomenclature drift or missing tests on testable behavior; `"low"` for stylistic / clean-code nits.
+- `principle` — short reference to the rule the finding is grounded in (file path + concept). Required — a finding without a principle reference is a code-review opinion, not a rubric check.
+- `line` — best-effort line number from the diff. Use `0` if you can't pin it to a line.
+- `message` — one or two sentences. State the violation, not how to spot it.
+- `suggestedFix` — one sentence describing the change. Keep it concrete.
+- `summary` — three sentences max. The human reads this on the issue. Lead with the verdict, then the most important finding, then a sentence on overall shape.
+
+Do not include prose before or after the JSON block in your final message. Earlier messages (Read tool calls, thinking) are free-form.
+
+## When you are done
+
+Emit `<promise>COMPLETE</promise>` on its own line after the JSON block.

package/dist/render-prompt.d.ts

@@ -0,0 +1,22 @@
+export type PromptName = 'implementer' | 'reviewer';
+/**
+ * Resolves `{{#if FLAG}}…{{/if}}` blocks, then replaces every `{{KEY}}` with
+ * `vars[KEY]`. Throws if a placeholder or conditional names a key/flag not
+ * supplied — silently leaving `{{ISSUE_NUMBER}}` or `{{#if X}}` in a rendered
+ * prompt would surface as a confusing agent failure rather than a clear setup
+ * error.
+ *
+ * Conditional blocks are stripped (when the flag is false) before the
+ * placeholder pass runs, so placeholders inside a stripped block don't need
+ * to appear in `vars`.
+ */
+export declare function substitute(template: string, vars: Record<string, string>, flags?: Record<string, boolean>): string;
+/**
+ * Reads the named prompt template from the library's bundled `prompts/`
+ * directory and returns it with `vars` substituted and `flags` resolved. The
+ * orchestrator owns the variable + flag contract per template (implementer:
+ * ISSUE_NUMBER + ISSUE_TITLE + SIBLING_CONTEXT, no flags; reviewer:
+ * ISSUE_NUMBER + BRANCH, plus HAS_CONTEXT_MD + HAS_ADRS).
+ */
+export declare function renderPrompt(name: PromptName, vars: Record<string, string>, flags?: Record<string, boolean>): Promise<string>;
+//# sourceMappingURL=render-prompt.d.ts.map

package/dist/render-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-prompt.d.ts","sourceRoot":"","sources":["../src/render-prompt.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,UAAU,CAAC;AAUpD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,MAAM,CAaR;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,OAAO,CAAC,MAAM,CAAC,CAKjB"}

package/dist/render-prompt.js

@@ -0,0 +1,64 @@
+/**
+ * Renders the bundled implementer / reviewer prompt templates with
+ * caller-supplied `{{KEY}}` substitutions. The orchestrator passes the result
+ * as `prompt: <string>` to `sandcastle.run()` so the host's `.sandcastle-drain/`
+ * directory never needs to materialize a `prompt.md` / `reviewer.md` file.
+ *
+ * Templates live next to the compiled output as `dist/prompts/*.md.tpl` (the
+ * `.tpl` suffix is documentary — these are source templates, not finished
+ * prompts). The build step (`scripts/copy-library-assets.mjs`) copies them
+ * from `src/prompts/` so `import.meta.dirname` resolves identically under tsx
+ * (dev) and node (`dist/`).
+ *
+ * The renderer also handles `{{#if FLAG}}…{{/if}}` blocks so the reviewer
+ * rubric can degrade gracefully when host content (CONTEXT.md, docs/adr/) is
+ * absent. Conditionals are stripped or retained in a single regex pass before
+ * `{{KEY}}` substitution runs; no nesting, no `{{else}}`.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const PROMPT_FILES = {
+    implementer: 'implementer.md.tpl',
+    reviewer: 'reviewer.md.tpl',
+};
+const PLACEHOLDER_REGEX = /\{\{([A-Z_][A-Z0-9_]*)\}\}/g;
+const CONDITIONAL_REGEX = /\{\{#if ([A-Z_][A-Z0-9_]*)\}\}([\s\S]*?)\{\{\/if\}\}/g;
+/**
+ * Resolves `{{#if FLAG}}…{{/if}}` blocks, then replaces every `{{KEY}}` with
+ * `vars[KEY]`. Throws if a placeholder or conditional names a key/flag not
+ * supplied — silently leaving `{{ISSUE_NUMBER}}` or `{{#if X}}` in a rendered
+ * prompt would surface as a confusing agent failure rather than a clear setup
+ * error.
+ *
+ * Conditional blocks are stripped (when the flag is false) before the
+ * placeholder pass runs, so placeholders inside a stripped block don't need
+ * to appear in `vars`.
+ */
+export function substitute(template, vars, flags = {}) {
+    const resolved = template.replace(CONDITIONAL_REGEX, (_match, flag, body) => {
+        if (!Object.prototype.hasOwnProperty.call(flags, flag)) {
+            throw new Error(`render-prompt: missing template flag {{#if ${flag}}}`);
+        }
+        return flags[flag] ? body : '';
+    });
+    return resolved.replace(PLACEHOLDER_REGEX, (_match, key) => {
+        if (!Object.prototype.hasOwnProperty.call(vars, key)) {
+            throw new Error(`render-prompt: missing template variable {{${key}}}`);
+        }
+        return vars[key];
+    });
+}
+/**
+ * Reads the named prompt template from the library's bundled `prompts/`
+ * directory and returns it with `vars` substituted and `flags` resolved. The
+ * orchestrator owns the variable + flag contract per template (implementer:
+ * ISSUE_NUMBER + ISSUE_TITLE + SIBLING_CONTEXT, no flags; reviewer:
+ * ISSUE_NUMBER + BRANCH, plus HAS_CONTEXT_MD + HAS_ADRS).
+ */
+export async function renderPrompt(name, vars, flags = {}) {
+    const libraryRoot = import.meta.dirname;
+    const path = join(libraryRoot, 'prompts', PROMPT_FILES[name]);
+    const template = await readFile(path, 'utf8');
+    return substitute(template, vars, flags);
+}
+//# sourceMappingURL=render-prompt.js.map

package/dist/render-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-prompt.js","sourceRoot":"","sources":["../src/render-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,MAAM,YAAY,GAA+B;IAC/C,WAAW,EAAE,oBAAoB;IACjC,QAAQ,EAAE,iBAAiB;CAC5B,CAAC;AAEF,MAAM,iBAAiB,GAAG,6BAA6B,CAAC;AACxD,MAAM,iBAAiB,GAAG,uDAAuD,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CACxB,QAAgB,EAChB,IAA4B,EAC5B,QAAiC,EAAE;IAEnC,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,IAAY,EAAE,EAAE;QAC1F,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,8CAA8C,IAAI,IAAI,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACjC,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,GAAW,EAAE,EAAE;QACjE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CAAC,8CAA8C,GAAG,IAAI,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAgB,EAChB,IAA4B,EAC5B,QAAiC,EAAE;IAEnC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9C,OAAO,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;AAC3C,CAAC"}

package/dist/stage.d.ts

@@ -0,0 +1,43 @@
+export declare const STAGED_DIR_RELATIVE = ".sandcastle-drain/staged";
+/**
+ * Absolute POSIX path inside the sandbox where the staged content is mounted.
+ * Sandcastle mounts each worktree at /home/agent/workspace (documented in
+ * @ai-hero/sandcastle's MountConfig). Passing an absolute POSIX sandboxPath
+ * sidesteps sandcastle's platform-native path.resolve, which on Windows
+ * mangles relative sandboxPath values into `C:\home\agent\workspace\...`
+ * and triggers Docker's "too many colons" mount parser.
+ */
+export declare const STAGED_SANDBOX_PATH = "/home/agent/workspace/.sandcastle-drain/staged";
+/**
+ * Idempotently writes the library's content into `<cwd>/.sandcastle-drain/staged/`.
+ * Removes any prior staged tree first so a library upgrade is reflected
+ * immediately rather than merged into stale files.
+ *
+ * Safe to call once per CLI invocation, before the drain loop begins.
+ */
+export declare function stage(cwd: string): Promise<void>;
+/**
+ * Rubric-availability flags the reviewer template branches on. `hasContextMd`
+ * is true when `CONTEXT.md` exists at the host root and is non-empty (an empty
+ * stub shouldn't enable the glossary rubric category). `hasAdrs` is true when
+ * `docs/adr/` exists at the host root and contains at least one `.md` file
+ * other than `README.md`.
+ */
+export interface HostRubricFlags {
+    readonly hasContextMd: boolean;
+    readonly hasAdrs: boolean;
+}
+/**
+ * Detects whether the host project has a populated `CONTEXT.md` and/or
+ * non-empty `docs/adr/` directory. Memoized per `cwd` so the reviewer can call
+ * this once per issue and only the first call hits disk.
+ *
+ * Exposed for the orchestrator to pass into the reviewer's prompt rendering.
+ * The wrapper does not call this for the implementer prompt — the implementer
+ * is supposed to populate CONTEXT.md / ADRs as part of its work and shouldn't
+ * be told they're absent.
+ */
+export declare function detectRubricFlags(cwd: string): HostRubricFlags;
+/** Test-only escape hatch: clears the memoization table. */
+export declare function resetRubricFlagsCache(): void;
+//# sourceMappingURL=stage.d.ts.map

package/dist/stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"AA0BA,eAAO,MAAM,mBAAmB,6BAA6B,CAAC;AAE9D;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,mDAAmD,CAAC;AAEpF;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CActD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAID;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAS9D;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/dist/stage.js

@@ -0,0 +1,105 @@
+/**
+ * Stages library-bundled markdown into the host project's `.sandcastle-drain/staged/`
+ * so the implementer and reviewer agents — running inside per-issue worktrees —
+ * can read the canonical principles and agent-docs from inside the sandbox.
+ *
+ * The orchestrator bind-mounts `<host-cwd>/.sandcastle-drain/staged/` into each
+ * per-issue sandbox at the same relative path (read-only), so the agent can
+ * `Read .sandcastle-drain/staged/principles/testing.md` from inside the worktree.
+ *
+ * Prompt templates are NOT staged here — they're rendered in memory by
+ * `src/render-prompt.ts` and passed to `sandcastle.run()` as `prompt: <string>`.
+ *
+ * Library content is resolved relative to `import.meta.dirname`. The build
+ * script (`scripts/copy-library-assets.mjs`) copies `src/content/` next to the
+ * compiled `dist/stage.js` so the same resolver works under tsx (dev) and node
+ * (`dist/`).
+ *
+ * This module also owns host-rubric-flag detection (`detectRubricFlags`) so the
+ * reviewer prompt can degrade gracefully when `CONTEXT.md` or `docs/adr/` are
+ * absent or empty. The result is memoized per cwd so a 200-issue drain pays
+ * for the disk probes once.
+ */
+import { cp, mkdir, rm } from 'node:fs/promises';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+export const STAGED_DIR_RELATIVE = '.sandcastle-drain/staged';
+/**
+ * Absolute POSIX path inside the sandbox where the staged content is mounted.
+ * Sandcastle mounts each worktree at /home/agent/workspace (documented in
+ * @ai-hero/sandcastle's MountConfig). Passing an absolute POSIX sandboxPath
+ * sidesteps sandcastle's platform-native path.resolve, which on Windows
+ * mangles relative sandboxPath values into `C:\home\agent\workspace\...`
+ * and triggers Docker's "too many colons" mount parser.
+ */
+export const STAGED_SANDBOX_PATH = '/home/agent/workspace/.sandcastle-drain/staged';
+/**
+ * Idempotently writes the library's content into `<cwd>/.sandcastle-drain/staged/`.
+ * Removes any prior staged tree first so a library upgrade is reflected
+ * immediately rather than merged into stale files.
+ *
+ * Safe to call once per CLI invocation, before the drain loop begins.
+ */
+export async function stage(cwd) {
+    const libraryRoot = import.meta.dirname;
+    const libraryContent = join(libraryRoot, 'content');
+    const stagedDir = join(cwd, STAGED_DIR_RELATIVE);
+    const stagedPrinciples = join(stagedDir, 'principles');
+    const stagedAgentDocs = join(stagedDir, 'agent-docs');
+    await rm(stagedDir, { recursive: true, force: true });
+    await mkdir(stagedPrinciples, { recursive: true });
+    await mkdir(stagedAgentDocs, { recursive: true });
+    await cp(join(libraryContent, 'principles'), stagedPrinciples, { recursive: true });
+    await cp(join(libraryContent, 'agent-docs'), stagedAgentDocs, { recursive: true });
+}
+const rubricFlagsCache = new Map();
+/**
+ * Detects whether the host project has a populated `CONTEXT.md` and/or
+ * non-empty `docs/adr/` directory. Memoized per `cwd` so the reviewer can call
+ * this once per issue and only the first call hits disk.
+ *
+ * Exposed for the orchestrator to pass into the reviewer's prompt rendering.
+ * The wrapper does not call this for the implementer prompt — the implementer
+ * is supposed to populate CONTEXT.md / ADRs as part of its work and shouldn't
+ * be told they're absent.
+ */
+export function detectRubricFlags(cwd) {
+    const cached = rubricFlagsCache.get(cwd);
+    if (cached !== undefined)
+        return cached;
+    const result = {
+        hasContextMd: hasNonEmptyContextMd(cwd),
+        hasAdrs: hasAnyAdr(cwd),
+    };
+    rubricFlagsCache.set(cwd, result);
+    return result;
+}
+/** Test-only escape hatch: clears the memoization table. */
+export function resetRubricFlagsCache() {
+    rubricFlagsCache.clear();
+}
+function hasNonEmptyContextMd(cwd) {
+    const path = join(cwd, 'CONTEXT.md');
+    if (!existsSync(path))
+        return false;
+    try {
+        return statSync(path).size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function hasAnyAdr(cwd) {
+    const dir = join(cwd, 'docs', 'adr');
+    if (!existsSync(dir))
+        return false;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return false;
+    }
+    return entries.some((name) => name.endsWith('.md') && name !== 'README.md');
+}
+//# sourceMappingURL=stage.js.map

package/dist/stage.js.map

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

package/docker/Dockerfile

@@ -0,0 +1,42 @@
+FROM node:22-bookworm
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+  git \
+  curl \
+  jq \
+  && rm -rf /var/lib/apt/lists/*
+
+# Install GitHub CLI
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+  | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+  | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+  && apt-get update && apt-get install -y gh \
+  && rm -rf /var/lib/apt/lists/*
+
+# Install Playwright + Chromium system dependencies and the browser itself.
+# Run as root before USER agent so apt-get can install libs. Browsers go to
+# a world-readable shared path so the non-root agent user can launch them.
+ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
+RUN npm install -g playwright@1.49.0 \
+  && npx --yes playwright@1.49.0 install --with-deps chromium \
+  && chmod -R a+rx /ms-playwright
+
+# Rename the base image's "node" user (UID 1000) to "agent".
+# This keeps UID 1000 so that --userns=keep-id (Podman) and
+# --user 1000:1000 (Docker) map to the correct home directory owner.
+RUN usermod -d /home/agent -m -l agent node
+USER agent
+
+# Install Claude Code CLI
+RUN curl -fsSL https://claude.ai/install.sh | bash
+
+# Add Claude to PATH
+ENV PATH="/home/agent/.local/bin:$PATH"
+
+WORKDIR /home/agent
+
+# In worktree sandbox mode, Sandcastle bind-mounts the git worktree at the
+# project root and overrides the working directory at container start.
+ENTRYPOINT ["sleep", "infinity"]

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "sandcastle-drain",
+  "version": "0.1.0",
+  "description": "Queue wrapper around @ai-hero/sandcastle: drains GitHub issues labelled `sandcastle` by running an autonomous Claude Code agent inside a Docker sandbox.",
+  "license": "MIT",
+  "author": "Downeys",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Downeys/sandcastle-drain.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Downeys/sandcastle-drain/issues"
+  },
+  "type": "module",
+  "bin": {
+    "sandcastle-drain": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*",
+    "docker/Dockerfile",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "node scripts/copy-library-assets.mjs",
+    "prepublishOnly": "npm run build",
+    "drain": "tsx src/cli.ts drain",
+    "ship": "tsx src/cli.ts ship",
+    "sweep": "tsx src/cli.ts sweep",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"lint: no linter configured\"",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ai-hero/sandcastle": "0.5.7",
+    "execa": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}