@cluesmith/codev 3.0.2 → 3.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/dist/agent-farm/cli.d.ts.map +1 -1
  2. package/dist/agent-farm/cli.js +44 -0
  3. package/dist/agent-farm/cli.js.map +1 -1
  4. package/dist/agent-farm/commands/attach.d.ts.map +1 -1
  5. package/dist/agent-farm/commands/attach.js +2 -117
  6. package/dist/agent-farm/commands/attach.js.map +1 -1
  7. package/dist/agent-farm/commands/dev.d.ts +20 -0
  8. package/dist/agent-farm/commands/dev.d.ts.map +1 -0
  9. package/dist/agent-farm/commands/dev.js +124 -0
  10. package/dist/agent-farm/commands/dev.js.map +1 -0
  11. package/dist/agent-farm/commands/setup.d.ts +27 -0
  12. package/dist/agent-farm/commands/setup.d.ts.map +1 -0
  13. package/dist/agent-farm/commands/setup.js +55 -0
  14. package/dist/agent-farm/commands/setup.js.map +1 -0
  15. package/dist/agent-farm/commands/spawn-worktree.d.ts +21 -2
  16. package/dist/agent-farm/commands/spawn-worktree.d.ts.map +1 -1
  17. package/dist/agent-farm/commands/spawn-worktree.js +42 -4
  18. package/dist/agent-farm/commands/spawn-worktree.js.map +1 -1
  19. package/dist/agent-farm/commands/spawn.d.ts.map +1 -1
  20. package/dist/agent-farm/commands/spawn.js +30 -15
  21. package/dist/agent-farm/commands/spawn.js.map +1 -1
  22. package/dist/agent-farm/commands/status.d.ts.map +1 -1
  23. package/dist/agent-farm/commands/status.js +4 -1
  24. package/dist/agent-farm/commands/status.js.map +1 -1
  25. package/dist/agent-farm/commands/stop.d.ts.map +1 -1
  26. package/dist/agent-farm/commands/stop.js +15 -8
  27. package/dist/agent-farm/commands/stop.js.map +1 -1
  28. package/dist/agent-farm/commands/workspace-add-architect.d.ts +18 -0
  29. package/dist/agent-farm/commands/workspace-add-architect.d.ts.map +1 -0
  30. package/dist/agent-farm/commands/workspace-add-architect.js +54 -0
  31. package/dist/agent-farm/commands/workspace-add-architect.js.map +1 -0
  32. package/dist/agent-farm/db/index.d.ts.map +1 -1
  33. package/dist/agent-farm/db/index.js +54 -1
  34. package/dist/agent-farm/db/index.js.map +1 -1
  35. package/dist/agent-farm/db/migrate.js +2 -2
  36. package/dist/agent-farm/db/migrate.js.map +1 -1
  37. package/dist/agent-farm/db/schema.d.ts +1 -1
  38. package/dist/agent-farm/db/schema.d.ts.map +1 -1
  39. package/dist/agent-farm/db/schema.js +3 -2
  40. package/dist/agent-farm/db/schema.js.map +1 -1
  41. package/dist/agent-farm/db/types.d.ts +7 -2
  42. package/dist/agent-farm/db/types.d.ts.map +1 -1
  43. package/dist/agent-farm/db/types.js +2 -0
  44. package/dist/agent-farm/db/types.js.map +1 -1
  45. package/dist/agent-farm/lib/builder-lookup.d.ts +26 -0
  46. package/dist/agent-farm/lib/builder-lookup.d.ts.map +1 -0
  47. package/dist/agent-farm/lib/builder-lookup.js +103 -0
  48. package/dist/agent-farm/lib/builder-lookup.js.map +1 -0
  49. package/dist/agent-farm/servers/tower-instances.d.ts +20 -1
  50. package/dist/agent-farm/servers/tower-instances.d.ts.map +1 -1
  51. package/dist/agent-farm/servers/tower-instances.js +260 -16
  52. package/dist/agent-farm/servers/tower-instances.js.map +1 -1
  53. package/dist/agent-farm/servers/tower-messages.d.ts +10 -1
  54. package/dist/agent-farm/servers/tower-messages.d.ts.map +1 -1
  55. package/dist/agent-farm/servers/tower-messages.js +137 -7
  56. package/dist/agent-farm/servers/tower-messages.js.map +1 -1
  57. package/dist/agent-farm/servers/tower-routes.d.ts.map +1 -1
  58. package/dist/agent-farm/servers/tower-routes.js +97 -31
  59. package/dist/agent-farm/servers/tower-routes.js.map +1 -1
  60. package/dist/agent-farm/servers/tower-terminals.d.ts +17 -1
  61. package/dist/agent-farm/servers/tower-terminals.d.ts.map +1 -1
  62. package/dist/agent-farm/servers/tower-terminals.js +78 -29
  63. package/dist/agent-farm/servers/tower-terminals.js.map +1 -1
  64. package/dist/agent-farm/servers/tower-tunnel.d.ts.map +1 -1
  65. package/dist/agent-farm/servers/tower-tunnel.js +3 -2
  66. package/dist/agent-farm/servers/tower-tunnel.js.map +1 -1
  67. package/dist/agent-farm/servers/tower-types.d.ts +18 -6
  68. package/dist/agent-farm/servers/tower-types.d.ts.map +1 -1
  69. package/dist/agent-farm/state.d.ts +50 -4
  70. package/dist/agent-farm/state.d.ts.map +1 -1
  71. package/dist/agent-farm/state.js +118 -12
  72. package/dist/agent-farm/state.js.map +1 -1
  73. package/dist/agent-farm/types.d.ts +28 -0
  74. package/dist/agent-farm/types.d.ts.map +1 -1
  75. package/dist/agent-farm/utils/agent-names.d.ts +5 -30
  76. package/dist/agent-farm/utils/agent-names.d.ts.map +1 -1
  77. package/dist/agent-farm/utils/agent-names.js +5 -54
  78. package/dist/agent-farm/utils/agent-names.js.map +1 -1
  79. package/dist/agent-farm/utils/architect-name.d.ts +37 -0
  80. package/dist/agent-farm/utils/architect-name.d.ts.map +1 -0
  81. package/dist/agent-farm/utils/architect-name.js +63 -0
  82. package/dist/agent-farm/utils/architect-name.js.map +1 -0
  83. package/dist/agent-farm/utils/config.d.ts +19 -0
  84. package/dist/agent-farm/utils/config.d.ts.map +1 -1
  85. package/dist/agent-farm/utils/config.js +16 -0
  86. package/dist/agent-farm/utils/config.js.map +1 -1
  87. package/dist/agent-farm/utils/git.d.ts +29 -0
  88. package/dist/agent-farm/utils/git.d.ts.map +1 -0
  89. package/dist/agent-farm/utils/git.js +38 -0
  90. package/dist/agent-farm/utils/git.js.map +1 -0
  91. package/dist/agent-farm/utils/shell.d.ts +13 -0
  92. package/dist/agent-farm/utils/shell.d.ts.map +1 -1
  93. package/dist/agent-farm/utils/shell.js +28 -0
  94. package/dist/agent-farm/utils/shell.js.map +1 -1
  95. package/dist/commands/adopt.d.ts.map +1 -1
  96. package/dist/commands/adopt.js +5 -0
  97. package/dist/commands/adopt.js.map +1 -1
  98. package/dist/commands/consult/index.d.ts.map +1 -1
  99. package/dist/commands/consult/index.js +2 -0
  100. package/dist/commands/consult/index.js.map +1 -1
  101. package/dist/commands/init.d.ts.map +1 -1
  102. package/dist/commands/init.js +5 -0
  103. package/dist/commands/init.js.map +1 -1
  104. package/package.json +5 -5
  105. package/skeleton/protocols/air/builder-prompt.md +6 -0
  106. package/skeleton/protocols/air/consult-types/impl-review.md +6 -0
  107. package/skeleton/protocols/air/consult-types/pr-review.md +6 -0
  108. package/skeleton/protocols/air/prompts/implement.md +6 -0
  109. package/skeleton/protocols/air/protocol.md +4 -0
  110. package/skeleton/protocols/aspir/builder-prompt.md +19 -3
  111. package/skeleton/protocols/aspir/consult-types/plan-review.md +6 -0
  112. package/skeleton/protocols/aspir/consult-types/spec-review.md +6 -0
  113. package/skeleton/protocols/aspir/prompts/specify.md +6 -0
  114. package/skeleton/protocols/aspir/protocol.md +4 -0
  115. package/skeleton/protocols/bugfix/consult-types/impl-review.md +44 -37
  116. package/skeleton/protocols/bugfix/consult-types/pr-review.md +65 -40
  117. package/skeleton/protocols/spir/builder-prompt.md +19 -3
  118. package/skeleton/protocols/spir/consult-types/plan-review.md +6 -0
  119. package/skeleton/protocols/spir/consult-types/spec-review.md +6 -0
  120. package/skeleton/protocols/spir/prompts/specify.md +6 -0
  121. package/skeleton/protocols/spir/protocol.md +4 -0
@@ -37,6 +37,10 @@ AIR is a minimal protocol for implementing small features (< 300 LOC) where the
37
37
  - Architectural changes → use **SPIR**
38
38
  - Complex features with multiple phases → use **SPIR** or **ASPIR**
39
39
 
40
+ ## Baked Decisions (Optional)
41
+
42
+ When filing an issue for AIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will treat each listed item as fixed during implementation; CMAP reviewers will not propose alternatives unless the implementation itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`.
43
+
40
44
  ## Protocol Phases
41
45
 
42
46
  ### I - Implement
@@ -30,6 +30,12 @@ You are running in STRICT mode. This means:
30
30
  Follow the ASPIR protocol: `codev/protocols/aspir/protocol.md`
31
31
  Read and internalize the protocol before starting any work.
32
32
 
33
+ ## Baked Decisions
34
+
35
+ 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.
36
+
37
+ 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.
38
+
33
39
  {{#if spec}}
34
40
  ## Spec
35
41
  Read the specification at: `{{spec.path}}`
@@ -53,13 +59,23 @@ Follow the implementation plan at: `{{plan.path}}`
53
59
  {{task_text}}
54
60
  {{/if}}
55
61
 
56
- ## Multi-PR Workflow
62
+ ## PR Strategy
63
+
64
+ **Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits within a single PR, not as separate PRs. The plan's instruction that "each phase commits independently" refers to git commits, not PRs.
65
+
66
+ By default, the PR is opened during/after the final implement phase, with all phase-commits already on the branch.
67
+
68
+ ### Architect-requested PRs
69
+
70
+ The architect MAY request a PR at any point — for spec review, mid-implementation feedback, slicing a large spec into shippable PRs, etc. When the architect explicitly asks for a PR earlier (or for additional PRs), follow that direction. The prohibition is specifically on the *builder* autonomously deciding to open per-phase PRs without architect request.
71
+
72
+ ### Multi-PR Mechanics (when the architect requests sequential PRs)
57
73
 
58
- Your worktree is persistent — it survives across PR merges. You can produce multiple PRs sequentially:
74
+ Your worktree is persistent — it survives across PR merges. When the architect asks for sequential PRs (e.g., to slice a large spec into shippable pieces), use this loop:
59
75
 
60
76
  1. Cut a branch, open a PR, wait for merge
61
77
  2. After merge: `git fetch origin main && git checkout -b <next-branch> origin/main`
62
- 3. Continue to the next phase, open another PR
78
+ 3. Continue to the next slice, open another PR
63
79
 
64
80
  **Important**: Do NOT run `git checkout main` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/main` via fetch.
65
81
 
@@ -3,6 +3,12 @@
3
3
  ## Context
4
4
  You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it.
5
5
 
6
+ ## Baked Decisions
7
+
8
+ If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed (this extends the existing "don't re-litigate spec decisions" rule with explicit baked-decision language). 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; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect.
9
+
10
+ If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
11
+
6
12
  ## Focus Areas
7
13
 
8
14
  1. **Spec Coverage**
@@ -3,6 +3,12 @@
3
3
  ## Context
4
4
  You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval.
5
5
 
6
+ ## Baked Decisions
7
+
8
+ If the issue body or the spec's Constraints section 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 spec **fails to honor** a stated baked decision — that is a real defect.
9
+
10
+ If the baked decisions themselves contain contradictions (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
11
+
6
12
  ## Focus Areas
7
13
 
8
14
  1. **Completeness**
@@ -31,6 +31,12 @@ ls codev/specs/{{project_id}}-*.md
31
31
 
32
32
  **If no spec exists:** Proceed to Step 1 below.
33
33
 
34
+ ### 0.5 Baked Decisions
35
+
36
+ Before exploring solution approaches, check the issue body for a section named "Baked Decisions" (any heading level, case-insensitive). If present, copy its content verbatim into the spec's Constraints section and treat each item as fixed. Do not autonomously relitigate the architect's choices in your Solution Exploration. If you discover a serious problem with a baked decision, raise it via `afx send architect` rather than overriding it in the spec.
37
+
38
+ If two baked decisions contradict each other (e.g., two different language choices), do not pick one — pause, flag the contradiction via `afx send`, and wait for resolution before drafting.
39
+
34
40
  ### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS)
35
41
 
36
42
  Before writing anything, ask clarifying questions to understand:
@@ -41,6 +41,10 @@ Use SPIR instead when:
41
41
  - The work is **high-risk** — security-sensitive, user-facing, or broadly impactful
42
42
  - You want to **review and adjust** the plan before implementation starts
43
43
 
44
+ ## Baked Decisions (Optional)
45
+
46
+ When filing an issue for ASPIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will copy the section verbatim into the spec's Constraints and treat each item as fixed; CMAP reviewers will not propose alternatives unless the spec itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`.
47
+
44
48
  ## Protocol Phases
45
49
 
46
50
  ASPIR follows the same four phases as SPIR. For full phase documentation, see the [SPIR protocol](../spir/protocol.md).
@@ -1,38 +1,54 @@
1
- # Implementation Review Prompt
1
+ # Implementation Review Prompt (BUGFIX)
2
2
 
3
3
  ## Context
4
- 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.
4
+ You are reviewing in-progress fix work for a **BUGFIX protocol** project. A builder has investigated a GitHub Issue, identified a root cause, and is implementing the fix + regression test. Your job is to verify the fix matches the issue's symptom and meets BUGFIX standards.
5
+
6
+ **BUGFIX is not SPIR.** There is **no spec, no plan, and no review document**. The GitHub Issue is the spec. The PR body will be the review. Do **not** request changes for missing `codev/specs/`, `codev/plans/`, or `codev/reviews/` artifacts.
5
7
 
6
8
  ## CRITICAL: Verify Before Flagging
7
9
 
8
10
  Before requesting changes for missing configuration, incorrect patterns, or framework issues:
9
- 1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions
10
- 2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs
11
- 3. **Do not assume** your training data reflects the version in use — verify against project files
12
- 4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed
11
+ 1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions.
12
+ 2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs.
13
+ 3. **Do not assume** your training data reflects the version in use — verify against project files.
14
+ 4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed.
13
15
 
14
16
  ## Focus Areas
15
17
 
16
- 1. **Spec Adherence**
17
- - Does the implementation fulfill the spec requirements for this phase?
18
- - Are acceptance criteria met?
18
+ 1. **Issue Adherence**
19
+ - Does the implementation actually resolve the symptom described in the GitHub Issue?
20
+ - Is the root cause fix targeted, or is it a workaround that masks the symptom?
21
+
22
+ 2. **Regression Test**
23
+ - Is there a regression test that exercises the exact scenario from the issue?
24
+ - Without the fix applied, would this test fail? (The whole point.)
25
+ - Is the test deterministic?
26
+ - If no test was added, has the builder justified why (e.g., docs-only change with no testable behavior)?
27
+
28
+ 3. **Scope Discipline**
29
+ - Is the change focused on the root cause only — no unrelated refactors, no drive-by fixes?
30
+ - Is the net diff staying under ~300 LOC? If it has grown larger, should this escalate to SPIR/TICK?
19
31
 
20
- 2. **Code Quality**
32
+ 4. **Code Quality**
21
33
  - Is the code readable and maintainable?
22
- - Are there obvious bugs or issues?
23
- - Are error cases handled appropriately?
34
+ - Are there obvious bugs or issues introduced by the fix?
35
+ - Are error cases handled appropriately for the path that was changed?
36
+ - No debug code, stray `console.log`, or commented-out code.
24
37
 
25
- 3. **Test Coverage**
26
- - Are the tests adequate for this phase?
27
- - Do tests cover the main paths AND edge cases?
38
+ 5. **Test Status**
39
+ - Existing tests still pass.
40
+ - Build still passes.
41
+ - No new flaky tests introduced.
28
42
 
29
- 4. **Plan Alignment**
30
- - Does the implementation follow the plan?
31
- - Are there plan items skipped or partially completed?
43
+ ## Out of Scope (Do NOT request changes for)
32
44
 
33
- 5. **UX Verification** (if spec has UX requirements)
34
- - Does the actual user experience match what the spec describes?
35
- - If spec says "async" or "non-blocking", is it actually async?
45
+ The following are **not** part of the BUGFIX protocol and must **not** be cited as REQUEST_CHANGES reasons:
46
+
47
+ - Missing `codev/specs/<N>-*.md`, `codev/plans/<N>-*.md`, or `codev/reviews/<N>-*.md` — BUGFIX produces none of these. The GitHub Issue is the spec; the PR body is the review.
48
+ - Commit format `[Spec NNNN][Phase]` — BUGFIX uses `Fix #N: ...` or `[Bugfix #N] ...`. This is the protocol-mandated format, **not** a bug.
49
+ - `status.yaml` fields such as `build_complete: false` — porch manages `status.yaml`; the builder is **forbidden** from editing it manually. Treat porch state as informational, not a fixable issue.
50
+ - "Plan Alignment" or "Spec Adherence" — there is no plan and no spec to align with.
51
+ - Phase-scoping concerns — BUGFIX is single-phase by design. There are no plan phases to scope against.
36
52
 
37
53
  ## Verdict Format
38
54
 
@@ -51,22 +67,13 @@ KEY_ISSUES:
51
67
  ```
52
68
 
53
69
  **Verdict meanings:**
54
- - `APPROVE`: Phase is complete, builder can proceed
55
- - `REQUEST_CHANGES`: Issues that must be fixed before proceeding
56
- - `COMMENT`: Minor suggestions, can proceed but note feedback
57
-
58
- ## Scoping (Multi-Phase Plans)
59
-
60
- When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl):
61
- - **ONLY review work belonging to the current plan phase**
62
- - The query will specify which phase you are reviewing
63
- - Do NOT request changes for functionality scheduled in later phases
64
- - Do NOT flag missing features that are out of scope for this phase
65
- - If unsure whether something belongs to this phase, check the plan file
70
+ - `APPROVE`: Fix and regression test are in good shape; builder can proceed to PR creation.
71
+ - `REQUEST_CHANGES`: Real BUGFIX-relevant issues (fix doesn't resolve the symptom, missing regression test without justification, scope creep, broken existing tests, etc.).
72
+ - `COMMENT`: Minor suggestions; builder can proceed but should consider the feedback.
66
73
 
67
74
  ## Notes
68
75
 
69
- - This is a phase-level review, not the final PR review
70
- - Focus on "does this phase work" not "is the whole feature done"
71
- - If referencing line numbers, use `file:line` format
72
- - The builder needs actionable feedback to continue
76
+ - This is an implementation-level review, not the final PR review.
77
+ - Focus on "does this fix actually resolve the issue, and is it protected by a regression test" — not on artifacts from other protocols.
78
+ - If referencing line numbers, use `file:line` format.
79
+ - The builder needs actionable, protocol-correct feedback to continue.
@@ -1,36 +1,59 @@
1
- # PR Ready Review Prompt
1
+ # PR Ready Review Prompt (BUGFIX)
2
2
 
3
3
  ## Context
4
- You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review.
4
+ You are performing a final self-check during the PR phase of the **BUGFIX protocol**. The builder has investigated a GitHub Issue, implemented a focused fix, and added a regression test. They are about to create — or have just created — a PR for the architect's integration review.
5
+
6
+ **BUGFIX is not SPIR.** Do **not** review against the SPIR three-document trinity. The artifacts of a BUGFIX project are:
7
+ - The originating **GitHub Issue** (serves as the spec)
8
+ - The **code fix** (minimal, focused on root cause)
9
+ - A **regression test** that fails without the fix and passes with it
10
+ - The **PR body** (Summary, Root Cause, Fix, Test Plan)
11
+
12
+ There is **no `codev/specs/`, `codev/plans/`, or `codev/reviews/` file** for a BUGFIX, and there should not be one. The commit format is `Fix #NNNN: <description>` (or `[Bugfix #NNNN] ...`), **not** `[Spec NNNN][Phase]`.
5
13
 
6
14
  ## Focus Areas
7
15
 
8
- 1. **Completeness**
9
- - Are all spec requirements implemented?
10
- - Are all plan phases complete?
11
- - Is the review document written (`codev/reviews/XXXX-name.md`)?
12
- - Are all commits properly formatted (`[Spec XXXX][Phase]`)?
13
-
14
- 2. **Test Status**
15
- - Do all tests pass?
16
- - Is test coverage adequate for the changes?
17
- - Are there any skipped or flaky tests?
18
-
19
- 3. **Code Cleanliness**
20
- - Is there any debug code left in?
21
- - Are there any TODO comments that should be resolved?
22
- - Are there any `// REVIEW:` comments that weren't addressed?
23
- - Is the code properly formatted?
24
-
25
- 4. **Documentation**
26
- - Are inline comments clear where needed?
27
- - Is the review document comprehensive?
28
- - Are any new APIs documented?
29
-
30
- 5. **PR Readiness**
31
- - Is the branch up to date with main?
32
- - Are commits atomic and well-described?
33
- - Is the change diff reasonable in size?
16
+ 1. **Issue Resolution**
17
+ - Does the fix actually resolve the symptom described in the issue?
18
+ - Does the PR body include `Fixes #<N>` so the issue auto-closes on merge?
19
+ - Does the PR description cover: Summary, Root Cause, Fix, Test Plan?
20
+
21
+ 2. **Regression Test**
22
+ - Is there a regression test that targets the exact scenario from the issue?
23
+ - Would the test fail without the fix? (If reviewers can't tell, ask the builder to demonstrate.)
24
+ - Is the test deterministic (not flaky)?
25
+ - If the fix is documentation-only or otherwise truly untestable, has the builder explicitly justified the absence of a test?
26
+
27
+ 3. **Scope Discipline**
28
+ - Is the change focused on the root cause? No unrelated refactors, no drive-by fixes for other bugs.
29
+ - Is the net diff under ~300 LOC (additions + deletions, excluding generated/lockfiles)?
30
+ - If the scope grew beyond a bugfix, should the builder have escalated to SPIR/TICK instead?
31
+
32
+ 4. **Code Cleanliness**
33
+ - No debug code, `console.log`, or commented-out blocks left behind.
34
+ - No stray TODOs introduced by this fix.
35
+ - Code follows existing project conventions.
36
+
37
+ 5. **Test Status**
38
+ - All existing tests pass.
39
+ - Build passes.
40
+ - No new flaky tests introduced.
41
+
42
+ 6. **PR Hygiene**
43
+ - Commits use the BUGFIX format: `Fix #<N>: ...` or `[Bugfix #<N>] ...` (**not** `[Spec NNNN][Phase]`).
44
+ - Branch is up to date with main (or close enough for clean merge).
45
+ - PR is linked to the issue.
46
+
47
+ ## Out of Scope (Do NOT request changes for)
48
+
49
+ The following are **not** part of the BUGFIX protocol and must **not** be cited as REQUEST_CHANGES reasons:
50
+
51
+ - Missing `codev/specs/<N>-*.md` — BUGFIX has no spec; the GitHub Issue is the spec.
52
+ - Missing `codev/plans/<N>-*.md` — BUGFIX has no plan.
53
+ - Missing `codev/reviews/<N>-*.md` — BUGFIX has no review document; review lives in the PR body.
54
+ - Commit format `[Spec NNNN][Phase]` — BUGFIX intentionally uses `Fix #N:` / `[Bugfix #N]`.
55
+ - `status.yaml` fields like `build_complete: false` — porch manages `status.yaml`; the builder is **forbidden** from editing it directly. Treat porch state as informational, not a fixable issue.
56
+ - Phase-scoping concerns — BUGFIX is a single-phase protocol; there are no plan phases to scope against.
34
57
 
35
58
  ## Verdict Format
36
59
 
@@ -49,24 +72,26 @@ KEY_ISSUES:
49
72
 
50
73
  PR_SUMMARY: |
51
74
  ## Summary
52
- [2-3 sentences describing what this PR does]
75
+ Fixes #<N>. [1-2 sentences on what was fixed.]
76
+
77
+ ## Root Cause
78
+ [Brief explanation of what caused the bug]
53
79
 
54
- ## Key Changes
55
- - [Change 1]
56
- - [Change 2]
80
+ ## Fix
81
+ [Brief explanation of the fix]
57
82
 
58
83
  ## Test Plan
59
- - [How to test]
84
+ - [Regression test description]
85
+ - [Manual verification, if applicable]
60
86
  ```
61
87
 
62
88
  **Verdict meanings:**
63
- - `APPROVE`: Ready to create PR
64
- - `REQUEST_CHANGES`: Issues to fix before PR creation
65
- - `COMMENT`: Minor items, can create PR but note feedback
89
+ - `APPROVE`: Bug is resolved, regression test is in place, PR is ready for architect review.
90
+ - `REQUEST_CHANGES`: Real BUGFIX-relevant issues to fix (missing regression test, fix doesn't resolve the symptom, scope creep, etc.).
91
+ - `COMMENT`: Minor items, can proceed but note feedback.
66
92
 
67
93
  ## Notes
68
94
 
69
- - This is the builder's final self-review before hand-off
70
- - The PR_SUMMARY in your output can be used as the PR description
71
- - Focus on "is this ready for someone else to review" not "is this perfect"
72
- - Any issues found here are cheaper to fix than during integration review
95
+ - This is the builder's final self-review before hand-off to the architect.
96
+ - The `PR_SUMMARY` block can be used directly as the PR description.
97
+ - Focus on "is this bug actually fixed and protected by a test" — not on artifacts from other protocols.
@@ -30,6 +30,12 @@ You are running in STRICT mode. This means:
30
30
  Follow the SPIR protocol: `codev/protocols/spir/protocol.md`
31
31
  Read and internalize the protocol before starting any work.
32
32
 
33
+ ## Baked Decisions
34
+
35
+ 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.
36
+
37
+ 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.
38
+
33
39
  {{#if spec}}
34
40
  ## Spec
35
41
  Read the specification at: `{{spec.path}}`
@@ -53,13 +59,23 @@ Follow the implementation plan at: `{{plan.path}}`
53
59
  {{task_text}}
54
60
  {{/if}}
55
61
 
56
- ## Multi-PR Workflow
62
+ ## PR Strategy
63
+
64
+ **Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits within a single PR, not as separate PRs. The plan's instruction that "each phase commits independently" refers to git commits, not PRs.
65
+
66
+ By default, the PR is opened during/after the final implement phase, with all phase-commits already on the branch.
67
+
68
+ ### Architect-requested PRs
69
+
70
+ The architect MAY request a PR at any point — for spec review, mid-implementation feedback, slicing a large spec into shippable PRs, etc. When the architect explicitly asks for a PR earlier (or for additional PRs), follow that direction. The prohibition is specifically on the *builder* autonomously deciding to open per-phase PRs without architect request.
71
+
72
+ ### Multi-PR Mechanics (when the architect requests sequential PRs)
57
73
 
58
- Your worktree is persistent — it survives across PR merges. You can produce multiple PRs sequentially:
74
+ Your worktree is persistent — it survives across PR merges. When the architect asks for sequential PRs (e.g., to slice a large spec into shippable pieces), use this loop:
59
75
 
60
76
  1. Cut a branch, open a PR, wait for merge
61
77
  2. After merge: `git fetch origin main && git checkout -b <next-branch> origin/main`
62
- 3. Continue to the next phase, open another PR
78
+ 3. Continue to the next slice, open another PR
63
79
  4. Repeat
64
80
 
65
81
  **Important**: Do NOT run `git checkout main` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/main` via fetch.
@@ -3,6 +3,12 @@
3
3
  ## Context
4
4
  You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it.
5
5
 
6
+ ## Baked Decisions
7
+
8
+ If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed (this extends the existing "don't re-litigate spec decisions" rule with explicit baked-decision language). 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; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect.
9
+
10
+ If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
11
+
6
12
  ## Focus Areas
7
13
 
8
14
  1. **Spec Coverage**
@@ -3,6 +3,12 @@
3
3
  ## Context
4
4
  You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval.
5
5
 
6
+ ## Baked Decisions
7
+
8
+ If the issue body or the spec's Constraints section 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 spec **fails to honor** a stated baked decision — that is a real defect.
9
+
10
+ If the baked decisions themselves contain contradictions (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
11
+
6
12
  ## Focus Areas
7
13
 
8
14
  1. **Completeness**
@@ -31,6 +31,12 @@ ls codev/specs/{{project_id}}-*.md
31
31
 
32
32
  **If no spec exists:** Proceed to Step 1 below.
33
33
 
34
+ ### 0.5 Baked Decisions
35
+
36
+ Before exploring solution approaches, check the issue body for a section named "Baked Decisions" (any heading level, case-insensitive). If present, copy its content verbatim into the spec's Constraints section and treat each item as fixed. Do not autonomously relitigate the architect's choices in your Solution Exploration. If you discover a serious problem with a baked decision, raise it via `afx send architect` rather than overriding it in the spec.
37
+
38
+ If two baked decisions contradict each other (e.g., two different language choices), do not pick one — pause, flag the contradiction via `afx send`, and wait for resolution before drafting.
39
+
34
40
  ### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS)
35
41
 
36
42
  Before writing anything, ask clarifying questions to understand:
@@ -79,6 +79,10 @@ Each phase follows a build-verify loop: build the artifact, then verify with 3-w
79
79
  - Dependency updates
80
80
  - Emergency hotfixes (but do a lightweight retrospective after)
81
81
 
82
+ ## Baked Decisions (Optional)
83
+
84
+ When filing an issue for SPIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will copy the section verbatim into the spec's Constraints and treat each item as fixed; CMAP reviewers will not propose alternatives unless the spec itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`.
85
+
82
86
  ## Protocol Phases
83
87
 
84
88
  ### S - Specify (Collaborative Design Exploration)