speccrew 0.1.0

package/.speccrew/skills/speccrew-dev-desktop/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: speccrew-dev-desktop
+description: Desktop Development SOP. Guide System Developer Agent to implement desktop application code (Electron/Tauri) according to system design documents. Reads design blueprints, extracts task checklist, and executes implementation task by task with local quality checks.
+tools: Bash, Edit, Write, Glob, Grep, Read
+---
+
+# Trigger Scenarios
+
+- System Designer Agent has completed desktop system design, user requests implementation
+- User asks "Start desktop development", "Implement desktop app", "Code Electron/Tauri app"
+- Detailed design documents are confirmed in `03.system-design/{platform_id}/`
+
+# Workflow
+
+## Step 1: Read Design Documents
+
+Read in order:
+
+1. **INDEX.md**: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/INDEX.md`
+2. **Module Design Documents**: All `*-design.md` files from same directory
+3. **API Contract**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md`
+4. **Techs Knowledge** (paths from agent context):
+   - `speccrew-workspace/knowledges/techs/{platform_id}/tech-stack.md`
+   - `speccrew-workspace/knowledges/techs/{platform_id}/architecture.md`
+   - `speccrew-workspace/knowledges/techs/{platform_id}/conventions-design.md`
+   - `speccrew-workspace/knowledges/techs/{platform_id}/conventions-dev.md`
+
+## Step 2: Analyze Existing Code Structure
+
+Use Glob/Grep to understand current codebase:
+
+| Target | Glob Pattern | Purpose |
+|--------|-------------|---------|
+| Main process | `src/main/**/*.{ts,js}` or `src-tauri/src/**/*.rs` | Understand main process structure |
+| Renderer process | `src/renderer/**/*.{tsx,vue,html}` or `src/**/*.{tsx,vue}` | Understand renderer structure |
+| IPC definitions | `src/main/ipc/**/*` or `src-tauri/src/commands/**/*.rs` | Understand IPC channel patterns |
+| Window management | `src/main/window/**/*` or patterns with `BrowserWindow` | Understand window patterns |
+| Preload scripts | `src/preload/**/*` or `preload.{ts,js}` | Understand preload patterns |
+| Native modules | `src/main/native/**/*` or binding files | Identify native dependencies |
+| State management | `src/renderer/stores/**/*` or `src/stores/**/*` | Understand store pattern |
+| API layer | `src/renderer/apis/**/*` or `src/apis/**/*` | Understand API encapsulation |
+| Configuration files | `package.json`, `tauri.conf.json`, `electron-builder.yml` | Build and config patterns |
+
+Document findings for reference in later steps.
+
+## Step 3: Extract Task List
+
+Create task record file:
+
+**Path**: `speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/[feature-name]-task.md`
+
+**Read Template**: `speccrew-dev-desktop/templates/TASK-RECORD-TEMPLATE.md`
+
+### Desktop-Specific Task Types
+
+| Task Type | Description | Example |
+|-----------|-------------|---------|
+| Main Process Module | Backend logic running in main process | Window manager, IPC handlers, native integrations |
+| Renderer Page/Component | UI components in renderer process | React/Vue components, pages, layouts |
+| IPC Channel Handler | Communication bridge between processes | `ipcMain.handle`, `#[tauri::command]` |
+| Preload Script | Context bridge for secure renderer access | `contextBridge.exposeInMainWorld` |
+| Window Management | Window creation, lifecycle, multi-window | BrowserWindow, Window configuration |
+| Native Integration | File system, system tray, notifications | Native API wrappers |
+| Menu/Shortcut | Application menus, keyboard shortcuts | Menu templates, global shortcuts |
+| Auto-Update | Update checking and installation | electron-updater, tauri-updater |
+| Security Hardening | Context isolation, CSP, permissions | Preload scripts, security configs |
+
+### Task ID Prefix
+
+Use `DT-` prefix for desktop tasks: `DT-001`, `DT-002`, etc.
+
+### Task Checklist Table
+
+| Task ID | Module | Description | Target Files | IPC Channel | Native Integration | Dependencies | Status |
+|---------|--------|-------------|--------------|-------------|-------------------|--------------|--------|
+| DT-001 | MainProcess | Create window manager | `src/main/window/manager.ts` | - | Window creation | - | Pending |
+| DT-002 | IPC | Implement file operations handler | `src/main/ipc/file.ts` | `file:read`, `file:write` | File system | DT-001 | Pending |
+| DT-003 | Renderer | Create main window UI | `src/renderer/pages/Main.tsx` | `file:*` | - | DT-002 | Pending |
+
+**Status**: Pending / In Progress / Completed / Blocked
+
+**Checkpoint A: Present task extraction summary to user for confirmation.**
+
+## Step 4: Implement Tasks
+
+### 4.1 Implementation Order
+
+Follow dependency order:
+1. Main process infrastructure (window manager, IPC setup)
+2. IPC channel handlers and preload scripts
+3. Renderer process components
+4. Native integrations
+5. Security configurations
+6. Auto-update mechanism
+
+### 4.2 Coding Standards
+
+- **Main Process**: Follow conventions-dev.md for Electron/Tauri backend code
+- **Renderer Process**: Follow frontend conventions (React/Vue/etc.)
+- **IPC Channels**: Use exact channel names from design document
+- **Types**: Use TypeScript types defined in design document
+- **Security**: Never expose `nodeIntegration`, always use context isolation
+
+### 4.3 Status Markers
+
+Use markers from design document:
+
+| Marker | Meaning | Action |
+|--------|---------|--------|
+| `[EXISTING]` | Reuse current code | Verify compatibility, no modification needed |
+| `[MODIFIED]` | Enhance existing code | Implement changes carefully |
+| `[NEW]` | Create brand new | Full implementation required |
+
+## Step 5: Local Checks (Per Task)
+
+After completing each task, run the following checks:
+
+### 5.1 Build Verification
+
+**Electron**:
+```bash
+npm run build:dev
+# or
+npm run electron:dev
+```
+
+**Tauri**:
+```bash
+npm run tauri dev
+# or
+npm run tauri build --debug
+```
+
+### 5.2 Lint Check
+
+```bash
+npm run lint
+# or
+npx eslint [modified-files]
+```
+
+### 5.3 Type Check (TypeScript projects)
+
+```bash
+npx tsc --noEmit
+```
+
+### 5.4 Security Audit
+
+| Check | Method |
+|-------|--------|
+| Context Isolation | Verify `contextIsolation: true` in window config |
+| nodeIntegration | Verify `nodeIntegration: false` |
+| Preload Script | Verify all IPC goes through preload |
+| CSP | Check Content Security Policy headers |
+
+### 5.5 Unit Tests
+
+```bash
+npm test -- [related-test-pattern]
+```
+
+### 5.6 Quick Verify
+
+- Application window launches without crash
+- No console errors in DevTools
+- IPC channels respond correctly
+- Native integrations work as expected
+
+**If checks fail**: Fix issues before marking task complete. Record complex issues in task file.
+
+## Step 6: Record Deviations
+
+If implementation deviates from design document:
+
+1. Stop and document the deviation
+2. Explain reason for deviation
+3. Get user confirmation or proceed with documented reason
+
+**Record in task file**:
+```markdown
+### Deviation Log
+- DT-002: Changed IPC payload structure from {original} to {new} because {reason}
+```
+
+## Step 7: Record Technical Debt
+
+If technical debt is identified:
+
+**Write to**: `speccrew-workspace/iterations/{number}-{type}-{name}/tech-debt/[feature-name]-tech-debt.md`
+
+**Categories**:
+- Security: Temporary security relaxations
+- Performance: Known performance issues
+- Refactoring: Code that needs cleanup
+- Dependencies: Version constraints or workarounds
+
+## Step 8: Complete Notification
+
+After all tasks complete, present summary:
+
+```
+Desktop Development Complete: {feature-name}
+Platform: {platform_id}
+Framework: {Electron/Tauri}
+
+Tasks Completed: {count}
+├── Main Process: {count}
+├── Renderer Process: {count}
+├── IPC Channels: {count}
+├── Native Integration: {count}
+└── Security/Other: {count}
+
+Deviations Recorded: {count}
+Technical Debt Items: {count}
+
+Task Record: speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/[feature-name]-task.md
+```
+
+**Ask user to confirm:**
+1. Are all IPC channels working correctly?
+2. Is context isolation properly configured?
+3. Do native integrations work as expected?
+4. Are there any security concerns?
+
+# Key Rules
+
+| Rule | Description |
+|------|-------------|
+| **Design Document READ-ONLY** | Design documents are reference only - do not modify. Record deviations in task file. |
+| **Actual Framework Syntax** | All code MUST use actual framework/library syntax from techs knowledge |
+| **Status Markers Required** | Use [EXISTING], [MODIFIED], [NEW] markers for all components, modules, and IPC handlers |
+| **Follow Techs Conventions** | Naming, directory structure, patterns must follow techs knowledge |
+| **Security First** | Never disable contextIsolation; never enable nodeIntegration in renderer |
+| **IPC Through Preload** | All main-renderer communication must go through preload scripts |
+| **Task Per File Group** | Each task should map to a logical file group or component |
+| **Local Checks Mandatory** | Run lint, type check, and quick verify before marking task complete |
+| **Tech Debt Recorded** | All technical debt must be written to iterations/{iter}/tech-debt/ |
+
+# Checklist
+
+- [ ] All design documents loaded before implementation
+- [ ] Existing code structure analyzed via Glob/Grep
+- [ ] Task record created with complete checklist
+- [ ] Checkpoint A passed: task extraction confirmed with user
+- [ ] Every design document module covered in task list
+- [ ] All IPC channels from design implemented
+- [ ] Context isolation enabled for all windows
+- [ ] Preload scripts expose only necessary APIs
+- [ ] Native integrations follow security best practices
+- [ ] Build verification passes (dev mode)
+- [ ] Lint check passes with no errors
+- [ ] Type check passes (TypeScript projects)
+- [ ] Unit tests pass for implemented modules
+- [ ] Quick verify: App launches without crash
+- [ ] All deviations recorded in task file
+- [ ] Technical debt recorded in tech-debt/ directory
+- [ ] Task record status updated to complete

package/.speccrew/skills/speccrew-dev-desktop/templates/TASK-RECORD-TEMPLATE.md

@@ -0,0 +1,161 @@
+# Desktop Development Task Record - [Feature Name]
+
+> Based on Design Document: [Link to 03.system-design/{platform_id}/[feature-name]-design.md]
+> Platform: {platform_id} | Framework: {Electron/Tauri}
+
+## Task Checklist
+
+| Task ID | Module | Description | Target Files | IPC Channel | Native Integration | Dependencies | Status |
+|---------|--------|-------------|--------------|-------------|-------------------|--------------|--------|
+| DT-001 | MainProcess | [Description] | `src/main/...` | - | [None/FileSystem/etc] | - | Pending |
+| DT-002 | IPC | [Description] | `src/main/ipc/...` | `channel:name` | [None/etc] | DT-001 | Pending |
+| DT-003 | Renderer | [Description] | `src/renderer/...` | `channel:name` | - | DT-002 | Pending |
+
+> Status: Pending / In Progress / Completed / Blocked
+
+## IPC Channel Registry
+
+<!-- AI-NOTE: Record all IPC channels created or modified during implementation -->
+
+| Channel Name | Direction | Payload Type | Handler Location | Description | Status |
+|--------------|-----------|--------------|------------------|-------------|--------|
+| [channel:name] | Renderer->Main | [Type] | `src/main/ipc/[file].ts` | [Description] | [NEW/MODIFIED/EXISTING] |
+| [channel:name] | Main->Renderer | [Type] | `src/main/window/[file].ts` | [Description] | [NEW/MODIFIED/EXISTING] |
+| [channel:name] | Bidirectional | [Type] | [Location] | [Description] | [NEW/MODIFIED/EXISTING] |
+
+## Native Integration Status
+
+<!-- AI-NOTE: Track all native integrations implemented -->
+
+| Integration Type | Feature | Implementation File | Status | Notes |
+|------------------|---------|---------------------|--------|-------|
+| File System | [Read/Write/Dialog] | `src/main/native/fs.ts` | [Done/Pending] | [Notes] |
+| System Tray | [Icon/Menu] | `src/main/tray.ts` | [Done/Pending] | [Notes] |
+| Notifications | [OS Notifications] | `src/main/notify.ts` | [Done/Pending] | [Notes] |
+| Menu Bar | [App Menu] | `src/main/menu.ts` | [Done/Pending] | [Notes] |
+| Shortcuts | [Global/Local] | `src/main/shortcuts.ts` | [Done/Pending] | [Notes] |
+| Protocol Handler | [Custom Protocol] | `src/main/protocol.ts` | [Done/Pending] | [Notes] |
+| Auto Update | [Check/Download/Install] | `src/main/updater.ts` | [Done/Pending] | [Notes] |
+
+## Security Checklist
+
+<!-- AI-NOTE: Verify all security configurations -->
+
+| Check Item | Configuration | Verified |
+|------------|---------------|----------|
+| Context Isolation | `contextIsolation: true` | [ ] Yes / [ ] No |
+| nodeIntegration | `nodeIntegration: false` | [ ] Yes / [ ] No |
+| enableRemoteModule | `enableRemoteModule: false` | [ ] Yes / [ ] No |
+| Preload Script | All IPC through preload | [ ] Yes / [ ] No |
+| CSP Header | [Policy string] | [ ] Yes / [ ] No |
+| Permission Scope | [Limited permissions] | [ ] Yes / [ ] No |
+
+## Window Management
+
+<!-- AI-NOTE: Track all windows created/modified -->
+
+| Window Name | Type | Status | Configuration |
+|-------------|------|--------|---------------|
+| [MainWindow] | BrowserWindow/Window | [NEW/MODIFIED/EXISTING] | [Size/frame/etc] |
+| [ModalWindow] | BrowserWindow/Window | [NEW/MODIFIED/EXISTING] | [Size/frame/etc] |
+
+## Implementation Progress
+
+### Completed Tasks
+
+- [DT-001] [Description] - Completed at [timestamp]
+- [DT-002] [Description] - Completed at [timestamp]
+
+### In Progress
+
+- [DT-003] [Description] - Started at [timestamp]
+
+### Blocked Tasks
+
+| Task ID | Block Reason | Blocking Issue | Planned Resolution |
+|---------|--------------|----------------|-------------------|
+| [DT-XXX] | [Reason] | [Issue link/description] | [Resolution plan] |
+
+## Deviation Log
+
+<!-- AI-NOTE: Record any deviations from design document with reasons -->
+
+| Task ID | Original Design | Implementation | Reason |
+|---------|-----------------|----------------|--------|
+| [DT-XXX] | [Original approach] | [Actual implementation] | [Why changed] |
+
+## Issues and Resolutions
+
+<!-- AI-NOTE: Record issues encountered during development -->
+
+| Issue ID | Task ID | Description | Severity | Resolution | Status |
+|----------|---------|-------------|----------|------------|--------|
+| [ISSUE-001] | [DT-XXX] | [Description] | [High/Med/Low] | [How resolved] | [Resolved/Pending] |
+
+## Local Verification Results
+
+### Build Verification
+
+| Check | Command | Result | Notes |
+|-------|---------|--------|-------|
+| Dev Build | `npm run electron:dev` / `npm run tauri dev` | [Pass/Fail] | [Notes] |
+| Production Build | `npm run build` | [Pass/Fail] | [Notes] |
+
+### Code Quality
+
+| Check | Command | Result | Notes |
+|-------|---------|--------|-------|
+| Lint | `npm run lint` | [Pass/Fail] | [Notes] |
+| Type Check | `npx tsc --noEmit` | [Pass/Fail] | [Notes] |
+| Unit Tests | `npm test` | [Pass/Fail] | [Notes] |
+
+### Security Verification
+
+| Check | Method | Result | Notes |
+|-------|--------|--------|-------|
+| Context Isolation | Code review | [Pass/Fail] | [Notes] |
+| Preload Script | Code review | [Pass/Fail] | [Notes] |
+| CSP Compliance | Header check | [Pass/Fail] | [Notes] |
+
+### Functional Verification
+
+| Check | Result | Notes |
+|-------|--------|-------|
+| App launches without crash | [Pass/Fail] | [Notes] |
+| IPC channels respond correctly | [Pass/Fail] | [Notes] |
+| Native integrations work | [Pass/Fail] | [Notes] |
+| No console errors | [Pass/Fail] | [Notes] |
+
+## Technical Debt
+
+<!-- AI-NOTE: Link to tech debt document if created -->
+
+Technical debt recorded in: `../tech-debt/[feature-name]-tech-debt.md`
+
+| Item | Category | Description | Priority |
+|------|----------|-------------|----------|
+| [TD-001] | [Security/Performance/Refactor] | [Description] | [High/Med/Low] |
+
+## Completion Summary
+
+- **Total Tasks**: [N]
+- **Completed**: [N]
+- **Blocked**: [N]
+- **Deviations**: [N]
+- **Technical Debt Items**: [N]
+
+### Final Checklist
+
+- [ ] All tasks completed or documented as blocked
+- [ ] All IPC channels tested
+- [ ] Security checklist verified
+- [ ] Local checks (lint, type, build) passing
+- [ ] Deviations documented with reasons
+- [ ] Technical debt recorded
+- [ ] Task record updated
+
+---
+
+**Status**: In Progress / Completed  
+**Last Updated**: [Timestamp]  
+**Developer**: [Agent/User name]

package/.speccrew/skills/speccrew-dev-frontend/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: speccrew-dev-frontend
+description: Frontend Development SOP. Guide System Developer Agent to implement frontend code according to system design documents. Reads design blueprints, extracts task checklist, and executes implementation task by task with local quality checks.
+tools: Bash, Edit, Write, Glob, Grep, Read
+---
+
+# Trigger Scenarios
+
+- System Developer Agent dispatches this skill with platform context
+- System design confirmed, user requests frontend development
+- User asks "Start frontend development" or "Implement frontend code"
+
+# Workflow
+
+## Step 1: Read Design Documents
+
+Read in order:
+
+1. **Platform INDEX**: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/INDEX.md`
+2. **Module design documents**: All `*-design.md` files listed in INDEX
+3. **API Contract**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/*-api-contract.md`
+4. **Task record template**: `speccrew-dev-frontend/templates/TASK-RECORD-TEMPLATE.md`
+
+## Step 2: Read Techs Knowledge
+
+Read platform-specific techs knowledge:
+
+| Document | Path | Purpose |
+|----------|------|---------|
+| Development conventions | `speccrew-workspace/knowledges/techs/{platform_id}/conventions-dev.md` | Naming, patterns, code style |
+| Architecture | `speccrew-workspace/knowledges/techs/{platform_id}/architecture.md` | State management, patterns |
+| Tech stack | `speccrew-workspace/knowledges/techs/{platform_id}/tech-stack.md` | Framework versions, libraries |
+| UI style guide | `speccrew-workspace/knowledges/techs/{platform_id}/ui-style/ui-style-guide.md` | Visual design tokens |
+| UI patterns | `speccrew-workspace/knowledges/techs/{platform_id}/ui-style-patterns/` | Reusable UI patterns |
+
+## Step 3: Extract Task List
+
+From design documents, extract ALL implementation items into a task checklist.
+
+### 3.1 Parse Module Designs
+
+For each module design document, identify:
+
+| Item Type | Markers | Example |
+|-----------|---------|---------|
+| Components | [NEW], [MODIFIED], [EXISTING] | `[NEW] ProductDetailDrawer` |
+| Store modules | [NEW], [MODIFIED], [EXISTING] | `[MODIFIED] useCartStore` |
+| API integration | API calls in pseudo-code | `api.getProduct(id)` |
+| Routes | Route configurations | `/products/:id` |
+| Styles | Layout/styling work | Flex layout, spacing |
+
+### 3.2 Generate Task Table
+
+<!-- AI-NOTE: Create one row per implementation task. Dependencies must reference other Task IDs. -->
+
+| Task ID | Module | Description | Target Files | Dependencies | Status |
+|---------|--------|-------------|--------------|--------------|--------|
+| FE-001 | {module} | {description} | {file paths from design} | {depends on} | Pending |
+| FE-002 | {module} | {description} | {file paths from design} | {depends on} | Pending |
+
+### 3.3 Checkpoint: User Confirmation
+
+**Present task checklist to user for confirmation before proceeding.**
+
+Wait for user approval before writing any code.
+
+### 3.4 Write Initial Task Record
+
+Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/{feature-name}-tasks.md`
+
+Use template from Step 1.
+
+## Step 4: Execute Tasks
+
+For each task in checklist order (respecting dependencies):
+
+### 4.1 Read Design Section
+
+Re-read the corresponding module design document section for this task.
+
+### 4.2 Implement According to Blueprint
+
+<!-- AI-NOTE: Dev skill does NOT use template filling. Write actual source code following the design blueprint directly. -->
+
+| Aspect | Implementation Rule |
+|--------|---------------------|
+| Framework syntax | Use actual syntax from conventions-dev.md |
+| Architecture patterns | Follow architecture.md patterns |
+| Component reuse | Use [EXISTING] components as marked in design |
+| Naming | Follow conventions strictly |
+| File paths | Use paths specified in design document |
+
+### 4.3 Update Task Status
+
+After each task completion:
+
+1. Update task status to "Done" in task record
+2. If deviation from design: record in Deviation Log section
+3. Continue to next task
+
+### 4.4 Handle Design Issues
+
+If design issue discovered during implementation:
+
+1. **Stop current task**
+2. **Report issue to user clearly** with:
+   - Task ID affected
+   - Design document reference
+   - Problem description
+   - Suggested resolution
+3. **Wait for user decision**:
+   - Backtrack to design phase, OR
+   - Proceed with explanation
+
+## Step 5: Local Checks
+
+After each task (or batch of related tasks):
+
+### 5.1 Lint Check
+
+```bash
+npm run lint
+# OR
+npx eslint {modified files}
+```
+
+### 5.2 Type Check (if TypeScript)
+
+```bash
+npx tsc --noEmit
+```
+
+### 5.3 Unit Tests
+
+Run relevant unit tests, ensure no regressions.
+
+### 5.4 Quick Verify
+
+- Page renders without console errors
+- No runtime exceptions
+
+### 5.5 Handle Failures
+
+| Scenario | Action |
+|----------|--------|
+| Checks pass | Mark task complete |
+| Simple fix | Fix immediately, then mark complete |
+| Complex issue | Record in task file "Issues" section, continue if possible |
+
+## Step 6: Complete Task Record
+
+### 6.1 Update Final Statuses
+
+Update task record file with final statuses for all tasks.
+
+### 6.2 Record Deviations
+
+Ensure all deviations are recorded with reasons:
+
+| Task ID | Design Intent | Actual Implementation | Reason |
+|---------|---------------|----------------------|--------|
+| FE-002 | Use A pattern | Used B pattern | [reason] |
+
+### 6.3 Write Tech Debt (if any)
+
+If tech debt identified, write to:
+
+`speccrew-workspace/iterations/{number}-{type}-{name}/tech-debt/{debt-id}.md`
+
+### 6.4 Present Completion Summary
+
+```
+Frontend Development Complete: {feature-name}
+Platform: {platform_id}
+
+Tasks: {completed}/{total} completed
+Deviations: {count}
+Tech Debt: {count}
+
+Task Record: speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/{feature-name}-tasks.md
+```
+
+# Key Rules
+
+| Rule | Description |
+|------|-------------|
+| **Design Blueprint First** | All code MUST follow the system design documents — do not invent architecture |
+| **Task Checklist Mandatory** | MUST extract and confirm task list before writing any code |
+| **Conventions Compliance** | Naming, patterns, directory structure MUST follow techs knowledge |
+| **Deviation Recording** | ANY difference from design MUST be recorded with reason |
+| **Local Check Gate** | Code MUST pass lint/type/test before task completion |
+
+# Checklist
+
+- [ ] All design documents loaded before implementation
+- [ ] Task checklist extracted and confirmed by user
+- [ ] Task record file created at `04.development/{platform_id}/`
+- [ ] Each task implemented following design blueprint
+- [ ] Local checks passed (lint, type, test) for each task
+- [ ] All deviations recorded with reasons
+- [ ] Tech debt items written to `tech-debt/` directory
+- [ ] Task record updated with final completion status