stonecut 1.1.1 → 1.2.1

package/src/local.ts

@@ -1,8 +1,9 @@
-/** Local spec source — reads issues from .stonecut/<name>/. */
+/** Local spec source — reads issues from .stonecut/prd/<name>/. */
 
 import { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, statSync } from "fs";
 import { join } from "path";
 import type { Issue, Source } from "./types";
+import { parseFrontmatter } from "./frontmatter";
 
 export class LocalSource implements Source<Issue> {
 	readonly name: string;
@@ -10,7 +11,7 @@ export class LocalSource implements Source<Issue> {
 
 	constructor(name: string) {
 		this.name = name;
-		this.specDir = join(".stonecut", name);
+		this.specDir = join(".stonecut", "prd", name);
 		this.validate();
 	}
 
@@ -65,18 +66,20 @@ export class LocalSource implements Source<Issue> {
 	}
 
 	async getPrdContent(): Promise<string> {
-		return readFileSync(join(this.specDir, "prd.md"), "utf-8");
+		const raw = readFileSync(join(this.specDir, "prd.md"), "utf-8");
+		return parseFrontmatter(raw).body;
 	}
 
 	async getNextIssue(): Promise<Issue | null> {
 		const completed = this.readStatus();
 		for (const issue of this.allIssues()) {
 			if (!completed.has(issue.number)) {
+				const raw = readFileSync(issue.path, "utf-8");
 				return {
 					number: issue.number,
 					filename: issue.filename,
 					path: issue.path,
-					content: readFileSync(issue.path, "utf-8"),
+					content: parseFrontmatter(raw).body,
 				};
 			}
 		}

package/src/prompt.ts

@@ -28,23 +28,3 @@ export async function renderLocal({
 		issue_content: issueContent,
 	});
 }
-
-export async function renderGithub({
-	prdContent,
-	issueNumber,
-	issueTitle,
-	issueContent,
-}: {
-	prdContent: string;
-	issueNumber: number;
-	issueTitle: string;
-	issueContent: string;
-}): Promise<string> {
-	return renderTemplate({
-		task_source: "a GitHub issue",
-		prd_content: prdContent,
-		issue_number: issueNumber,
-		issue_filename: issueTitle,
-		issue_content: issueContent,
-	});
-}

package/src/runner.ts

@@ -15,6 +15,9 @@ import {
 	snapshotWorkingTree as realSnapshotWorkingTree,
 	stageChanges as realStageChanges,
 } from "./git";
+import { readFileSync } from "fs";
+import { parseFrontmatter } from "./frontmatter";
+import { getSourceProvider } from "./sources/index";
 import type {
 	GitOps,
 	IterationResult,
@@ -39,6 +42,81 @@ 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.
  *
@@ -102,7 +180,7 @@ export async function commitIssue(
  *
  * Uses the provided Session to execute each issue's prompt.
  * After each successful run, Stonecut stages and commits the changes.
- * Works with both LocalSource and GitHubSource.
+ * Works with LocalSource (the single execution path).
  *
  * A failing issue is retried once (2 total attempts). If it fails
  * a second time, the session stops — issues are sequential vertical
@@ -116,6 +194,7 @@ export async function runAfkLoop<T extends { number: number }>(
 	commitMessage: (issue: T) => string,
 	session: Session,
 	onNoChanges?: (issue: T, output: string | undefined) => void,
+	syncBack?: SyncBackConfig<T>,
 ): Promise<IterationResult[]> {
 	const { logger, git, runner, runnerName } = session;
 
@@ -243,6 +322,15 @@ export async function runAfkLoop<T extends { number: number }>(
 
 		// Commit succeeded — mark issue complete
 		await source.completeIssue(issue);
+
+		// Sync completion back to external source if configured
+		if (syncBack) {
+			const issuePath = syncBack.getIssuePath(issue);
+			if (issuePath) {
+				await syncBackIssue(issuePath, logger, syncBack.readFile, syncBack.resolveProvider);
+			}
+		}
+
 		logger.log(
 			`Issue ${issue.number}: committed and completed ` + `(${fmtTime(runResult.durationSeconds)})`,
 		);
@@ -257,6 +345,14 @@ export async function runAfkLoop<T extends { number: number }>(
 		logger.log("");
 	}
 
+	// Sync PRD completion back to external source if all issues are done
+	if (syncBack?.prdPath) {
+		const nextIssue = await source.getNextIssue();
+		if (nextIssue === null && results.some((r) => r.success)) {
+			await syncBackPrd(syncBack.prdPath, logger, syncBack.readFile, syncBack.resolveProvider);
+		}
+	}
+
 	// Session summary
 	const totalElapsed = (performance.now() - sessionStart) / 1000;
 	printSummary(results, totalElapsed, logger);

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>

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

@@ -0,0 +1,98 @@
+---
+name: stonecut-review-architecture
+description: Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable.
+---
+
+# Review Architecture
+
+Explore a codebase like an AI would, surface architectural friction, discover opportunities for improving testability, and propose module-deepening refactors.
+
+A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside.
+
+## Process
+
+### 1. Explore the codebase
+
+Use the Agent tool with subagent_type=Explore to navigate the codebase naturally. Do NOT follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small files?
+- Where are modules so shallow that the interface is nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
+- Where do tightly-coupled modules create integration risk in the seams between them?
+- Which parts of the codebase are untested, or hard to test?
+
+The friction you encounter IS the signal.
+
+### 2. Present candidates
+
+Present a numbered list of deepening opportunities. For each candidate, show:
+
+- **Cluster**: Which modules/concepts are involved
+- **Why they're coupled**: Shared types, call patterns, co-ownership of a concept
+- **Dependency category**: See [REFERENCE.md](REFERENCE.md) for the four categories
+- **Test impact**: What existing tests would be replaced by boundary tests
+
+Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
+
+### 3. User picks a candidate
+
+### 4. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would need to rely on
+- A rough illustrative code sketch to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 5.
+
+### 5. Design multiple interfaces
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category, what's being hidden). This brief is independent of the user-facing explanation in Step 4. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1-3 entry points max"
+- Agent 2: "Maximize flexibility — support many use cases and extension"
+- Agent 3: "Optimize for the most common caller — make the default case trivial"
+- Agent 4 (if applicable): "Design around the ports & adapters pattern for cross-boundary dependencies"
+
+Each sub-agent outputs:
+
+1. Interface signature (types, methods, params)
+2. Usage example showing how callers use it
+3. What complexity it hides internally
+4. Dependency strategy (how deps are handled — see [REFERENCE.md](REFERENCE.md))
+5. Trade-offs
+
+Present designs sequentially, then compare them in prose.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid.
+
+### 6. User picks an interface (or accepts recommendation)
+
+### 7. Choose a destination
+
+Ask the user where to save the RFC:
+
+- **Local file** — Save as `.stonecut/<name>/rfc.md` in the project. Ask the user: "What should I name this spec?" Create the `.stonecut/<name>/` directory if it doesn't exist.
+- **GitHub issue** — Create a GitHub issue using `gh issue create --label rfc`. Before creating, ensure the `rfc` label exists:
+
+  ```bash
+  # Only create the label if it doesn't already exist
+  if ! gh label list --search "rfc" --json name --jq '.[].name' | grep -qx "rfc"; then
+    gh label create rfc --description "Request for Comments — architecture/design decision" --color "D93F0B"
+  fi
+  ```
+
+If the project already has a `.stonecut/` directory, default to suggesting local. Otherwise, just ask.
+
+### 8. Write the RFC
+
+Use the template in [REFERENCE.md](REFERENCE.md). Do NOT ask the user to review before creating — just create it and share the result.
+
+The RFC captures design decisions — what was chosen, what was rejected, and why. The PRD writer (whether in this session or a future one) will explore the codebase itself; the RFC's job is to carry the decisions so they don't need to be re-derived. Leave implementation-level detail (exact signatures, migration steps, test file changes) for the PRD and issues.
+
+## Next Step
+
+Once the RFC is saved, ask the user: "Ready to write the PRD? I can run `/stonecut-prd` next."

package/src/skills.ts

@@ -17,7 +17,12 @@ import {
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
 
-export const SKILL_NAMES = ["stonecut-interview", "stonecut-prd", "stonecut-issues"];
+export const SKILL_NAMES = [
+	"stonecut-interview",
+	"stonecut-prd",
+	"stonecut-issues",
+	"stonecut-review-architecture",
+];
 
 /**
  * Return the path to the skills/ directory shipped with this package.

package/src/{github.ts → sources/github.ts}

@@ -1,6 +1,11 @@
-/** GitHub source — wraps the gh CLI to interact with GitHub issues. */
+/**
+ * GitHub source provider — fetches PRDs and issues via the gh CLI.
+ *
+ * Reuses the validation and API patterns from src/github.ts but
+ * structured as a stateless SourceProvider.
+ */
 
-import type { GitHubIssue, GitHubPrd, Source } from "./types";
+import type { IssueData, PrdData, PrdSummary, SourceProvider } from "./types.js";
 
 function runSync(cmd: string[]): { exitCode: number; stdout: string; stderr: string } {
 	const proc = Bun.spawnSync(cmd, {
@@ -14,18 +19,15 @@ function runSync(cmd: string[]): { exitCode: number; stdout: string; stderr: str
 	};
 }
 
-export class GitHubSource implements Source<GitHubIssue> {
-	readonly prdNumber: number;
+export class GitHubSourceProvider implements SourceProvider {
 	readonly owner: string;
 	readonly repo: string;
 
-	constructor(prdNumber: number) {
-		this.prdNumber = prdNumber;
-		GitHubSource.validateGhCli();
-		const [owner, repo] = GitHubSource.getOwnerRepo();
+	constructor() {
+		GitHubSourceProvider.validateGhCli();
+		const [owner, repo] = GitHubSourceProvider.getOwnerRepo();
 		this.owner = owner;
 		this.repo = repo;
-		this.validatePrd();
 	}
 
 	static validateGhCli(): void {
@@ -64,53 +66,98 @@ export class GitHubSource implements Source<GitHubIssue> {
 		throw new Error(`Error: could not parse owner/repo from remote URL: ${url}`);
 	}
 
-	validatePrd(): void {
+	async fetchPrd(identifier: string): Promise<PrdData> {
+		const issueNumber = Number(identifier);
+		this.validatePrdLabel(issueNumber);
+
+		const result = runSync(["gh", "issue", "view", String(issueNumber), "--json", "title,body"]);
+		if (result.exitCode !== 0) {
+			throw new Error(`Error: failed to fetch PRD issue #${issueNumber}.`);
+		}
+		const data = JSON.parse(result.stdout);
+		return {
+			issueNumber,
+			title: (data.title ?? "").trim(),
+			body: (data.body ?? "").trim(),
+		};
+	}
+
+	async fetchIssues(identifier: string): Promise<IssueData[]> {
+		const issueNumber = Number(identifier);
+		const nodes = this.fetchSubIssues(issueNumber);
+		return nodes
+			.sort((a, b) => a.number - b.number)
+			.map((n) => ({
+				title: n.title,
+				body: n.body ?? "",
+				number: n.number,
+				state: n.state,
+			}));
+	}
+
+	async listPrds(): Promise<PrdSummary[]> {
+		const result = runSync([
+			"gh",
+			"issue",
+			"list",
+			"--label",
+			"prd",
+			"--state",
+			"open",
+			"--json",
+			"number,title",
+			"--limit",
+			"50",
+		]);
+		if (result.exitCode !== 0) {
+			throw new Error(`Error: failed to list PRD issues: ${result.stderr.trim()}`);
+		}
+		const data: Array<{ number: number; title: string }> = JSON.parse(result.stdout);
+		return data
+			.sort((a, b) => a.number - b.number)
+			.map((d) => ({ number: d.number, title: d.title }));
+	}
+
+	async onIssueComplete(issueId: string): Promise<void> {
+		const result = runSync(["gh", "issue", "close", issueId]);
+		if (result.exitCode !== 0) {
+			throw new Error(`Error: failed to close issue #${issueId}: ${result.stderr.trim()}`);
+		}
+	}
+
+	async onPrdComplete(prdId: string): Promise<void> {
+		const result = runSync(["gh", "issue", "close", prdId]);
+		if (result.exitCode !== 0) {
+			throw new Error(`Error: failed to close PRD issue #${prdId}: ${result.stderr.trim()}`);
+		}
+	}
+
+	private validatePrdLabel(issueNumber: number): void {
 		const result = runSync([
 			"gh",
 			"issue",
 			"view",
-			String(this.prdNumber),
+			String(issueNumber),
 			"--json",
 			"labels",
 			"-q",
 			".labels[].name",
 		]);
 		if (result.exitCode !== 0) {
-			throw new Error(`Error: GitHub issue #${this.prdNumber} not found.`);
+			throw new Error(`Error: GitHub issue #${issueNumber} not found.`);
 		}
 		const labels = result.stdout
 			.trim()
 			.split("\n")
 			.filter((l) => l);
 		if (!labels.includes("prd")) {
-			throw new Error(`Error: Issue #${this.prdNumber} does not have the 'prd' label.`);
+			throw new Error(`Error: Issue #${issueNumber} does not have the 'prd' label.`);
 		}
 	}
 
-	async getPrdContent(): Promise<string> {
-		const prd = this.getPrd();
-		return prd.body;
-	}
-
-	getPrd(): GitHubPrd {
-		const result = runSync(["gh", "issue", "view", String(this.prdNumber), "--json", "title,body"]);
-		if (result.exitCode !== 0) {
-			throw new Error(`Error: failed to fetch PRD issue #${this.prdNumber}.`);
-		}
-		const data = JSON.parse(result.stdout);
-		return {
-			number: this.prdNumber,
-			title: (data.title ?? "").trim(),
-			body: (data.body ?? "").trim(),
-		};
-	}
-
-	private fetchSubIssues(): Array<{
-		number: number;
-		title: string;
-		state: string;
-		body: string;
-	}> {
+	private fetchSubIssues(
+		issueNumber: number,
+	): Array<{ number: number; title: string; state: string; body: string }> {
 		const query = `
 query($owner: String!, $repo: String!, $number: Int!) {
   repository(owner: $owner, name: $repo) {
@@ -135,7 +182,7 @@ query($owner: String!, $repo: String!, $number: Int!) {
 			"-F",
 			`repo=${this.repo}`,
 			"-F",
-			`number=${this.prdNumber}`,
+			`number=${issueNumber}`,
 			"-f",
 			`query=${query}`,
 		]);
@@ -145,34 +192,4 @@ query($owner: String!, $repo: String!, $number: Int!) {
 		const data = JSON.parse(result.stdout);
 		return data.data.repository.issue.subIssues.nodes;
 	}
-
-	async getNextIssue(): Promise<GitHubIssue | null> {
-		const subIssues = this.fetchSubIssues();
-		const openIssues = subIssues
-			.filter((i) => i.state === "OPEN")
-			.sort((a, b) => a.number - b.number);
-		if (openIssues.length === 0) {
-			return null;
-		}
-		const first = openIssues[0];
-		return {
-			number: first.number,
-			title: first.title,
-			body: first.body ?? "",
-		};
-	}
-
-	async getRemainingCount(): Promise<[number, number]> {
-		const subIssues = this.fetchSubIssues();
-		const total = subIssues.length;
-		const remaining = subIssues.filter((i) => i.state === "OPEN").length;
-		return [remaining, total];
-	}
-
-	async completeIssue(issue: GitHubIssue): Promise<void> {
-		const result = runSync(["gh", "issue", "close", String(issue.number)]);
-		if (result.exitCode !== 0) {
-			throw new Error(`Error: failed to close issue #${issue.number}: ${result.stderr.trim()}`);
-		}
-	}
 }

package/src/sources/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Source provider registry — maps provider names to their implementations.
+ */
+
+import type { SourceProvider } from "./types.js";
+import { GitHubSourceProvider } from "./github.js";
+
+const PROVIDERS: Record<string, new () => SourceProvider> = {
+	github: GitHubSourceProvider,
+};
+
+export function getSourceProvider(name: string): SourceProvider {
+	const Cls = PROVIDERS[name];
+	if (!Cls) {
+		const available = Object.keys(PROVIDERS).sort().join(", ");
+		throw new Error(`Unknown source provider '${name}'. Available providers: ${available}`);
+	}
+	return new Cls();
+}
+
+export type { SourceProvider, PrdData, IssueData, PrdSummary } from "./types.js";