@cluesmith/codev 3.2.3 → 3.3.0

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

@@ -1,184 +1,65 @@
 # Plan: [Title]
 
-## Metadata
-- **ID**: plan-[YYYY-MM-DD]-[short-name]
-- **Status**: draft
-- **Specification**: [Link to codev/specs/spec-file.md]
-- **Created**: [YYYY-MM-DD]
+**Specification**: [Link to codev/specs/XXXX-*.md]
 
 ## 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
+The implementation approach chosen and why, referencing the spec's selected approach.
 
 ## Phases (Machine Readable)
 
-<!-- REQUIRED: porch uses this JSON to track phase progress. Update this when adding/removing phases. -->
+<!-- REQUIRED: porch parses this JSON to track phase progress. Keep it in sync when you add or remove phases; at least two 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"}
+    {"id": "phase_2", "title": "Phase 2 Title Here"}
   ]
 }
 ```
 
 ## Phase Breakdown
 
+Repeat this block per phase. Each phase is self-contained, independently testable, valuable, and a single atomic commit.
+
 ### Phase 1: [Descriptive Name]
+
 **Dependencies**: None
 
-#### Objectives
-- [Clear, single objective for this phase]
-- [What value does this phase deliver?]
+#### Objective
+
+The single goal of this phase and the value it delivers.
+
+#### Files to Create / Modify
+
+Specific paths.
 
 #### 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
+- [ ] …
+- [ ] Tests for this phase
 
-#### Test Plan
-- **Unit Tests**: [What to test]
-- **Integration Tests**: [What to test]
-- **Manual Testing**: [Scenarios to verify]
+#### Acceptance Criteria
 
-#### Rollback Strategy
-[How to revert this phase if issues arise]
+- [ ] Testable criterion(s), plus build and tests passing.
 
-#### Risks
-- **Risk**: [Specific risk for this phase]
-  - **Mitigation**: [How to address]
+#### Test Plan
 
----
+Unit / integration / manual scenarios that verify this phase.
 
 ### Phase 2: [Descriptive Name]
-**Dependencies**: Phase 1
-
-[Repeat structure for each phase]
 
----
+**Dependencies**: Phase 1
 
-### Phase 3: [Descriptive Name]
-**Dependencies**: Phase 2
+[Same structure.]
 
-[Continue for all phases]
+## Risks and Mitigation
 
-## Dependency Map
-```
-Phase 1 ──→ Phase 2 ──→ Phase 3
-             ↓
-         Phase 4 (optional)
-```
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| … | | | |
 
-## 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]
+## Documentation Updates
 
+Which docs change (README, API docs, arch/lessons) — or none.

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

@@ -2,119 +2,60 @@
 
 ## Summary
 
-[1-3 sentences: what was built, how many phases, net outcome.]
+1–3 sentences: what was built, how many phases, the net outcome.
 
 ## Spec Compliance
 
+Each acceptance criterion and whether it was met, with the phase that delivered it.
+
 - [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.]
+What changed from the plan, per phase, and why. "None" if the plan held.
 
 ## 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."]
+Per phase that had consultation, each reviewer's concerns and how you responded — **Addressed** (changed), **Rebutted** (why it does not apply), or **N/A** (out of scope / moot). "No concerns raised — all consultations approved" when that is true; note COMMENT verdicts and any `CONSULT_ERROR`.
 
 ### [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)
+- **Concern**: … → **Addressed** / **Rebutted** / **N/A**: …
 
 ## 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 was hard and how it resolved.
 
 ### What Would Be Done Differently
-- [Actionable improvement for future builders]
+
+### Methodology Improvements
+
+Suggested improvements to the SPIR protocol or the tooling.
 
 ## Architecture Updates
 
-[What you routed where — HOT `codev/resources/arch-critical.md` (tiny, capped, always-injected) vs COLD `codev/resources/arch.md` (reference) — or why no changes were needed.]
+What you routed where — HOT `codev/resources/arch-critical.md` (tiny, capped, always-injected) vs COLD `codev/resources/arch.md` (reference) — or why no change was needed. Note any hot-tier demotion made to respect the cap.
 
-- Routed: [hot | cold] — [fact/section] — [what was added/changed; note any demotion if the hot file was full]
-- Or: "No architecture updates needed — [brief reason]"
+- Routed: [hot | cold] — [fact] — [what changed]
+- Or: "No architecture updates needed — [reason]"
 
 ## Lessons Learned Updates
 
-[What you routed where — HOT `codev/resources/lessons-critical.md` (capped) vs COLD `codev/resources/lessons-learned.md` (reference) — or why no changes were needed.]
+What you routed where — HOT `codev/resources/lessons-critical.md` (capped) vs COLD `codev/resources/lessons-learned.md` (reference) — or why no change was needed.
 
-- Routed: [hot | cold] — [category] — [lesson summary]
-- Or: "No lessons learned updates needed — [brief reason]"
+- Routed: [hot | cold] — [category] — [lesson]
+- Or: "No lessons learned updates needed — [reason]"
 
-## Technical Debt
+## Flaky Tests
 
-- [Any shortcuts taken or inconsistencies introduced]
+Pre-existing tests skipped as flaky during this project — name, file path, observed failure mode. "No flaky tests encountered" if none.
 
 ## Follow-up Items
 
-- [Items identified for future work, outside this spec's scope]
+Work identified for later, outside this spec's scope.

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

@@ -3,152 +3,58 @@
 <!--
 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
+Keep implementation phases, file paths, code, and "first we will… then we will…"
+out of the spec — those 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.]
+
+What problem is being solved, why it matters, who is affected, and the current pain points.
 
 ## Current State
-[Describe how things work today. What are the limitations? What workarounds exist? Include specific examples.]
+
+How things work today, and the limitations or workarounds that motivate the change. Concrete 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?]
+How things should work after implementation, and the specific improvements users will see.
 
 ## 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
+
+Measurable, testable acceptance criteria — the conditions under which this spec is satisfied.
+
+- [ ] …
 
 ## Constraints
-### Technical Constraints
-- [Existing system limitations]
-- [Technology stack requirements]
-- [Integration points]
 
-### Business Constraints
-- [Timeline requirements]
-- [Budget considerations]
-- [Compliance requirements]
+Technical and business constraints that bound the solution: existing-system limits, required stack, integration points, compliance.
 
 ## Assumptions
-- [List assumptions being made]
-- [Include dependencies on other work]
-- [Note any prerequisites]
 
-## Solution Approaches
-
-### Approach 1: [Name]
-**Description**: [Brief overview of this approach]
+Assumptions being made and dependencies on other work.
 
-**Pros**:
-- [Advantage 1]
-- [Advantage 2]
+## Solution Approaches
 
-**Cons**:
-- [Disadvantage 1]
-- [Disadvantage 2]
+More than one approach where the space is open. For each: a short description, its trade-offs (pros/cons), and its risk/complexity. Name the recommended one and why.
 
-**Estimated Complexity**: [Low/Medium/High]
-**Risk Level**: [Low/Medium/High]
+### Approach 1: [Name]
 
 ### 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]
+Ranked by how much they block: **Critical** (blocks progress) · **Important** (shapes design) · **Nice-to-know** (optimization).
 
 ## 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]
+The functional and non-functional scenarios that verify the success criteria — happy paths, edge cases, error conditions.
 
-## Dependencies
-- **External Services**: [List any external APIs or services]
-- **Internal Systems**: [List internal dependencies]
-- **Libraries/Frameworks**: [List required libraries]
+## Risks and Mitigation
 
-## References
-- [Link to relevant documentation in codev/ref/]
-- [Link to related specifications]
-- [Link to architectural diagrams]
-- [Link to research materials]
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| … | | | |
 
-## 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]
+## References
 
+Related specs, research, or documentation.