feat: sandcastle refinement loop with critic-based convergence

.sandcastle/concurrency-pool.ts

@@ -0,0 +1,69 @@
+/** Internal node for the O(1) FIFO waiting queue. Not exported. */
+interface QueueNode {
+  next: null | QueueNode;
+  resolve: () => void;
+}
+
+/**
+ * A concurrency limiter that restricts parallel execution to a maximum number of tasks.
+ * Queue operations are O(1) amortized (singly-linked list).
+ */
+export class ConcurrencyPool {
+  private head: null | QueueNode = null;
+  private running = 0;
+  private tail: null | QueueNode = null;
+
+  /**
+   * @param max - Maximum number of concurrent tasks. Must be a positive integer >= 1.
+   */
+  constructor(private readonly max: number) {
+    if (!Number.isInteger(max) || max < 1) {
+      throw new RangeError("ConcurrencyPool max must be a positive integer >= 1");
+    }
+  }
+
+  /**
+   * Executes the given async function, waiting if the pool is at capacity.
+   * @param fn - Async function to execute within the pool.
+   * @returns The result of the function.
+   * @remarks Re-entrant calls using the same pool instance may deadlock when all slots are occupied.
+   */
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+
+  private acquire(): Promise<void> {
+    if (this.running < this.max) {
+      this.running++;
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      const node: QueueNode = { next: null, resolve };
+      if (this.tail === null) {
+        this.head = node;
+        this.tail = node;
+      } else {
+        this.tail.next = node;
+        this.tail = node;
+      }
+    });
+  }
+
+  private release(): void {
+    this.running--;
+    const next = this.head;
+    if (next !== null) {
+      this.head = next.next;
+      if (this.head === null) {
+        this.tail = null;
+      }
+      this.running++;
+      next.resolve();
+    }
+  }
+}

.sandcastle/constants.ts

@@ -0,0 +1,64 @@
+import { execFile } from "node:child_process";
+import util from "node:util";
+
+/** Model identifier used for implementation and critic agents. */
+export const AGENT_MODEL = "github-copilot/claude-sonnet-4.6";
+
+/** Number of context lines around a diff hunk used for hash computation. */
+export const CONTEXT_HASH_RADIUS = 3;
+
+/** Async execFile — does not block the event loop. Same error shape as execFileSync. */
+export const execFileAsync = util.promisify(execFile);
+
+/** Timeout in milliseconds for git operations. */
+export const GIT_TIMEOUT_MS = 30_000;
+
+/** Number of characters to retain from a SHA for display purposes. */
+export const HASH_PREFIX_LENGTH = 16;
+
+/** Maximum number of characters captured from stderr before truncation. */
+export const MAX_STDERR_CHARS = 500;
+
+/** Maximum number of characters allowed in a PR or commit title. */
+export const MAX_TITLE_LENGTH = 200;
+
+/** Model identifier used for planning and orchestration agents. */
+export const PLANNER_MODEL = "github-copilot/claude-opus-4.6";
+
+/** Timeout in milliseconds for git push operations. */
+export const PUSH_TIMEOUT_MS = 60_000;
+
+/** Timeout in milliseconds for a single sandcastle task execution. */
+export const TASK_TIMEOUT_MS = 15 * 60 * 1000;
+
+/** Full validation command run after each implementation round. */
+export const VALIDATION_COMMAND =
+  "npm run type-check && npm run test && npm run test:node && npm run test:edge && npm run prettier-check && npm run lint && npm run build && npm run check-build && npm run build:v2 && npm run check-build:v2";
+
+/** Timeout in milliseconds for the validation command. */
+export const VALIDATION_TIMEOUT_MS = 120_000;
+
+/**
+ * Returns the current HEAD commit SHA for the given working directory.
+ * @param cwd - Absolute path to the git repository root.
+ * @returns The full SHA string, or `null` if the command fails.
+ */
+export async function getHeadSha(cwd: string): Promise<null | string> {
+  try {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], {
+      cwd,
+    });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Converts an unknown thrown value to a human-readable error message.
+ * @param err - The caught value (may be an `Error` or any other type).
+ * @returns The `message` property if `err` is an `Error`, otherwise `String(err)`.
+ */
+export function toErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

.sandcastle/critic-prompt.md

@@ -0,0 +1,64 @@
+# Critic Agent
+
+Analyze the implementation on branch `{{BRANCH}}` and produce structured findings.
+
+## Task
+
+Run `git diff main...{{BRANCH}}` to see all changes. Examine the diff carefully. For each issue found, produce a structured finding.
+
+Read `AGENTS.md` and `CONTRIBUTING.md` for the project's coding standards.
+
+## Output Format
+
+Output your findings as JSON wrapped in nonce-tagged delimiters. Use EXACTLY this tag format:
+
+```text
+<findings-{{NONCE}}>[...]</findings-{{NONCE}}>
+```
+
+Each finding must have this structure:
+
+```json
+{
+  "file": "path/to/file.ts",
+  "line": 42,
+  "title": "short description of the issue",
+  "severity": "CRITICAL|HIGH|MEDIUM|LOW",
+  "category": "security|logic|performance|architecture|style",
+  "confidence": "HIGH|MEDIUM|LOW",
+  "description": "detailed explanation of why this is a problem",
+  "suggestion": "how to fix it"
+}
+```
+
+If no issues are found, output:
+
+```text
+<findings-{{NONCE}}>[]</findings-{{NONCE}}>
+```
+
+## Rules
+
+- Report ≤5 findings. HIGH and CRITICAL only. Omit LOW/MEDIUM unless zero higher-severity issues exist.
+- If >5 HIGH/CRITICAL issues exist, report the top 5 and add a summary note in the last finding's description.
+- Do NOT modify any files. Do NOT commit. Do NOT push.
+- Only report issues in the CHANGED code (not pre-existing issues).
+- Use HIGH confidence only when you've verified the issue by reading the relevant code.
+- Use MEDIUM confidence for pattern-based detection.
+- Use LOW confidence for style preferences or uncertain issues.
+- Focus on: logic errors, missing edge cases, security issues, type safety violations, test gaps.
+- Do NOT report formatting issues (prettier handles those).
+
+## Known Design Decisions (do not flag)
+
+- Mid-loop validation convergence bypasses critic (ARCS pattern — deterministic tests > subjective review).
+- `process.exit()` at script end kills timed-out sandboxes (no cooperative cancellation available in sandcastle).
+- Content-addressed dedup hash includes line number (collision reduction tradeoff, bounded by hard cap).
+
+## Completion
+
+After outputting the findings, output:
+
+```text
+<promise>COMPLETE</promise>
+```