stonecut 1.2.0 → 1.3.0

package/src/execute.ts

@@ -0,0 +1,142 @@
+/**
+ * Execution orchestration — non-interactive, prompt-free.
+ *
+ * executeLocal: set up session, checkout branch, run loop, push/PR.
+ * pushAndMaybePr: push branch and conditionally create PR.
+ * buildReport: format iteration results for PR body.
+ *
+ * This module never imports @clack/prompts — the interactive/execution
+ * boundary is enforced by module structure.
+ */
+
+import { checkoutOrCreateBranch, createPr, pushBranch } from "./git";
+import { LocalSource } from "./local";
+import { slugifyBranchComponent } from "./naming";
+import { renderLocal } from "./prompt";
+import { Logger } from "./logger";
+import { defaultGitOps, runAfkLoop } from "./runner";
+import { getRunner } from "./runners/index";
+import type { Issue, IterationResult, Session } from "./types";
+
+// ---------------------------------------------------------------------------
+// Stonecut report
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the Stonecut Report section for a PR body.
+ */
+export function buildReport(
+	results: IterationResult[],
+	runnerName: string,
+	closingRefs?: string[],
+): string {
+	const lines = ["## Stonecut Report", `**Runner:** ${runnerName}`, ""];
+	for (const r of results) {
+		if (r.success) {
+			lines.push(`- #${r.issueNumber} ${r.issueFilename}: completed`);
+		} else {
+			const reason = r.error || "unknown error";
+			lines.push(`- #${r.issueNumber} ${r.issueFilename}: failed — ${reason}`);
+		}
+	}
+
+	if (closingRefs && closingRefs.length > 0) {
+		lines.push("");
+		lines.push(closingRefs.join("\n"));
+	}
+
+	return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Post-loop: push and conditionally create PR
+// ---------------------------------------------------------------------------
+
+export async function pushAndMaybePr(
+	results: IterationResult[],
+	source: {
+		getRemainingCount(): Promise<[number, number]>;
+		getClosingRefs?(completedIssueNumbers: number[]): string[];
+	},
+	branch: string,
+	baseBranch: string,
+	prTitle: string,
+	runnerName: string,
+	logger: { log(message: string): void },
+): Promise<void> {
+	if (!results.some((r) => r.success)) {
+		return;
+	}
+
+	pushBranch(branch);
+	logger.log(`Pushed branch '${branch}'.`);
+
+	const [remaining, total] = await source.getRemainingCount();
+	if (remaining === 0) {
+		const completed = results.filter((r) => r.success).map((r) => r.issueNumber);
+		const closingRefs = source.getClosingRefs?.(completed);
+		const body = buildReport(results, runnerName, closingRefs);
+		createPr(prTitle, body, baseBranch);
+		logger.log("Created PR.");
+	} else {
+		logger.log(`${remaining}/${total} issues remaining — PR deferred.`);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Execution orchestration
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a local PRD run — non-interactive orchestration.
+ *
+ * All parameters are explicit: no interactive prompts, no @clack/prompts.
+ * Handles branch checkout, runner session, loop, push, and PR creation.
+ */
+export async function executeLocal(
+	name: string,
+	branch: string,
+	baseBranch: string,
+	iterations: number | "all",
+	runnerName: string,
+): Promise<void> {
+	const runner = getRunner(runnerName);
+	const source = new LocalSource(name);
+	const prdIdentifier = slugifyBranchComponent(name) || "spec";
+	const logger = new Logger(prdIdentifier);
+
+	const session: Session = { logger, git: defaultGitOps, runner, runnerName };
+
+	try {
+		checkoutOrCreateBranch(branch);
+		console.log("");
+
+		const prdContent = await source.getPrdContent();
+		const results = await runAfkLoop<Issue>(
+			source,
+			iterations,
+			(issue) =>
+				renderLocal({
+					prdContent,
+					issueNumber: issue.number,
+					issueFilename: issue.filename,
+					issueContent: issue.content,
+				}),
+			(issue) => issue.filename,
+			(issue) => `Issue ${issue.number}: ${issue.filename}`,
+			session,
+		);
+
+		await pushAndMaybePr(
+			results,
+			source,
+			branch,
+			baseBranch,
+			`Stonecut: ${name}`,
+			runnerName,
+			logger,
+		);
+	} finally {
+		logger.close();
+	}
+}

package/src/git.ts

@@ -5,28 +5,9 @@
  * All functions throw on failure. No process.exit, no console output.
  */
 
+import { runSync } from "./spawn";
 import type { WorkingTreeSnapshot } from "./types";
 
-/**
- * Run a command synchronously, optionally in a specific working directory.
- * When cwd is omitted, uses the current process working directory.
- */
-function runSync(
-	cmd: string[],
-	cwd?: string,
-): { exitCode: number; stdout: string; stderr: string } {
-	const proc = Bun.spawnSync(cmd, {
-		stdout: "pipe",
-		stderr: "pipe",
-		...(cwd && { cwd }),
-	});
-	return {
-		exitCode: proc.exitCode,
-		stdout: proc.stdout.toString(),
-		stderr: proc.stderr.toString(),
-	};
-}
-
 /** Detect the remote's default branch, falling back to "main". */
 export function defaultBranch(cwd?: string): string {
 	const result = runSync(["git", "symbolic-ref", "refs/remotes/origin/HEAD"], cwd);

package/src/import.ts

@@ -37,7 +37,7 @@ export async function importSpec(options: ImportOptions): Promise<ImportResult>
 		throw new Error("Could not derive a spec name from the PRD title. Use --name to specify one.");
 	}
 
-	const specDir = join(".stonecut", specName);
+	const specDir = join(".stonecut", "specs", specName);
 
 	if (existsSync(specDir)) {
 		if (!options.force) {

package/src/local.ts

@@ -1,4 +1,4 @@
-/** Local spec source — reads issues from .stonecut/<name>/. */
+/** Local spec source — reads issues from .stonecut/specs/<name>/. */
 
 import { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, statSync } from "fs";
 import { join } from "path";
@@ -11,7 +11,7 @@ export class LocalSource implements Source<Issue> {
 
 	constructor(name: string) {
 		this.name = name;
-		this.specDir = join(".stonecut", name);
+		this.specDir = join(".stonecut", "specs", name);
 		this.validate();
 	}
 
@@ -86,6 +86,32 @@ export class LocalSource implements Source<Issue> {
 		return null;
 	}
 
+	getClosingRefs(completedIssueNumbers: number[]): string[] {
+		const completed = new Set(completedIssueNumbers);
+		const refs: string[] = [];
+		const all = this.allIssues();
+
+		for (const issue of all) {
+			if (!completed.has(issue.number)) continue;
+			const raw = readFileSync(issue.path, "utf-8");
+			const num = parseInt(parseFrontmatter(raw).meta.issue, 10);
+			if (num && !isNaN(num)) {
+				refs.push(`Closes #${num}`);
+			}
+		}
+
+		const allComplete = all.every((i) => completed.has(i.number));
+		if (allComplete) {
+			const raw = readFileSync(join(this.specDir, "prd.md"), "utf-8");
+			const num = parseInt(parseFrontmatter(raw).meta.issue, 10);
+			if (num && !isNaN(num)) {
+				refs.push(`Closes #${num}`);
+			}
+		}
+
+		return refs;
+	}
+
 	async getRemainingCount(): Promise<[number, number]> {
 		const completed = this.readStatus();
 		const all = this.allIssues();

package/src/prd.ts

@@ -0,0 +1,136 @@
+/**
+ * PRD selection UI — filesystem scanning, interactive picker, and inline
+ * GitHub import flow.
+ *
+ * This is the only extracted module that imports @clack/prompts, as it is
+ * part of the interactive UI layer.
+ */
+
+import * as clack from "@clack/prompts";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { importSpec } from "./import";
+import { getSourceProvider } from "./sources/index";
+
+/** A locally available PRD with its completion status. */
+export interface LocalPrdEntry {
+	name: string;
+	completed: number;
+	total: number;
+}
+
+/**
+ * Scan .stonecut subdirectories for directories containing prd.md and compute
+ * completion counts from status.json.
+ */
+export function scanLocalPrds(baseDir: string = ".stonecut/specs"): LocalPrdEntry[] {
+	if (!existsSync(baseDir)) return [];
+
+	const entries: LocalPrdEntry[] = [];
+	for (const name of readdirSync(baseDir)) {
+		const specDir = join(baseDir, name);
+		if (!statSync(specDir).isDirectory()) continue;
+		if (!existsSync(join(specDir, "prd.md"))) continue;
+
+		const issuesDir = join(specDir, "issues");
+		let total = 0;
+		if (existsSync(issuesDir) && statSync(issuesDir).isDirectory()) {
+			total = readdirSync(issuesDir).filter((f) => f.endsWith(".md")).length;
+		}
+
+		let completed = 0;
+		const statusPath = join(specDir, "status.json");
+		if (existsSync(statusPath)) {
+			try {
+				const data = JSON.parse(readFileSync(statusPath, "utf-8"));
+				completed = Array.isArray(data.completed) ? data.completed.length : 0;
+			} catch {
+				// Malformed status.json — treat as 0 completed
+			}
+		}
+
+		entries.push({ name, completed, total });
+	}
+	return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Format a PRD entry for display in the wizard.
+ */
+export function formatPrdOption(entry: LocalPrdEntry): string {
+	if (entry.total === 0) return `${entry.name} (no issues)`;
+	if (entry.completed === 0) return `${entry.name} (not started)`;
+	return `${entry.name} (${entry.completed}/${entry.total} done)`;
+}
+
+/** Sentinel value for the "Import from GitHub" wizard option. */
+const IMPORT_FROM_GITHUB = "__import_from_github__";
+
+/**
+ * Prompt the user to select a local PRD or import from GitHub.
+ * Returns the local spec name to run.
+ */
+export async function promptForPrd(): Promise<{ kind: "local"; name: string }> {
+	const prds = scanLocalPrds();
+
+	const options: Array<{ value: string; label: string }> = prds.map((entry) => ({
+		value: entry.name,
+		label: formatPrdOption(entry),
+	}));
+	options.push({ value: IMPORT_FROM_GITHUB, label: "Import from GitHub" });
+
+	const selection = await clack.select({
+		message: "Select a PRD:",
+		options,
+	});
+
+	if (clack.isCancel(selection)) {
+		throw new Error("Cancelled.");
+	}
+
+	if (selection === IMPORT_FROM_GITHUB) {
+		const specName = await inlineGitHubImport();
+		return { kind: "local", name: specName };
+	}
+
+	return { kind: "local", name: selection as string };
+}
+
+/**
+ * Inline GitHub import flow within the wizard.
+ * Lists PRDs by `prd` label, user picks one, import runs.
+ * Returns the imported spec name.
+ */
+async function inlineGitHubImport(): Promise<string> {
+	const provider = getSourceProvider("github");
+	const prdList = await provider.listPrds();
+
+	if (prdList.length === 0) {
+		throw new Error("No open PRDs with the 'prd' label found on GitHub.");
+	}
+
+	const prdOptions = prdList.map((p) => ({
+		value: String(p.number),
+		label: `#${p.number}: ${p.title}`,
+	}));
+
+	const selected = await clack.select({
+		message: "Select a GitHub PRD to import:",
+		options: prdOptions,
+	});
+
+	if (clack.isCancel(selected)) {
+		throw new Error("Cancelled.");
+	}
+
+	const result = await importSpec({
+		provider: "github",
+		identifier: selected as string,
+	});
+
+	console.log(
+		`Imported PRD #${result.prdIssueNumber} → ${result.specDir}/ (${result.issueCount} issues)`,
+	);
+
+	return result.specName;
+}

package/src/runner.ts

@@ -1,11 +1,12 @@
 /**
- * Runner — commit flow, orchestration loop, and session helpers.
+ * Runner — orchestration loop, commit flow, and session helpers.
  *
  * verifyAndFix: single check → fix cycle.
  * commitIssue: stage, commit, retry on failure up to maxRetries times.
  * runAfkLoop: main orchestration loop over issues from any source.
  * fmtTime / printSummary: session output formatting.
  *
+ * Sync-back logic lives in sync-back.ts.
  * Modules throw on failure. No process.exit, no console output.
  */
 
@@ -15,9 +16,8 @@ import {
 	snapshotWorkingTree as realSnapshotWorkingTree,
 	stageChanges as realStageChanges,
 } from "./git";
-import { readFileSync } from "fs";
-import { parseFrontmatter } from "./frontmatter";
-import { getSourceProvider } from "./sources/index";
+import { syncBackIssue, syncBackPrd } from "./sync-back";
+import type { SyncBackConfig } from "./sync-back";
 import type {
 	GitOps,
 	IterationResult,
@@ -42,81 +42,6 @@ export const consoleLogger: LogWriter = {
 	close: () => {},
 };
 
-/**
- * Configuration for syncing issue/PRD completion back to an external source.
- *
- * When provided to runAfkLoop, the runner reads frontmatter from completed
- * issue files. If a `source` field is present, the corresponding provider
- * is resolved and notified of the completion.
- */
-export interface SyncBackConfig<T> {
-	/** Return the file path for a completed issue, or undefined to skip sync-back. */
-	getIssuePath: (issue: T) => string | undefined;
-	/** Path to the PRD file, used for sync-back after all issues complete. */
-	prdPath?: string;
-	/** Read a file's contents. Injectable for testing; defaults to fs.readFileSync. */
-	readFile?: (path: string) => string;
-	/** Resolve a source provider by name. Injectable for testing; defaults to getSourceProvider. */
-	resolveProvider?: (name: string) => {
-		onIssueComplete(id: string): Promise<void>;
-		onPrdComplete(id: string): Promise<void>;
-	};
-}
-
-/**
- * Sync a completed issue back to its external source.
- *
- * Reads frontmatter from the issue file. If `source` and `issue` fields
- * are present, resolves the provider and calls onIssueComplete.
- * Failures are logged as warnings but never thrown.
- */
-export async function syncBackIssue(
-	filePath: string,
-	logger: LogWriter,
-	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
-	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
-): Promise<void> {
-	try {
-		const content = readFile(filePath);
-		const { meta } = parseFrontmatter(content);
-		if (!meta.source || !meta.issue) return;
-
-		const provider = resolveProvider!(meta.source);
-		await provider.onIssueComplete(meta.issue);
-		logger.log(`Synced issue #${meta.issue} back to ${meta.source}`);
-	} catch (err: unknown) {
-		const message = err instanceof Error ? err.message : String(err);
-		logger.log(`Warning: sync-back failed for issue at ${filePath}: ${message}`);
-	}
-}
-
-/**
- * Sync PRD completion back to its external source.
- *
- * Reads frontmatter from the PRD file. If `source` and `issue` fields
- * are present, resolves the provider and calls onPrdComplete.
- * Failures are logged as warnings but never thrown.
- */
-export async function syncBackPrd(
-	filePath: string,
-	logger: LogWriter,
-	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
-	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
-): Promise<void> {
-	try {
-		const content = readFile(filePath);
-		const { meta } = parseFrontmatter(content);
-		if (!meta.source || !meta.issue) return;
-
-		const provider = resolveProvider!(meta.source);
-		await provider.onPrdComplete(meta.issue);
-		logger.log(`Synced PRD #${meta.issue} back to ${meta.source}`);
-	} catch (err: unknown) {
-		const message = err instanceof Error ? err.message : String(err);
-		logger.log(`Warning: sync-back failed for PRD at ${filePath}: ${message}`);
-	}
-}
-
 /**
  * Single check → fix cycle.
  *

package/src/skills/stonecut-issues/SKILL.md

@@ -12,7 +12,7 @@ You are breaking a PRD into issues as part of the Stonecut workflow. Each issue
 Determine where the PRD lives. Check these in order:
 
 1. **Conversation context** — If a PRD was created earlier in this conversation (via `/stonecut-prd` or otherwise), you already know where it is. State where you found it and confirm with the user.
-2. **Ask the user** — If no PRD is in context, ask: "Where is the PRD? Give me a local file path (e.g., `.stonecut/ASC-1/prd.md`) or a GitHub issue number."
+2. **Ask the user** — If no PRD is in context, ask: "Where is the PRD? Give me a local file path (`.stonecut/specs/<name>/prd.md`) or a GitHub issue number."
 
 If given a GitHub issue number, fetch it with `gh issue view <number>`.
 If given a local path, read the file.
@@ -63,7 +63,7 @@ Iterate until the user approves the breakdown.
 
 Default to **matching the PRD location**:
 
-- If the PRD is a **local file** (e.g., `.stonecut/ASC-1/prd.md`), default to creating issues in the same directory under `issues/` (e.g., `.stonecut/ASC-1/issues/01-short-title.md`).
+- If the PRD is a **local file**, default to creating issues under `.stonecut/specs/<name>/issues/`.
 - If the PRD is a **GitHub issue**, default to creating issues as GitHub issues using `gh issue create`.
 
 Confirm with the user before creating. If they want a different destination, respect that.
@@ -75,7 +75,7 @@ Confirm with the user before creating. If they want a different destination, res
 Create each issue as a markdown file in the issues directory. Use zero-padded numbering with a kebab-case descriptive suffix:
 
 ```
-.stonecut/<name>/issues/
+.stonecut/specs/<name>/issues/
   01-short-descriptive-title.md
   02-another-slice-title.md
   ...
@@ -88,7 +88,7 @@ Create issues in dependency order (blockers first). Use the local issue template
 
 ## Parent PRD
 
-See `.stonecut/<name>/prd.md`
+See `.stonecut/specs/<name>/prd.md`
 
 ## What to build
 

package/src/skills/stonecut-prd/SKILL.md

@@ -29,7 +29,7 @@ Check with the user that these modules match their expectations. Ask which modul
 
 Ask the user where to save the PRD:
 
-- **Local file** — Save as `.stonecut/<name>/prd.md` in the project. Ask the user: "What should I name this spec?" The name can be anything — a ticket ID (e.g., `ASC-1`), a descriptive slug (e.g., `auth-refactor`), or whatever fits. Create the `.stonecut/<name>/` directory if it doesn't exist.
+- **Local file** — Save as `.stonecut/specs/<name>/prd.md` in the project. Ask the user: "What should I name this spec?" The name can be anything — a ticket ID (e.g., `ASC-1`), a descriptive slug (e.g., `auth-refactor`), or whatever fits. Create the `.stonecut/specs/<name>/` directory if it doesn't exist.
 - **GitHub issue** — Create a GitHub issue using `gh issue create --label prd`. Before creating, ensure the `prd` label exists:
 
   ```bash

package/src/skills/stonecut-review-architecture/REFERENCE.md

@@ -0,0 +1,109 @@
+# Reference
+
+## Dependency Categories
+
+When assessing a candidate for deepening, classify its dependencies:
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — just merge the modules and test directly.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (e.g., PGLite for Postgres, in-memory filesystem). Deepenable if the test substitute exists. The deepened module is tested with the local stand-in running in the test suite.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a port (interface) at the module boundary. The deep module owns the logic; the transport is injected. Tests use an in-memory adapter. Production uses the real HTTP/gRPC/queue adapter.
+
+Recommendation shape: "Define a shared interface (port), implement an HTTP adapter for production and an in-memory adapter for testing, so the logic can be tested as one deep module even though it's deployed across a network boundary."
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. Mock at the boundary. The deepened module takes the external dependency as an injected port, and tests provide a mock implementation.
+
+## Testing Strategy
+
+The core principle: **replace, don't layer.**
+
+- Old unit tests on shallow modules are waste once boundary tests exist — delete them
+- Write new tests at the deepened module's interface boundary
+- Tests assert on observable outcomes through the public interface, not internal state
+- Tests should survive internal refactors — they describe behavior, not implementation
+
+## RFC Template
+
+<rfc-template>
+
+## Context
+
+Why this exploration was initiated:
+
+- What motivated the review (e.g., preparing for new features, observable friction, scaling concerns)
+- What areas of the codebase were explored
+- High-level findings from the exploration
+
+## Constraints
+
+Non-negotiable rules that narrow the solution space:
+
+- Architectural invariants that must be preserved
+- Backward compatibility requirements
+- Testing or deployment constraints
+
+## Problem
+
+Describe the architectural friction:
+
+- Which modules are shallow and tightly coupled
+- What integration risk exists in the seams between them
+- Why this makes the codebase harder to navigate and maintain
+
+## Alternatives Considered
+
+For each design explored during the multi-agent step:
+
+- **Design name** — One-line summary of the approach
+- Key trade-offs: what it gains, what it loses
+- Why it was accepted, rejected, or partially adopted
+
+Include a comparison (table or prose) so the reader can see why the chosen design won.
+
+## Proposed Design
+
+The chosen design. For each new or modified module:
+
+- What the module owns (responsibilities)
+- What it hides (implementation details callers don't see)
+- What it exposes (the public surface area — described, not full signatures)
+- Dependency graph between modules (which depends on which, and why)
+
+## Dependency Strategy
+
+Which category applies and how dependencies are handled:
+
+- **In-process**: merged directly
+- **Local-substitutable**: tested with [specific stand-in]
+- **Ports & adapters**: port definition, production adapter, test adapter
+- **Mock**: mock boundary for external services
+
+## Testing Impact
+
+High-level testing implications of the design:
+
+- What new boundary tests the design enables
+- What existing test patterns become redundant
+- Any test infrastructure changes needed
+
+## Implementation Guidance
+
+Durable architectural guidance — the _what and why_, not the _how_:
+
+- What the module should own (responsibilities)
+- What it should hide (implementation details)
+- What it should expose (the interface contract)
+- Key invariants the implementation must preserve
+
+Do NOT include specific file-level migration steps, exact function signatures, or line-by-line changes. Those belong in the PRD and issues.
+
+</rfc-template>