Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
591867e
feat(lib): add resolveDefaultBranch helper
amrmelsayed May 22, 2026
a888136
[Bugfix #777][Bugfix #784] fix(consult): resolve default branch + use…
amrmelsayed May 22, 2026
67bed26
[Bugfix #777] feat(consult): --branch flag and PR-default ref resolve…
amrmelsayed May 22, 2026
22d27e2
[Bugfix #777] docs(protocols): use integration branch instead of lite…
amrmelsayed May 22, 2026
361aa5a
test(consult): cover non-main default branch, three-dot scope, and re…
amrmelsayed May 22, 2026
9da29fb
[Bugfix #777] test(baked-decisions): refresh AIR pr-review baseline a…
amrmelsayed May 22, 2026
2e48467
[Bugfix #777] fix(bugfix-protocol): default-branch shell substitution…
amrmelsayed May 22, 2026
fa16f0f
[Bugfix #777] fix(consult): scope architect impl diff against PR.base…
amrmelsayed May 22, 2026
90be0e6
test(consult): cover PR.baseRefName != repo default as merge-base anchor
amrmelsayed May 22, 2026
9b0ee17
[Bugfix #777] fix(consult): surface fetch failures instead of silentl…
amrmelsayed May 22, 2026
b1840ef
[Bugfix #777] refactor(consult): collapse redundant merge-base, use e…
amrmelsayed May 22, 2026
f68f24e
[Bugfix #777] fix(protocols): default-branch resolution falls through…
amrmelsayed May 22, 2026
5f7deb4
[Bugfix #777] fix(consult): tolerate stale pr-search.sh overrides wit…
amrmelsayed May 22, 2026
cbdd129
[Bugfix #777] fix(consult): verify both PR refs up front; convert las…
amrmelsayed May 22, 2026
5390eec
[Bugfix #777] fix(protocols): complete the || echo main → ${VAR:-main…
amrmelsayed May 22, 2026
c6144d7
[Bugfix #777][Bugfix #784] fix(protocols): anchor diff invocations at…
amrmelsayed May 22, 2026
fa270cf
test(protocols): add regression-guard audit for #777 / #784 prompt pa…
amrmelsayed May 22, 2026
76bafa0
docs(consult-types/pr-review): add reviewer-scope rule against flaggi…
amrmelsayed May 22, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion codev-skeleton/protocols/air/consult-types/pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,11 @@ If the baked decisions themselves contain contradictions, do not pick one — `R
5. **PR Quality**
- Does the PR link to the issue?
- Is the PR body review section informative?
- Is the branch up to date with main?
- Is the branch 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.

## Verdict Format

Expand Down
6 changes: 3 additions & 3 deletions codev-skeleton/protocols/aspir/builder-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,18 +74,18 @@ The architect MAY request a PR at any point — for spec review, mid-implementat
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:

1. Cut a branch, open a PR, wait for merge
2. After merge: `git fetch origin main && git checkout -b <next-branch> origin/main`
2. After merge: `git fetch origin <integration-branch> && git checkout -b <next-branch> origin/<integration-branch>` — where `<integration-branch>` is the branch the architect targets PRs at (usually `main`; check the open PR's `baseRefName` if unsure)
3. Continue to the next slice, open another PR

**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.
**Important**: Do NOT run `git checkout <integration-branch>` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/<integration-branch>` via fetch.

Record PRs: `porch done {{project_id}} --pr <N> --branch <name>`
Record merges: `porch done {{project_id}} --merged <N>`

## Verify Phase

After the final PR merges, the project enters the **verify** phase. You stay alive through verify:
1. Pull main into your worktree
1. Pull the integration branch into your worktree
2. Run `porch done {{project_id}}` to signal verification is ready
3. The architect approves `verify-approval` when satisfied

Expand Down
6 changes: 5 additions & 1 deletion codev-skeleton/protocols/aspir/consult-types/pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,14 @@ You are performing a final self-check during the Review phase. The builder has c
- Are any new APIs documented?

5. **PR Readiness**
- Is the branch up to date with main?
- Is the branch up to date with its base (the integration branch the PR targets)?
- Are commits atomic and well-described?
- Is the change diff reasonable in size?

## 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.

## Verdict Format

After your review, provide your verdict in exactly this format:
Expand Down
3 changes: 2 additions & 1 deletion codev-skeleton/protocols/bugfix/consult-types/pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ There is **no `codev/specs/`, `codev/plans/`, or `codev/reviews/` file** for a B

6. **PR Hygiene**
- Commits use the BUGFIX format: `Fix #<N>: ...` or `[Bugfix #<N>] ...` (**not** `[Spec NNNN][Phase]`).
- Branch is up to date with main (or close enough for clean merge).
- Branch is up to date with its base (or close enough for clean merge).
- PR is linked to the issue.

## Out of Scope (Do NOT request changes for)
Expand All @@ -54,6 +54,7 @@ The following are **not** part of the BUGFIX protocol and must **not** be cited
- Commit format `[Spec NNNN][Phase]` — BUGFIX intentionally uses `Fix #N:` / `[Bugfix #N]`.
- `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.
- Phase-scoping concerns — BUGFIX is a single-phase protocol; there are no plan phases to scope against.
- **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

Expand Down
6 changes: 5 additions & 1 deletion codev-skeleton/protocols/maintain/consult-types/pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,14 @@ You are performing a final self-check during the Review phase. The builder has c
- Are any new APIs documented?

5. **PR Readiness**
- Is the branch up to date with main?
- Is the branch up to date with its base (the integration branch the PR targets)?
- Are commits atomic and well-described?
- Is the change diff reasonable in size?

## 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.

## Verdict Format

After your review, provide your verdict in exactly this format:
Expand Down
2 changes: 1 addition & 1 deletion codev-skeleton/protocols/pir/builder-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ If you encounter **pre-existing flaky tests** (intermittent failures unrelated t
If your Claude session crashes mid-flow, Tower's `while true` loop will relaunch you with the same prompt. On startup:

1. Run `porch next {{project_id}}` to learn what phase you're in
2. If `gate_pending`: read the latest plan file (plan-approval) or `git diff "$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' || echo main)"` (dev-approval) plus any new GitHub issue comments; check `afx send` queue. Decide whether to revise or just announce you're back.
2. If `gate_pending`: read the latest plan file (plan-approval) or `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'); git diff "$(git merge-base "${DEFAULT_BRANCH:-main}" HEAD)"` (dev-approval) plus any new GitHub issue comments; check `afx send` queue. Decide whether to revise or just announce you're back.
3. Otherwise: pick up where you left off

## Getting Started
Expand Down
1 change: 1 addition & 0 deletions codev-skeleton/protocols/pir/consult-types/pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ KEY_ISSUES:
- **DO** flag obvious problems the human reviewer at the gate might have missed
- **DO NOT** redesign the approach — that was settled at `plan-approval` and validated at `dev-approval`
- **DO NOT** demand changes the human reviewer already accepted at the `dev-approval` gate (the human ran the code and approved it; you didn't)
- **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.

## Notes

Expand Down
10 changes: 6 additions & 4 deletions codev-skeleton/protocols/pir/prompts/implement.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,16 @@ Implement the approved plan, write tests, and pause at the `dev-approval` gate s

Run `porch next {{project_id}}`. If the response is `gate_pending` on `dev-approval`, the code is already written and you're awaiting review. In that case:

1. Resolve your repo's default branch (falls back to `main` if `origin/HEAD` isn't set):
1. Resolve your repo's default branch and the merge-base. The merge-base anchors the diff at the branch's fork point, so commits the base branch picked up *after* you branched don't show up as phantom "scope creep". (`DEFAULT_BRANCH` falls back to `main` if `origin/HEAD` isn't set.)

```bash
DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' || echo main)
DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
MERGE_BASE=$(git merge-base "$DEFAULT_BRANCH" HEAD)
```

2. Check for feedback:
- `git diff "$DEFAULT_BRANCH"` — has the reviewer made any direct edits to your code?
- `git diff "$MERGE_BASE"` — has the reviewer made any direct edits to your code?
- `gh issue view {{issue.number}} --comments`
- `afx send` queue messages
3. If feedback requires code changes: make them, re-run build + tests, recommit.
Expand Down Expand Up @@ -113,7 +115,7 @@ When the gate goes pending, output a short prose summary in the pane to orient t

> **What changed**: 2–3 sentence summary.
>
> **Files**: `git diff --stat "$DEFAULT_BRANCH"` style list — paths and +/-. (Resolve `$DEFAULT_BRANCH` once per session: `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' || echo main)`.)
> **Files**: `git diff --stat "$MERGE_BASE"` style list — paths and +/-. (Resolve `$MERGE_BASE` once per session: `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'); DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}; MERGE_BASE=$(git merge-base "$DEFAULT_BRANCH" HEAD)`. Anchoring at the merge-base excludes commits the base branch picked up after you branched.)
>
> **Test results**: `npm run build` ✓, `npm test` ✓ (X tests, Y new).
>
Expand Down
5 changes: 3 additions & 2 deletions codev-skeleton/protocols/pir/prompts/review.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Fixes #{{issue.number}}

## Files Changed

Output of `git diff --stat "$DEFAULT_BRANCH"`, formatted as a list (resolve once: `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' || echo main)`):
Output of `git diff --stat "$MERGE_BASE"`, formatted as a list (resolve once: `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'); DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}; MERGE_BASE=$(git merge-base "$DEFAULT_BRANCH" HEAD)`. Anchoring at the merge-base keeps the file list scoped to *your* changes, not commits the base branch absorbed after you branched.):

- `path/to/file.ts` (+12 / -3)
- `path/to/new-file.ts` (+45 / -0)
Expand Down Expand Up @@ -249,7 +249,8 @@ Together with the `--pr` record from step 4a and the `--merged` record from step
**If the PR cannot be created (e.g., merge conflicts with the default branch):**
- Rebase on the default branch:
```bash
DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' || echo main)
DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
git fetch origin "$DEFAULT_BRANCH" && git rebase "origin/$DEFAULT_BRANCH"
```
- Resolve conflicts (do NOT use destructive shortcuts)
Expand Down
6 changes: 3 additions & 3 deletions codev-skeleton/protocols/spir/builder-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,19 +74,19 @@ The architect MAY request a PR at any point — for spec review, mid-implementat
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:

1. Cut a branch, open a PR, wait for merge
2. After merge: `git fetch origin main && git checkout -b <next-branch> origin/main`
2. After merge: `git fetch origin <integration-branch> && git checkout -b <next-branch> origin/<integration-branch>` — where `<integration-branch>` is the branch the architect targets PRs at (usually `main`; check the open PR's `baseRefName` if unsure)
3. Continue to the next slice, open another PR
4. Repeat

**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.
**Important**: Do NOT run `git checkout <integration-branch>` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/<integration-branch>` via fetch.

Record PRs in status.yaml: `porch done {{project_id}} --pr <N> --branch <name>`
Record merges: `porch done {{project_id}} --merged <N>`

## Verify Phase

After the final PR merges, the project enters the **verify** phase. You stay alive through verify:
1. Pull main into your worktree
1. Pull the integration branch into your worktree
2. Run `porch done {{project_id}}` to signal verification is ready
3. The architect approves `verify-approval` when satisfied

Expand Down
6 changes: 5 additions & 1 deletion codev-skeleton/protocols/spir/consult-types/pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,14 @@ You are performing a final self-check during the Review phase. The builder has c
- Are any new APIs documented?

5. **PR Readiness**
- Is the branch up to date with main?
- Is the branch up to date with its base (the integration branch the PR targets)?
- Are commits atomic and well-described?
- Is the change diff reasonable in size?

## 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.

## Verdict Format

After your review, provide your verdict in exactly this format:
Expand Down
6 changes: 5 additions & 1 deletion codev/protocols/air/consult-types/pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,11 @@ If the baked decisions themselves contain contradictions, do not pick one — `R
5. **PR Quality**
- Does the PR link to the issue?
- Is the PR body review section informative?
- Is the branch up to date with main?
- Is the branch 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.

## Verdict Format

Expand Down
6 changes: 5 additions & 1 deletion codev/protocols/aspir/consult-types/pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,14 @@ You are performing a final self-check during the Review phase. The builder has c
- Are any new APIs documented?

5. **PR Readiness**
- Is the branch up to date with main?
- Is the branch up to date with its base (the integration branch the PR targets)?
- Are commits atomic and well-described?
- Is the change diff reasonable in size?

## 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.

## Verdict Format

After your review, provide your verdict in exactly this format:
Expand Down
3 changes: 2 additions & 1 deletion codev/protocols/bugfix/consult-types/pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ There is **no `codev/specs/`, `codev/plans/`, or `codev/reviews/` file** for a B

6. **PR Hygiene**
- Commits use the BUGFIX format: `Fix #<N>: ...` or `[Bugfix #<N>] ...` (**not** `[Spec NNNN][Phase]`).
- Branch is up to date with main (or close enough for clean merge).
- Branch is up to date with its base (or close enough for clean merge).
- PR is linked to the issue.

## Out of Scope (Do NOT request changes for)
Expand All @@ -54,6 +54,7 @@ The following are **not** part of the BUGFIX protocol and must **not** be cited
- Commit format `[Spec NNNN][Phase]` — BUGFIX intentionally uses `Fix #N:` / `[Bugfix #N]`.
- `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.
- Phase-scoping concerns — BUGFIX is a single-phase protocol; there are no plan phases to scope against.
- **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

Expand Down
10 changes: 7 additions & 3 deletions codev/protocols/bugfix/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,7 @@ git commit -m "[Bugfix #N] Test: Add regression test"
git pull
```

2. Verify the fix is on main:
2. Verify the fix is on the integration branch:
```bash
git log --oneline -5 # Should see the bugfix commits
```
Expand Down Expand Up @@ -324,7 +324,11 @@ Before marking PR ready, the Builder must verify:
The "< 300 LOC" threshold is measured as **net diff** (additions + deletions):

```bash
git diff --stat main | tail -1
DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
# Anchor at the merge-base so commits the base branch picked up after you
# branched aren't counted toward this PR's LOC budget.
git diff --stat "$(git merge-base "$DEFAULT_BRANCH" HEAD)" | tail -1
# Example: "3 files changed, 145 insertions(+), 52 deletions(-)"
# Net diff = 145 + 52 = 197 LOC ✓ (under 300)
```
Expand Down Expand Up @@ -480,7 +484,7 @@ afx send architect "Merged. Ready for cleanup."

# 11. Architect cleans up
git pull
git log --oneline -3 # Verify fix is on main
git log --oneline -3 # Verify fix is on the integration branch
afx cleanup --issue 42
# → Removes .builders/bugfix-42/
# → Deletes origin/builder/bugfix-42-login-fails-when-userna
Expand Down
6 changes: 5 additions & 1 deletion codev/protocols/maintain/consult-types/pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,14 @@ You are performing a final self-check during the Review phase. The builder has c
- Are any new APIs documented?

5. **PR Readiness**
- Is the branch up to date with main?
- Is the branch up to date with its base (the integration branch the PR targets)?
- Are commits atomic and well-described?
- Is the change diff reasonable in size?

## 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.

## Verdict Format

After your review, provide your verdict in exactly this format:
Expand Down
2 changes: 1 addition & 1 deletion codev/protocols/pir/builder-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ If you encounter **pre-existing flaky tests** (intermittent failures unrelated t
If your Claude session crashes mid-flow, Tower's `while true` loop will relaunch you with the same prompt. On startup:

1. Run `porch next {{project_id}}` to learn what phase you're in
2. If `gate_pending`: read the latest plan file (plan-approval) or `git diff "$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' || echo main)"` (dev-approval) plus any new GitHub issue comments; check `afx send` queue. Decide whether to revise or just announce you're back.
2. If `gate_pending`: read the latest plan file (plan-approval) or `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'); git diff "$(git merge-base "${DEFAULT_BRANCH:-main}" HEAD)"` (dev-approval) plus any new GitHub issue comments; check `afx send` queue. Decide whether to revise or just announce you're back.
3. Otherwise: pick up where you left off

## Getting Started
Expand Down
1 change: 1 addition & 0 deletions codev/protocols/pir/consult-types/pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ KEY_ISSUES:
- **DO** flag obvious problems the human reviewer at the gate might have missed
- **DO NOT** redesign the approach — that was settled at `plan-approval` and validated at `dev-approval`
- **DO NOT** demand changes the human reviewer already accepted at the `dev-approval` gate (the human ran the code and approved it; you didn't)
- **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.

## Notes

Expand Down
Loading
Loading