@accelerationguy/accel 1.0.0

package/modules/drive/src/references/context-management.md

@@ -0,0 +1,219 @@
+<context_management>
+
+## Purpose
+
+Strategies for working effectively within context window limits. Context is a finite resource - use it deliberately to maximize productive work per session.
+
+## Context Brackets
+
+Drive uses context brackets to adapt behavior based on remaining capacity:
+
+| Bracket | Remaining | Mode | Behavior |
+|---------|-----------|------|----------|
+| FRESH | >70% | LEAN | Minimal injection, trust recent context |
+| MODERATE | 40-70% | STANDARD | Reinforce key context, consider plan splits |
+| DEEP | 20-40% | CONSERVATIVE | Summarize before new reads, plan handoffs |
+| CRITICAL | <20% | PRESERVATION | Finish current task, prepare handoff |
+
+## Strategies by Bracket
+
+### FRESH (>70%)
+- Work directly in session
+- Load full files when needed
+- Multiple parallel operations OK
+- Good time for complex multi-step work
+
+### MODERATE (40-70%)
+- Re-read key files (PROJECT.md, STATE.md) before decisions
+- Consider splitting large remaining work
+- Prefer summaries over full prior plan content
+- Single-concern plans
+
+### DEEP (20-40%)
+- Read SUMMARY.md instead of full PLAN.md
+- Defer new complex work to fresh session
+- Focus on completing current plan
+- Prepare handoff documentation
+
+### CRITICAL (<20%)
+- Complete current task only
+- Write comprehensive handoff
+- No new file reads unless essential
+- Update STATE.md with resume context
+
+## Lean Injection Principles
+
+### Load What You Need
+```markdown
+<!-- GOOD: Targeted loading -->
+<context>
+@.drive/STATE.md
+@src/models/user.ts  (the specific file being modified)
+</context>
+
+<!-- BAD: Kitchen sink -->
+<context>
+@.drive/PROJECT.md
+@.drive/ROADMAP.md
+@.drive/STATE.md
+@.drive/phases/01-foundation/01-01-SUMMARY.md
+@.drive/phases/01-foundation/01-02-SUMMARY.md
+@src/models/user.ts
+@src/models/product.ts
+@src/api/routes.ts
+</context>
+```
+
+### Summary Before Full
+When referencing prior work:
+
+```markdown
+<!-- GOOD: Reference summary -->
+@.drive/phases/01-foundation/01-01-SUMMARY.md
+
+<!-- AVOID: Full plan + summary -->
+@.drive/phases/01-foundation/01-01-PLAN.md
+@.drive/phases/01-foundation/01-01-SUMMARY.md
+```
+
+Summaries capture what was built. Plans capture what was intended. After completion, the summary is more useful.
+
+### Progressive Detail
+Start with high-level, drill down only when needed:
+
+1. Read STATE.md (current position)
+2. Read relevant SUMMARY.md (what was built)
+3. Read specific source files (implementation details)
+
+Don't load implementation details until you need them.
+
+## Plan Sizing for Context
+
+### Target: ~50% Context Usage Per Plan
+A plan should use roughly half the available context:
+- Leaves room for execution output
+- Allows error recovery
+- Supports verification steps
+
+### Single Concern Per Plan
+```
+GOOD: "Create User model and API endpoints"
+BAD: "Create User model, Product model, Order model, and all API endpoints"
+```
+
+### 2-3 Tasks Maximum
+More tasks = more context per plan. Split large phases into multiple plans.
+
+## Avoiding Reflexive Chaining
+
+**Anti-pattern: Reflexive chain**
+```yaml
+# Plan 01-01
+depends_on: []
+
+# Plan 01-02
+depends_on: ["01-01"]  # Does 02 actually need 01's output?
+
+# Plan 01-03
+depends_on: ["01-02"]  # Does 03 actually need 02's output?
+```
+
+This creates false sequential execution and unnecessary context loading.
+
+**Pattern: Genuine dependencies only**
+```yaml
+# Plan 01-01: Create User model
+depends_on: []
+
+# Plan 01-02: Create Product model
+depends_on: []  # Independent! Can parallelize.
+
+# Plan 01-03: Create Order model (references User and Product)
+depends_on: ["01-01", "01-02"]  # Genuine: imports types from both
+```
+
+## Session Handoffs
+
+When context is exhausted or work spans sessions, Drive provides explicit handoff support.
+
+### Two Levels of Continuity
+
+| Level | File | When to Use |
+|-------|------|-------------|
+| Light | STATE.md Session Continuity | Quick breaks, same-day resume |
+| Full | HANDOFF-{date}.md | Context limits, next-day resume, zero-context sessions |
+
+### STATE.md Session Continuity Section
+Always updated. Minimal but sufficient for quick resume:
+
+```markdown
+## Session Continuity
+
+Last session: 2026-01-28 11:15
+Stopped at: Phase 3, Plan 01, Task 2 complete
+Next action: Create context-management.md reference
+Resume file: .drive/phases/03-references-layer/03-01-PLAN.md
+Resume context:
+- Task 1 complete (checkpoints.md, plan-format.md created)
+- Task 2 in progress
+- 55% context remaining
+```
+
+### HANDOFF.md Document
+For zero-context sessions or complex multi-session work. Created by `/drive:pause`:
+
+- Self-contained entry point (assumes no prior context)
+- What was accomplished this session
+- What's in progress
+- Key decisions made
+- Current blockers
+- Exact next action
+- Loop position (PLAN/APPLY/UNIFY markers)
+
+**When to use HANDOFF vs STATE.md alone:**
+- **STATE.md only:** Quick break, returning soon, context might persist
+- **HANDOFF + STATE.md:** End of day, context limits, sharing with fresh session
+
+### Session Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/drive:pause` | Create HANDOFF, update STATE, prepare for break |
+| `/drive:resume` | Restore context from HANDOFF/STATE, suggest next action |
+| `/drive:progress` | Mid-session check, suggests ONE next action |
+
+## Anti-Patterns
+
+**Loading everything "just in case":**
+```markdown
+<context>
+@everything/that/might/be/relevant.md
+</context>
+```
+Why bad: Wastes context on unused content.
+
+**Ignoring bracket transitions:**
+```
+At 35% context: "Let me start this new complex task"
+```
+Why bad: May not have room to complete. Start fresh.
+
+**No handoff preparation:**
+```
+At 15% context: Continue working without noting state
+```
+Why bad: Next session loses context. Always prepare resume.
+
+## Context Budget Heuristics
+
+| Activity | Typical Cost |
+|----------|--------------|
+| PLAN.md template | ~3-5k tokens |
+| Read source file | ~1-3k tokens |
+| Task execution | ~5-15k tokens |
+| Verification output | ~2-5k tokens |
+| SUMMARY.md write | ~2-3k tokens |
+
+Plan your work with these estimates in mind.
+
+</context_management>

package/modules/drive/src/references/git-strategy.md

@@ -0,0 +1,206 @@
+<overview>
+Git integration for Drive workflow.
+</overview>
+
+<core_principle>
+
+**Commit outcomes, not process.**
+
+The git log should read like a changelog of what shipped, not a diary of planning activity.
+
+</core_principle>
+
+<commit_points>
+
+| Event                   | Commit? | Why                                              |
+| ----------------------- | ------- | ------------------------------------------------ |
+| PROJECT + ROADMAP init  | YES     | Project initialization                           |
+| PLAN.md created         | NO      | Intermediate - commit with plan completion       |
+| Research notes          | NO      | Intermediate                                     |
+| **Task completed**      | YES     | Atomic unit of work (1 commit per task)          |
+| **Plan completed**      | YES     | Metadata commit (SUMMARY + STATE + ROADMAP)      |
+| HANDOFF created         | YES     | WIP state preserved                              |
+
+</commit_points>
+
+<commit_formats>
+
+## Project Initialization
+
+```
+docs: initialize [project-name] ([N] phases)
+
+[One-liner from PROJECT.md]
+
+Phases:
+1. [phase-name]: [goal]
+2. [phase-name]: [goal]
+3. [phase-name]: [goal]
+```
+
+What to commit:
+```bash
+git add .drive/
+git commit
+```
+
+## Task Completion (During APPLY)
+
+Each task gets its own commit immediately after completion.
+
+```
+{type}({phase}-{plan}): {task-name}
+
+- [Key change 1]
+- [Key change 2]
+- [Key change 3]
+```
+
+**Commit types:**
+- `feat` - New feature/functionality
+- `fix` - Bug fix
+- `test` - Test-only (TDD RED phase)
+- `refactor` - Code cleanup (TDD REFACTOR phase)
+- `perf` - Performance improvement
+- `chore` - Dependencies, config, tooling
+- `docs` - Documentation changes
+
+**Examples:**
+
+```bash
+# Standard task
+git add src/api/auth.ts src/types/user.ts
+git commit -m "feat(08-02): create user registration endpoint
+
+- POST /auth/register validates email and password
+- Checks for duplicate users
+- Returns JWT token on success
+"
+
+# TDD task - RED phase
+git add src/__tests__/jwt.test.ts
+git commit -m "test(07-02): add failing test for JWT generation
+
+- Tests token contains user ID claim
+- Tests token expires in 1 hour
+- Tests signature verification
+"
+```
+
+## Plan Completion (After UNIFY)
+
+After all tasks committed, one final metadata commit captures plan completion.
+
+```
+docs({phase}-{plan}): complete [plan-name]
+
+AC Results:
+- AC-1: [PASS/FAIL]
+- AC-2: [PASS/FAIL]
+
+SUMMARY: .drive/phases/XX-name/{phase}-{plan}-SUMMARY.md
+```
+
+What to commit:
+```bash
+git add .drive/phases/XX-name/
+git add .drive/STATE.md
+git add .drive/ROADMAP.md
+git commit
+```
+
+**Note:** Code files NOT included - already committed per-task.
+
+## Handoff (WIP)
+
+```
+wip({phase}): paused at plan [NN] task [X]/[Y]
+
+Current: [task name]
+[If blocked:] Blocked: [reason]
+```
+
+What to commit:
+```bash
+git add .drive/
+git commit
+```
+
+</commit_formats>
+
+<example_log>
+
+**Per-task commits (Drive approach):**
+
+```
+# Phase 08.5 - Quality Patterns
+d4e5f6 docs(08.5-01): complete quality references
+a1b2c3 feat(08.5-01): create git-strategy.md
+7g8h9i feat(08.5-01): create tdd.md
+4d5e6f feat(08.5-01): create quality-principles.md
+
+# Phase 08 - Documentation
+3m4n5o docs(08-02): complete workflow docs
+6p7q8r feat(08-02): create unify-phase.md
+9s0t1u feat(08-02): create apply-phase.md
+2v3w4x docs(08-01): complete command docs
+5y6z7a feat(08-01): create resume.md command
+8b9c0d feat(08-01): create pause.md command
+
+# Phase 07 - Session Continuity
+1e2f3g docs(07-01): complete handoff workflow
+4h5i6j feat(07-01): create pause-work.md
+7k8l9m feat(07-01): add session continuity to STATE.md
+
+# Initialization
+0n1o2p docs: initialize drive-framework (8 phases)
+```
+
+Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
+
+</example_log>
+
+<anti_patterns>
+
+**Still don't commit (intermediate artifacts):**
+- PLAN.md creation (commit with plan completion)
+- Research notes
+- Minor planning tweaks
+- "Fixed typo in roadmap"
+
+**Do commit (outcomes):**
+- Each task completion (feat/fix/test/refactor)
+- Plan completion metadata (docs)
+- Project initialization (docs)
+- Handoffs (wip)
+
+**Key principle:** Commit working code and shipped outcomes, not planning process.
+
+</anti_patterns>
+
+<commit_strategy_rationale>
+
+## Why Per-Task Commits?
+
+**Context engineering for AI:**
+- Git history becomes primary context source for future Claude sessions
+- `git log --grep="{phase}-{plan}"` shows all work for a plan
+- `git diff <hash>^..<hash>` shows exact changes per task
+- Less reliance on parsing SUMMARY.md = more context for actual work
+
+**Failure recovery:**
+- Task 1 committed ✅, Task 2 failed ❌
+- Claude in next session: sees task 1 complete, can retry task 2
+- Can `git reset --hard` to last successful task
+
+**Debugging:**
+- `git bisect` finds exact failing task, not just failing plan
+- `git blame` traces line to specific task context
+- Each commit is independently revertable
+
+**Observability:**
+- Solo developer + Claude workflow benefits from granular attribution
+- Atomic commits are git best practice
+- "Commit noise" irrelevant when consumer is Claude, not humans
+
+</commit_strategy_rationale>

package/modules/drive/src/references/loop-phases.md

@@ -0,0 +1,254 @@
+<loop_phases>
+
+## Purpose
+
+Explain the semantics of Drive's three loop phases: PLAN, APPLY, UNIFY. Every unit of work follows this loop. Skipping phases breaks traceability and increases risk.
+
+## The Loop
+
+```
+    ┌─────────────────────────────────────────┐
+    │                                         │
+    ▼                                         │
+  PLAN ────────► APPLY ────────► UNIFY ───────┘
+    │              │               │
+    │              │               │
+ Define work   Execute work   Reconcile
+ Get approval  Verify tasks   Update state
+```
+
+## PLAN Phase
+
+**Purpose:** Define what will be built, how it will be verified, and what's out of scope.
+
+**Artifacts Created:**
+- `{phase}-{plan}-PLAN.md` in `.drive/phases/{phase-name}/`
+
+**Activities:**
+1. Analyze requirements and context
+2. Define objective (Goal, Purpose, Output)
+3. Write acceptance criteria (Given/When/Then)
+4. Break down into tasks with Files, Action, Verify, Done
+5. Set boundaries (DO NOT CHANGE, SCOPE LIMITS)
+6. Define verification checklist
+7. **Wait for approval before proceeding**
+
+**Entry Condition:**
+- Prior plan completed (UNIFY done) OR first plan
+- ROADMAP indicates this phase is next
+
+**Exit Condition:**
+- PLAN.md created with all required sections
+- User has approved the plan
+- STATE.md updated to show "ready for APPLY"
+
+**Loop Position:**
+```
+PLAN ──▶ APPLY ──▶ UNIFY
+  ✓        ○        ○     [PLAN complete, awaiting APPLY]
+```
+
+## APPLY Phase
+
+**Purpose:** Execute the approved plan by completing tasks in order, verifying each.
+
+**Artifacts Created:**
+- Code/files specified in PLAN.md
+- APPLY-LOG (optional, for complex plans)
+
+**Activities:**
+1. Read PLAN.md to load task definitions
+2. For each auto task, follow the Execute/Qualify (E/Q) loop:
+   - **Execute** the action
+   - **Report status** (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED)
+   - **Qualify** against spec and linked AC (re-read output, run verify fresh, compare)
+   - Score: PASS / GAP / DRIFT — loop on gaps until resolved
+3. Stop at checkpoints, wait for human
+4. On checkpoint failure: classify root cause (intent/spec/code) before fixing
+5. Track deviations from plan
+
+### Task Execution Statuses
+
+After executing each task, report one of four statuses before qualification:
+
+| Status | Meaning | What Happens Next |
+|---|---|---|
+| **DONE** | Task completed, no concerns | Standard qualify check against spec + AC |
+| **DONE_WITH_CONCERNS** | Completed but have doubts | Qualify focuses on flagged concerns first, then full check |
+| **NEEDS_CONTEXT** | Can't complete — missing information | Pause execution. Surface what's missing. Wait for user input |
+| **BLOCKED** | Can't complete — structural impediment | Stop. Report what was attempted, what's blocking, what help is needed |
+
+**Rules:**
+- NEVER silently produce work you're unsure about — instead report DONE_WITH_CONCERNS, because pretending confidence when you have doubts produces work that fails during verification or in production
+- NEEDS_CONTEXT is not failure — it's honest communication that prevents wasted work on wrong assumptions
+- BLOCKED must include specifics — instead of a vague "I'm stuck", because specificity enables the user to unblock you efficiently
+
+### Execute/Qualify (E/Q) Loop
+
+Every auto task follows the E/Q loop:
+
+```
+EXECUTE → REPORT STATUS → QUALIFY → (fix gaps) → NEXT TASK
+```
+
+The Qualify step independently verifies output against the spec — instead of trusting execution memory, because the implementer's report of their own work is inherently optimistic. Qualify re-reads the actual files, runs verify commands fresh, and compares line-by-line against the task spec and linked AC.
+
+Qualify scores each task: **PASS** (matches spec), **GAP** (missing something), or **DRIFT** (built something different). GAP and DRIFT trigger a fix-and-requalify loop (max 3 attempts before escalating to user).
+
+### Diagnostic Failure Routing
+
+When a checkpoint:human-verify fails, classify before fixing:
+- **Intent issue** → re-plan the phase with updated intent
+- **Spec issue** → fix the plan (ACs/tasks) before patching code
+- **Code issue** → standard fix-in-place
+
+This prevents the anti-pattern of patching code when the plan itself was wrong.
+
+**Entry Condition:**
+- PLAN.md exists and is approved
+- STATE.md shows loop position at PLAN complete
+
+**Exit Condition:**
+- All tasks completed with PASS qualify status (or blocked with documentation)
+- All checkpoint verifications resolved
+- Ready for reconciliation
+
+**Loop Position:**
+```
+PLAN ──▶ APPLY ──▶ UNIFY
+  ✓        ✓        ○     [APPLY complete, ready for UNIFY]
+```
+
+## UNIFY Phase
+
+**Purpose:** Reconcile what was planned vs. what was built. Close the loop.
+
+**Artifacts Created:**
+- `{phase}-{plan}-SUMMARY.md` in `.drive/phases/{phase-name}/`
+- Updated `STATE.md`
+- Updated `ROADMAP.md` (if phase complete)
+
+**Activities:**
+1. Compare PLAN.md tasks to actual execution
+2. Document what was built (files, lines)
+3. Record acceptance criteria results (PASS/FAIL)
+4. Note any deviations and why
+5. Update STATE.md:
+   - Loop position
+   - Progress percentages
+   - Session continuity
+6. Update ROADMAP.md if phase is complete
+
+**Entry Condition:**
+- APPLY phase complete (all tasks done or documented blockers)
+
+**Exit Condition:**
+- SUMMARY.md created with results
+- STATE.md updated with new position
+- Loop closed, ready for next PLAN
+
+**Loop Position:**
+```
+PLAN ──▶ APPLY ──▶ UNIFY
+  ✓        ✓        ✓     [Loop complete, ready for next PLAN]
+```
+
+## Loop Invariants
+
+**Never Skip PLAN:**
+```
+# BAD
+"Let me just quickly implement this without a plan"
+
+# GOOD
+"Let me create a PLAN.md first, even for small work"
+```
+Why: No plan = no acceptance criteria = no way to verify completion.
+
+**Never Execute Without Approval:**
+```
+# BAD
+"I've written the plan, now executing..."
+
+# GOOD
+"Plan created. Ready to execute when you approve."
+```
+Why: Plans may have incorrect assumptions. Approval catches issues early.
+
+**Always Close With UNIFY:**
+```
+# BAD
+"Tasks done. Moving to next phase."
+
+# GOOD
+"Tasks done. Creating SUMMARY.md and updating STATE.md."
+```
+Why: No UNIFY = no record of what was built = lost traceability.
+
+## Phase Transitions
+
+### PLAN → APPLY
+Trigger: User approves plan (explicit signal)
+
+Validation:
+- [ ] PLAN.md has all required sections
+- [ ] Acceptance criteria are testable
+- [ ] Tasks have Files, Action, Verify, Done
+- [ ] Boundaries are clear
+
+### APPLY → UNIFY
+Trigger: All tasks complete OR blockers documented
+
+Validation:
+- [ ] Each task verification passed (or blocker recorded)
+- [ ] No skipped tasks
+- [ ] Deviations noted
+
+### UNIFY → PLAN (next)
+Trigger: SUMMARY.md created, STATE.md updated
+
+Validation:
+- [ ] SUMMARY.md has AC results
+- [ ] STATE.md reflects new position
+- [ ] ROADMAP.md updated if phase complete
+
+## Visual Loop Position Format
+
+STATE.md displays loop position visually:
+
+```markdown
+## Loop Position
+
+Current loop state:
+```
+PLAN ──▶ APPLY ──▶ UNIFY
+  ✓        ○        ○     [Description of current state]
+```
+```
+
+Symbols:
+- `✓` = Phase complete
+- `○` = Phase pending
+- `►` = Currently in this phase (optional)
+
+## Anti-Patterns
+
+**Partial loops:**
+```
+PLAN → APPLY → (skip UNIFY) → PLAN
+```
+Why bad: No record of what was built. Can't track progress.
+
+**Implicit approval:**
+```
+"I assume the plan is approved and will proceed"
+```
+Why bad: May execute on flawed assumptions. Always wait for explicit approval.
+
+**UNIFY debt:**
+```
+"I'll write the SUMMARY later"
+```
+Why bad: Context degrades. Write SUMMARY immediately after APPLY.
+
+</loop_phases>