worktrees 0.1.0

data/specs/001-build-a-tool/plan.md

@@ -0,0 +1,241 @@
+# Implementation Plan: Manage Git feature worktrees
+
+
+**Branch**: `[001-build-a-tool]` | **Date**: 2025-09-15 | **Spec**: /Users/drewgoddyn/projects/claude-worktrees/specs/001-build-a-tool/spec.md
+**Input**: Feature specification from `/specs/001-build-a-tool/spec.md`
+
+## Execution Flow (/plan command scope)
+```
+1. Load feature spec from Input path
+   → If not found: ERROR "No feature spec at {path}"
+2. Fill Technical Context (scan for NEEDS CLARIFICATION)
+   → Detect Project Type from context (web=frontend+backend, mobile=app+api)
+   → Set Structure Decision based on project type
+3. Evaluate Constitution Check section below
+   → If violations exist: Document in Complexity Tracking
+   → If no justification possible: ERROR "Simplify approach first"
+   → Update Progress Tracking: Initial Constitution Check
+4. Execute Phase 0 → research.md
+   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
+5. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, or `GEMINI.md` for Gemini CLI).
+6. Re-evaluate Constitution Check section
+   → If new violations: Refactor design, return to Phase 1
+   → Update Progress Tracking: Post-Design Constitution Check
+7. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
+8. STOP - Ready for /tasks command
+```
+
+**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
+- Phase 2: /tasks command creates tasks.md
+- Phase 3-4: Implementation execution (manual or via tools)
+
+## Summary
+Manage lifecycle and navigation of Git feature worktrees via a CLI: create from a chosen base, list and switch between them, and safely clean them up with conservative safety checks and explicit opt-in for branch deletion when fully merged. Technical approach: POSIX shell (bash) tooling built around Git CLI, global hidden worktrees root at `$HOME/.worktrees`, strict naming and validation, and structured output with `--format json` for tooling.
+
+## Technical Context
+**Language/Version**: Bash (POSIX), Git ≥ 2.33  
+**Primary Dependencies**: Git CLI  
+**Storage**: Filesystem (worktrees under `$HOME/.worktrees` by default)  
+**Testing**: bats (planned), shellcheck for linting  
+**Target Platform**: macOS/Linux shells
+**Project Type**: single  
+**Performance Goals**: Responsive CLI; list paging defaults pageSize=20, max=100  
+**Constraints**: Conservative safety for removal; structured outputs; zero external runtimes  
+**Scale/Scope**: Up to ~100 worktrees per repo (paged listing)
+
+## Constitution Check
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+**Simplicity**:
+- Projects: 2 (cli, tests)
+- Using framework directly? (no wrapper classes)
+- Single data model? (no DTOs unless serialization differs)
+- Avoiding patterns? (no Repository/UoW without proven need)
+
+**Architecture**:
+- EVERY feature as library? (no direct app code)
+- Libraries listed: `worktrees-cli` (feature lifecycle commands)
+- CLI per library: commands provide `--help|--version|--format`
+- Library docs: llms.txt/GEMINI.md planned
+
+**Testing (NON-NEGOTIABLE)**:
+- RED-GREEN-Refactor cycle enforced? (test MUST fail first)
+- Git commits show tests before implementation?
+- Order: Contract→Integration→E2E→Unit strictly followed?
+- Real dependencies used? (actual DBs, not mocks)
+- Integration tests for: new libraries, contract changes, shared schemas?
+- FORBIDDEN: Implementation before test, skipping RED phase
+
+**Observability**:
+- Structured logging included?
+- Frontend logs → backend? (unified stream)
+- Error context sufficient?
+
+**Versioning**:
+- Version number assigned? (MAJOR.MINOR.BUILD)
+- BUILD increments on every change?
+- Breaking changes handled? (parallel tests, migration plan)
+
+## Project Structure
+
+### Documentation (this feature)
+```
+specs/[###-feature]/
+├── plan.md              # This file (/plan command output)
+├── research.md          # Phase 0 output (/plan command)
+├── data-model.md        # Phase 1 output (/plan command)
+├── quickstart.md        # Phase 1 output (/plan command)
+├── contracts/           # Phase 1 output (/plan command)
+└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
+```
+
+### Source Code (repository root)
+```
+# Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure]
+```
+
+**Structure Decision**: Option 1 (Single project: src/, tests/)
+
+## Phase 0: Outline & Research
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+   ```
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+## Phase 1: Design & Contracts
+*Prerequisites: research.md complete*
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Generate API contracts** from functional requirements:
+   - For each user action → endpoint
+   - Use standard REST/GraphQL patterns
+   - Output OpenAPI/GraphQL schema to `/contracts/`
+
+3. **Generate contract tests** from contracts:
+   - One test file per endpoint
+   - Assert request/response schemas
+   - Tests must fail (no implementation yet)
+
+4. **Extract test scenarios** from user stories:
+   - Each story → integration test scenario
+   - Quickstart test = story validation steps
+
+5. **Update agent file incrementally** (O(1) operation):
+   - Run `/scripts/bash/update-agent-context.sh cursor` for your AI assistant
+   - Run `/scripts/bash/update-agent-contxt.sh clude` for your AI assistant
+   - If exists: Add only NEW tech from current plan
+   - Preserve manual additions between markers
+   - Update recent changes (keep last 3)
+   - Keep under 150 lines for token efficiency
+   - Output to repository root
+
+**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
+
+## Phase 2: Task Planning Approach
+*This section describes what the /tasks command will do - DO NOT execute during /plan*
+
+**Task Generation Strategy**:
+- Load `/templates/tasks-template.md` as base
+- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
+- Each contract → contract test task [P]
+- Each entity → model creation task [P] 
+- Each user story → integration test task
+- Implementation tasks to make tests pass
+
+**Ordering Strategy**:
+- TDD order: Tests before implementation 
+- Dependency order: Models before services before UI
+- Mark [P] for parallel execution (independent files)
+
+**Estimated Output**: 25-30 numbered, ordered tasks in tasks.md
+
+**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
+
+## Phase 3+: Future Implementation
+*These phases are beyond the scope of the /plan command*
+
+**Phase 3**: Task execution (/tasks command creates tasks.md)  
+**Phase 4**: Implementation (execute tasks.md following constitutional principles)  
+**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
+
+## Complexity Tracking
+*Fill ONLY if Constitution Check has violations that must be justified*
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
+
+
+## Progress Tracking
+*This checklist is updated during execution flow*
+
+**Phase Status**:
+- [x] Phase 0: Research complete (/plan command)
+- [x] Phase 1: Design complete (/plan command)
+- [x] Phase 2: Task planning complete (/plan command - describe approach only)
+- [x] Phase 3: Tasks generated (/tasks command)
+- [x] Phase 4: Implementation complete (Ruby CLI T001-T035)
+- [x] Phase 5: Validation passed (all tests passing, spec-kit gates cleared)
+
+**Gate Status**:
+- [x] Initial Constitution Check: PASS
+- [x] Post-Design Constitution Check: PASS
+- [x] All NEEDS CLARIFICATION resolved
+- [x] Complexity deviations documented (Ruby chosen over Bash for better testing, maintainability)
+
+**Final Status**: ✅ COMPLETE - Ruby implementation delivered with comprehensive test suite
+
+---
+*Based on Constitution v2.1.1 - See `/memory/constitution.md`*

data/specs/001-build-a-tool/quickstart.md

@@ -0,0 +1,67 @@
+# Quickstart: Manage Git feature worktrees
+
+Prerequisites:
+- Git ≥ 2.33
+- macOS or Linux shell (zsh/bash)
+
+Concepts:
+- Feature worktrees are isolated working copies tied to branches, created under a global root (default `$HOME/.worktrees`).
+- Names must match `NNN-kebab-feature` (lowercase, ≤ 40 chars feature part).
+
+Common flows:
+
+## Create a worktree
+```bash
+worktrees create 001-build-a-tool --base main --format json
+```
+
+## List worktrees (paged)
+```bash
+# Text format (default)
+worktrees list --page 1 --page-size 20
+
+# JSON format with all status fields
+worktrees list --format json --page 1 --page-size 20
+
+# Fast JSON format without expensive status checks (for large repos)
+worktrees list --format json --no-status --page-size 50
+```
+
+## Switch to a worktree (allowed even if current is dirty; warning shown)
+```bash
+worktrees switch 001-build-a-tool
+```
+
+## Remove a worktree safely (keep branch)
+```bash
+worktrees remove 001-build-a-tool
+```
+
+## Remove and delete branch when fully merged
+```bash
+worktrees remove 001-build-a-tool --delete-branch --merged-into main
+```
+
+## Check current status
+```bash
+worktrees status
+```
+
+## Advanced Options
+- Use `--root <path>` to override the global worktrees root
+- Use `--reuse-branch` to reuse an existing local branch not checked out elsewhere
+- Use `--sibling` to create a sibling branch when the branch is already checked out in another worktree
+- Use `--no-status` with list command for better performance on large repositories
+- Use `--format json` for structured output suitable for scripts and tools
+
+## Performance Tips
+For repositories with many worktrees (>100):
+```bash
+# Use filters to narrow results
+worktrees list --filter-name "001-*" --filter-base main
+
+# Skip expensive git status checks for faster listing
+worktrees list --no-status --page-size 100
+```
+
+

data/specs/001-build-a-tool/research.md

@@ -0,0 +1,76 @@
+# Research: Manage Git feature worktrees
+
+This document consolidates decisions made to resolve ambiguities and define the technical approach for the Git worktrees management tool. Each decision includes rationale and alternatives considered.
+
+## Unknowns Resolved
+
+### U1. Language/Runtime for CLI
+- Decision: Bash (POSIX-compatible) using Git CLI; require Git ≥ 2.33.
+- Rationale: Native fit for Git operations; zero external runtime; easiest distribution; portable across macOS/Linux.
+- Alternatives considered: Python 3.11 (richer stdlib, dependency mgmt), Node.js 20 (ecosystem). Rejected for added runtime dependency and packaging overhead for v1.
+
+### U2. Default worktrees root
+- Decision: `$HOME/.worktrees` as the global hidden root; override via `--root` flag or config env `WORKTREES_ROOT`.
+- Rationale: Hidden, global, avoids clutter inside repo; clear single place to manage storage.
+- Alternatives considered: Project-local `.worktrees` under repo root (risks clutter, nested repos), `$HOME/worktrees` (not hidden).
+
+### U3. Base detection when not provided
+- Decision: Default to repository default branch (remote HEAD) if available; else `main` if present; else `master`.
+- Mechanism: Use `git symbolic-ref --quiet refs/remotes/origin/HEAD` to detect remote HEAD; fall back via `git show-ref --verify` checks.
+- Rationale: Matches FR-008; ensures predictable default.
+
+### U4. Naming convention enforcement
+- Decision: Enforce regex `^[0-9]{3}-[a-z0-9-]{1,40}$`; case-insensitive uniqueness across worktrees; reserved names `main`, `master` disallowed.
+- Rationale: Meets FR-005; prevents collisions; keeps names readable and sortable.
+- Alternatives considered: Allow uppercase/underscores; rejected for cross-platform safety and simplicity.
+
+### U5. Pre-existing local branch with requested feature name (different base)
+- Decision: Error by default. Provide `--reuse-branch` to reuse if not checked out in any worktree; require explicit `--base` acknowledgment mismatch.
+- Rationale: Safety first; avoids silent divergence.
+
+### U6. Branch already checked out in another worktree
+- Decision: Disallow duplicate checkout. Offer selecting existing worktree or `--sibling <suffix>` to create a sibling branch (e.g., `-2`).
+- Rationale: Aligns FR-013 and Git worktree rules.
+
+### U7. Dirty-state policies
+- Decision: Switching allowed with a prominent warning summarizing dirty state. Removal blocked if tracked changes exist or an operation is in progress; removal blocked if unpushed commits or no upstream. `--force` only deletes untracked/ignored files.
+- Rationale: Matches FR-011.
+
+### U8. Cleanup semantics for tags
+- Decision: Never delete tags automatically. Tag deletion (if desired) must be manual.
+- Rationale: Tags are often shared/released artifacts; high risk to remove automatically.
+
+### U9. Scale expectations and listing
+- Decision: Expect up to ~100 worktrees per repo. Implement filtering by name and base; paging with `--page` and `--page-size` (default 20, max 100).
+- Rationale: Keeps CLI responsive; avoids overwhelming output (Edge case note in spec).
+
+### U10. Safety checks for removal
+- Decision: Consider fully merged only if `git merge-base --is-ancestor <branch> <base>` returns success; require explicit `--delete-branch` and `--merged-into <base>` to delete branch.
+- Rationale: Prevents data loss and enforces explicit user intent.
+
+### U11. Worktree path issues
+- Decision: Prevent creation if target path exists/non-empty; robust quoting for spaces/special chars; treat names differing only by case as duplicates on case-insensitive filesystems.
+- Rationale: Cross-platform correctness and safety.
+
+### U12. Non-repo execution
+- Decision: Detect repo root via `git rev-parse --show-toplevel`; refuse commands outside a repo; print clear guidance.
+- Rationale: Avoid misuse and unclear state.
+
+## Best Practices Collected
+- Provide `--format json|text` across commands; default `text` for humans, `json` for tooling.
+- Print actionable errors with remediation steps (e.g., suggest `git fetch --all --prune` when base missing remotely).
+- Log to stderr for warnings/errors; stdout reserved for primary output payloads.
+- Exit codes: 0 success, 2 validation error, 3 precondition failure, 4 conflict, 5 unsafe state, 6 not found.
+
+## Decisions Summary
+- Language: Bash + Git CLI; Tests planned with `bats` during implementation.
+- Root: `$HOME/.worktrees` with `--root` and `WORKTREES_ROOT` override.
+- Naming: `^[0-9]{3}-[a-z0-9-]{1,40}$`, case-insensitive unique; reserved names disallowed.
+- Defaults: Base auto-detected from remote HEAD; explicit override supported.
+- Safety: Conservative removal policy; explicit flags for dangerous ops.
+- Scale: Paging and filtering supported in list.
+- Tags: Never auto-deleted.
+
+All NEEDS CLARIFICATION items are resolved above.
+
+

data/specs/001-build-a-tool/spec.md

@@ -0,0 +1,153 @@
+# Feature Specification: Manage Git feature worktrees
+
+**Feature Branch**: `[001-build-a-tool]`  
+**Created**: 2025-09-15  
+**Status**: Draft  
+**Input**: User description: "Build a tool to manage Git worktrees for feature-based development: enable quick creation of feature-specific worktrees from a chosen base, list and switch between worktrees, enforce clear naming to avoid collisions, and support safe cleanup of completed worktrees. Focus narrowly on worktree lifecycle and navigation."
+
+## Execution Flow (main)
+```
+1. Parse user description from Input
+   → If empty: ERROR "No feature description provided"
+2. Extract key concepts from description
+   → Identify: actors, actions, data, constraints
+3. For each unclear aspect:
+   → Mark with [NEEDS CLARIFICATION: specific question]
+4. Fill User Scenarios & Testing section
+   → If no clear user flow: ERROR "Cannot determine user scenarios"
+5. Generate Functional Requirements
+   → Each requirement must be testable
+   → Mark ambiguous requirements
+6. Identify Key Entities (if data involved)
+7. Run Review Checklist
+   → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
+   → If implementation details found: ERROR "Remove tech details"
+8. Return: SUCCESS (spec ready for planning)
+```
+
+---
+
+## ⚡ Quick Guidelines
+- ✅ Focus on WHAT users need and WHY
+- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
+- 👥 Written for business stakeholders, not developers
+
+### Section Requirements
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+When creating this spec from a user prompt:
+1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
+2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
+3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+4. **Common underspecified areas**:
+   - User types and permissions
+   - Data retention/deletion policies  
+   - Performance targets and scale
+   - Error handling behaviors
+   - Integration requirements
+   - Security/compliance needs
+
+---
+
+## User Scenarios & Testing *(mandatory)*
+
+### Primary User Story
+As a developer working across multiple features, I want to create isolated Git worktrees per feature, list and switch between them, and safely clean them up when finished so that I can work in parallel without polluting my main repository workspace.
+
+### Acceptance Scenarios
+1. **Given** no existing worktree for a requested feature, **When** a developer requests creation from a specified base, **Then** a uniquely named feature worktree is created and made active.
+2. **Given** multiple worktrees exist, **When** a developer requests a list of worktrees, **Then** the system returns each worktree's name, source/base reference, and whether it is currently active.
+3. **Given** a feature worktree exists, **When** a developer switches to it, **Then** the active working copy becomes that worktree without modifying other worktrees.
+4. **Given** a finished worktree, **When** a developer requests safe cleanup, **Then** the worktree is removed without unintended data loss, the branch is kept by default, and branch deletion is allowed only with explicit opt-in and only if fully merged into a specified base.
+5. **Given** a worktree has uncommitted changes, **When** a developer switches away to another worktree, **Then** switching proceeds and a clear warning summarizes the dirty state.
+6. **Given** a worktree has uncommitted changes or untracked/ignored files, **When** a developer requests removal, **Then** removal is blocked by default; explicit force is allowed only for untracked/ignored files; removal is never allowed if there are unpushed commits or an operation (e.g., rebase/merge/cherry-pick) in progress.
+
+### Edge Cases
+- Base reference does not exist or is unreachable.
+- Duplicate or invalid feature name: prevent collisions and guide the user to choose a different name.
+- Existing branch without a corresponding worktree: on create, reuse the existing branch for the new worktree; no new branch is required.
+- Attempt to remove the currently active worktree: disallow and guide the user.
+- Worktree directory manually moved or deleted outside the tool: detect and reconcile or offer cleanup.
+- Large repositories with many worktrees: provide filtering or paging for listing. [NEEDS CLARIFICATION: expected scale and limits]
+- Base reference exists only on remote and is not fetched locally: auto-fetch the base; on fetch failure, abort with clear guidance.
+- Branch already checked out in another worktree: disallow duplicate checkout; offer selecting the existing worktree or creating a sibling branch via explicit opt-in.
+- Pre-existing local branch name conflicts with requested feature name (different base): decide whether to reuse or error. [NEEDS CLARIFICATION]
+- Target worktree path already exists or is non-empty: prevent creation and guide to a new path/name.
+- Worktree path contains spaces or special characters: ensure operations handle quoting safely.
+- Case-insensitive filesystem collisions (e.g., macOS): treat names differing only by case as duplicates.
+- Dirty worktree handling: switching away is allowed with a warning; removal is blocked if tracked changes are present and blocked by default for untracked/ignored files unless explicitly forced; removal is never allowed if there are unpushed commits/no upstream or an operation in progress.
+- Command executed outside a Git repository or inside a nested repository: detect repository root and prevent misuse with clear messaging.
+- Stale worktree metadata after manual filesystem changes: offer pruning or repair.
+- Environment lacks required Git features/version for worktrees: detect and inform with remediation steps.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+- **FR-001**: The system MUST allow developers to create isolated feature worktrees from a specified base reference.
+- **FR-002**: The system MUST list existing worktrees for the current repository with name, base reference, and active status.
+- **FR-003**: The system MUST switch the active working copy to a selected worktree on request.
+- **FR-004**: The system MUST safely remove a finished worktree without unintended data loss; keep the branch by default, and allow branch deletion only with explicit opt-in and only if fully merged into a specified base.
+- **FR-005**: The system MUST enforce this naming convention and uniqueness:
+   - Format: NNN-kebab-feature
+   - Charset: lowercase [a-z0-9-]
+   - Length: feature segment ≤ 40 characters
+   - Uniqueness: case-insensitive unique across existing worktrees
+   - Reserved names disallowed: 'main', 'master'
+- **FR-006**: The system MUST validate preconditions (e.g., base reference existence, clean state) and provide actionable feedback, including auto-fetching a remote-only base before creation and aborting with clear guidance on failure.
+- **FR-007**: The system MUST present clear status of the current worktree (name, base reference, path).
+- **FR-008**: The system MUST select a default base when none is provided: use the repository's default branch (remote HEAD) when available; else use 'main' if it exists; else use 'master'. The chosen base MUST be displayed and always overrideable via flag/config.
+- **FR-009**: The system MUST handle invalid or conflicting operations with informative messages (e.g., cannot remove active worktree).
+- **FR-010**: The system MUST default to a global hidden worktrees root under the user's workspace (kept separate from primary repositories) and MUST allow override via flag and config. The chosen location MUST be displayed.
+- **FR-011**: The system MUST enforce conservative dirty-state policies: allow switching between worktrees even if the current worktree is dirty (with a visible warning); block removal if tracked changes are present or an operation is in progress; block removal if the branch has unpushed commits or no upstream; allow explicit force solely to delete untracked/ignored files.
+- **FR-012**: The system SHOULD provide responsive UX for common operations (create, list, switch); specific performance targets are deferred until post-MVP metrics are collected.
+ - **FR-013**: When a requested branch is already checked out in another worktree, the system MUST disallow duplicate checkout and offer either selecting the existing worktree or creating a sibling branch via explicit opt-in.
+ - **FR-014**: When creating a worktree and a local branch with the requested name exists and is not checked out in any worktree, the system MUST reuse that branch rather than creating a new branch.
+ - **FR-015**: For v1, the system MUST expose a command-line interface. Non-CLI interfaces are out of scope.
+ - **FR-016**: For v1, the system MUST operate only on the current Git repository; cross-repository scanning or actions are out of scope.
+
+*Ambiguities to resolve:*
+- Cleanup semantics are [NEEDS CLARIFICATION: whether to delete associated tags]
+
+### Key Entities *(include if feature involves data)*
+- **Feature Worktree**: An isolated working copy tied to a specific feature branch; created from a base reference.
+- **Base Reference**: The source branch or commit from which a feature worktree is created.
+- **Feature Name**: The human-readable label used to name and identify a worktree.
+- **Repository**: The Git project within which feature worktrees are managed.
+
+---
+
+## Review & Acceptance Checklist
+*GATE: Automated checks run during main() execution*
+
+### Content Quality
+- [ ] No implementation details (languages, frameworks, APIs)
+- [ ] Focused on user value and business needs
+- [ ] Written for non-technical stakeholders
+- [ ] All mandatory sections completed
+
+### Requirement Completeness
+- [ ] No [NEEDS CLARIFICATION] markers remain
+- [ ] Requirements are testable and unambiguous  
+- [ ] Success criteria are measurable
+- [ ] Scope is clearly bounded
+- [ ] Dependencies and assumptions identified
+
+---
+
+## Execution Status
+*Updated by main() during processing*
+
+- [ ] User description parsed
+- [ ] Key concepts extracted
+- [ ] Ambiguities marked
+- [ ] User scenarios defined
+- [ ] Requirements generated
+- [ ] Entities identified
+- [ ] Review checklist passed
+
+---
+
+