@alecsibilia/luca 13.0.0-alpha.1

package/dist/claude/skills/milestone-audit/SKILL.md

@@ -0,0 +1,545 @@
+---
+name: milestone-audit
+description: Audit milestone completion against original requirements and acceptance criteria.
+---
+
+<main>
+# Luca Audit Milestone
+
+Audit milestone completion against original intent with cross-phase code review.
+
+**Arguments:** `[version]` (optional - uses current milestone if not provided)
+
+## Sub-agent Delegation Requirements
+
+This skill is an **orchestrator**. YOU MUST delegate work to sub-agents using the Task tool.
+
+**Required sub-agents for this skill:**
+
+- `lu-integration-checker` - Verifies cross-phase integration
+- `dx-advocate` - Code quality review (milestone-wide)
+- `code-simplifier` - DRY and complexity review
+- `code-architect` - Architecture coherence review
+- `ui` - Tailwind/styling review
+- `security-auditor` - Security review (milestone-wide)
+
+**DO NOT** attempt to check integration or review code yourself. Spawn the appropriate subagents via the `Task` tool.
+
+## Model Profile
+
+```bash
+MODEL_PROFILE=$(cat .luca/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+**Model lookup table:**
+
+| Agent                     | quality | balanced | budget |
+| ------------------------- | ------- | -------- | ------ |
+| lu-integration-checker | sonnet  | sonnet   | haiku  |
+| dx-advocate               | opus    | sonnet   | haiku  |
+| code-simplifier           | opus    | sonnet   | haiku  |
+| code-architect            | opus    | sonnet   | haiku  |
+| tailwind-auditor          | opus    | sonnet   | haiku  |
+| security-auditor          | opus    | sonnet   | haiku  |
+
+> **Current Limitation:** Cursor's Task tool only supports `model="fast"` or inheriting from parent. This table is preserved for future compatibility.
+
+**Current model variable values:**
+
+```
+# All audit agents require reasoning → omit (inherit from parent)
+integration_checker_model = (omit)
+reviewer_model = (omit)  # dx-advocate, code-simplifier, etc.
+```
+
+## Process
+
+### 1. Load Context
+
+- Read all phase `verify.json` files for the milestone
+- Recall requirements from MuninnDB (`brain:project-requirements`)
+- Recall the project identity from MuninnDB (`brain:project-identity`) for original intent
+
+### 2. Check Requirements Coverage
+
+- Compare completed requirements to original v1 list
+- Identify any gaps or partial implementations
+
+### 3. Spawn Integration Checker
+
+**MANDATORY**: You MUST spawn the integration-checker (run as a `reviewer` subagent with perspective=integration). Do NOT verify integration yourself.
+
+First, read the phase context:
+
+```bash
+VERIFICATION_FILES=$(find .luca/phases -name "verify.json" -exec cat {} \;)
+ROADMAP_CONTENT=$(cat .luca/roadmap.md)
+# Recall requirements from MuninnDB:
+# mcp__muninn__muninn_recall_tree(vault: "<repo_vault>", id: "brain:project-requirements")
+```
+
+Then spawn the integration checker:
+
+````python
+Task(
+  prompt="""
+<integration_context>
+
+**Milestone:** v{version}
+
+**Phase Verifications:**
+{verification_files}
+
+**Requirements:**
+{requirements_content}
+
+**Roadmap:**
+{roadmap_content}
+
+</integration_context>
+
+<verification_targets>
+1. Cross-phase wiring: Do components from different phases connect properly?
+2. End-to-end flows: Do user journeys work across phase boundaries?
+3. Data flow: Is data passed correctly between phases?
+4. API contracts: Do interfaces match expectations?
+</verification_targets>
+
+<output_requirements>
+Return status and any integration gaps found:
+```yaml
+status: passed | gaps_found
+integration_score: N/M
+gaps:
+  - description: "Gap description"
+    phases_affected: ["01", "03"]
+    severity: critical | high | medium
+````
+
+</output_requirements>
+
+Verify cross-phase integration for this milestone.
+""",
+subagent_type="lu-integration-checker",
+model="{checker_model}",
+description="Integration check: v{version}"
+)
+
+````
+
+**Do NOT proceed until the Task returns.**
+
+### 4. Milestone-wide Code Quality Review
+
+**Get all files changed in this milestone:**
+
+```bash
+# Find milestone start commit (first commit on this branch or tag)
+MILESTONE_START=$(git merge-base main HEAD 2>/dev/null || git rev-list --max-parents=0 HEAD)
+
+# Get all TypeScript/TSX files changed since milestone start
+CHANGED_FILES=$(git diff --name-only $MILESTONE_START HEAD -- '*.ts' '*.tsx' 2>/dev/null | head -100)
+FILE_COUNT=$(echo "$CHANGED_FILES" | grep -c '.' || echo "0")
+````
+
+**If files changed:** Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Luca ► MILESTONE CODE REVIEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Reviewing {FILE_COUNT} files changed across all phases...
+```
+
+**MANDATORY**: Spawn ALL reviewers in PARALLEL. Do NOT review code yourself.
+
+First, read project standards:
+
+```bash
+CLAUDE_CONTENT=$(cat CLAUDE.md 2>/dev/null || echo "No CLAUDE.md")
+```
+
+Then spawn ALL reviewers in PARALLEL (same message, multiple Task calls):
+
+````python
+# DX Advocate - conventions across phases
+Task(
+  prompt="""
+Review files changed across this milestone for code quality issues.
+
+**Changed files (all phases):**
+{changed_files}
+
+**Project standards:**
+{claude_content}
+
+**Your focus:** Conventions consistency across phases, snake_case keys, Lodash usage patterns
+
+**Milestone-level concerns:**
+- Cross-phase patterns and consistency
+- DRY violations across phases
+- Accumulated tech debt
+
+**Return format:**
+```yaml
+issues:
+  - severity: CRITICAL|HIGH|MEDIUM|LOW
+    file: path/to/file.ts
+    line: 42
+    issue: Brief description
+    suggestion: How to fix
+    cross_phase: true|false
+````
+
+If no issues: `issues: []`
+""",
+subagent_type="dx-advocate",
+model="{reviewer_model}",
+description="Milestone DX review"
+)
+
+# Code Simplifier - DRY across phases
+
+Task(
+prompt="""
+Review files changed across this milestone for complexity and duplication.
+
+**Changed files (all phases):**
+{changed_files}
+
+**Your focus:** DRY violations across phases, duplicated utilities, refactoring opportunities
+
+**Return format:**
+
+```yaml
+issues:
+  - severity: CRITICAL|HIGH|MEDIUM|LOW
+    file: path/to/file.ts
+    line: 42
+    issue: Brief description
+    suggestion: How to fix
+    cross_phase: true|false
+```
+
+""",
+subagent_type="code-simplifier",
+model="{reviewer_model}",
+description="Milestone simplification review"
+)
+
+# Code Architect - architecture coherence
+
+Task(
+prompt="""
+Review files changed across this milestone for architecture issues.
+
+**Changed files (all phases):**
+{changed_files}
+
+**Your focus:** Architecture consistency, module boundaries, file organization, pattern coherence across phases
+
+**Return format:**
+
+```yaml
+issues:
+  - severity: CRITICAL|HIGH|MEDIUM|LOW
+    file: path/to/file.ts
+    line: 42
+    issue: Brief description
+    suggestion: How to fix
+    cross_phase: true|false
+```
+
+""",
+subagent_type="code-architect",
+model="{reviewer_model}",
+description="Milestone architecture review"
+)
+
+# Tailwind Auditor - styling consistency
+
+Task(
+prompt="""
+Review files changed across this milestone for Tailwind/styling issues.
+
+**Changed files (all phases):**
+{changed_files}
+
+**Your focus:** Dynamic color system usage, shadcn anti-patterns, Tailwind consistency
+
+**Return format:**
+
+```yaml
+issues:
+  - severity: CRITICAL|HIGH|MEDIUM|LOW
+    file: path/to/file.ts
+    line: 42
+    issue: Brief description
+    suggestion: How to fix
+    cross_phase: true|false
+```
+
+""",
+subagent_type="ui",
+model="{reviewer_model}",
+description="Milestone Tailwind review"
+)
+
+# Security Auditor - security across milestone
+
+Task(
+prompt="""
+Review files changed across this milestone for security issues.
+
+**Changed files (all phases):**
+{changed_files}
+
+**Your focus:** Auth patterns consistency, API security across all endpoints, data flow
+
+**Return format:**
+
+```yaml
+issues:
+  - severity: CRITICAL|HIGH|MEDIUM|LOW
+    file: path/to/file.ts
+    line: 42
+    issue: Brief description
+    suggestion: How to fix
+    cross_phase: true|false
+```
+
+""",
+subagent_type="security-auditor",
+model="{reviewer_model}",
+description="Milestone security review"
+)
+
+```
+
+**Do NOT proceed until ALL Tasks return.**
+
+**Agent-specific focus:**
+
+- **dx-advocate**: "Conventions consistency across phases, snake_case keys, Lodash usage patterns"
+- **code-simplifier**: "DRY violations across phases, duplicated utilities, refactoring opportunities"
+- **code-architect**: "Architecture consistency, module boundaries, file organization, pattern coherence across phases"
+- **tailwind-auditor**: "Dynamic color system usage, shadcn anti-patterns (text-muted-foreground, bg-primary), Tailwind consistency"
+- **security-auditor**: "Auth patterns consistency, API security across all endpoints, data flow"
+
+**Merge findings:** Combine all issues, categorize by severity and cross-phase flag. Store each reviewer's raw output keyed by agent name for potential debate analysis.
+
+### 4.5 Adversarial Debate Round (Conditional)
+
+**Gate check:**
+
+\`\`\`bash
+# Read debate config
+DEBATE_ENABLED=$(cat .luca/config.json 2>/dev/null | grep -o '"milestone_debate_enabled"[[:space:]]*:[[:space:]]*[a-z]*' | grep -o '[a-z]*$' || echo "true")
+COMPLEXITY=$(luca state read 2>/dev/null | jq -r '.complexity // "MODERATE"')
+\`\`\`
+
+**Skip if:** \`DEBATE_ENABLED\` is "false" OR complexity is below COMPLEX, OR no disagreements detected among reviewer outputs from Step 4.
+
+**If all gates pass, proceed with debate:**
+
+#### 4.5.1 Normalize and Detect
+
+Collect all 5 code reviewer outputs (excluding integration checker) from Step 4.
+
+- Normalize findings using tribunal detector
+- Detect disagreements by file:line grouping
+- Check severity gate (CRITICAL/HIGH required)
+
+**Display tribunal start banner if disagreements found:**
+
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Luca >>> MILESTONE DEBATE ROUND
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{N} disagreements detected across {M} reviewers.
+Running adversarial rebuttal round...
+\`\`\`
+
+#### 4.5.2 Rebuttal Round
+
+For each disagreement, spawn challenger and defender in PARALLEL:
+
+\`\`\`\`python
+# For each disagreement: spawn challenger and defender
+# Use the SAME reviewer agent type as the original finding
+
+Task(
+  prompt="""
+{challenger_prompt from buildRebuttalPrompts, augmented with milestone context}
+""",
+  subagent_type="{challenger_agent_type}",
+  description="Challenge: {finding_summary}"
+)
+
+Task(
+  prompt="""
+{defender_prompt from buildRebuttalPrompts, augmented with milestone context}
+""",
+  subagent_type="{defender_agent_type}",
+  description="Defend: {finding_summary}"
+)
+\`\`\`\`
+
+**Do NOT proceed until ALL rebuttal Tasks return.**
+
+#### 4.5.3 Resolve and Unify
+
+Parse rebuttal responses. For each:
+- Determine resolution: upheld, withdrawn, or modified
+- Calculate confidence scores
+- Build unified recommendations
+
+#### 4.5.4 Display Debate Results
+
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Luca >>> DEBATE COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| Metric                | Value |
+|-----------------------|-------|
+| Disagreements found   | {N}   |
+| Rebuttals conducted   | {N}   |
+| Findings withdrawn    | {N}   |
+| Findings modified     | {N}   |
+| Consensus confidence  | {avg} |
+| Estimated token cost  | {N}   |
+\`\`\`
+
+#### 4.5.5 Replace Merged Findings
+
+Replace the raw merged findings from Step 4 with unified recommendations from the debate. The unified recommendations carry confidence scores and debate history, which are used in Step 5 for the audit report.
+
+### 5. Create Audit Report
+
+Location: `.luca/milestones/v{version}-audit.md` (per LUCA_DIR_CONTRACT)
+
+Include:
+- Requirements status
+- Integration status
+- Code quality findings (from step 4, or unified recommendations if debate ran)
+- Gaps identified
+- Tech debt (populated from code review findings)
+
+**If debate ran (Step 4.5),** add a Debate Analysis section after code quality findings:
+
+\`\`\`markdown
+### Debate Analysis
+
+**Disagreements Resolved:** {N}
+**Findings Withdrawn after Challenge:** {N}
+**Findings Modified after Challenge:** {N}
+
+#### High-Confidence Findings (>0.8)
+
+| Finding | Severity | File | Confidence | Debate Status |
+|---------|----------|------|------------|---------------|
+| {issue} | {sev}    | {f}  | {conf}     | upheld/unchallenged |
+
+#### Contested Findings (0.5-0.8)
+
+| Finding | Severity | File | Confidence | Challenge Summary |
+|---------|----------|------|------------|-------------------|
+| {issue} | {sev}    | {f}  | {conf}     | {summary}         |
+
+#### Withdrawn Findings
+
+| Original Finding | Original Severity | Withdrawn By | Reason |
+|------------------|-------------------|--------------|--------|
+| {issue}          | {sev}             | {agent}      | {why}  |
+\`\`\`
+
+**If debate did NOT run,** omit the Debate Analysis section entirely. The report should be identical to the pre-debate format.
+
+### 6. Present Results
+
+**Route A: Clean audit**
+
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Luca ► MILESTONE v{version} AUDIT COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Requirements: {X}/{Y} complete ✓
+Integration: passed ✓
+Code quality: passed ✓
+
+## ▶ Next Up
+
+/milestone-complete — archive and celebrate
+
+```
+
+**Route B: Issues found**
+
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Luca ► MILESTONE v{version} AUDIT ⚠
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Requirements: {X}/{Y} complete
+Integration: {status}
+Code quality: {N} issues found
+Debate: {ran/skipped} {if ran: {N} disagreements resolved, {N} withdrawn, {N} modified}
+
+### Gaps Found
+
+- {gap 1}
+- {gap 2}
+
+### Tech Debt
+
+- {item 1}
+- {item 2}
+
+### Cross-Phase Issues
+
+| File   | Issue   | Phases Affected |
+| ------ | ------- | --------------- |
+| {file} | {issue} | {phases}        |
+
+## ▶ Next Up
+
+/milestone-gaps — create phases to close gaps
+/milestone-complete — proceed anyway (tech debt noted)
+
+```
+
+## Success Criteria
+
+- [ ] All phase VERIFICATION.md files read
+- [ ] Requirements coverage calculated
+- [ ] Integration checker spawned
+- [ ] Code review subagents spawned (dx-advocate, code-simplifier, code-architect, tailwind-auditor, security-auditor)
+- [ ] Cross-phase patterns identified
+- [ ] Tech debt populated from code review findings
+- [ ] `.luca/milestones/v<version>-audit.md` created
+- [ ] Gaps clearly identified
+- [ ] Debate round evaluated (gate check performed; debate ran if gates passed)
+- [ ] If debate ran: unified recommendations replace raw merged findings
+- [ ] If debate ran: audit report includes Debate Analysis section
+- [ ] If debate skipped: behavior identical to pre-debate milestone-audit
+
+## Next Steps
+
+| Condition | Action | Command |
+|-----------|--------|---------|
+| Audit passed | Complete milestone | `/milestone-complete` |
+| Gaps found | Plan gap closure | `/milestone-gaps` |
+| Want to review | Check progress | `/progress` |
+
+**Primary:** `/milestone-complete` — Archive and prepare for next (if audit passed)
+
+**Also available:**
+- `/milestone-gaps` — Create phases to close gaps
+- `/progress` — Review audit results
+</main>

package/dist/claude/skills/milestone-complete/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: milestone-complete
+description: Archive a completed milestone, extract learnings, and prepare for the next version.
+---
+
+<main>
+# Luca Complete Milestone
+
+Mark milestone complete, archive snapshots to `.luca/milestones/`, and reset the workflow state + roadmap for the next cycle.
+
+**Arguments:** `<version>` (e.g., "1.0", "1.1", "2.0")
+
+**Purpose:** Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
+
+**Output:** Milestone archived (roadmap snapshot + backlog snapshot + audit), `brain:project-identity` MuninnDB tree evolved, learnings consolidated, git tagged.
+
+## Learning Consolidation (NEW)
+
+At milestone completion, consolidate all learnings:
+
+### Step 0: Final Learning Extraction
+
+Before archiving, ensure all session learnings are captured:
+
+1. **Check for unextracted session learnings** in MuninnDB:
+
+   ```
+   mcp__muninn__muninn_recall(vault: "default", context: "current session context and unextracted findings")
+   ```
+
+2. **Invoke lu-learner** if candidate learnings exist
+
+3. **Review milestone-specific insights** in MuninnDB:
+   - Patterns that were validated multiple times -> bump to High confidence via `mcp__muninn__muninn_evolve`
+   - Decisions that held throughout milestone -> mark as Established
+   - Pitfalls that were successfully avoided -> note as Validated
+
+### Step 1: Archive Milestone Memory
+
+Create milestone-specific memory snapshot in MuninnDB:
+
+```
+# Export milestone memory graph for archival
+mcp__muninn__muninn_export_graph(vault: "default")
+```
+
+Store the export as `.luca/milestones/v{version}-backlog-snapshot.json` (per LUCA_DIR_CONTRACT).
+
+Include in archive:
+
+- All patterns validated during this milestone
+- Key decisions and their outcomes
+- Pitfalls discovered and avoided
+
+### Step 2: Clean Session State
+
+After archiving, clear session context:
+
+```
+mcp__muninn__muninn_forget(vault: "default", id: "session:*")
+```
+
+Long-term learnings persist in MuninnDB across milestones.
+
+## State Machine Integration
+
+When updating state during milestone completion, use the `luca` CLI write surface:
+
+```bash
+# Read current workflow state
+STATE_JSON=$(luca state read 2>/dev/null || echo '{"initialized":false}')
+```
+
+After archiving the milestone, reset workflow state for the next milestone:
+
+```bash
+luca workflow reset 2>/dev/null || true
+```
+
+Milestone identity (`milestone:v<version>`) is stored as an atomic engram in MuninnDB — there is no separate `current_milestone` state field on `.luca/state.json`. After completion, store the completed-milestone marker:
+
+```
+mcp__muninn__muninn_remember(vault: "<repo_vault>", concept: "milestone:v{version}-complete", content: "<summary + outcomes>", tags: ["milestone","complete"])
+```
+
+The durable milestone snapshot files (`.luca/milestones/v<SEMVER>-{roadmap,audit,backlog-snapshot}.md`) carry the human-readable archive.
+
+## Process
+
+0. **Check for audit:**
+
+   - Look for `.luca/milestones/v{version}-audit.md`
+   - If missing or stale: recommend `/milestone-audit` first
+   - If audit status is `gaps_found`: recommend `/milestone-gaps` first
+   - If audit status is `passed`: proceed
+
+1. **Verify readiness:**
+
+   - Check all phases have completed plans (SUMMARY.md exists)
+   - Present milestone scope and stats
+   - Wait for confirmation
+
+2. **Gather stats:**
+
+   - Count phases, plans, tasks
+   - Calculate git range, file changes, LOC
+   - Extract timeline from git log
+
+3. **Extract accomplishments:**
+
+   - Read all phase SUMMARY.md files
+   - Extract 4-6 key accomplishments
+   - Present for approval
+
+4. **Archive milestone snapshot:**
+
+   - Create `.luca/milestones/v{version}-roadmap.md` (snapshot of the closing roadmap)
+   - Create `.luca/milestones/v{version}-audit.md` (milestone audit summary)
+   - Create `.luca/milestones/v{version}-backlog-snapshot.{json,md}` (per LUCA_DIR_CONTRACT — captured in Step 2 above)
+   - Reset the active roadmap via `luca roadmap create --file <next-milestone.json>` when a new milestone is ready; or leave the active roadmap empty until `/milestone-new`.
+
+5. **Evolve requirements traceability in MuninnDB:**
+
+   - Mark all v1 requirements as complete in `brain:project-requirements` (vault: repo vault)
+   - The legacy hand-authored `REQUIREMENTS.md` has no canonical home; this step is a MuninnDB tree mutation only.
+
+6. **Update project identity in MuninnDB:**
+
+   - Update `brain:project-identity` to reflect the shipped version (add a `current-version` child, advance the milestone marker)
+   - Set the next-milestone goals as an engram for the upcoming `/milestone-new` to pick up
+
+7. **Commit and tag:**
+
+   ```bash
+   git add .
+   bun run commit --message="archive v{version} milestone" --type=chore --scope=milestone --no-push --skip-checks
+   git tag -a v{version} -m "[milestone summary]"
+   ```
+
+   - Ask about pushing tag
+
+8. **Offer next steps:**
+   - `/milestone-new` — start next milestone
+
+## Success Criteria
+
+- [ ] Milestone snapshot archived to `.luca/milestones/v{version}-roadmap.md` + `v{version}-audit.md` + `v{version}-backlog-snapshot.{json,md}`
+- [ ] Requirements traceability evolved in MuninnDB (`brain:project-requirements` v1 items marked complete)
+- [ ] Active `.luca/roadmap.md` reset (or left empty until next milestone opens)
+- [ ] `brain:project-identity` MuninnDB tree updated with current shipped version
+- [ ] Git tag v{version} created
+- [ ] Commit successful
+
+## Next Steps
+
+| Condition | Action | Command |
+|-----------|--------|---------|
+| Ready for next milestone | Start new milestone | `/milestone-new` |
+| Want to review completion | Check progress | `/progress` |
+| Need to create PR | Create pull request | Run `gh pr create` |
+
+**Primary:** `/milestone-new` — Start the next milestone cycle
+
+**Also available:**
+
+- `/progress` — Review completed work
+- `/help` — See all available commands
+</main>