@cluesmith/codev 3.2.3 → 3.3.0

package/skeleton/.codex/skills/update-arch-docs/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: update-arch-docs
+description: "Audit, prune, and update the project's governance docs — the COLD reference archives `codev/resources/arch.md` and `codev/resources/lessons-learned.md` AND their always-on HOT companions `codev/resources/arch-critical.md` and `codev/resources/lessons-critical.md` (Spec 987, hot/cold two-tier model). Use this skill when running MAINTAIN's arch-doc step, or when asked to update / audit / prune any of those four files. It polices the hot-tier cap (capped facts/lessons + a bounded cold-doc map), enforces displacement (demote to cold when full), keeps each hot file's map accurate, and is opinionated about what NOT to put in each tier (per-spec changelogs, exhaustive enumerations, aspirational state). Two modes: diff-mode (apply a specific change) and audit-mode (propose cuts with reasons). Edits files directly via normal file-edit tooling; no destructive shell commands."
+---
+
+# update-arch-docs
+
+This skill maintains the project's governance docs, each split into **two tiers** (Spec 987):
+
+- **COLD reference archives** — `codev/resources/arch.md` (architecture) and `codev/resources/lessons-learned.md` (durable wisdom). Full, on-demand; grepped/read for depth.
+- **HOT always-on companions** — `codev/resources/arch-critical.md` and `codev/resources/lessons-critical.md`. Tiny, **hard-capped**, **always injected** into every porch prompt and into CLAUDE.md/AGENTS.md. Each holds capped facts/lessons **plus a bounded "consult when…" map** of its cold doc's top-level topics.
+
+It is invoked by the MAINTAIN protocol's documentation step, and ad-hoc whenever someone updates, audits, or prunes any of these files. The skill is opinionated about *what does not belong* in each tier and **polices the hot-tier cap, displacement, and map accuracy**. Use it whenever a doc change touches any of the four files.
+
+## What this skill does NOT do
+
+These are the patterns that have, in practice, caused arch.md and lessons-learned.md to grow without bound. Treat them as bright-line rejections during both audit-mode and diff-mode work.
+
+### In arch.md
+
+- **Per-file enumerations** that go stale the moment they're written. Document the *shape* of a directory and the handful of load-bearing files; do not list every file. `git ls-files` is authoritative; the doc is for orientation.
+- **Per-spec changelog sections** ("Spec 0042 added X, Spec 0073 changed Y"). Architecture is current state, not history. The git log + the spec/review documents own the changelog framing.
+- **Specs/plans tables** that mirror the contents of `codev/specs/` and `codev/plans/`. These are duplicative and rot quickly. Link to the directory; do not paginate it into the doc.
+- **Aspirational state** ("we plan to…", "in the next phase we'll…"). That belongs in the relevant meta-spec or roadmap doc, not in the architecture body. arch.md describes what *is*, not what *might be*.
+- **Date-stamped narrative** ("As of 2026-Q2, the system uses…"). Dates make the doc look fresh while making it harder to maintain. Use git log + commit dates for temporal context.
+- **Duplication of meta-spec content**. If a subsystem has its own meta-spec under `codev/architecture/<domain>.md` or under `codev/specs/`, arch.md should carry a 1-paragraph summary plus a pointer — not a copy.
+- **Retired-component graveyards**. When a component is removed, delete its section. `git log` retains history; an arch.md that describes things that no longer exist is misleading.
+
+### In the HOT files (`arch-critical.md`, `lessons-critical.md`)
+
+These are capped, always-on, and **behavior-changers only**. Bright-line rejections:
+
+- **Anything over the cap.** Each hot file fits in a handful of lines (≈10 single-line facts/lessons + a cold-doc map of ≈12 top-level topics, ≤35 lines). To add an entry, **demote** a weaker one into the cold doc (displacement) — never grow the hot file.
+- **Spec-narrow recipes / reference detail.** Those go in the COLD archive (reference), never the hot file.
+- **A full/auto table of contents** in the cold-doc map. The map lists only **top-level** cold-doc sections, each with a one-line "consult when…" — never every entry.
+- **Multi-paragraph entries.** One line each.
+
+### In the COLD archives (`arch.md`, `lessons-learned.md`)
+
+These are the on-demand **reference**. They may hold spec-narrow recipes and deeper detail — the anti-accretion discipline lives in the hot cap, not here. Still avoid:
+
+- **Multi-paragraph lesson entries**. Split or compress to 1–3 sentences.
+- **Duplicate adjacent entries**. Fold variations of the same lesson into one.
+- **Spec-numbered narrative framing** ("Lesson from #0468:…"). State the general principle; link the review if needed.
+
+### In either file (process)
+
+- **Destructive shell commands**. The skill must not invoke `rm -rf`, `git rm`, or destructive `sed` scripts. All edits go through the normal Edit tool. The MAINTAIN PR diff is the human-confirmation step; that's enough.
+
+## arch.md vs. lessons-learned.md (two-doc framing)
+
+Treat the two files as siblings with different purposes. When in doubt about which file a fact belongs in, route by purpose:
+
+| Purpose | Goes in |
+|---|---|
+| Current system shape — services, transports, key mental models | `arch.md` |
+| Mechanism for a unique subsystem | `arch.md` (subsystem section) — or its own meta-spec if the mechanism is large enough to warrant one, with arch.md keeping a 1-paragraph summary + pointer |
+| Pointers ("see meta-spec X for details") | `arch.md` |
+| A durable engineering pattern that applies across multiple specs | `lessons-learned.md` |
+| A system-shape surprise verified-wrong in production ("looks like X but isn't") | `arch.md` § "Verified-Wrong Assumptions" — *not* lessons-learned.md, because it's a property of the system, not a general pattern |
+
+The "system-shape surprise" routing is the one most often gotten wrong. If a future reader needs to know "the system *looks* like X but actually does Y", that is system shape and lives in arch.md. If they need to know "we learned that doing X is generally a bad idea", that is engineering wisdom and lives in lessons-learned.md.
+
+That arch-vs-lessons routing is the **cold-tier** axis. **Orthogonal to it is the hot/cold axis**: once you know a fact is architecture (or a lesson), decide whether it is *behavior-changing enough* to earn a slot in the capped hot companion, or whether it is reference detail for the cold archive.
+
+## Hot tier: cap, displacement, and map accuracy
+
+The hot files (`arch-critical.md`, `lessons-critical.md`) are the behavior-changers, and their value depends on staying tiny. When MAINTAIN runs — or any update touches them — enforce:
+
+- **Cap.** Each hot file fits in a handful of lines: ≈10 single-line facts/lessons **plus** a cold-doc map of ≈12 top-level topics, ≤35 lines total. If an addition would exceed the cap, **demote** the weakest existing entry into the corresponding cold doc rather than growing the hot file. The cap is load-bearing: it is what keeps the hot tier cheap enough to inject into *every* prompt.
+- **Map accuracy (bounded AND accurate).** Each hot file ends with a "Map of <cold doc> (consult when…)" listing only the cold doc's **top-level** sections, each with a one-line "consult when…". As cold-doc sections are added / renamed / removed, update the map to match — but keep it top-level only; never expand it into a full table of contents (that re-creates the accretion the hot tier exists to avoid).
+- **Behavior-changers only.** A hot entry must be something that should change a decision up front. Reference detail, recipes, and one-offs belong in the cold archive — demote on sight.
+
+## Sizing by purpose, not by line count
+
+There is no line-count budget for either file. The right size for each section is determined by what the section needs to do. If a subsystem genuinely has unique mechanism that takes 80 lines to explain clearly, 80 lines is the right size. If a subsystem can be described in 5 lines and a pointer to a meta-spec, 5 lines is right.
+
+What's *wrong* is bulk that comes from any of the patterns in "What this skill does NOT do" above. Strip those, and the file's size will land where it belongs.
+
+When proposing a section, ask: "Could a future reader skip this section without losing anything load-bearing?" If yes, the section should not exist. The doc's purpose is orientation, not completeness.
+
+## Mode: diff-mode (apply a specific change)
+
+Use diff-mode when the request is specific: "add a section about the new caching layer," "update the Glossary entry for Tower," "remove the reference to the deleted dashboard-server."
+
+In diff-mode:
+
+1. Find the smallest section that needs to change.
+2. Apply the change via the Edit tool.
+3. If the change adds new content, run a quick sanity check against "What this skill does NOT do" before saving — make sure the new content is current state, not aspirational; not duplicative of a meta-spec; not a per-spec changelog entry.
+4. Surface the resulting diff for review.
+
+Diff-mode is fast. It is the right mode for ~80% of post-MAINTAIN documentation work.
+
+## Mode: audit-mode (identify what to cut)
+
+Use audit-mode when the request is general: "the doc feels stale," "MAINTAIN says it's time to prune," "review arch.md against the principles."
+
+In audit-mode:
+
+1. Read the file end-to-end.
+2. For each section in arch.md, run through the per-section pruning checklist (from the MAINTAIN protocol):
+   - Does it describe *current state*? If aspirational, the section moves to a meta-spec; the arch.md keeps a 1-paragraph summary + pointer (or nothing, if the meta-spec stands on its own).
+   - Does it duplicate a meta-spec? If yes, replace with a 1-paragraph summary + pointer.
+   - Is it a per-file enumeration that's gone stale? If yes, prune to the directory shape + a few key files.
+   - Is it a changelog/narrative section ("Spec 0042 added X")? If yes, absorb the architecturally-relevant facts and remove the spec-numbered framing.
+   - Is the component still alive? If retired, delete the section entirely.
+3. For each entry in the COLD `lessons-learned.md`, run the per-entry checklist:
+   - Is it terse (1–3 sentences)? If multi-paragraph, split or compress.
+   - Is the topic section the right one? If filed under "Architecture (continued)" or a spec-numbered section, move it to the right topical home.
+   - Is it a duplicate of an adjacent entry? If yes, fold them.
+   - (Spec-narrow recipes are **kept** here as reference — do not cut them just for being spec-narrow. Anti-accretion now lives in the hot cap, not in the cold archive.)
+
+   Then audit each **HOT** file (`arch-critical.md`, `lessons-critical.md`):
+   - **Cap**: within ≈10 entries + a ≈12-topic map, ≤35 lines? If over, **demote** the weakest entries into the cold doc.
+   - **Map accuracy**: does every map topic name a real top-level cold-doc section, and is any new/renamed section reflected? Fix drift; keep the map top-level only.
+   - **Behavior-changers only**: demote any reference detail that crept in.
+4. **When in doubt, KEEP.** This rule comes from the MAINTAIN protocol and applies in audit-mode too. A confident cut is better than three speculative ones. Bias toward fewer, higher-confidence proposals with clear rationale; do not chase a maximum cut count.
+5. Apply the cuts via the Edit tool — the skill does not produce a "candidate-cuts list and stop." The diff *is* the proposal. The MAINTAIN PR review is the human-confirmation step.
+6. Surface a short reason alongside each cut in the run file (`codev/maintain/NNNN.md`) so PR reviewers can evaluate intent ("removed because: per-spec changelog framing"; "compressed because: duplicates the orchestrator meta-spec").
+
+Audit-mode is slower than diff-mode and produces larger diffs. Reserve it for explicit audit invocations, not for routine doc updates.
+
+## Output contract
+
+The skill commits to the following:
+
+- It edits the four governance files — `codev/resources/arch.md` / `arch-critical.md` and `codev/resources/lessons-learned.md` / `lessons-critical.md` — directly via the Edit tool.
+- It does not invoke destructive shell commands (no `rm -rf`, no `git rm`, no destructive `sed`). File deletions happen only through Edit removing the relevant content; whole-file removal would be a structural change that is out of scope for this skill.
+- In audit-mode, every removal is paired with a one-line reason in the MAINTAIN run file's `## Audit Findings` section. Rationale lives there so reviewers can evaluate intent without re-deriving it from the diff.
+- The skill does not modify other files (specs, plans, reviews, source code). If a fact belongs somewhere else, the skill flags it; it does not move it.
+- The skill does not edit live arch.md or lessons-learned.md content as a side effect of being read or invoked — only when the user/MAINTAIN protocol explicitly asks for an update or audit.

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

@@ -4,33 +4,33 @@ You are implementing {{input_description}}.
 
 {{#if mode_soft}}
 ## Mode: SOFT
-You are running in SOFT mode. This means:
-- You follow the AIR protocol yourself (no porch orchestration)
-- The architect monitors your work and verifies you're adhering to the protocol
-- Consultation is optional — use your judgement based on complexity
-- You have flexibility in execution, but must stay compliant with the protocol
+
+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 AIR 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.
 
 ## Baked Decisions
 
-If the issue body contains a section named "Baked Decisions" (any heading level, case-insensitive), treat its contents as fixed architectural decisions baked in by the architect. Do not autonomously override them in your spec, plan, or implementation. If you discover a serious reason to question a baked decision, surface that concern to the architect via `afx send` rather than relitigating it inside the spec/plan/review.
+If the issue body contains a section named "Baked Decisions" (any heading level,
+case-insensitive), treat its contents as fixed architectural decisions baked in by the
+architect. Do not autonomously override them in your spec, plan, or implementation. If you
+discover a serious reason to question a baked decision, surface that concern to the architect
+via `afx send` rather than relitigating it inside the spec/plan/review.
 
-If the architect's baked-decisions section contains internal contradictions (e.g., two different language choices), do not pick one — pause, flag the contradiction to the architect via `afx send`, and wait for resolution before proceeding.
+If the architect's baked-decisions section contains internal contradictions (e.g., two different
+language choices), do not pick one — pause, flag the contradiction to the architect via
+`afx send`, and wait for resolution before proceeding.
 
 {{#if issue}}
 ## Issue #{{issue.number}}
@@ -38,44 +38,25 @@ If the architect's baked-decisions section contains internal contradictions (e.g
 
 **Description**:
 {{issue.body}}
+{{/if}}
 
 ## Your Mission
-1. Read the issue requirements carefully
-2. Implement the feature (< 300 LOC)
-3. Write tests for the feature
-4. Create PR with review in the PR body (NOT as a separate file)
-5. Notify architect via `afx send architect "PR #N ready for review (implements #{{issue.number}})"`
 
-**IMPORTANT**: AIR produces NO spec, plan, or review files. The review goes in the PR body.
+1. Implement the feature from the issue (<300 LOC)
+2. Write tests for it
+3. Open a PR with the review **in the PR body**, not as a separate file
+4. Notify: `afx send architect "PR #N ready for review (implements #{{issue.number}})"`
+
+**AIR produces no spec, plan, or review files.** That is the whole economy of the protocol.
+
+If the feature turns out larger than AIR fits (>300 LOC, or an architectural decision the issue
+does not make), stop and say so rather than growing it quietly:
 
-If the feature is too complex (> 300 LOC or architectural changes), notify the Architect via:
 ```bash
 afx send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to ASPIR."
 ```
 
 ## Notifications
-Always use `afx send architect "..."` to notify the architect at key moments:
-- **PR ready**: `afx send architect "PR #N ready for review (implements #{{issue.number}})"`
-- **PR merged**: `afx send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."`
-- **Blocked**: `afx 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 the PR body under a "Flaky Tests" section
-5. Commit the skip and continue with your work
-
-## Getting Started
-1. Read the AIR protocol
-2. Review the issue details
-3. Implement the feature
-
----
-
-## Protocol Reference (full text)
 
-{{protocol_reference}}
+The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR
+merged, blocked.

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

@@ -1,43 +1,32 @@
 # Implementation Review Prompt
 
 ## Context
-You are reviewing implementation work for a small feature built under the AIR protocol. The builder implemented directly from a GitHub issue — there is no spec or plan document. Your job is to verify the implementation matches the issue requirements and follows good practices.
 
-## CRITICAL: Verify Before Flagging
+You are reviewing implementation work built under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec or plan document. Verify it matches the issue and follows good practice; review against the issue, not against artifacts AIR does not produce.
 
-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
+## Verify before flagging
+
+Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data:
+
+- Check `package.json` for the actual dependency versions — framework conventions change between major versions.
+- Read the actual config files (or confirm their deliberate absence) before flagging a missing config.
 
 ## Baked Decisions
 
 If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the implementation **fails to honor** a stated baked decision — that is a real defect.
 
-If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
+If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
 
 ## Focus Areas
 
-1. **Issue Adherence**
-   - Does the implementation fulfill the issue requirements?
-   - Are the described 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?
-   - Do tests cover the main paths AND edge cases?
-
-4. **Scope**
-   - Is the change under 300 LOC? If not, should this be escalated to ASPIR?
-   - Does the implementation stay focused on the issue, or does it include unrelated changes?
+- **Issue Adherence** — the implementation fulfills the issue's requirements and acceptance criteria.
+- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled.
+- **Test Coverage** — tests are adequate and cover main paths and edge cases.
+- **Scope** — the change stays focused on the issue and under ~300 LOC; if larger, it should escalate to ASPIR.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -51,14 +40,8 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Implementation looks good, ready for PR
-- `REQUEST_CHANGES`: Issues that must be fixed
-- `COMMENT`: Minor suggestions, can proceed but note feedback
-
-## Notes
+- `APPROVE`: implementation looks good, ready for PR.
+- `REQUEST_CHANGES`: issues that must be fixed.
+- `COMMENT`: minor suggestions; can proceed but note the feedback.
 
-- AIR has no spec or plan — review against the GitHub issue
-- Focus on "does this feature work correctly" not "is this architecturally perfect"
-- If referencing line numbers, use `file:line` format
-- The builder needs actionable feedback
+AIR has no spec or plan — review against the GitHub issue, and judge "does this feature work correctly", not "is this architecturally perfect".

package/skeleton/protocols/air/consult-types/pr-review.md

@@ -1,48 +1,30 @@
 # PR Ready Review Prompt
 
 ## Context
-You are performing a review of a pull request created under the AIR protocol. The builder implemented a small feature directly from a GitHub issue — there are no spec, plan, or review files. The review is embedded in the PR body.
+
+You are reviewing a pull request created under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec, plan, or review file. The review is embedded in the PR body.
 
 ## Baked Decisions
 
 If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the code **fails to honor** a stated baked decision — that is a real defect.
 
-If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
+If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
 
 ## Focus Areas
 
-1. **Completeness**
-   - Are the issue requirements implemented?
-   - Is the PR body review section filled out (summary, key decisions, test plan)?
-   - Are commits properly formatted?
-
-2. **Test Status**
-   - Do all tests pass?
-   - Is test coverage adequate for the changes?
-   - Are there any skipped or flaky tests?
-
-3. **Code Cleanliness**
-   - Is there any debug code left in?
-   - Are there any TODO comments that should be resolved?
-   - Is the code properly formatted?
-
-4. **Scope**
-   - Is the change under 300 LOC?
-   - Does the implementation stay focused on the issue?
-   - Are there unrelated changes bundled in?
-
-5. **PR Quality**
-   - Does the PR link to the issue?
-   - Is the PR body review section informative?
-   - Is the branch up to date with its base (the integration branch the PR targets)?
+- **Completeness** — the issue's requirements are implemented and the PR body's review section (summary, key decisions, test plan) is filled out.
+- **Test Status** — all tests pass, coverage is adequate, and any skipped/flaky tests are accounted for.
+- **Code Cleanliness** — no debug code, no stray `TODO`, code properly formatted.
+- **Scope** — the change stays under ~300 LOC and focused on the issue, with no unrelated changes bundled in.
+- **PR Quality** — the PR links to the issue, the body's review section is informative, and the branch is up to date with its base (the integration branch the PR targets).
 
 ## Scope
 
-- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself.
+Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -56,13 +38,8 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Ready for architect review
-- `REQUEST_CHANGES`: Issues to fix before review
-- `COMMENT`: Minor items, can proceed but note feedback
-
-## Notes
+- `APPROVE`: ready for architect review.
+- `REQUEST_CHANGES`: issues to fix before review.
+- `COMMENT`: minor items; can proceed but note the feedback.
 
-- AIR has no spec, plan, or review files — review the PR body and code diff
-- Focus on "is this ready for someone else to review" not "is this perfect"
-- Any issues found here are cheaper to fix than during integration review
+AIR has no spec, plan, or review files — review the PR body and the code diff.

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

@@ -2,9 +2,9 @@
 
 You are executing the **IMPLEMENT** phase of the AIR protocol.
 
-## Your Goal
+## Goal
 
-Read the GitHub issue, implement the feature, and add tests. Keep it focused and under 300 LOC.
+Implement the feature described in the issue, with tests, as a focused change under ~300 LOC. AIR produces no `codev/specs/` or `codev/plans/` artifacts.
 
 ## Baked Decisions
 
@@ -17,79 +17,26 @@ If two baked decisions contradict each other, do not pick one — pause, flag th
 - **Issue**: #{{issue.number}} — {{issue.title}}
 - **Current State**: {{current_state}}
 
-## Process
+## What must be true when you finish
 
-### 1. Read the Issue
+- **The feature matches the issue.** You have read it fully — desired behavior, acceptance criteria, any examples — and implemented exactly what it describes: no refactoring of surrounding code, no features beyond the issue, no unrelated bug fixes (file separate issues for those). Self-documenting code, no debug or commented-out code, existing project conventions.
+- **Tests exist.** They cover the happy path and the key edge cases, and are deterministic. (Purely declarative changes — config only — may not need them; say so.)
+- **Build and tests pass.** Confirm the real project commands (check `package.json` if unsure) and run them; fix failures before signaling.
+- **The change stays within AIR scope.** If it grows past ~300 LOC or turns architectural, signal `TOO_COMPLEX` rather than pressing on.
 
-Read the full issue description. Identify:
-- What is the desired behavior?
-- What are the acceptance criteria?
-- Are there examples or mockups?
-- What files/modules are likely affected?
-
-### 2. Implement the Feature
-
-Apply a focused implementation:
-- Implement what the issue describes — no more, no less
-- Do NOT refactor surrounding code
-- Do NOT add features beyond what's described in the issue
-- Do NOT fix unrelated bugs you happen to notice (file separate issues)
-
-**Code Quality**:
-- Self-documenting code (clear names, obvious structure)
-- No commented-out code or debug prints
-- Follow existing project conventions
-
-### 3. Add Tests
-
-Write tests that:
-- Cover the main happy path
-- Cover key edge cases
-- Are deterministic (not flaky)
-
-Place tests following project conventions (`__tests__/`, `*.test.ts`, etc.).
-
-### 4. Verify the Build
-
-Run build and tests:
-
-```bash
-npm run build      # Must pass
-npm test           # Must pass
-```
-
-Fix any failures before proceeding. If build/test commands don't exist, check `package.json`.
-
-### 5. Commit
-
-Stage and commit your changes:
-- Use explicit file paths (never `git add -A` or `git add .`)
-- Commit message: `[Air #{{issue.number}}] feat: <brief description>`
+Commit with an explicit staged path and the message `[Air #{{issue.number}}] feat: <brief description>`.
 
 ## Signals
 
-When implementation and tests are complete and passing:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If the feature is too complex for AIR (> 300 LOC or architectural):
-
-```
-<signal>TOO_COMPLEX</signal>
-```
-
-If you're blocked (missing context, unclear requirements, etc.):
-
-```
-<signal>BLOCKED:reason goes here</signal>
-```
-
-## Important Notes
-
-1. **Stay focused** — Implement what the issue describes, nothing else
-2. **Tests are expected** — Add tests unless the change is purely declarative (e.g., config only)
-3. **Build AND tests must pass** — Don't signal complete until both pass
-4. **Stay under 300 LOC** — If the feature grows beyond this, signal `TOO_COMPLEX`
-5. **No spec/plan artifacts** — AIR does not create files in `codev/specs/` or `codev/plans/`
+- Implementation and tests complete and passing:
+  ```
+  <signal>PHASE_COMPLETE</signal>
+  ```
+- Too complex for AIR (> ~300 LOC or architectural):
+  ```
+  <signal>TOO_COMPLEX</signal>
+  ```
+- Blocked (missing context, unclear requirements):
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```

package/skeleton/protocols/air/prompts/pr.md

@@ -2,32 +2,20 @@
 
 You are executing the **PR** phase of the AIR protocol.
 
-## Your Goal
+## Goal
 
-Create a pull request with the review embedded in the PR body, optionally run CMAP, and notify the architect.
+Open the PR with the review embedded in its body, optionally run CMAP, and notify the architect.
 
 ## Context
 
 - **Issue**: #{{issue.number}} — {{issue.title}}
 - **Current State**: {{current_state}}
 
-## Process
+## Create the PR
 
-### 1. Create the Pull Request
+**The PR body IS the review for AIR** — do not create a file in `codev/reviews/`. Include a summary, the key decisions, and a test plan in the body itself.
 
-Create a PR that links to the issue. The PR body IS the review — include a summary, key decisions, and test plan.
-
-**PR body requirements**: The PR body MUST include `Closes #<N>` (where `<N>` is
-the driving issue number) so GitHub auto-closes the issue on merge. If the PR
-closes multiple issues (e.g. duplicates consolidated), include one `Closes #<N>`
-per issue. Without this, GitHub will not auto-close the issue.
-
-**Exception**: if this PR only partially addresses the issue, use `Refs #<N>`
-or `Part of #<N>` instead of `Closes` — the issue stays open until a
-follow-up PR closes it.
-
-**Note**: substitute the real issue number for `<N>` — do not leave the
-placeholder or any `{{...}}` template tag in the committed PR body.
+The body must carry `Closes #<N>` for the driving issue — one per issue if several — so GitHub auto-closes it on merge. **Exception:** a partial fix uses `Refs #<N>` or `Part of #<N>` instead. Substitute the real number for `<N>`; leave no `{{...}}` tag or `<N>` placeholder in the committed body.
 
 ```bash
 gh pr create --title "[Air #<N>] feat: <brief description>" --body "$(cat <<'EOF'
@@ -35,15 +23,15 @@ gh pr create --title "[Air #<N>] feat: <brief description>" --body "$(cat <<'EOF
 
 <1-2 sentence description of the feature>
 
-Closes #<N>  <!-- Substitute <N> with the real issue number -->
+Closes #<N>  <!-- Substitute <N>; use "Refs #<N>" for a partial fix -->
 
 ## What Changed
 
-<Brief explanation of the implementation approach>
+<the implementation approach>
 
 ## Key Decisions
 
-<Any notable decisions made during implementation, or "None — straightforward implementation">
+<notable decisions, or "None — straightforward implementation">
 
 ## Test Plan
 
@@ -53,16 +41,14 @@ Closes #<N>  <!-- Substitute <N> with the real issue number -->
 
 ## Review Notes
 
-<Anything the reviewer should pay special attention to, or "Standard implementation — no special concerns">
+<anything the reviewer should focus on, or "Standard implementation — no special concerns">
 EOF
 )"
 ```
 
-**IMPORTANT**: Do NOT create a review file in `codev/reviews/`. The PR body IS the review for AIR.
+## Optional CMAP review
 
-### 2. Optional CMAP Review
-
-If the implementation is non-trivial, run 3-way consultation:
+CMAP is your judgement call for AIR. Skip it for simple changes (config, small UI); run it for features touching core logic or several modules:
 
 ```bash
 consult -m gemini --protocol air --type pr &
@@ -70,41 +56,23 @@ consult -m codex --protocol air --type pr &
 consult -m claude --protocol air --type pr &
 ```
 
-All three should run in the background (`run_in_background: true`).
-
-**This is optional** — use your judgement. For simple features (config changes, small UI additions), you may skip consultation. For features touching core logic or multiple modules, run it.
+If you run it, wait for all three, record each verdict, fix real issues, and push.
 
-### 3. Address Feedback (if CMAP was run)
-
-If you ran CMAP:
-- Wait for all consultations to complete
-- Record each model's verdict
-- Fix any issues identified
-- Push updates to the PR branch
-
-### 4. Notify Architect
-
-Send notification with PR link:
+## Notify the architect
 
 ```bash
 afx send architect "PR #<number> ready for review (implements issue #{{issue.number}})"
 ```
 
-If CMAP was run, include verdicts:
-```bash
-afx send architect "PR #<number> ready for review (implements issue #{{issue.number}}). CMAP: gemini=<verdict>, codex=<verdict>, claude=<verdict>"
-```
+If you ran CMAP, include the verdicts: `CMAP: gemini=<verdict>, codex=<verdict>, claude=<verdict>`.
 
 ## Signals
 
-When PR is created and ready for review:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If you're blocked:
-
-```
-<signal>BLOCKED:reason goes here</signal>
-```
+- PR created and ready for review:
+  ```
+  <signal>PHASE_COMPLETE</signal>
+  ```
+- Blocked:
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```