inkos/docs/plans/2026-03-29-book-create-atomic-init-implementation-plan.md

Book Create Atomic Init Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Make book create atomic so malformed Architect output or failed initialization never leaves a half-built book directory behind.

Architecture: Stage new books in a temporary directory, require Architect to return all mandatory sections, and delete stale incomplete directories instead of resuming them. Promote the staged directory into place only after all initialization steps succeed.

Tech Stack: TypeScript, Vitest, Commander CLI, Node fs/promises

---

Task 1: Lock down Architect missing-section failure

Files:

• Modify: packages/core/src/__tests__/architect.test.ts
• Modify: packages/core/src/agents/architect.ts

Step 1: Write the failing test

Add a test showing generateFoundation() rejects when book_rules is missing from the LLM response.

Step 2: Run test to verify it fails

Run: pnpm vitest run src/__tests__/architect.test.ts -t "throws when a required foundation section is missing"

Step 3: Write minimal implementation

Change parseSections() to throw on missing required sections instead of returning placeholder content.

Step 4: Run test to verify it passes

Run the same Vitest command and confirm it passes.

Task 2: Lock down atomic init rollback

Files:

• Modify: packages/core/src/__tests__/pipeline-runner.test.ts
• Modify: packages/core/src/state/manager.ts
• Modify: packages/core/src/pipeline/runner.ts

Step 1: Write the failing test

Add a regression showing initBook() leaves no final books/<bookId>/ when foundation generation fails.

Step 2: Run test to verify it fails

Run: pnpm vitest run src/__tests__/pipeline-runner.test.ts -t "cleans staged files when initBook fails before foundation is complete"

Step 3: Write minimal implementation

Implement staged initialization in a temporary directory, then rename into place only after success. Add helper methods in StateManager as needed for path-based control-doc/index/snapshot writes.

Step 4: Run test to verify it passes

Run the same Vitest command and confirm it passes.

Task 3: Lock down stale incomplete-directory cleanup at CLI level

Files:

• Modify: packages/cli/src/__tests__/cli-integration.test.ts
• Modify: packages/cli/src/commands/book.ts

Step 1: Write the failing test

Add a CLI regression where a stale incomplete books/<bookId>/ exists before book create, and verify the command does not preserve that stale directory when create later fails.

Step 2: Run test to verify it fails

Run: pnpm vitest run src/__tests__/cli-integration.test.ts -t "removes stale incomplete book directories before retrying create"

Step 3: Write minimal implementation

Replace “resume incomplete book creation” behavior with stale-directory cleanup plus fresh atomic create.

Step 4: Run test to verify it passes

Run the same Vitest command and confirm it passes.

Task 4: Run focused verification

Files:

• No production changes expected

Step 1: Run targeted suite

Run:

pnpm vitest run src/__tests__/architect.test.ts src/__tests__/pipeline-runner.test.ts

in packages/core, and:

pnpm vitest run src/__tests__/cli-integration.test.ts

in packages/cli.

Step 2: Run typecheck

Run:

pnpm typecheck

in packages/core and packages/cli.

Step 3: Commit

git add docs/plans/2026-03-29-book-create-atomic-init-design.md docs/plans/2026-03-29-book-create-atomic-init-implementation-plan.md packages/core/src/agents/architect.ts packages/core/src/pipeline/runner.ts packages/core/src/state/manager.ts packages/core/src/__tests__/architect.test.ts packages/core/src/__tests__/pipeline-runner.test.ts packages/cli/src/commands/book.ts packages/cli/src/__tests__/cli-integration.test.ts
git commit -m "fix: make book creation fail closed"