@cluesmith/codev 3.0.0-rc.9 → 3.0.1

package/skeleton/porch/prompts/understand.md

@@ -1,61 +0,0 @@
-# Understand Phase Prompt (TICK)
-
-You are working in a TICK protocol - fast autonomous implementation for amendments.
-
-## Your Mission
-
-Understand the existing spec and what amendment is being requested. TICK is for small changes to existing, integrated features.
-
-## Input Context
-
-Read these files:
-1. `codev/specs/{project-id}-*.md` - The existing spec (being amended)
-2. `codev/plans/{project-id}-*.md` - The existing plan
-3. `codev/status/{project-id}-*.md` - Current state and amendment description
-
-## Workflow
-
-### 1. Identify the Amendment
-
-From the status file, understand:
-- What change is being requested?
-- What's the scope? (Should be < 300 LOC)
-- What existing code will be affected?
-
-### 2. Verify TICK is Appropriate
-
-TICK is appropriate when:
-- [ ] Feature already has an integrated spec
-- [ ] Change is small (< 300 LOC)
-- [ ] Requirements are clear
-- [ ] No architectural changes needed
-
-If NOT appropriate, signal: `<signal>NEEDS_SPIR</signal>`
-
-### 3. Document Understanding
-
-Update status file with:
-```markdown
-## Amendment Understanding
-
-**Existing Spec**: {spec-id}
-**Amendment Request**: {description}
-**Scope**: {estimated LOC}
-**Files to Change**:
-- file1.ts
-- file2.ts
-
-**Approach**: {brief description of how to implement}
-```
-
-### 4. Signal Completion
-
-When understanding is complete:
-1. Update status file
-2. Output: `<signal>UNDERSTOOD</signal>`
-
-## Constraints
-
-- DO NOT start implementing
-- DO NOT create new spec files (amend existing)
-- Keep scope small - if > 300 LOC, recommend SPIR instead

package/skeleton/porch/prompts/verify.md

@@ -1,58 +0,0 @@
-# Verify Phase Prompt (TICK)
-
-You are in the Verify phase of TICK protocol.
-
-## Your Mission
-
-Verify that the amendment implementation is complete and correct. Run tests and build to ensure nothing is broken.
-
-## Input Context
-
-Read these files:
-1. `codev/specs/{project-id}-*.md` - Spec with amendment
-2. `codev/status/{project-id}-*.md` - Implementation notes
-
-## Workflow
-
-### 1. Run Build
-
-```bash
-npm run build
-```
-
-If build fails:
-- Output: `<signal>VERIFICATION_FAILED</signal>`
-- Include error details in output
-
-### 2. Run Tests
-
-```bash
-npm test
-```
-
-If tests fail:
-- Output: `<signal>VERIFICATION_FAILED</signal>`
-- Include which tests failed
-
-### 3. Quick Manual Check
-
-Verify:
-- [ ] Amendment matches the request
-- [ ] No unintended side effects
-- [ ] Code follows project conventions
-
-### 4. Signal Completion
-
-When all checks pass:
-1. Update status file with verification results
-2. Output: `<signal>VERIFIED</signal>`
-
-## Backpressure
-
-Both build AND tests must pass before VERIFIED can be signaled. This is non-negotiable.
-
-## Constraints
-
-- DO NOT add new features
-- DO NOT refactor unrelated code
-- Keep verification focused on the amendment

package/skeleton/protocols/maintain/prompts/audit.md

@@ -1,111 +0,0 @@
-# AUDIT Phase Prompt
-
-You are executing the **AUDIT** phase of the MAINTAIN protocol.
-
-## Your Goal
-
-Analyze the codebase to identify dead code, unused dependencies, and stale documentation.
-
-## Context
-
-- **Current State**: {{current_state}}
-
-## Process
-
-### 1. Determine Base Commit
-
-Find the last maintenance run:
-```bash
-ls codev/maintain/
-```
-
-If previous runs exist, note the base commit to focus on changes since then.
-
-### 2. Scan for Dead Code
-
-Run static analysis tools:
-
-```bash
-# TypeScript/JavaScript
-npx ts-prune 2>/dev/null || echo "ts-prune not available"
-npx depcheck 2>/dev/null || echo "depcheck not available"
-
-# Check for unused exports
-grep -r "export " --include="*.ts" --include="*.tsx" | head -50
-```
-
-### 3. Scan for Unused Dependencies
-
-Check package.json for unused dependencies:
-```bash
-cat package.json | grep -A100 '"dependencies"' | head -50
-```
-
-Cross-reference with actual imports in the codebase.
-
-### 4. Scan for Stale Documentation
-
-Check for references to deleted files/functions:
-```bash
-# Recent changes
-git log --oneline -20
-
-# Check if arch.md references exist
-grep -E "src/|packages/" codev/resources/arch.md | head -20
-```
-
-### 5. Create Audit Report
-
-Create a maintenance run file: `codev/maintain/NNN.md`
-
-Document:
-- Dead code identified (with file paths)
-- Unused dependencies
-- Stale documentation references
-- Recommended actions
-
-Use the template structure:
-```markdown
-# Maintenance Run NNN
-
-**Date**: YYYY-MM-DD
-**Base Commit**: <commit-hash>
-
-## Dead Code Identified
-
-| File | Item | Reason |
-|------|------|--------|
-| path/to/file.ts | unusedFunction() | Not imported anywhere |
-
-## Unused Dependencies
-
-| Package | Reason |
-|---------|--------|
-| some-pkg | Not imported |
-
-## Stale Documentation
-
-| Document | Issue |
-|----------|-------|
-| arch.md | References deleted module |
-
-## Recommended Actions
-
-1. Remove X
-2. Update Y
-3. ...
-```
-
-## Signals
-
-When audit report is complete:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If blocked:
-
-```
-<signal>BLOCKED:reason</signal>
-```

package/skeleton/protocols/maintain/prompts/clean.md

@@ -1,91 +0,0 @@
-# CLEAN Phase Prompt
-
-You are executing the **CLEAN** phase of the MAINTAIN protocol.
-
-## Your Goal
-
-Remove the dead code and unused dependencies identified in the audit phase.
-
-## Context
-
-- **Current State**: {{current_state}}
-
-## Prerequisites
-
-Read the audit report from the previous phase:
-```bash
-ls -la codev/maintain/
-cat codev/maintain/*.md | tail -100
-```
-
-## Process
-
-### 1. Remove Dead Code
-
-For each item identified in the audit:
-
-1. Verify it's truly unused (double-check with grep)
-2. Use `git rm` for tracked files
-3. For untracked files, move to `.trash/` before deleting
-
-**CRITICAL**: Use soft deletion first:
-```bash
-mkdir -p codev/maintain/.trash/$(date +%Y-%m-%d)
-mv path/to/file codev/maintain/.trash/$(date +%Y-%m-%d)/
-```
-
-### 2. Remove Unused Dependencies
-
-```bash
-# Remove from package.json
-npm uninstall <package-name>
-```
-
-### 3. Verify Build After Each Removal
-
-After each significant removal:
-```bash
-npm run build
-npm test -- --exclude='**/e2e/**'
-```
-
-If build fails, revert the change and investigate.
-
-### 4. Commit Changes
-
-Make atomic commits for each logical change:
-```bash
-git add <specific-files>
-git commit -m "[Maintain] Remove unused X"
-```
-
-**NEVER use `git add -A` or `git add .`**
-
-## Important Rules
-
-1. **One removal at a time** - Don't batch unrelated changes
-2. **Verify after each removal** - Build must pass
-3. **Document what was removed** - Update the maintenance run file
-4. **Soft delete first** - Move to .trash/ before permanent deletion
-5. **Check for side effects** - Grep for references before removing
-
-## Output
-
-Update the maintenance run file with:
-- What was removed
-- Build/test status after removal
-- Any issues encountered
-
-## Signals
-
-When all dead code is removed and build passes:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If blocked:
-
-```
-<signal>BLOCKED:reason</signal>
-```

package/skeleton/protocols/maintain/prompts/sync.md

@@ -1,113 +0,0 @@
-# SYNC Phase Prompt
-
-You are executing the **SYNC** phase of the MAINTAIN protocol.
-
-## Your Goal
-
-Update documentation to match the current state of the codebase.
-
-## Context
-
-- **Current State**: {{current_state}}
-
-## Process
-
-### 1. Update arch.md
-
-Read the current architecture doc and compare with actual codebase:
-
-```bash
-cat codev/resources/arch.md
-ls -la packages/ src/ 2>/dev/null
-```
-
-Update:
-- Directory structure (if changed)
-- Component descriptions
-- Key files and their purposes
-- Remove references to deleted code
-- Add new utilities/components
-
-**arch.md must explain HOW things work, not just WHAT they are.**
-
-### 2. Generate/Update lessons-learned.md
-
-Scan review documents for lessons:
-
-```bash
-ls codev/reviews/
-```
-
-Extract actionable lessons:
-- Testing practices
-- Architecture decisions
-- Process improvements
-- Patterns to follow/avoid
-
-Format:
-```markdown
-## [Topic]
-- [From NNN] Lesson description
-```
-
-### 3. Sync CLAUDE.md with AGENTS.md
-
-Compare the two files:
-```bash
-diff CLAUDE.md AGENTS.md | head -50
-```
-
-They must be identical. Update the stale one to match.
-
-### 4. Prune Documentation
-
-Check document sizes:
-```bash
-wc -l CLAUDE.md AGENTS.md README.md
-```
-
-Target ~400 lines for CLAUDE.md/README.md (guideline, not mandate).
-
-For any content removed, document:
-- WHAT was removed
-- WHY it was removed (OBSOLETE, DUPLICATIVE, MOVED, VERBOSE)
-- WHERE it moved (if applicable)
-
-### 5. Commit Documentation Changes
-
-```bash
-git add codev/resources/arch.md codev/resources/lessons-learned.md
-git commit -m "[Maintain] Update arch.md and lessons-learned.md"
-
-git add CLAUDE.md AGENTS.md
-git commit -m "[Maintain] Sync CLAUDE.md with AGENTS.md"
-```
-
-## Important Rules
-
-1. **Never invent structure** - Only document what exists
-2. **Verify file paths** - Check that referenced files exist
-3. **Keep it current** - Remove obsolete references
-4. **Preserve important content** - Don't delete patterns/best practices
-5. **Document deletions** - Every removal needs justification
-
-## Output
-
-Update the maintenance run file with:
-- Documents updated
-- What was added/removed/changed
-- Any issues encountered
-
-## Signals
-
-When documentation is synchronized:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If blocked:
-
-```
-<signal>BLOCKED:reason</signal>
-```

package/skeleton/protocols/maintain/prompts/verify.md

@@ -1,110 +0,0 @@
-# VERIFY Phase Prompt
-
-You are executing the **VERIFY** phase of the MAINTAIN protocol.
-
-## Your Goal
-
-Run final validation and prepare for PR creation.
-
-## Context
-
-- **Current State**: {{current_state}}
-
-## Process
-
-### 1. Run Full Test Suite
-
-```bash
-npm run build
-npm test
-```
-
-Both must pass. If either fails, go back and fix the issue.
-
-### 2. Run Linting
-
-```bash
-npm run lint 2>/dev/null || echo "No lint script"
-```
-
-Fix any linting errors.
-
-### 3. Verify Documentation Links
-
-Check that documentation references resolve:
-```bash
-# Check arch.md file references
-grep -oE 'src/[^ ]+|packages/[^ ]+' codev/resources/arch.md | while read f; do
-  [ -e "$f" ] || echo "Missing: $f"
-done
-```
-
-### 4. Update Maintenance Run Summary
-
-Finalize the maintenance run file with:
-
-```markdown
-## Summary
-
-- **Dead code removed**: X files, Y functions
-- **Dependencies removed**: Z packages
-- **Documentation updated**: arch.md, lessons-learned.md
-- **All tests passing**: Yes/No
-- **Build status**: Success/Failure
-
-## Next Maintenance
-
-Recommended focus areas for next run:
-- ...
-```
-
-### 5. Create PR
-
-```bash
-git push origin HEAD
-
-gh pr create --title "[Maintain] Codebase maintenance run NNN" --body "$(cat <<'EOF'
-## Summary
-
-- Dead code removal
-- Documentation sync
-- Dependency cleanup
-
-## Changes
-
-[List key changes]
-
-## Verification
-
-- [x] Build passes
-- [x] Tests pass
-- [x] Documentation updated
-EOF
-)"
-```
-
-## Validation Checklist
-
-Before signaling complete:
-
-- [ ] All tests pass
-- [ ] Build succeeds
-- [ ] No import/module errors
-- [ ] Documentation links resolve
-- [ ] Linter passes (if configured)
-- [ ] Maintenance run file is complete
-- [ ] PR is created
-
-## Signals
-
-When validation passes and PR is ready:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If blocked:
-
-```
-<signal>BLOCKED:reason</signal>
-```

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

@@ -1,65 +0,0 @@
-# {{protocol_name}} Builder ({{mode}} mode)
-
-You are implementing {{input_description}}.
-
-{{#if mode_soft}}
-## Mode: SOFT
-You are running in SOFT mode. This means:
-- You follow the TICK protocol yourself (no porch orchestration)
-- The architect monitors your work and verifies you're adhering to the protocol
-- Run consultations manually when the protocol calls for them
-- You have flexibility in execution, but must stay compliant with the protocol
-{{/if}}
-
-{{#if mode_strict}}
-## Mode: STRICT
-You are running in STRICT mode. This means:
-- Porch orchestrates your work
-- Run: `porch next` to get your next tasks
-- Follow porch signals and gate approvals
-
-### ABSOLUTE RESTRICTIONS (STRICT MODE)
-- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
-- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
-- **NEVER skip the 3-way review** — always follow porch next → porch done cycle
-{{/if}}
-
-## Protocol
-Follow the TICK protocol: `codev/protocols/tick/protocol.md`
-
-TICK is for amendments to existing SPIR specifications. You will:
-1. Identify the target spec to amend
-2. Update the spec with the amendment
-3. Update the plan
-4. Implement the changes
-5. Defend with tests
-6. Create review
-
-{{#if spec}}
-## Target Spec
-The spec to amend is at: `{{spec.path}}`
-{{/if}}
-
-{{#if plan}}
-## Target Plan
-The plan to amend is at: `{{plan.path}}`
-{{/if}}
-
-{{#if task}}
-## Amendment Description
-{{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
-3. Follow the amendment workflow

package/skeleton/protocols/tick/consult-types/impl-review.md

@@ -1,72 +0,0 @@
-# Implementation Review Prompt
-
-## Context
-You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan.
-
-## CRITICAL: Verify Before Flagging
-
-Before requesting changes for missing configuration, incorrect patterns, or framework issues:
-1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions
-2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs
-3. **Do not assume** your training data reflects the version in use — verify against project files
-4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed
-
-## Focus Areas
-
-1. **Spec Adherence**
-   - Does the implementation fulfill the spec requirements for this phase?
-   - Are acceptance criteria met?
-
-2. **Code Quality**
-   - Is the code readable and maintainable?
-   - Are there obvious bugs or issues?
-   - Are error cases handled appropriately?
-
-3. **Test Coverage**
-   - Are the tests adequate for this phase?
-   - Do tests cover the main paths AND edge cases?
-
-4. **Plan Alignment**
-   - Does the implementation follow the plan?
-   - Are there plan items skipped or partially completed?
-
-5. **UX Verification** (if spec has UX requirements)
-   - Does the actual user experience match what the spec describes?
-   - If spec says "async" or "non-blocking", is it actually async?
-
-## Verdict Format
-
-After your review, provide your verdict in exactly this format:
-
-```
----
-VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
-SUMMARY: [One-line summary of your assessment]
-CONFIDENCE: [HIGH | MEDIUM | LOW]
----
-KEY_ISSUES:
-- [Issue 1 or "None"]
-- [Issue 2]
-...
-```
-
-**Verdict meanings:**
-- `APPROVE`: Phase is complete, builder can proceed
-- `REQUEST_CHANGES`: Issues that must be fixed before proceeding
-- `COMMENT`: Minor suggestions, can proceed but note feedback
-
-## Scoping (Multi-Phase Plans)
-
-When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl):
-- **ONLY review work belonging to the current plan phase**
-- The query will specify which phase you are reviewing
-- Do NOT request changes for functionality scheduled in later phases
-- Do NOT flag missing features that are out of scope for this phase
-- If unsure whether something belongs to this phase, check the plan file
-
-## Notes
-
-- This is a phase-level review, not the final PR review
-- Focus on "does this phase work" not "is the whole feature done"
-- If referencing line numbers, use `file:line` format
-- The builder needs actionable feedback to continue