@cluesmith/codev 3.2.3 → 3.3.0

package/skeleton/protocols/bugfix/protocol.md

@@ -1,78 +1,72 @@
 # BUGFIX Protocol
 
-> Lightweight, issue-driven protocol for minor bug fixes. **Investigate → Fix → PR**, with a single `pr` gate before merge. No spec or plan artifacts: the GitHub issue is the spec, and the review goes in the PR body.
+Investigate → Fix → PR, driven by a GitHub issue. No spec, no plan, no artifact files: the issue
+is the specification and the PR body carries the reasoning.
 
-## When to Use
+Use it for a defect whose fix is isolated. For a small *feature* use AIR; for anything needing a
+design decision use SPIR.
 
-Use BUGFIX when a bug is reported as a GitHub Issue and:
+## The state machine
 
-- The reproduction is clear (or inferable) and the root cause is isolated
-- The fix is small (guideline: < 300 LOC net diff) and contained to one area
-- No architectural changes or new design decisions are needed
-
-Escalate to **SPIR** (or another heavier protocol) instead when:
-
-- It is actually a feature request, not a bug
-- The root cause reveals a deeper architectural issue
-- The fix needs design review, spans multiple components, or clearly exceeds ~300 LOC
-
-## Phases
-
-```
-investigate → fix → pr
+```json
+{{> protocols/bugfix/protocol.json}}
 ```
 
-### Investigate
-
-Read the issue, reproduce the bug, and identify the root cause. Confirm the fix fits BUGFIX scope. If it does not, signal `BLOCKED` and recommend escalation to the architect (`afx send architect "..."`). No code in this phase.
-
-### Fix
+## Phases
 
-Apply the minimal change that resolves the root cause, and add a regression test that fails without the fix and passes with it. Keep it focused: do not refactor surrounding code, do not fix unrelated bugs (file separate issues), do not add features. Run the build and tests (porch's `checks` block runs `npm run build` and `npm test`).
+**Investigate** — reproduce the bug and identify the root cause. **No code in this phase.**
+Confirm the fix fits BUGFIX scope; if it does not, signal `BLOCKED` and recommend escalation
+rather than growing the project quietly.
 
-Commit with the issue-driven format:
+**Fix** — the minimal change that resolves the root cause, plus a regression test that **fails
+without the fix and passes with it**. A test that passes either way documents nothing. Do not
+refactor surrounding code, fix unrelated bugs (file separate issues), or add features.
 
 ```
-[Bugfix #<N>] Fix: <what was fixed>
-[Bugfix #<N>] Test: <regression test added>
+[Bugfix #42] Fix: URL-encode username before API call
+[Bugfix #42] Test: regression for unencoded username
 ```
 
-### PR (gated by `pr`)
+**PR** — open with `gh pr create`, body carrying Summary, Root Cause, Fix and Test Plan plus
+`Fixes #<N>` so the issue closes on merge. Run one CMAP pass (Gemini, Codex, Claude), record
+each verdict, and address or rebut every `REQUEST_CHANGES`. Notify the architect with the
+verdicts, then `porch done <id>` and wait.
 
-1. Push the branch and open a PR with `gh pr create`. The body includes Summary, Root Cause, Fix, and Test Plan, plus `Fixes #<N>` so the issue auto-closes on merge.
-2. Run a multi-agent CMAP review on the PR (Gemini, Codex, Claude) and record each verdict. Address or rebut any `REQUEST_CHANGES`; add a regression test if a real defect surfaced.
-3. Notify the architect: `afx send architect "PR #<M> ready for review (fixes #<N>). CMAP: gemini=..., codex=..., claude=..."`.
-4. Run `porch done <id>` to request the `pr` gate, then wait. **The merge is gated by porch state, never by typed prose in your pane.**
-5. The human reviews the PR and the CMAP results on GitHub, then approves the gate: `porch approve <id> pr --a-human-explicitly-approved-this`.
-6. porch wakes the builder with a merge task. Merge with `gh pr merge --merge` (do **not** pass `--delete-branch`: the builder is checked out on this branch in a worktree), then run `porch done <id>` and notify the architect that it is merged and ready for cleanup.
+Merge with `gh pr merge --merge`. **Do not pass `--delete-branch`** — the builder is checked out
+on that branch in a worktree, and deleting it out from under them breaks the worktree.
 
-## Gate
+## The gate exists to make merge authorization structural
 
-BUGFIX has one human gate, `pr`, on the merge step. It exists so the merge trigger is structured porch state (approved or not), not free-text typed into the builder's pane. This eliminates the self-merge bug class: a builder cannot infer authorization from ambiguous input.
+BUGFIX has one human gate, `pr`. Its purpose is that the merge trigger is **porch state** —
+approved or not — rather than free text typed into the builder's pane. That closes the
+self-merge bug class: a builder cannot infer authorization from ambiguous prose.
 
-## Multi-Agent Consultation
+## Consultation
 
-A single CMAP pass at the PR (Gemini, Codex, Claude). There is no per-phase consultation: the issue is the spec and the fix is small, so review effort concentrates on the final PR.
+One CMAP pass at the PR. No per-phase consultation: the issue is the spec and the fix is small,
+so review effort concentrates where it can still change the outcome.
 
 ## Scope
 
-The < 300 LOC threshold is a **guideline**, measured as net diff (additions + deletions) anchored at the merge-base with the default branch. A well-contained 350-LOC fix is fine; a 200-LOC fix smeared across ten files may warrant escalation.
+The <300 LOC threshold is a **guideline**, measured as net diff (additions + deletions) against
+the merge-base with the default branch. A well-contained 350-line fix is fine; a 200-line fix
+smeared across ten files probably warrants escalation.
 
 ## Escalation
 
-If, mid-fix, the change outgrows BUGFIX (architectural impact, multiple components, unclear root cause after investigation, or more than ~300 LOC), notify the architect with specifics and recommend escalating to SPIR. Do not silently expand scope.
-
-## Branch Naming
+If the change outgrows BUGFIX mid-flight — architectural impact, multiple components, unclear
+root cause after investigation — notify the architect with specifics and recommend SPIR. **Do
+not silently expand scope.**
 
-```
-builder/bugfix-<issue-number>-<slug>
-```
-
-## Edge Cases
+## Edge cases
 
 | Scenario | Action |
 |---|---|
-| Cannot reproduce | Document the attempts in an issue comment, ask the reporter for detail, notify the architect |
-| Fix outgrows scope (architectural / multi-component / > ~300 LOC) | Notify the architect, recommend escalation; do not proceed |
-| Unrelated test failures | Out of scope: note them for the architect, do not fix them here |
-| Multiple bugs in one issue | Fix only the primary bug; file separate issues for the rest |
+| Cannot reproduce | Document the attempts on the issue, ask the reporter for detail, notify the architect |
+| Fix outgrows scope | Notify the architect and recommend escalation; do not proceed |
+| Unrelated test failures | Out of scope — note them for the architect, do not fix here |
+| Multiple bugs in one issue | Fix the primary one; file separate issues for the rest |
+
+## Branch naming
+
+`builder/bugfix-<issue>-<slug>`

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

@@ -1,82 +1,49 @@
 # {{protocol_name}} Builder ({{mode}} mode)
 
-You are executing a disciplined experiment.
+You are implementing {{input_description}}.
 
 {{#if mode_soft}}
 ## Mode: SOFT
-You are running in SOFT mode. This means:
-- You follow the EXPERIMENT protocol yourself (no porch orchestration)
-- The architect monitors your work and verifies you're adhering to the protocol
-- Document your findings thoroughly
+
+You follow the protocol yourself; the architect verifies compliance.
 {{/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
+
+Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never
+hand-edit `status.yaml` — only porch commands modify project state.
 {{/if}}
 
 ## Protocol
-Follow the EXPERIMENT protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
-
-## EXPERIMENT Overview
-The EXPERIMENT protocol ensures disciplined experimentation:
 
-1. **Hypothesis Phase**: Define what you're testing and success criteria
-2. **Design Phase**: Plan the experiment approach
-3. **Execute Phase**: Run the experiment and gather data
-4. **Analyze Phase**: Evaluate results and draw conclusions
+The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not
+need to fetch it.
 
-{{#if task}}
 ## Experiment Focus
+
 {{task_text}}
-{{/if}}
 
 ## Key Principles
-- Start with a clear, falsifiable hypothesis
-- Define success/failure criteria upfront
-- Keep scope minimal for quick iteration
-- Document findings regardless of outcome
-- Separate experiment artifacts from production code
 
-## If You Open a PR
+- Start with a **clear, falsifiable hypothesis** and define success/failure criteria **upfront** —
+  an experiment scored after the fact always succeeds
+- Keep scope minimal for fast iteration
+- **Document findings regardless of outcome.** A directory containing only successes has been
+  curated, not run
+- Keep experiment artifacts separate from production code
 
-Most experiments are committed to a branch without a PR, but if you do open one
-to integrate findings and the experiment was triggered by a GitHub issue:
-
-**PR body requirements**: The PR body MUST include `Closes #<N>` (for feature
-issues) or `Fixes #<N>` (for bug issues) for the driving issue so GitHub
-auto-closes it on merge. If the PR closes multiple issues, include one keyword
-per issue.
-
-**Exception**: if this PR only partially addresses the issue (e.g. experiment
-validates an approach but production implementation is deferred), use
-`Refs #<N>` or `Part of #<N>` instead — the issue stays open until a follow-up
-PR closes it.
-
-## 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
+## If You Open a PR
 
-## Getting Started
-1. Read the EXPERIMENT protocol document
-2. Define your hypothesis clearly
-3. Follow the phases in order
+Most experiments are committed to a branch without a PR. If you do open one and the experiment
+came from a GitHub issue, the body **must** carry `Closes #<N>` (feature) or `Fixes #<N>` (bug)
+so GitHub auto-closes it on merge — one keyword per issue if several.
 
----
+**Exception**: if the PR only *partially* addresses the issue (the experiment validates an
+approach but the production implementation is deferred), use `Refs #<N>` or `Part of #<N>` so
+the issue stays open for the follow-up.
 
-## Protocol Reference (full text)
+## Notifications
 
-{{protocol_reference}}
+The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR
+merged, blocked.

package/skeleton/protocols/experiment/protocol.md

@@ -1,203 +1,37 @@
 # EXPERIMENT Protocol
 
-## Overview
+A disciplined experiment: state the hypothesis before running it, record what actually happened,
+and keep the result whichever way it goes.
 
-Disciplined experimentation: Each experiment gets its own directory with `notes.md` tracking goals, code, and results.
+Use it for evaluating models or libraries, proof-of-concept work, and technique comparisons —
+questions that should be settled by evidence rather than by argument.
 
-**Core Principle**: Document what you're trying, what you did, and what you learned.
-
-## When to Use
-
-**Use for**: Testing approaches, evaluating models, prototyping, proof-of-concept work, research spikes
-
-**Skip for**: Production code (use SPIR), simple one-off scripts
-
-## Structure
-
-```
-experiments/
-├── 1_descriptive_name/
-│   ├── notes.md           # Goal, code, results
-│   ├── experiment.py      # Your experiment code
-│   └── data/
-│       ├── input/         # Input data
-│       └── output/        # Results, plots, etc.
-└── 2_another_experiment/
-    ├── notes.md
-    └── ...
-```
-
-## Workflow
-
-### 1. Create Experiment Directory
-
-```bash
-# Create numbered directory
-mkdir -p experiments/1_experiment_name
-cd experiments/1_experiment_name
-
-# Initialize notes.md from template
-touch notes.md   # then fill it from the embedded template at the end of this protocol
-```
-
-Or ask your AI assistant: "Create a new experiment for [goal]"
-
-### 2. Document the Goal
-
-Before writing code, clearly state what you're trying to learn in `notes.md`:
-
-```markdown
-## Goal
-
-What specific question are you trying to answer?
-What hypothesis are you testing?
-```
-
-### 3. Write Experiment Code
-
-- Keep it simple - experiments don't need production polish
-- Reuse existing project modules where possible
-- Any structure is fine - focus on learning, not architecture
-
-**Dependencies**: If your experiment requires libraries not in the main project:
-1. Do NOT add them to the main project's `requirements.txt` or `pyproject.toml`
-2. Create a `requirements.txt` inside your experiment folder
-3. Document installation in `notes.md`
-
-### 4. Run and Observe
-
-Execute your experiment and capture results:
-- Save output files to `data/output/`
-- Take screenshots of visualizations
-- Log key metrics
-
-### 5. Document Results
-
-Update `notes.md` with:
-- What happened (actual results)
-- What you learned (insights)
-- What's next (follow-up actions)
-
-### 6. Commit
-
-```bash
-git add experiments/1_experiment_name/
-git commit -m "[Experiment 1] Brief description of findings"
-```
-
-## Best Practices
-
-### Keep It Simple
-- Experiments don't need production polish
-- Skip comprehensive error handling
-- Focus on answering the question
-
-### Document Honestly
-- Include failures - they're valuable learnings
-- Note dead ends and why they didn't work
-- Be specific about what surprised you
-
-### Track Time Investment
-- Wall clock time: Total elapsed time
-- Developer time: Active working time (excluding waiting)
-- Helps estimate future similar work
-
-### Use Project Modules
-- Don't duplicate existing code
-- Import from your `src/` directory
-- Experiments validate approaches, not reimplement them
-
-### Commit Progress
-- Use `[Experiment ####]` commit prefix
-- Commit intermediate results
-- Include output files when reasonable
-
-## Integration with Other Protocols
-
-### Experiment → SPIR
-When an experiment validates an approach for production use:
-
-1. Create a specification referencing the experiment
-2. Link to experiment results as evidence
-3. Use experiment code as reference implementation
-
-Example spec reference:
-```markdown
-## Background
-
-Experiment 5 validated that [approach] achieves [results].
-See: experiments/5_validation_test/notes.md
-```
-
-## Numbering Convention
-
-Use four-digit sequential numbering (consistent with project list):
-- `1_`, `2_`, `3_`...
-- Shared sequence across all experiments
-- Descriptive name after the number (snake_case)
-
-Examples:
-- `1_api_response_caching`
-- `2_model_comparison`
-- `3_performance_baseline`
-
-## Git Workflow
-
-### Commits
-```
-[Experiment 1] Initial setup and goal
-[Experiment 1] Add baseline measurements
-[Experiment 1] Complete - caching improves latency 40%
-```
-
-### When to Commit
-- After setting up the experiment
-- After significant findings
-- When completing the experiment
-
-**Data Management**:
-- Include `data/output/` ONLY if files are small (summary metrics, small plots)
-- Do NOT commit large datasets, binary model checkpoints, or heavy artifacts
-- Add appropriate entries to `.gitignore` for large files
-- Consider storing large outputs externally and linking in notes
-
-## Example Experiment
+## The state machine
 
-```
-experiments/1_caching_strategy/
-├── notes.md
-├── benchmark.py
-├── cache_test.py
-└── data/
-    ├── input/
-    │   └── sample_requests.json
-    └── output/
-        ├── results.csv
-        └── latency_chart.png
+```json
+{{> protocols/experiment/protocol.json}}
 ```
 
-**notes.md excerpt:**
-```markdown
-# Experiment 1: Caching Strategy Evaluation
+## Structure
 
-**Status**: Complete
+Each experiment gets a numbered directory under `codev/experiments/` with a `notes.md` recording
+the hypothesis, method, results and conclusion.
 
-**Date**: 2024-01-15
+## Notes structure
 
-## Goal
-Determine if Redis caching improves API response times for repeated queries.
+`notes.md` uses this structure:
 
-## Results
-- 40% latency reduction for cached queries
-- Cache hit rate: 73% after warm-up
-- Memory usage: 50MB for 10k cached responses
+{{> protocols/experiment/templates/notes.md}}
 
-## Next Steps
-Create SPIR spec for production caching implementation.
-```
+## The discipline that makes it worth doing
 
-## Template: notes.md
+**Write the hypothesis and the success criteria before running anything.** An experiment scored
+after the fact always succeeds — you discover the criterion the result happens to meet.
 
-Create `notes.md` with the following content:
+**Record negative results.** "We tried X and it did not work, here is why" is the output that
+saves the next person a week. An experiment directory containing only successes is a directory
+that has been curated rather than run.
 
-{{> protocols/experiment/templates/notes.md}}
+**Keep the experiment separate from production code.** Experimental code answers a question; it
+has not earned the standards production code is held to, and promoting it silently is how a
+proof of concept becomes a maintenance burden nobody chose.

package/skeleton/protocols/experiment/templates/notes.md

@@ -1,97 +1,37 @@
 # Experiment ####: Name
 
-**Status**: In Progress | Complete | Disproved | Aborted
-
-**Date**: YYYY-MM-DD
+**Status**: In Progress | Complete | Disproved | Aborted · **Date**: YYYY-MM-DD
 
 ## Goal
 
-What are you trying to learn or test? Be specific about:
-- The question you're answering
-- The hypothesis you're testing
-- Success criteria (how will you know if it worked?)
-
-## Effort
-
-**Approximate time spent**: [e.g., "4 hours"]
-
-*(Optional: Break down into setup, coding, analysis if helpful)*
+The question you are answering, the hypothesis you are testing, and the success criteria — how you will know if it worked.
 
 ## Approach
 
-Brief description of the approach being tested:
-- Key technique or method
-- Why this approach was chosen
-- Any alternatives considered
+The technique being tested, why it was chosen, and any alternatives considered.
 
 ## Environment & Reproduction
 
-**How to run**:
-```bash
-# Command to reproduce results
-python experiment.py --input data/input/sample.json
-```
-
-**Dependencies** (if different from main project):
-- List any additional packages required
-- Or reference: `pip install -r requirements.txt`
-
-**Environment notes**:
-- Python version, key library versions if relevant
-- Any seeds or configuration needed for reproducibility
+How to run it (the exact command), any dependencies beyond the main project, and the version/seed/config notes needed to reproduce the result.
 
 ## Code
 
-List your experiment files:
-- [`experiment.py`](experiment.py) - Brief description
-- [Other files as needed]
+The experiment files, each with a one-line description.
 
 ## Results
 
-### Summary
-
-One-paragraph summary of key findings.
-
-### Key Findings
-
-1. **Finding one**: Description and significance
-2. **Finding two**: Description and significance
-3. **Finding three**: Description and significance
-
-### Metrics
+A one-paragraph summary, then the key findings and the metrics that support them.
 
 | Metric | Value | Notes |
 |--------|-------|-------|
-| Metric 1 | Value | Context |
-| Metric 2 | Value | Context |
-
-### Output Files
-
-- `data/output/results.csv` - Raw results data
-- `data/output/chart.png` - Visualization of findings
+| | | |
 
-## What Worked
+Output artifacts (data, charts) with their paths.
 
-- List things that went well
-- Approaches that proved effective
-- Useful discoveries
+## What Worked / What Didn't
 
-## What Didn't Work
-
-- Failed approaches (and why)
-- Dead ends encountered
-- Surprising obstacles
+What proved effective, and the failed approaches or dead ends (with why).
 
 ## Next Steps
 
-Based on these findings:
-
-1. **Immediate**: What should happen right after this experiment?
-2. **Follow-up experiments**: What new questions emerged?
-3. **Production path**: If validated, what's needed for production? (SPIR spec?)
-
-## References
-
-- Links to relevant documentation
-- Related experiments
-- External resources consulted
+The immediate next action, any follow-up experiments the findings raised, and — if validated — the production path (e.g. a SPIR spec).

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

@@ -1,62 +1,41 @@
 # {{protocol_name}} Builder ({{mode}} mode)
 
-You are executing the MAINTAIN protocol to clean up and synchronize the codebase.
+You are implementing {{input_description}}.
 
 {{#if mode_soft}}
 ## Mode: SOFT
-You are running in SOFT mode. This means:
-- You follow the MAINTAIN protocol yourself (no porch orchestration)
-- The architect monitors your work and verifies you're adhering to the protocol
-- Work through each step methodically
+
+You follow the protocol yourself; the architect verifies compliance.
 {{/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
+
+Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never
+hand-edit `status.yaml` — only porch commands modify project state.
 {{/if}}
 
 ## Protocol
-Follow the MAINTAIN protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
+
+The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not
+need to fetch it.
 
 ## MAINTAIN Overview
 
-Two phases:
-1. **Maintain**: Single pass — audit findings, clean dead code, sync docs, verify build
-2. **Review**: Create PR with 3-way consultation
+Two phases: **Maintain** (one pass — audit, clean, sync docs, verify build) then **Review**
+(PR with 3-way consultation).
 
 ## Key Rules
-- Use soft deletion (move to `codev/maintain/.trash/`)
-- Verify build passes after each removal (`cd packages/codev && pnpm build && pnpm test`)
-- Update documentation to match current architecture
-- Don't remove anything actively used
-- One removal at a time — commit after each
-- Document every deletion with justification
-- Never use `git add -A` or `git add .`
-
-## 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 maintenance run file
-5. Commit the skip and continue with your work
-
-## Getting Started
-1. Read the MAINTAIN protocol document
-2. Run `porch next` to get your first task
-3. Work through audit → clean → sync → verify in a single pass
-4. Document everything in the maintenance run file
-
----
-
-## Protocol Reference (full text)
-
-{{protocol_reference}}
+
+- **Soft-delete**: move removals to `codev/maintain/.trash/`, do not delete outright
+- Verify the build after each removal (`cd packages/codev && pnpm build && pnpm test`)
+- **One removal at a time, commit after each** — a bundled cleanup commit cannot be bisected
+- Treat every audit hit as a *candidate*: a detector cannot tell "vestigial" from "used by a
+  path you did not search". Confirm with a targeted grep before removing
+- Don't remove anything actively used; document every deletion with its justification
+- Never `git add -A` / `--all` / `.` — stage each file explicitly by path
+
+## Notifications
+
+The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR
+merged, blocked.