@cluesmith/codev 2.0.11 → 2.0.13

package/skeleton/protocols/aspir/templates/plan.md

@@ -0,0 +1,204 @@
+# Plan: [Title]
+
+## Metadata
+- **ID**: plan-[YYYY-MM-DD]-[short-name]
+- **Status**: draft
+- **Specification**: [Link to codev/specs/spec-file.md]
+- **Created**: [YYYY-MM-DD]
+
+## Executive Summary
+[Brief overview of the implementation approach chosen and why. Reference the specification's selected approach.]
+
+## Success Metrics
+[Copy from specification and add implementation-specific metrics]
+- [ ] All specification criteria met
+- [ ] Test coverage >90%
+- [ ] Performance benchmarks achieved
+- [ ] Zero critical security issues
+- [ ] Documentation complete
+
+## Phases (Machine Readable)
+
+<!-- REQUIRED: porch uses this JSON to track phase progress. Update this when adding/removing phases. -->
+
+```json
+{
+  "phases": [
+    {"id": "phase_1", "title": "Phase 1 Title Here"},
+    {"id": "phase_2", "title": "Phase 2 Title Here"},
+    {"id": "phase_3", "title": "Phase 3 Title Here"}
+  ]
+}
+```
+
+## Phase Breakdown
+
+### Phase 1: [Descriptive Name]
+**Dependencies**: None
+
+#### Objectives
+- [Clear, single objective for this phase]
+- [What value does this phase deliver?]
+
+#### Deliverables
+- [ ] [Specific deliverable 1]
+- [ ] [Specific deliverable 2]
+- [ ] [Tests for this phase]
+- [ ] [Documentation updates]
+
+#### Implementation Details
+[Specific technical approach for this phase. Include:
+- Key files/modules to create or modify
+- Architectural decisions
+- API contracts
+- Data models]
+
+#### Acceptance Criteria
+- [ ] [Testable criterion 1]
+- [ ] [Testable criterion 2]
+- [ ] All tests pass
+- [ ] Code review completed
+
+#### Test Plan
+- **Unit Tests**: [What to test]
+- **Integration Tests**: [What to test]
+- **Manual Testing**: [Scenarios to verify]
+
+#### Rollback Strategy
+[How to revert this phase if issues arise]
+
+#### Risks
+- **Risk**: [Specific risk for this phase]
+  - **Mitigation**: [How to address]
+
+---
+
+### Phase 2: [Descriptive Name]
+**Dependencies**: Phase 1
+
+[Repeat structure for each phase]
+
+---
+
+### Phase 3: [Descriptive Name]
+**Dependencies**: Phase 2
+
+[Continue for all phases]
+
+## Dependency Map
+```
+Phase 1 ──→ Phase 2 ──→ Phase 3
+             ↓
+         Phase 4 (optional)
+```
+
+## Resource Requirements
+### Development Resources
+- **Engineers**: [Expertise needed]
+- **Environment**: [Dev/staging requirements]
+
+### Infrastructure
+- [Database changes]
+- [New services]
+- [Configuration updates]
+- [Monitoring additions]
+
+## Integration Points
+### External Systems
+- **System**: [Name]
+  - **Integration Type**: [API/Database/Message Queue]
+  - **Phase**: [Which phase needs this]
+  - **Fallback**: [What if unavailable]
+
+### Internal Systems
+[Repeat structure]
+
+## Risk Analysis
+### Technical Risks
+| Risk | Probability | Impact | Mitigation | Owner |
+|------|------------|--------|------------|-------|
+| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] |
+
+### Schedule Risks
+| Risk | Probability | Impact | Mitigation | Owner |
+|------|------------|--------|------------|-------|
+| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] |
+
+## Validation Checkpoints
+1. **After Phase 1**: [What to validate]
+2. **After Phase 2**: [What to validate]
+3. **Before Production**: [Final checks]
+
+## Monitoring and Observability
+### Metrics to Track
+- [Metric 1: Description and threshold]
+- [Metric 2: Description and threshold]
+
+### Logging Requirements
+- [What to log and at what level]
+- [Retention requirements]
+
+### Alerting
+- [Alert condition and severity]
+- [Who to notify]
+
+## Documentation Updates Required
+- [ ] API documentation
+- [ ] Architecture diagrams
+- [ ] Runbooks
+- [ ] User guides
+- [ ] Configuration guides
+
+## Post-Implementation Tasks
+- [ ] Performance validation
+- [ ] Security audit
+- [ ] Load testing
+- [ ] User acceptance testing
+- [ ] Monitoring validation
+
+## Expert Review
+**Date**: [YYYY-MM-DD]
+**Model**: [Model consulted]
+**Key Feedback**:
+- [Feasibility assessment]
+- [Missing considerations]
+- [Risk identification]
+- [Alternative suggestions]
+
+**Plan Adjustments**:
+- [How the plan was modified based on feedback]
+
+## Approval
+- [ ] Technical Lead Review
+- [ ] Engineering Manager Approval
+- [ ] Resource Allocation Confirmed
+- [ ] Expert AI Consultation Complete
+
+## Change Log
+| Date | Change | Reason | Author |
+|------|--------|--------|--------|
+| [Date] | [What changed] | [Why] | [Who] |
+
+## Notes
+[Additional context, assumptions, or considerations]
+
+---
+
+## Amendment History
+
+This section tracks all TICK amendments to this plan. TICKs modify both the spec and plan together as an atomic unit.
+
+<!-- When adding a TICK amendment, add a new entry below this line in chronological order -->
+
+<!--
+### TICK-001: [Amendment Title] (YYYY-MM-DD)
+
+**Changes**:
+- [Phase added]: [Description of new phase]
+- [Phase modified]: [What was updated]
+- [Implementation steps]: [New steps added]
+
+**Review**: See `reviews/####-name-tick-001.md`
+
+---
+-->

package/skeleton/protocols/aspir/templates/review.md

@@ -0,0 +1,120 @@
+# Review: [Feature/Project Name]
+
+## Summary
+
+[1-3 sentences: what was built, how many phases, net outcome.]
+
+## Spec Compliance
+
+- [x] AC1: [Description] (Phase N)
+- [x] AC2: [Description] (Phase N)
+- [ ] ACn: [Not met — reason]
+
+## Deviations from Plan
+
+- **Phase N**: [What changed and why]
+
+## Key Metrics
+
+- **Commits**: [N] on the branch
+- **Tests**: [N] passing ([N] existing + [N] new)
+- **Files created**: [list]
+- **Files deleted**: [list]
+- **Net LOC impact**: [+/-N lines]
+
+## Timelog
+
+All times [timezone], [date range].
+
+| Time | Event |
+|------|-------|
+| HH:MM | First commit: [description] |
+| HH:MM | [Phase/milestone] |
+| — | **GATE: [gate-name]** (human approval required) |
+| HH:MM | Implementation begins |
+| HH:MM | Phase N complete after N iterations |
+| HH:MM | **GATE: pr** |
+
+### Autonomous Operation
+
+| Period | Duration | Activity |
+|--------|----------|----------|
+| Spec + Plan | ~Nm | [Summary] |
+| Human gate wait | ~Nh Nm | Idle — waiting for approval |
+| Implementation → PR | ~Nh Nm | N phases, N consultation rounds |
+
+**Total wall clock** (first commit to pr): **Xh Ym**
+**Total autonomous work time** (excluding gate waits): **~Xh Ym**
+**Context window resets**: [N] (resumed automatically / required manual restart)
+
+## Consultation Iteration Summary
+
+[N] consultation files produced ([N] rounds x [N] models). [N] APPROVE, [N] REQUEST_CHANGES, [N] COMMENT.
+
+| Phase | Iters | Who Blocked | What They Caught |
+|-------|-------|-------------|------------------|
+| Specify | N | [Model] | [Brief description] |
+| Plan | N | [Model] | [Brief description] |
+| Phase 1 | N | [Model] | [Brief description] |
+| Phase N | N | [Model] | [Brief description] |
+| Review | N | [Model] | [Brief description] |
+
+**Most frequent blocker**: [Model] — blocked in N of N rounds, focused on: [pattern].
+
+### Avoidable Iterations
+
+Iterations that could have been prevented with better builder behavior:
+
+1. **[Pattern]**: [Specific thing the builder should have done without needing reviewer feedback. E.g., "Run exhaustive grep before claiming all instances fixed."]
+
+2. **[Pattern]**: [Another avoidable iteration pattern.]
+
+## Consultation Feedback
+
+[For each phase that had consultation, summarize every reviewer's concerns and how the builder responded. Use **Addressed** (fixed), **Rebutted** (disagreed with reasoning), or **N/A** (out of scope/moot) for each concern. If all reviewers approved with no concerns: "No concerns raised — all consultations approved."]
+
+### [Phase] Phase (Round N)
+
+#### Gemini
+- **Concern**: [Summary of concern]
+  - **Addressed**: [What was changed]
+
+#### Codex
+- **Concern**: [Summary of concern]
+  - **Rebutted**: [Why current approach is correct]
+
+#### Claude
+- No concerns raised (APPROVE)
+
+## Lessons Learned
+
+### What Went Well
+- [Specific positive observation — what worked and why]
+
+### Challenges Encountered
+- **[Challenge]**: [How it was resolved. How many iterations it cost.]
+
+### What Would Be Done Differently
+- [Actionable improvement for future builders]
+
+## Architecture Updates
+
+[What was added/changed in `codev/resources/arch.md`, or why no changes were needed.]
+
+- Updated: [section name] — [what was added/changed]
+- Or: "No architecture updates needed — [brief reason]"
+
+## Lessons Learned Updates
+
+[What was added/changed in `codev/resources/lessons-learned.md`, or why no changes were needed.]
+
+- Added: [category] — [lesson summary]
+- Or: "No lessons learned updates needed — [brief reason]"
+
+## Technical Debt
+
+- [Any shortcuts taken or inconsistencies introduced]
+
+## Follow-up Items
+
+- [Items identified for future work, outside this spec's scope]

package/skeleton/protocols/aspir/templates/spec.md

@@ -0,0 +1,182 @@
+# Specification: [Title]
+
+<!--
+SPEC vs PLAN BOUNDARY:
+This spec defines WHAT and WHY. The plan defines HOW and WHEN.
+
+DO NOT include in this spec:
+- Implementation phases or steps
+- File paths to modify
+- Code examples or pseudocode
+- "First we will... then we will..."
+
+These belong in codev/plans/XXXX-*.md
+-->
+
+## Metadata
+- **ID**: spec-[YYYY-MM-DD]-[short-name]
+- **Status**: draft
+- **Created**: [YYYY-MM-DD]
+
+## Clarifying Questions Asked
+<!-- Document the questions you asked the user/stakeholder and their answers -->
+[List the questions you asked to understand the problem better and the responses received. This shows the discovery process.]
+
+## Problem Statement
+[Clearly articulate the problem being solved. Include context about why this is important, who is affected, and what the current pain points are.]
+
+## Current State
+[Describe how things work today. What are the limitations? What workarounds exist? Include specific examples.]
+
+## Desired State
+[Describe the ideal solution. How should things work after implementation? What specific improvements will users see?]
+
+## Stakeholders
+- **Primary Users**: [Who will directly use this feature?]
+- **Secondary Users**: [Who else is affected?]
+- **Technical Team**: [Who will implement and maintain this?]
+- **Business Owners**: [Who has decision authority?]
+
+## Success Criteria
+- [ ] [Specific, measurable criterion 1]
+- [ ] [Specific, measurable criterion 2]
+- [ ] [Specific, measurable criterion 3]
+- [ ] All tests pass with >90% coverage
+- [ ] Performance benchmarks met (specify below)
+- [ ] Documentation updated
+
+## Constraints
+### Technical Constraints
+- [Existing system limitations]
+- [Technology stack requirements]
+- [Integration points]
+
+### Business Constraints
+- [Timeline requirements]
+- [Budget considerations]
+- [Compliance requirements]
+
+## Assumptions
+- [List assumptions being made]
+- [Include dependencies on other work]
+- [Note any prerequisites]
+
+## Solution Approaches
+
+### Approach 1: [Name]
+**Description**: [Brief overview of this approach]
+
+**Pros**:
+- [Advantage 1]
+- [Advantage 2]
+
+**Cons**:
+- [Disadvantage 1]
+- [Disadvantage 2]
+
+**Estimated Complexity**: [Low/Medium/High]
+**Risk Level**: [Low/Medium/High]
+
+### Approach 2: [Name]
+[Repeat structure for additional approaches]
+
+[Add as many approaches as appropriate for the problem]
+
+## Open Questions
+
+### Critical (Blocks Progress)
+- [ ] [Question that must be answered before proceeding]
+
+### Important (Affects Design)
+- [ ] [Question that influences technical decisions]
+
+### Nice-to-Know (Optimization)
+- [ ] [Question that could improve the solution]
+
+## Performance Requirements
+- **Response Time**: [e.g., <200ms p95]
+- **Throughput**: [e.g., 1000 requests/second]
+- **Resource Usage**: [e.g., <500MB memory]
+- **Availability**: [e.g., 99.9% uptime]
+
+## Security Considerations
+- [Authentication requirements]
+- [Authorization model]
+- [Data privacy concerns]
+- [Audit requirements]
+
+## Test Scenarios
+### Functional Tests
+1. [Scenario 1: Happy path]
+2. [Scenario 2: Edge case]
+3. [Scenario 3: Error condition]
+
+### Non-Functional Tests
+1. [Performance test scenario]
+2. [Security test scenario]
+3. [Load test scenario]
+
+## Dependencies
+- **External Services**: [List any external APIs or services]
+- **Internal Systems**: [List internal dependencies]
+- **Libraries/Frameworks**: [List required libraries]
+
+## References
+- [Link to relevant documentation in codev/ref/]
+- [Link to related specifications]
+- [Link to architectural diagrams]
+- [Link to research materials]
+
+## Risks and Mitigation
+| Risk | Probability | Impact | Mitigation Strategy |
+|------|------------|--------|-------------------|
+| [Risk 1] | Low/Med/High | Low/Med/High | [How to address] |
+| [Risk 2] | Low/Med/High | Low/Med/High | [How to address] |
+
+## Expert Consultation
+<!-- Only if user requested multi-agent consultation -->
+**Date**: [YYYY-MM-DD]
+**Models Consulted**: [e.g., GPT-5 and Gemini Pro]
+**Sections Updated**:
+- [Section name]: [Brief description of change based on consultation]
+- [Section name]: [Brief description of change based on consultation]
+
+Note: All consultation feedback has been incorporated directly into the relevant sections above.
+
+## Approval
+- [ ] Technical Lead Review
+- [ ] Product Owner Review
+- [ ] Stakeholder Sign-off
+- [ ] Expert AI Consultation Complete
+
+## Notes
+[Any additional context or considerations not covered above]
+
+---
+
+## Amendments
+
+This section tracks all TICK amendments to this specification. TICKs are lightweight changes that refine an existing spec rather than creating a new one.
+
+<!-- When adding a TICK amendment, add a new entry below this line in chronological order -->
+
+<!--
+### TICK-001: [Amendment Title] (YYYY-MM-DD)
+
+**Summary**: [One-line description of what changed]
+
+**Problem Addressed**:
+[Why this amendment was needed - what gap or issue in the original spec]
+
+**Spec Changes**:
+- [Section modified]: [What changed and why]
+- [New section added]: [Purpose]
+
+**Plan Changes**:
+- [Phase added/modified]: [Description]
+- [Implementation steps]: [What was updated]
+
+**Review**: See `reviews/####-name-tick-001.md`
+
+---
+-->

package/skeleton/protocols/bugfix/builder-prompt.md

@@ -54,6 +54,15 @@ Always use `af send architect "..."` to notify the architect at key moments:
 - **Blocked**: `af send architect "Blocked on issue #{{issue.number}}: [reason]"`
 {{/if}}
 
+## Handling Flaky Tests
+
+If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
+1. **DO NOT** edit `status.yaml` to bypass checks
+2. **DO NOT** skip porch checks or use any workaround to avoid the failure
+3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
+4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section
+5. Commit the skip and continue with your work
+
 ## Getting Started
 1. Read the BUGFIX protocol
 2. Review the issue details

package/skeleton/protocols/experiment/builder-prompt.md

@@ -46,6 +46,15 @@ The EXPERIMENT protocol ensures disciplined experimentation:
 - Document findings regardless of outcome
 - Separate experiment artifacts from production code
 
+## Handling Flaky Tests
+
+If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
+1. **DO NOT** edit `status.yaml` to bypass checks
+2. **DO NOT** skip porch checks or use any workaround to avoid the failure
+3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
+4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section
+5. Commit the skip and continue with your work
+
 ## Getting Started
 1. Read the EXPERIMENT protocol document
 2. Define your hypothesis clearly

package/skeleton/protocols/maintain/builder-prompt.md

@@ -40,6 +40,15 @@ The MAINTAIN protocol handles codebase hygiene:
 - Update documentation to match current architecture
 - Don't remove anything actively used
 
+## Handling Flaky Tests
+
+If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
+1. **DO NOT** edit `status.yaml` to bypass checks
+2. **DO NOT** skip porch checks or use any workaround to avoid the failure
+3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
+4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section
+5. Commit the skip and continue with your work
+
 ## Getting Started
 1. Read the MAINTAIN protocol document
 2. Start with the Audit phase

package/skeleton/protocols/spir/builder-prompt.md

@@ -60,6 +60,15 @@ Always use `af send architect "..."` to notify the architect at key moments:
 - **PR merged**: `af send architect "Project {{project_id}} complete. PR merged. Ready for cleanup."`
 - **Blocked**: `af send architect "Blocked on project {{project_id}}: [reason]"`
 
+## Handling Flaky Tests
+
+If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
+1. **DO NOT** edit `status.yaml` to bypass checks
+2. **DO NOT** skip porch checks or use any workaround to avoid the failure
+3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
+4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section
+5. Commit the skip and continue with your work
+
 ## Getting Started
 1. Read the protocol document thoroughly
 2. Review the spec and plan (if available)

package/skeleton/protocols/spir/prompts/implement.md

@@ -206,3 +206,10 @@ Signal `BLOCKED` with details about what's missing.
 
 **If build or tests fail and you can't fix it**:
 Signal `BLOCKED` with the error message.
+
+**If you encounter pre-existing flaky tests** (tests that fail intermittently but are unrelated to your changes):
+1. **DO NOT** edit `status.yaml` to bypass checks
+2. **DO NOT** skip porch checks or use workarounds to avoid the failure
+3. **DO** mark the flaky test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent timeout, skipped pending investigation`)
+4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section so the team can follow up
+5. Commit the skip and continue with your work

package/skeleton/protocols/spir/prompts/review.md

@@ -98,6 +98,11 @@ Brief description of what was implemented.
 
 [See instructions below]
 
+## Flaky Tests
+- [Any pre-existing tests that were skipped as flaky during this project]
+- [Include test name, file path, and observed failure mode]
+- [If none: "No flaky tests encountered"]
+
 ## Follow-up Items
 - [Any items identified for future work]
 ```

package/skeleton/protocols/tick/builder-prompt.md

@@ -50,6 +50,15 @@ The plan to amend is at: `{{plan.path}}`
 {{task_text}}
 {{/if}}
 
+## Handling Flaky Tests
+
+If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
+1. **DO NOT** edit `status.yaml` to bypass checks
+2. **DO NOT** skip porch checks or use any workaround to avoid the failure
+3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
+4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section
+5. Commit the skip and continue with your work
+
 ## Getting Started
 1. Read the TICK protocol thoroughly
 2. Identify what needs to change in the existing spec

package/skeleton/templates/AGENTS.md

@@ -9,6 +9,7 @@ This project uses **Codev** for AI-assisted development.
 ## Available Protocols
 
 - **SPIR**: Multi-phase development with consultation (`codev/protocols/spir/protocol.md`)
+- **ASPIR**: Autonomous SPIR — no human gates on spec/plan (`codev/protocols/aspir/protocol.md`)
 - **TICK**: Fast autonomous implementation (`codev/protocols/tick/protocol.md`)
 - **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`)
 - **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`)

package/skeleton/templates/CLAUDE.md

@@ -7,6 +7,7 @@ This project uses **Codev** for AI-assisted development.
 ## Available Protocols
 
 - **SPIR**: Multi-phase development with consultation (`codev/protocols/spir/protocol.md`)
+- **ASPIR**: Autonomous SPIR — no human gates on spec/plan (`codev/protocols/aspir/protocol.md`)
 - **TICK**: Fast autonomous implementation (`codev/protocols/tick/protocol.md`)
 - **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`)
 - **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`)

package/templates/tower.html

@@ -1460,36 +1460,13 @@
       }
     }
 
-    // Restart a workspace
+    // Restart a workspace dashboard (refresh UI state without touching terminals)
     async function restartInstance(workspacePath) {
       try {
-        // First stop
-        await authFetch('./api/stop', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ workspacePath })
-        });
-
-        // Wait a moment for processes to die
-        await new Promise(r => setTimeout(r, 1000));
-
-        // Then start
-        const response = await authFetch('./api/launch', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ workspacePath })
-        });
-
-        const result = await response.json();
-
-        if (!result.success) {
-          throw new Error(result.error || 'Restart failed');
-        }
-
-        showToast('Workspace restarting...', 'success');
-        setTimeout(refresh, 2000);
+        showToast('Refreshing dashboard...', 'success');
+        await refresh();
       } catch (err) {
-        showToast('Failed to restart: ' + err.message, 'error');
+        showToast('Failed to refresh: ' + err.message, 'error');
       }
     }