procedure-cli 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:z.ai)",
+      "mcp__plugin_context7_context7__resolve-library-id",
+      "mcp__plugin_context7_context7__query-docs",
+      "Bash(npm init:*)",
+      "Bash(npm install:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx tsx:*)",
+      "WebFetch(domain:skills.sh)",
+      "WebFetch(domain:openclaw.com)",
+      "WebSearch",
+      "Bash(npm run typecheck:*)",
+      "Bash(npm run build:*)",
+      "Bash(pnpm install:*)",
+      "Bash(node -e:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)"
+    ]
+  }
+}

package/.env.example

@@ -0,0 +1,2 @@
+ZAI_API_KEY=
+OPENAI_API_KEY=

package/AGENTS.md

@@ -0,0 +1,113 @@
+# Repository Guidelines
+
+This file provides guidance to coding agents (including Codex) working in this repository.
+
+See `docs/PRD.md` for product requirements and `docs/USER-STORIES.md` for acceptance criteria.
+
+## Build & Test
+
+```bash
+npm run dev                 # Run CLI directly (tsx, no build step)
+npm run typecheck           # Typecheck (fast — run first)
+npm run lint                # Alias of typecheck
+npm run build               # Compile to dist/
+npx tsx src/cli.tsx         # Run entry point directly
+```
+
+Important safety note: never run `npm run dev` from this repo root when validating scaffolding behavior. Generation writes to `process.cwd()`. Use a temp directory.
+
+## Code Style
+
+- TypeScript strict mode, ESM (`"type": "module"` in `package.json`).
+- JSX runtime: `react-jsx`.
+- Ink UI components use `.tsx`; pure logic modules use `.ts`.
+- Handlebars templates use `.hbs` in `templates/`.
+- Providers live in `src/providers/`, one provider per file.
+- Never hardcode API keys; use `ZAI_API_KEY` and `OPENAI_API_KEY`.
+
+## Architecture
+
+- Entry point: `src/cli.tsx`
+- UI root / wizard controller: `src/app.tsx`
+- Step implementations: `src/steps/`
+- Reusable UI components: `src/components/`
+- Core logic: `src/lib/`
+  - `template.ts`: Handlebars rendering + file scaffolding
+  - `powerline.ts`: Claude powerline setup
+  - `git.ts`: git init + initial commit flow
+  - `fs.ts`: filesystem helpers
+  - `types.ts`: shared type definitions
+- Templates: `templates/`
+- Config: `config/`
+- Docs: `docs/`
+
+## Workflow
+
+### Planning
+- Use planning for non-trivial changes (3+ steps or architecture-impacting work).
+- If execution deviates materially, stop and re-plan.
+
+### Verification
+- Do not mark work complete without evidence.
+- Minimum verification: `npm run typecheck` and `npm run build`.
+
+### Bug Fixing
+- Resolve root cause; avoid temporary patches.
+- Ground fixes in reproducible evidence (logs, failing behavior, code path).
+
+### Elegance
+- For non-trivial changes, prefer clean, maintainable solutions over tactical hacks.
+- Avoid over-engineering simple fixes.
+
+## Task Management
+
+### Solo Work
+1. Plan the approach.
+2. Implement in small, coherent changes.
+3. Verify before claiming completion.
+4. Update procedural docs when corrected by the user.
+
+### Agent Teams
+1. Plan before delegation.
+2. Assign clear deliverables per task.
+3. Keep file ownership non-overlapping across agents.
+4. Include file paths and constraints in handoffs.
+
+## Code Review & Fix Logging
+
+Two append-only logs live at repo root: `CODE-REVIEW.md` and `CODE-FIXED.md`.
+
+### CODE-REVIEW.md
+- For review findings only.
+- Entry ID format: `CR-YYYYMMDD-###`.
+- Findings ordered by severity (`High`, `Medium`, `Low`).
+- Each finding must include: `file:line` evidence, recommendation, and status (`New`, `Still Open`, `Fixed`, `Regressed`, `Not Reproducible`).
+- Scope boundary: when reviewing, write only to `CODE-REVIEW.md`.
+
+### CODE-FIXED.md
+- For fixes applied to review findings.
+- Entry ID format: `CF-YYYYMMDD-###`.
+- Each entry references source `CR-` entry ID.
+- Log only actions taken, changed files/lines, deferred rationale, and verification results.
+- Scope boundary: when fixing, write only to `CODE-FIXED.md`.
+
+### Procedure
+1. Reviewing: read latest `CODE-REVIEW.md` and latest `CODE-FIXED.md` first; append a new `CR-` entry to `CODE-REVIEW.md`.
+2. Fixing: read review + fix logs; fix unresolved findings; append a new `CF-` entry to `CODE-FIXED.md`.
+3. Re-reviewing: append a new `CR-` entry with validation matrix and status updates.
+
+## Core Principles
+
+- Simplicity first.
+- Root-cause rigor over temporary fixes.
+- Minimal necessary code impact.
+
+## Lessons (Project-Specific)
+
+- Keep timeline `│` lines vertically aligned.
+- Validate required wizard inputs.
+- Use select menus for known-option fields (package manager, license, architecture).
+- Keep errors visually distinct and below inputs.
+- Keep generation confirmation explicit before file writes.
+- Tech stack multi-select should prefill from Stack & Style selections.
+- If generation is skipped, end-state messaging must not imply files were scaffolded.

package/CLAUDE.md

@@ -0,0 +1,136 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+See docs/PRD.md for product requirements and docs/USER-STORIES.md for user stories with acceptance criteria.
+
+## Build & Test
+
+```bash
+npm run dev                 # Run CLI directly (tsx, no build step)
+npm run typecheck           # Typecheck (fast — run first)
+npm run build               # Compile to dist/
+npx tsx src/cli.tsx         # Run entry point directly
+```
+
+## Code Style
+
+- TypeScript strict mode, ESM (`"type": "module"` in package.json)
+- JSX runtime: `react-jsx` (no `import React` needed in components, but keep it for clarity in entry points)
+- Ink components use `.tsx` extension; pure logic uses `.ts`
+- Handlebars templates use `.hbs` extension in `templates/`
+- Providers live in `src/providers/` — one file per provider, each exports a single provider instance
+- Environment variables for API keys: `ZAI_API_KEY`, `OPENAI_API_KEY` (never hardcode)
+
+## Architecture
+
+- **Entry point**: `src/cli.tsx` — parses args, calls `render(<App />)`
+- **UI layer**: `src/app.tsx` — Ink root component, wizard controller with 7-step flow
+- **Wizard steps**: `src/steps/` — one component per step, each receives `onComplete` callback
+- **UI components**: `src/components/` — banner, timeline, step-indicator, gutter-line, guttered-select
+- **Core logic**: `src/lib/` — pure functions, no UI
+  - `template.ts` — Handlebars rendering, file scaffolding
+  - `powerline.ts` — Claude Code powerline setup (from setup-powerline.sh logic)
+  - `git.ts` — git init + initial commit
+  - `fs.ts` — directory/file helpers
+  - `types.ts` — WizardAnswers interface, StepId type
+- **Templates**: `templates/` — Handlebars files (.hbs) rendered with wizard answers into target projects
+- **Config**: `config/` — defaults, stack presets, bundled powerline config
+- **AI providers**: `src/providers/` — Z.ai uses `@ai-sdk/openai-compatible` (GLM models), OpenAI uses `@ai-sdk/openai`
+- **AI SDK 6**: All AI calls go through Vercel AI SDK 6 (`ai` package). Use `generateText`, `streamText`, or `generateObject` — not raw fetch
+- **Docs**: `docs/` — PRD, User Stories (Gherkin A/C), methodology explainer (Vietnamese)
+
+## Workflow
+
+### Planning
+- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
+- If something goes sideways, STOP and re-plan — don't keep pushing
+- A good plan lets you one-shot the implementation
+
+### Verification
+- Never mark a task complete without proving it works
+- Run `npm run typecheck` then `npm run dev` to verify
+- Ask yourself: "Would a staff engineer approve this?"
+
+### Self-Improvement
+- After ANY correction from the user: update the Lessons section below
+- Write rules that prevent the same mistake from recurring
+
+### Bug Fixing
+- Given a bug report: just fix it. Don't ask for hand-holding
+- Point at logs, errors, failing tests — then resolve them
+
+### Elegance
+- For non-trivial changes: pause and ask "is there a more elegant way?"
+- If a fix feels hacky, step back and implement the clean solution
+- Skip this for simple, obvious fixes — don't over-engineer
+
+## Task Management
+
+### Solo Work
+1. Plan first (plan mode for complex tasks)
+2. Track progress with TaskCreate/TaskUpdate for multi-step work
+3. Verify before claiming done
+4. Update Lessons after corrections
+
+### Agent Teams
+1. Plan-then-team: design approach BEFORE spawning a team
+2. Each task = one clear deliverable with verification steps
+3. File ownership: each teammate owns specific files — NEVER have two edit the same file
+4. Include file paths and constraints in task descriptions — teammates don't inherit context
+5. DMs by default, broadcast only for critical blocking issues
+6. 3-5 teammates max
+
+## Code Review & Fix Logging
+
+Two tracking files live at the project root. Both are append-only logs — never delete or rewrite past entries.
+
+### CODE-REVIEW.md — review findings
+- Created/appended during code review sessions.
+- Entry ID format: `CR-YYYYMMDD-###` (zero-padded sequence per day).
+- Findings ordered by severity (`High`, `Medium`, `Low`).
+- Every finding includes `file:line` evidence, a clear recommendation, and `Status` (`New`, `Still Open`, `Fixed`, `Regressed`, `Not Reproducible`).
+
+### CODE-FIXED.md — fix results
+- Created/appended when fixing findings from CODE-REVIEW.md.
+- Entry ID format: `CF-YYYYMMDD-###`.
+- Each entry references its source review by `CR-` Entry ID — do NOT re-describe findings, only document actions taken.
+- Fixed findings include `file:line` for every change made.
+- Deferred findings include rationale and a revisit trigger.
+- Verification section must confirm `npm run typecheck` + `npm run build` status after fixes.
+
+### Procedure
+1. **Reviewing**:
+   - **First**: Read CODE-REVIEW.md → Read CODE-FIXED.md → understand current state of findings and fixes.
+   - **Then**: Read codebase → append findings to CODE-REVIEW.md with a new `CR-` entry (write to CODE-REVIEW.md only, never modify CODE-FIXED.md).
+   - **Never** fix code during a reviewing process.
+2. **Fixing**:
+   - **First**: Read CODE-REVIEW.md → Read CODE-FIXED.md → identify unfixed findings.
+   - **Then**: Fix only unfixed findings → append a new `CF-` entry to CODE-FIXED.md (write to CODE-FIXED.md only, never modify CODE-REVIEW.md).
+   - **Never** perform a code review during a fixing process.
+
+## Core Principles
+
+- **Simplicity First**: Make every change as simple as possible. Minimal code impact.
+- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
+- **Minimal Impact**: Changes should only touch what's necessary.
+
+## Lessons
+
+- Timeline `│` lines must stay vertically aligned — never indent content in a way that breaks the straight line from dot to dot
+- Required wizard fields must validate: don't allow empty submissions for project name, description, etc.
+- Active step needs visual animation (spinner/pulse) so user knows the CLI is waiting for input
+- Errors display below the input field in a distinct color (red/yellow) — never inline with the prompt
+- Completed steps need visual acknowledgment (checkmark, color change) beyond just swapping the dot symbol
+- Always add an intro/tagline under the ASCII banner so the user knows what the tool does
+- NEVER run `npm run dev` from the procedure project directory — scaffolding writes to cwd and overwrites procedure's own files. Always test in a temp directory.
+- Select menus (not text input) for fields with known options: package manager, license, architecture pattern
+- Don't prefill fields from unrelated previous answers (e.g., project name → description)
+- Architecture notes should be auto-generated from the selected pattern — users may not know best practices
+- Generation step must show a summary and ask for confirmation before writing files
+- Use `<Text>` not `<Box>` for single-line elements — `<Box>` creates flex containers that add visual gaps
+- Step components must return `<>` fragments, NOT `<Box flexDirection="column">` — only timeline.tsx gets the outer Box
+- Completed step summaries go on a SEPARATE `│  ` line below the step name, not on the same line (prevents wrapping)
+- Custom GutteredSelect/GutteredMultiSelect for select menus — `@inkjs/ui` Select breaks the `│` gutter line
+- Tech stack multi-select should prefill from Stack & Style selections (language + framework)
+- Stack & Style = dev setup (language, framework, code style → CLAUDE.md). Tech Stack = full product stack (databases, infra → PRD/README)

package/CODE-FIXED.md

@@ -0,0 +1,124 @@
+# Code Fix Log
+
+## Writing Standard
+- Each entry documents fixes applied for a specific `CODE-REVIEW.md` entry.
+- Reference the source review by its Entry ID (e.g., `CR-20260221-001`). Do NOT re-describe findings — only document actions taken.
+- For finding details, the reader should consult the referenced `CODE-REVIEW.md` entry.
+- Each finding is referenced as `Finding #N (Severity)` matching the review's numbering.
+- Fixed findings must include `file:line` for every change made.
+- Deferred findings must include rationale and a revisit trigger.
+- Verification section must confirm `npm run typecheck` + `npm run build` status after fixes.
+- Language: English only. Tone: Technical, concise, action-focused.
+
+### Entry ID Convention
+- Required field for every entry: `Entry ID`.
+- Format: `CF-YYYYMMDD-###`
+- Example: `CF-20260222-001`
+- `###` is a zero-padded sequence number for that day.
+
+---
+
+## Entry 2026-02-22
+
+### Entry ID
+- `CF-20260222-001`
+
+### Source Review
+- `CR-20260221-001` (CODE-REVIEW.md entry 2026-02-21)
+
+### Fixes Applied
+
+1. Finding #1 (High) — **Fixed**
+- `src/lib/powerline.ts:33` — Changed `--config=~/.claude/powerline-config.json` to `--config=.claude/powerline-config.json` so the status-line command reads from the project-local path where the config is actually written.
+
+2. Finding #2 (Medium) — **Fixed**
+- `src/lib/git.ts:3-11` — Added `hasGitIdentity()` helper that pre-checks `git config user.name` and `git config user.email`.
+- `src/lib/git.ts:13-28` — Refactored `initGit()` to return `{ committed: boolean; reason?: string }`. Skips `git commit` when identity is missing and returns a descriptive reason string.
+
+3. Finding #3 (Medium) — **Fixed**
+- `src/lib/powerline.ts:21-29` — Wrapped `JSON.parse(raw)` in try/catch; malformed `.claude/settings.json` now falls back to empty object instead of throwing.
+
+4. Finding #4 (Medium) — **Fixed**
+- `src/lib/template.ts:38-44` — Added `checkConflicts(targetDir)` function that returns list of existing output files that would be overwritten.
+- `src/steps/generation.tsx:5,61,102-113` — Imported `checkConflicts`, added yellow warning in summary phase listing files that will be overwritten before user confirms.
+
+5. Finding #5 (Low) — **Fixed**
+- `src/lib/types.ts:64` — Added `generationSkipped: boolean` field to `WizardAnswers`.
+- `src/app.tsx:49` — Added `generationSkipped: false` to `EMPTY_ANSWERS`.
+- `src/app.tsx:83` — Updated `getSummary` case 5 to return `"skipped"` when `generationSkipped` is true.
+- `src/steps/generation.tsx:9` — Changed `onComplete` prop type to `(partial: Partial<WizardAnswers>) => void`.
+- `src/steps/generation.tsx:35` — On successful generation, calls `onComplete({ generationSkipped: false })`.
+- `src/steps/generation.tsx:48` — On cancel, calls `onComplete({ generationSkipped: true })`.
+- `src/app.tsx:179` — Changed `onComplete={() => handleStepComplete({})}` to `onComplete={handleStepComplete}`.
+
+6. Finding #6 (Low) — **Fixed**
+- `templates/docs/USER-STORIES.md.hbs:1-32` — Added Handlebars `{{#if userStories.length}}` conditional with fallback starter template content when `userStories` is empty. Fallback includes example user story in Gherkin format with clear TODO instructions.
+
+### Deferred
+None — all 6 findings fixed.
+
+### Verification Notes
+- `npm run typecheck`: pass (0 errors)
+- All fixes verified through code inspection.
+
+### Residual Risks / Testing Gaps
+- No automated tests for `checkConflicts()` behavior.
+- No automated tests for `initGit()` across machines with missing git identity.
+- No automated tests for malformed `.claude/settings.json` handling.
+- No automated tests asserting generation summary truthfulness when user cancels.
+- No runtime test for Handlebars `{{#if userStories.length}}` fallback rendering.
+
+---
+
+## Entry 2026-02-22
+
+### Entry ID
+- `CF-20260222-002`
+
+### Source Review
+- `CR-20260221-002` (CODE-REVIEW.md entry 2026-02-21)
+
+### Fixes Applied
+
+1. Finding #7 (Medium) — **Fixed**
+- `src/lib/git.ts:13-20` — Added `hasStagedFiles()` helper that runs `git status --porcelain`; returns `false` when index is empty.
+- `src/lib/git.ts:30-33` — Added early return `{ committed: false, reason: 'Nothing to commit — directory is empty.' }` before identity check, preventing hard crash on empty-directory init.
+
+2. Finding #8 (Low) — **Fixed**
+- `src/app.tsx:133-141` — Wrapped completion message in `answers.generationSkipped` conditional. Skip path shows neutral `"Generation was skipped — no files were written."` Scaffold path retains original project name + doc check message.
+
+3. Finding #6 re-raised (Low, Still Open in CR-20260221-002) — **Already Fixed**
+- Covered by `CF-20260222-001` Finding #6: `templates/docs/USER-STORIES.md.hbs` Handlebars fallback added in previous fix cycle. No further action required.
+
+### Deferred
+None.
+
+### Verification Notes
+- `npm run typecheck`: pass (0 errors)
+- `npm run build`: pass
+
+---
+
+## Entry 2026-02-22
+
+### Entry ID
+- `CF-20260222-003`
+
+### Source Review
+- `CR-20260221-004` (CODE-REVIEW.md entry 2026-02-21)
+
+### Fixes Applied
+
+1. Finding #9 (Low, Still Open) — **Fixed**
+- `src/steps/powerline.tsx:22` — Added `gitCommitted?: boolean` to `SetupResult` interface.
+- `src/steps/powerline.tsx:41-44` — `runSetup()` now stores `gitResult.committed` in `setupResult.gitCommitted`.
+- `src/steps/powerline.tsx:125-133` — "Git repository initialized." only renders when `setupResult.gitCommitted` is true. When commit failed, only the yellow warning with reason is shown (no mixed success/failure messaging).
+
+### Deferred
+None.
+
+### Verification Notes
+- `npm run typecheck`: pass
+- `npm run build`: pass
+
+---

package/CODE-REVIEW.md

@@ -0,0 +1,253 @@
+# Code Review Log
+
+## Writing Standard
+- Language: English only.
+- Tone: Technical, concise, objective, and evidence-based.
+- Ordering: Findings listed by severity (`High`, `Medium`, `Low`).
+- Evidence: Every finding includes at least one concrete file reference (`path:line`).
+- Actionability: Every finding includes a clear recommendation.
+- Validation: Verification notes must be based on actual checks (inspection and/or command output).
+- Lifecycle: Each finding includes `Status`: `New`, `Still Open`, `Fixed`, `Regressed`, or `Not Reproducible`.
+
+### Entry ID Convention
+- Required field for every entry: `Entry ID`
+- Format: `CR-YYYYMMDD-###`
+- Example: `CR-20260221-001`
+
+---
+
+## Entry 2026-02-21
+
+### Entry ID
+- `CR-20260221-001`
+
+### Scope
+- Full review of current `procedure` CLI codebase.
+- Focus areas: scaffolding safety, setup reliability, output integrity, and runtime checks.
+
+### Findings (ordered by severity)
+
+1. High - Powerline setup writes config to project-local path but references home-directory config (`Status: New`)
+- `src/lib/powerline.ts:29`
+- `src/lib/powerline.ts:41`
+- `settings.json` is configured with `--config=~/.claude/powerline-config.json`, but setup copies config to `<targetDir>/.claude/powerline-config.json`.
+- This creates a path mismatch: generated config may not be the file that the configured command reads.
+- Recommendation: align both paths. Either copy config to `~/.claude/powerline-config.json` or point the status-line command at `<targetDir>/.claude/powerline-config.json`.
+
+2. Medium - Git bootstrap can fail on machines without global git identity (`Status: New`)
+- `src/lib/git.ts:8`
+- `initGit()` runs `git commit` unconditionally; this fails when `user.name`/`user.email` are not configured.
+- Recommendation: pre-check git identity and show a guided fallback, or skip initial commit when identity is missing.
+
+3. Medium - `settings.json` parsing is not resilient to malformed existing config (`Status: New`)
+- `src/lib/powerline.ts:22`
+- `src/lib/powerline.ts:23`
+- Existing `.claude/settings.json` is parsed without `try/catch`; malformed JSON aborts setup.
+- Recommendation: wrap JSON parse in defensive handling (fallback to empty object + warning message).
+
+4. Medium - Generation flow can overwrite existing files without confirmation (`Status: New`)
+- `src/lib/template.ts:23`
+- `src/lib/template.ts:44`
+- `src/steps/generation.tsx:33`
+- Scaffolding writes directly into `process.cwd()` and unconditionally overwrites files such as `README.md`, `CLAUDE.md`, and docs.
+- Recommendation: add collision detection and explicit overwrite confirmation (or backup/skip mode).
+
+5. Low - "Skip generation" path still marks generation step as completed in timeline summary (`Status: New`)
+- `src/steps/generation.tsx:47`
+- `src/app.tsx:82`
+- `src/app.tsx:177`
+- Canceling generation advances the wizard, and summary still reports `"files generated"`, which can be inaccurate.
+- Recommendation: track generation result explicitly (`generated: true/false`) and render truthful summary text.
+
+6. Low - Generated `USER-STORIES.md` can be nearly empty in normal flow (`Status: New`)
+- `src/steps/product-context.tsx:80`
+- `templates/docs/USER-STORIES.md.hbs:3`
+- Wizard currently sets `userStories: []` with no later collection step, so output often contains only title/header.
+- Recommendation: either collect at least one story in wizard flow or generate a starter template section when `userStories` is empty.
+
+### Verification Notes
+- `npm run lint`: pass (`tsc --noEmit`).
+- `npm run build`: pass (`tsc`).
+- Runtime checks performed in temp directories with compiled modules:
+- `setupPowerline()` writes `.claude/powerline-config.json` but status command references `~/.claude/powerline-config.json`.
+- `setupPowerline()` throws on malformed `.claude/settings.json` (`SyntaxError`).
+- `initGit()` failed at `git commit` in environment without configured identity.
+- `scaffoldAll()` overwrote pre-existing `README.md` content.
+- `scaffoldAll()` with default wizard-shaped payload produced a mostly empty `docs/USER-STORIES.md` (`# demo — User Stories` only).
+
+### Residual Risks / Testing Gaps
+- No automated tests for overwrite-protection behavior in generation flow.
+- No automated tests for malformed `.claude/settings.json` handling.
+- No automated tests for `initGit()` behavior across machines with missing git identity.
+- No tests asserting generation summary truthfulness when user cancels.
+
+---
+
+## Entry 2026-02-21
+
+### Entry ID
+- `CR-20260221-002`
+
+### Supersedes
+- `CR-20260221-001`
+
+### Scope
+- Validate `CR-20260221-001` findings against current code.
+- Perform a fresh review pass for post-fix regressions and remaining issues.
+
+### Validation Matrix
+| Finding # | Previous Severity | Current Status | Evidence | Notes |
+|-----------|-------------------|----------------|----------|-------|
+| 1 | High | Fixed | `src/lib/powerline.ts:34`, `src/lib/powerline.ts:46` | Status-line command now points to project-local `.claude/powerline-config.json`, matching copied destination. |
+| 2 | Medium | Fixed | `src/lib/git.ts:13`, `src/lib/git.ts:19`, `src/lib/git.ts:27` | `initGit()` now checks identity and can return `{ committed: false, reason }` instead of failing immediately for missing identity. |
+| 3 | Medium | Fixed | `src/lib/powerline.ts:22`, `src/lib/powerline.ts:25` | Existing `settings.json` parse is wrapped in `try/catch`; malformed JSON no longer aborts setup. |
+| 4 | Medium | Fixed | `src/lib/template.ts:38`, `src/steps/generation.tsx:61`, `src/steps/generation.tsx:108` | Generation step now detects collisions and explicitly warns users before proceeding. |
+| 5 | Low | Fixed | `src/steps/generation.tsx:48`, `src/app.tsx:84` | Generation skip state is tracked and reflected in step summary (`"skipped"`). |
+| 6 | Low | Still Open | `src/steps/product-context.tsx:80`, `templates/docs/USER-STORIES.md.hbs:3` | `userStories` remains hardcoded to empty with no collection step. |
+
+### Findings (ordered by severity)
+1. Medium - Git init flow can hard-fail when Generation is skipped in an empty directory (`Finding #7`, `Status: New`)
+- `src/lib/git.ts:26`
+- `src/steps/powerline.tsx:47`
+- `initGit()` always attempts a commit. If no files exist (e.g., user skips generation in an empty folder), `git commit` fails and Powerline step enters unrecoverable error state.
+- Recommendation: allow empty initial commit (`--allow-empty`) or skip commit when index is empty while still completing setup.
+
+2. Low - Final completion message can be misleading when Generation was skipped (`Finding #8`, `Status: New`)
+- `src/app.tsx:134`
+- `src/app.tsx:137`
+- Completion text always says project "has been scaffolded" and prompts to check generated docs, even when step 6 was skipped.
+- Recommendation: gate final message content on `generationSkipped` and show a neutral completion message for skip flow.
+
+3. Low - Generated `USER-STORIES.md` can still be nearly empty (`Finding #6`, `Status: Still Open`)
+- `src/steps/product-context.tsx:80`
+- `templates/docs/USER-STORIES.md.hbs:3`
+- Wizard still outputs `userStories: []`, so file may contain only title/header.
+- Recommendation: collect user stories during wizard flow or render a starter section/template when array is empty.
+
+### Verification Notes
+- `npm run typecheck`: pass.
+- `npm run build`: pass.
+- Runtime probes:
+- `setupPowerline()` now writes a status command using `--config=.claude/powerline-config.json` and succeeds with malformed existing settings (parse fallback observed).
+- `initGit()` succeeds when files exist; still fails on empty repo commit path.
+
+### Residual Risks / Testing Gaps
+- No automated test for `initGit()` empty-index behavior.
+- No integration test for skip-generation + git-init flow.
+- No automated test asserting end-screen messaging for `generationSkipped`.
+
+---
+
+## Entry 2026-02-21
+
+### Entry ID
+- `CR-20260221-003`
+
+### Supersedes
+- `CR-20260221-002`
+
+### Scope
+- Validate `CR-20260221-002` findings against current code.
+- Perform a new post-fix review pass for regressions and unresolved issues.
+
+### Validation Matrix
+| Finding # | Previous Severity | Current Status | Evidence | Notes |
+|-----------|-------------------|----------------|----------|-------|
+| 7 | Medium | Fixed | `src/lib/git.ts:28`, `src/lib/git.ts:29` | Empty-index case is now handled; commit is skipped with a structured reason. |
+| 8 | Low | Fixed | `src/app.tsx:133`, `src/app.tsx:134`, `src/app.tsx:137` | Final completion messaging now reflects `generationSkipped`. |
+| 6 | Low | Still Open | `src/steps/product-context.tsx:80`, `templates/docs/USER-STORIES.md.hbs:3` | User stories are still not collected in wizard flow. |
+
+### Findings (ordered by severity)
+1. Low - Powerline step can claim git initialized even when commit was skipped (`Finding #9`, `Status: New`)
+- `src/steps/powerline.tsx:125`
+- `src/steps/powerline.tsx:127`
+- `src/steps/powerline.tsx:130`
+- `src/steps/powerline.tsx:132`
+- UI always shows "Git repository initialized." when user selected git setup (`wantGit === true`), even if `initGit()` returned `committed: false` (e.g., empty directory or missing identity). This creates mixed success/failure messaging.
+- Recommendation: track commit outcome separately (e.g., `gitCommitted`) and render success text only when true; otherwise show warning-only state.
+
+2. Low - Generated `USER-STORIES.md` can still be nearly empty (`Finding #6`, `Status: Still Open`)
+- `src/steps/product-context.tsx:80`
+- `templates/docs/USER-STORIES.md.hbs:3`
+- Wizard still outputs `userStories: []`, so generated file may contain only title/header.
+- Recommendation: collect at least one story in wizard flow or render a fallback starter template when empty.
+
+### Verification Notes
+- `npm run typecheck`: pass.
+- `npm run build`: pass.
+- Runtime probe:
+- `initGit()` in empty directory now returns `{ committed: false, reason: "Nothing to commit — directory is empty." }` instead of throwing.
+
+### Residual Risks / Testing Gaps
+- No UI test covering mixed-result messaging in Powerline step (`wantGit` true + `committed` false).
+- No automated test asserting non-empty/default content for generated `docs/USER-STORIES.md`.
+
+---
+
+## Entry 2026-02-21
+
+### Entry ID
+- `CR-20260221-004`
+
+### Supersedes
+- `CR-20260221-003`
+
+### Scope
+- Correct review status drift by reconciling against latest `CODE-FIXED.md`.
+- Run a fresh current-state review after reconciliation.
+
+### Validation Matrix
+| Finding # | Previous Severity | Current Status | Evidence | Notes |
+|-----------|-------------------|----------------|----------|-------|
+| 6 | Low | Fixed | `CODE-FIXED.md:54`, `templates/docs/USER-STORIES.md.hbs:3`, `templates/docs/USER-STORIES.md.hbs:23` | Previously mis-labeled as open in `CR-20260221-003`; fix existed in `CF-20260222-001` and template fallback is present. |
+| 9 | Low | Still Open | `src/steps/powerline.tsx:125`, `src/steps/powerline.tsx:130` | Success and warning can render together when commit is skipped. |
+
+### Findings (ordered by severity)
+1. Low - Powerline step can claim git initialized even when commit was skipped (`Finding #9`, `Status: Still Open`)
+- `src/steps/powerline.tsx:125`
+- `src/steps/powerline.tsx:127`
+- `src/steps/powerline.tsx:130`
+- `src/steps/powerline.tsx:132`
+- UI always shows "Git repository initialized." when `wantGit` is true, even when `initGit()` reports `{ committed: false, reason }`.
+- Recommendation: track commit outcome (e.g., `gitCommitted`) and render the success line only when a commit actually succeeded.
+
+### Verification Notes
+- Procedure compliance: read latest `CODE-REVIEW.md` and latest `CODE-FIXED.md` before this review.
+- `npm run typecheck`: pass.
+- `npm run build`: pass.
+- Runtime probe: scaffolding with empty `userStories` now renders fallback user-story starter content (`fallback-ok`), confirming `Finding #6` is fixed.
+
+### Residual Risks / Testing Gaps
+- No UI test for Powerline mixed-result messaging (`wantGit` true + `committed` false).
+
+---
+
+## Entry 2026-02-21
+
+### Entry ID
+- `CR-20260221-005`
+
+### Supersedes
+- `CR-20260221-004`
+
+### Scope
+- Fresh review cycle after `CF-20260222-003`.
+- Validate open findings against latest code and current build/typecheck status.
+
+### Validation Matrix
+| Finding # | Previous Severity | Current Status | Evidence | Notes |
+|-----------|-------------------|----------------|----------|-------|
+| 9 | Low | Fixed | `CODE-FIXED.md:112`, `src/steps/powerline.tsx:22`, `src/steps/powerline.tsx:127`, `src/steps/powerline.tsx:132` | Powerline now separates success and warning states by commit outcome (`gitCommitted`). |
+| 6 | Low | Fixed | `CODE-FIXED.md:54`, `templates/docs/USER-STORIES.md.hbs:3`, `templates/docs/USER-STORIES.md.hbs:23` | USER-STORIES fallback remains in place for empty `userStories`. |
+
+### Findings (ordered by severity)
+- No new functional findings identified in this review cycle.
+
+### Verification Notes
+- Procedure compliance: read latest `CODE-REVIEW.md` and latest `CODE-FIXED.md` before review.
+- `npm run typecheck`: pass.
+- `npm run build`: pass.
+- Code inspection confirms `CF-20260222-003` fix is present in current `src/steps/powerline.tsx`.
+
+### Residual Risks / Testing Gaps
+- No automated UI tests currently cover end-to-end Powerline branching (`gitCommitted` true/false).