@cluesmith/codev 3.3.1 → 3.3.3

package/scripts/forge/gitlab/pr-create.sh

@@ -0,0 +1,53 @@
+#!/bin/sh
+# Forge concept: pr-create (GitLab via glab CLI — merge requests)
+# forge-executable: glab
+#
+# Input:  CODEV_PR_TITLE (required)
+#         CODEV_PR_BODY  (required, may be empty)
+#         CODEV_PR_BASE, CODEV_PR_HEAD, CODEV_PR_REPO, CODEV_PR_DRAFT (optional)
+# Output: {"number": <int>, "url": "<web url>"}
+#
+# ⚠️ UNVERIFIED — `glab` is not available in the authoring environment (same
+#    constraint as gitea/issue-search.sh, #920). Written against glab's
+#    documented `mr create` flags; smoke-test before relying on it. Without this
+#    file the gitlab preset would fall through to the GitHub default and shell
+#    out to `gh` — the bug this concept exists to close (#1455).
+#
+# `glab mr create --yes` skips the interactive prompts and prints the new MR's
+# URL; the number (GitLab's `iid`) is its last path segment.
+set -e
+
+if [ -z "$CODEV_PR_TITLE" ]; then
+  echo "pr-create: CODEV_PR_TITLE is required" >&2
+  exit 2
+fi
+
+# An empty body is allowed; an *absent* one is not. Without this, forgetting the
+# variable opens a PR with no body at exit 0 — the silent failure #1455 is about.
+if [ -z "${CODEV_PR_BODY+x}" ]; then
+  echo "pr-create: CODEV_PR_BODY is required (set it to \"\" for an empty body)" >&2
+  exit 2
+fi
+
+set -- --title "$CODEV_PR_TITLE" --description "$CODEV_PR_BODY" --yes
+if [ -n "$CODEV_PR_BASE" ]; then set -- "$@" --target-branch "$CODEV_PR_BASE"; fi
+if [ -n "$CODEV_PR_HEAD" ]; then set -- "$@" --source-branch "$CODEV_PR_HEAD"; fi
+if [ -n "$CODEV_PR_REPO" ]; then set -- "$@" --repo "$CODEV_PR_REPO"; fi
+if [ "$CODEV_PR_DRAFT" = "1" ]; then set -- "$@" --draft; fi
+
+url=$(glab mr create "$@" | grep -E '^https?://' | tail -n 1)
+
+if [ -z "$url" ]; then
+  echo "pr-create: glab mr create returned no MR URL" >&2
+  exit 1
+fi
+
+number=${url##*/}
+case "$number" in
+  '' | *[!0-9]*)
+    echo "pr-create: could not parse an MR number from '$url'" >&2
+    exit 1
+    ;;
+esac
+
+printf '{"number":%s,"url":"%s"}\n' "$number" "$url"

package/scripts/forge/gitlab/pr-search.sh

@@ -1,3 +1,5 @@
 #!/bin/sh
 # Forge concept: pr-search (GitLab via glab CLI)
-exec glab mr list --search "$CODEV_SEARCH_QUERY" --output json
+# --all is required so the search includes merged/closed MRs; without it
+# `glab mr list` defaults to opened only and post-merge lookups return nothing (#759).
+exec glab mr list --all --search "$CODEV_SEARCH_QUERY" --output json

package/scripts/forge/linear/issue-view.sh

@@ -1,7 +1,13 @@
 #!/bin/sh
 # Forge concept: issue-view (Linear via GraphQL API)
 # Input: CODEV_ISSUE_ID (e.g. "ENG-123")
-# Output: JSON {title, body, state, url, comments[]}
+# Output: JSON {title, body, state, url, author, createdAt, assignees, labels, milestone, comments[]}
+#
+# Maps Linear's fields into the forge-neutral IssueView shape. Linear has a
+# single `assignee` (emitted as a one-element `assignees` array) and `project`
+# rather than milestones (mapped into `milestone.title`). These fields are
+# optional by contract, so anything Linear leaves null degrades to an omitted
+# line. Best-effort preset (Spec 589).
 set -e
 
 if [ -z "$LINEAR_API_KEY" ]; then
@@ -18,7 +24,7 @@ curl -sf -X POST https://api.linear.app/graphql \
   -H "Content-Type: application/json" \
   -H "Authorization: $LINEAR_API_KEY" \
   -d "$(jq -n --arg id "$CODEV_ISSUE_ID" '{
-    query: "query($id: String!) { issueVcsByFilter: issues(filter: { identifier: { eq: $id } }) { nodes { title url description state { name } comments { nodes { body createdAt user { displayName } } } } } }",
+    query: "query($id: String!) { issueVcsByFilter: issues(filter: { identifier: { eq: $id } }) { nodes { title url description createdAt state { name } creator { displayName } assignee { displayName } labels { nodes { name } } project { name } comments { nodes { body createdAt user { displayName } } } } } }",
     variables: { id: $id }
   }')" \
   | jq 'if (.data.issueVcsByFilter.nodes | length) == 0 then
@@ -29,6 +35,11 @@ curl -sf -X POST https://api.linear.app/graphql \
       url: .url,
       body: (.description // ""),
       state: .state.name,
+      author: (if .creator then { login: .creator.displayName } else null end),
+      createdAt: .createdAt,
+      assignees: (if .assignee then [{ login: .assignee.displayName }] else [] end),
+      labels: [(.labels.nodes // [])[] | { name: .name }],
+      milestone: (if .project then { title: .project.name } else null end),
       comments: [.comments.nodes[] | {
         body: .body,
         createdAt: .createdAt,

package/skeleton/.claude/skills/arch-save/SKILL.md

@@ -107,8 +107,14 @@ guarantee about the clear's completion. If the timing is wrong the re-init arriv
 wrong moment, which costs one manual message (see below) and nothing else. That is the
 whole reason this cycle can be built on a delay rather than on machinery.
 
-Delayed sends are **not persisted** — if Tower restarts inside the window, the message is
-dropped. That is recoverable; see below.
+Delayed sends **are persisted**. The body is written to the durable mailbox at request time
+with a `not_before` timestamp, so Tower keeps no timer for it and a restart inside the window
+does not lose it — the re-init is delivered once the delay passes. The one thing a restart does
+drop is the Ctrl+C nudge of a delayed `--interrupt`, which this cycle does not use.
+
+That removes a failure mode this section used to warn about, but not the need for the recovery
+path below: delivery still waits on an empty prompt, so a re-init can arrive late rather than
+never.
 
 **If this send fails, do not end your turn.** Step 4 queued the `/clear`, but it does not
 take effect until your turn ends — so at this moment you still have your full context and

package/skeleton/.claude/skills/builder-refresh/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: builder-refresh
+description: Refresh a builder's own context at a protocol boundary — save working state, verify it, clear, and re-orient. Use when porch emits a context-refresh task, or the builder is told to "refresh your context" / "run a self-refresh". A builder does not invoke this autonomously mid-task; porch chooses the moment. Counterpart to the architect's /arch-save.
+argument-hint: "(none — porch's refresh task supplies the commands)"
+---
+
+# /builder-refresh — save, clear, and come back knowing where you are
+
+You are a builder that has reached a protocol boundary. Your context can be discarded
+here safely, because everything that matters is already on disk: the spec, the plan,
+`status.yaml`, your thread narrative, and git history. A fresh context re-orients from
+those artifacts rather than from memory.
+
+**The enforcement is in the command, not in this document.** `afx self-refresh` refuses to
+clear on an unverified save, refuses when the re-entry cannot be scheduled, and refuses
+when your worktree has uncommitted tracked changes. This skill sequences the steps and
+explains the judgement calls; it cannot and does not decide whether the clear is safe.
+
+## When NOT to run this
+
+**Porch chooses the moment. You do not.** Run this when porch's refresh task tells you to,
+or when the architect directs it. Do not invoke it mid-task on your own judgement — a
+boundary is a point a fresh context can resume *from*, and a mid-task snapshot resumes into
+confusion.
+
+If you are not at a boundary and think you need a refresh anyway, say so to the architect
+rather than doing it: `afx send architect "..."`.
+
+## The procedure
+
+### 1. Use the commands porch gave you
+
+Porch's refresh task contains the exact two commands for this boundary, including the
+`--boundary` flag. **Run those, verbatim.**
+
+Do not retype them from memory and do not omit the flag. `--boundary` binds the challenge
+to the boundary it was issued at, so a challenge left behind by an aborted refresh cannot
+be used to clear you at a *later* boundary, against a save describing work that has since
+moved on. That guard has been silently disabled twice by an instruction that dropped the
+flag, which is why this document deliberately does not restate the commands.
+
+If you arrived here without a porch task — an architect-directed refresh, say — there is no
+boundary to bind, and the flagless form is correct. Run `afx self-refresh --help` for the
+exact spelling rather than guessing it.
+
+### 2. Write your working state
+
+The first command prints a save request naming a file and a marker line. Write that file.
+
+**The marker must be the FIRST LINE**, reproduced exactly. A save whose nonce appears
+further down is refused — that check exists because echoing the request back into the file
+otherwise passed every gate, and echoing instructions is something agents do by accident.
+
+**Write for a cold reader** — a competent agent that wakes up with your worktree, your
+branch, and no memory of this conversation. Most of your state is already on disk, so do
+not restate the spec or the plan. Carry only what the artifacts do not contain:
+
+- **receipts** — what is done and *verified*, with paths and commit hashes, distinguishing
+  "written" from "verified";
+- **deviations** from the plan, and why;
+- **flaky or skipped tests**, and what you did about them;
+- **deferred work**, and the reason;
+- **standing orders** from the architect you are still bound by, including anything you
+  were told NOT to do;
+- **the next concrete action**.
+
+Pointers, not prose. The save has a minimum size, and it is not a word count to pad — a
+file below it is indistinguishable from a stub. If you genuinely have less than that to
+say, you are probably omitting receipts or standing orders.
+
+### 3. Run the execute command, then stop
+
+The second command verifies your save, writes a re-orientation to disk, schedules your
+re-entry, and clears you — in that order, and only if every step succeeds.
+
+**Then end your turn.** Do not start new work. The clear takes effect when the turn ends.
+
+## If it refuses
+
+Most refusals happen **before** anything destructive, and those leave your context
+untouched. One does not. Read which you got.
+
+### Pre-clear refusals — your context is intact
+
+| Refusal | What it means |
+|---|---|
+| state file missing / too small / wrong nonce | Your save did not satisfy the gate — check the marker is on line 1 |
+| worktree has uncommitted tracked changes | Commit first; a refreshed context re-orients from git, so uncommitted work is invisible to it |
+| Tower is not running, or did not schedule the re-entry | Clearing would strand you, so it refused |
+| challenge missing / already consumed / for a different boundary | Run the begin step again |
+| invalid parameters | A flag is out of range — nothing was read or written |
+| challenge could not be marked consumed | Nothing was cleared, but a re-entry **is** already queued and will arrive; ignore it. Retrying queues a second one |
+
+For any of these: **report it and carry on.**
+
+```bash
+afx send architect "Context refresh refused at <boundary>: <the reason it printed>"
+```
+
+Then run `porch next` for your normal tasks. **The refresh never blocks your work** — the
+boundary is recorded as consumed either way, so a failed refresh costs you some context and
+nothing else.
+
+### `clear-failed` — you cannot assume anything
+
+If the command reports that the clear was attempted but **may still have landed**, do not
+treat that as a pre-clear refusal. Sending `/clear` can succeed on the wire and still report
+an error, so from inside this turn it is genuinely unknown whether your context survives.
+
+- A re-entry message **is** already queued and will arrive shortly. If your context was
+  cleared, that message is your re-orientation. If it was not, the message is harmless and
+  can be ignored.
+- Do not start new work in this state.
+- Tell the architect explicitly that the outcome is ambiguous:
+
+```bash
+afx send architect "Self-refresh clear-failed at <boundary> — clear may or may not have landed; re-entry is queued"
+```
+
+## After the clear
+
+A re-entry message arrives shortly, identifying itself as an automatic context refresh. It
+carries your identity, protocol, project, worktree and branch, and points at
+`.builder-reorient.md` — the full spawn-quality frame, on disk.
+
+It will tell you to run `porch next`. Do that; porch's state is untouched by the clear and
+its next task emission *is* your re-orientation.
+
+**If the re-entry never arrives**, nothing is lost. `.builder-reorient.md` is on disk and
+the architect can send you back with one message. Say so if you notice.
+
+## What this does not do
+
+- It does not write `status.yaml`. Only porch does, and the boundary is already recorded
+  there before you are asked to refresh.
+- It does not decide *whether* to refresh. Porch decided that.
+- It does not retry. A boundary is refreshed at most once, so a refusal means this boundary
+  simply does not get a refresh.

package/skeleton/.claude/skills/generate-image/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-image
-description: AI image generation via Gemini. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY.
+description: AI image generation via Gemini, or Atlas Cloud with `-p atlas`. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY, or ATLASCLOUD_API_KEY when using `-p atlas`.
 ---
 
 # generate-image - AI Image Generation
@@ -22,6 +22,7 @@ Note: this is a `codev` subcommand, not standalone.
 -r, --resolution <res>     Resolution: 1K, 2K, 4K (default: 1K)
 -a, --aspect <ratio>       Aspect ratio (default: 1:1)
 --ref <image>              Reference image (repeatable, max 14)
+-p, --provider <name>      Provider: gemini (default) or atlas
 ```
 
 ## Aspect ratios
@@ -43,3 +44,23 @@ codev generate-image prompt.txt -o result.png    # Prompt from .txt file
 - Prompt can be a `.txt` file path (auto-detected by extension)
 - Reference images must exist on disk
 - Requires `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable
+
+## Alternative provider: Atlas Cloud
+
+`-p atlas` generates through Atlas Cloud, which serves the same Nano Banana Pro
+model over a submit-then-poll REST API. Useful when a Google AI Studio key is
+not available. Requires `ATLASCLOUD_API_KEY`; the default provider is unchanged.
+
+```bash
+codev generate-image "A sunset over mountains" -p atlas -a 16:9
+```
+
+Measured differences on that path:
+
+- `-a/--aspect` works (`1:1` returns 1024x1024, `16:9` returns 1376x768).
+- `-r/--resolution` has no equivalent field; a note is printed and the model's
+  default resolution comes back.
+- `--ref` is not supported (text-to-image only) and exits with an error rather
+  than silently ignoring the images.
+- The model returns JPEG, so the output file is named after its actual bytes
+  instead of writing JPEG into the default `output.png`.

package/skeleton/.codex/skills/arch-save/SKILL.md

@@ -107,8 +107,14 @@ guarantee about the clear's completion. If the timing is wrong the re-init arriv
 wrong moment, which costs one manual message (see below) and nothing else. That is the
 whole reason this cycle can be built on a delay rather than on machinery.
 
-Delayed sends are **not persisted** — if Tower restarts inside the window, the message is
-dropped. That is recoverable; see below.
+Delayed sends **are persisted**. The body is written to the durable mailbox at request time
+with a `not_before` timestamp, so Tower keeps no timer for it and a restart inside the window
+does not lose it — the re-init is delivered once the delay passes. The one thing a restart does
+drop is the Ctrl+C nudge of a delayed `--interrupt`, which this cycle does not use.
+
+That removes a failure mode this section used to warn about, but not the need for the recovery
+path below: delivery still waits on an empty prompt, so a re-init can arrive late rather than
+never.
 
 **If this send fails, do not end your turn.** Step 4 queued the `/clear`, but it does not
 take effect until your turn ends — so at this moment you still have your full context and

package/skeleton/.codex/skills/builder-refresh/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: builder-refresh
+description: Refresh a builder's own context at a protocol boundary — save working state, verify it, clear, and re-orient. Use when porch emits a context-refresh task, or the builder is told to "refresh your context" / "run a self-refresh". A builder does not invoke this autonomously mid-task; porch chooses the moment. Counterpart to the architect's /arch-save.
+argument-hint: "(none — porch's refresh task supplies the commands)"
+---
+
+# /builder-refresh — save, clear, and come back knowing where you are
+
+You are a builder that has reached a protocol boundary. Your context can be discarded
+here safely, because everything that matters is already on disk: the spec, the plan,
+`status.yaml`, your thread narrative, and git history. A fresh context re-orients from
+those artifacts rather than from memory.
+
+**The enforcement is in the command, not in this document.** `afx self-refresh` refuses to
+clear on an unverified save, refuses when the re-entry cannot be scheduled, and refuses
+when your worktree has uncommitted tracked changes. This skill sequences the steps and
+explains the judgement calls; it cannot and does not decide whether the clear is safe.
+
+## When NOT to run this
+
+**Porch chooses the moment. You do not.** Run this when porch's refresh task tells you to,
+or when the architect directs it. Do not invoke it mid-task on your own judgement — a
+boundary is a point a fresh context can resume *from*, and a mid-task snapshot resumes into
+confusion.
+
+If you are not at a boundary and think you need a refresh anyway, say so to the architect
+rather than doing it: `afx send architect "..."`.
+
+## The procedure
+
+### 1. Use the commands porch gave you
+
+Porch's refresh task contains the exact two commands for this boundary, including the
+`--boundary` flag. **Run those, verbatim.**
+
+Do not retype them from memory and do not omit the flag. `--boundary` binds the challenge
+to the boundary it was issued at, so a challenge left behind by an aborted refresh cannot
+be used to clear you at a *later* boundary, against a save describing work that has since
+moved on. That guard has been silently disabled twice by an instruction that dropped the
+flag, which is why this document deliberately does not restate the commands.
+
+If you arrived here without a porch task — an architect-directed refresh, say — there is no
+boundary to bind, and the flagless form is correct. Run `afx self-refresh --help` for the
+exact spelling rather than guessing it.
+
+### 2. Write your working state
+
+The first command prints a save request naming a file and a marker line. Write that file.
+
+**The marker must be the FIRST LINE**, reproduced exactly. A save whose nonce appears
+further down is refused — that check exists because echoing the request back into the file
+otherwise passed every gate, and echoing instructions is something agents do by accident.
+
+**Write for a cold reader** — a competent agent that wakes up with your worktree, your
+branch, and no memory of this conversation. Most of your state is already on disk, so do
+not restate the spec or the plan. Carry only what the artifacts do not contain:
+
+- **receipts** — what is done and *verified*, with paths and commit hashes, distinguishing
+  "written" from "verified";
+- **deviations** from the plan, and why;
+- **flaky or skipped tests**, and what you did about them;
+- **deferred work**, and the reason;
+- **standing orders** from the architect you are still bound by, including anything you
+  were told NOT to do;
+- **the next concrete action**.
+
+Pointers, not prose. The save has a minimum size, and it is not a word count to pad — a
+file below it is indistinguishable from a stub. If you genuinely have less than that to
+say, you are probably omitting receipts or standing orders.
+
+### 3. Run the execute command, then stop
+
+The second command verifies your save, writes a re-orientation to disk, schedules your
+re-entry, and clears you — in that order, and only if every step succeeds.
+
+**Then end your turn.** Do not start new work. The clear takes effect when the turn ends.
+
+## If it refuses
+
+Most refusals happen **before** anything destructive, and those leave your context
+untouched. One does not. Read which you got.
+
+### Pre-clear refusals — your context is intact
+
+| Refusal | What it means |
+|---|---|
+| state file missing / too small / wrong nonce | Your save did not satisfy the gate — check the marker is on line 1 |
+| worktree has uncommitted tracked changes | Commit first; a refreshed context re-orients from git, so uncommitted work is invisible to it |
+| Tower is not running, or did not schedule the re-entry | Clearing would strand you, so it refused |
+| challenge missing / already consumed / for a different boundary | Run the begin step again |
+| invalid parameters | A flag is out of range — nothing was read or written |
+| challenge could not be marked consumed | Nothing was cleared, but a re-entry **is** already queued and will arrive; ignore it. Retrying queues a second one |
+
+For any of these: **report it and carry on.**
+
+```bash
+afx send architect "Context refresh refused at <boundary>: <the reason it printed>"
+```
+
+Then run `porch next` for your normal tasks. **The refresh never blocks your work** — the
+boundary is recorded as consumed either way, so a failed refresh costs you some context and
+nothing else.
+
+### `clear-failed` — you cannot assume anything
+
+If the command reports that the clear was attempted but **may still have landed**, do not
+treat that as a pre-clear refusal. Sending `/clear` can succeed on the wire and still report
+an error, so from inside this turn it is genuinely unknown whether your context survives.
+
+- A re-entry message **is** already queued and will arrive shortly. If your context was
+  cleared, that message is your re-orientation. If it was not, the message is harmless and
+  can be ignored.
+- Do not start new work in this state.
+- Tell the architect explicitly that the outcome is ambiguous:
+
+```bash
+afx send architect "Self-refresh clear-failed at <boundary> — clear may or may not have landed; re-entry is queued"
+```
+
+## After the clear
+
+A re-entry message arrives shortly, identifying itself as an automatic context refresh. It
+carries your identity, protocol, project, worktree and branch, and points at
+`.builder-reorient.md` — the full spawn-quality frame, on disk.
+
+It will tell you to run `porch next`. Do that; porch's state is untouched by the clear and
+its next task emission *is* your re-orientation.
+
+**If the re-entry never arrives**, nothing is lost. `.builder-reorient.md` is on disk and
+the architect can send you back with one message. Say so if you notice.
+
+## What this does not do
+
+- It does not write `status.yaml`. Only porch does, and the boundary is already recorded
+  there before you are asked to refresh.
+- It does not decide *whether* to refresh. Porch decided that.
+- It does not retry. A boundary is refreshed at most once, so a refusal means this boundary
+  simply does not get a refresh.

package/skeleton/.codex/skills/generate-image/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-image
-description: AI image generation via Gemini. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY.
+description: AI image generation via Gemini, or Atlas Cloud with `-p atlas`. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY, or ATLASCLOUD_API_KEY when using `-p atlas`.
 ---
 
 # generate-image - AI Image Generation
@@ -22,6 +22,7 @@ Note: this is a `codev` subcommand, not standalone.
 -r, --resolution <res>     Resolution: 1K, 2K, 4K (default: 1K)
 -a, --aspect <ratio>       Aspect ratio (default: 1:1)
 --ref <image>              Reference image (repeatable, max 14)
+-p, --provider <name>      Provider: gemini (default) or atlas
 ```
 
 ## Aspect ratios
@@ -43,3 +44,23 @@ codev generate-image prompt.txt -o result.png    # Prompt from .txt file
 - Prompt can be a `.txt` file path (auto-detected by extension)
 - Reference images must exist on disk
 - Requires `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable
+
+## Alternative provider: Atlas Cloud
+
+`-p atlas` generates through Atlas Cloud, which serves the same Nano Banana Pro
+model over a submit-then-poll REST API. Useful when a Google AI Studio key is
+not available. Requires `ATLASCLOUD_API_KEY`; the default provider is unchanged.
+
+```bash
+codev generate-image "A sunset over mountains" -p atlas -a 16:9
+```
+
+Measured differences on that path:
+
+- `-a/--aspect` works (`1:1` returns 1024x1024, `16:9` returns 1376x768).
+- `-r/--resolution` has no equivalent field; a note is printed and the model's
+  default resolution comes back.
+- `--ref` is not supported (text-to-image only) and exits with an error rather
+  than silently ignoring the images.
+- The model returns JPEG, so the output file is named after its actual bytes
+  instead of writing JPEG into the default `output.png`.

package/skeleton/protocol-schema.json

@@ -39,6 +39,23 @@
       "description": "Signals that can be emitted during protocol execution",
       "additionalProperties": { "$ref": "#/$defs/signal" }
     },
+    "context_refresh": {
+      "type": "object",
+      "description": "Boundaries at which builders automatically refresh their context (Spec 1470). Absent means no refreshes.",
+      "additionalProperties": false,
+      "properties": {
+        "on_enter": {
+          "type": "array",
+          "description": "Protocol phase ids to refresh on entry to. Each must name a phase this protocol declares.",
+          "uniqueItems": true,
+          "items": { "type": "string" }
+        },
+        "on_plan_phase_advance": {
+          "type": "boolean",
+          "description": "Refresh when advancing from one plan phase to the next. Requires a 'per_plan_phase' phase. Excludes the first plan phase, which coincides with entering the phase itself."
+        }
+      }
+    },
     "phase_completion": {
       "type": "object",
       "description": "Checks run when a plan phase completes",

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

@@ -18,7 +18,8 @@ Open the PR with the review embedded in its body, optionally run CMAP, and notif
 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'
+export CODEV_PR_TITLE="[Air #<N>] feat: <brief description>"
+export CODEV_PR_BODY="$(cat <<'EOF'
 ## Summary
 
 <1-2 sentence description of the feature>
@@ -44,8 +45,12 @@ Closes #<N>  <!-- Substitute <N>; use "Refs #<N>" for a partial fix -->
 <anything the reviewer should focus on, or "Standard implementation — no special concerns">
 EOF
 )"
+
+{{pr_create_command}}
 ```
 
+The command above is your forge's `pr-create` concept, substituted by porch (`gh pr create` by default). It takes `CODEV_PR_TITLE` / `CODEV_PR_BODY` — optionally `CODEV_PR_BASE`, `CODEV_PR_HEAD`, `CODEV_PR_REPO` — from the environment, which is why they are exported rather than prefixed onto the command line: an inline override that spells `--title "$CODEV_PR_TITLE"` needs them set in the calling shell too. It prints `{"number": <int>, "url": "<url>"}`.
+
 ## Optional CMAP review
 
 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:

package/skeleton/protocols/air/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "air",
   "version": "1.0.0",
   "description": "AIR: Autonomous Implement & Review — lightweight protocol for small features from GitHub Issues",

package/skeleton/protocols/aspir/prompts/review.md

@@ -44,7 +44,8 @@ The review's `## Architecture Updates` and `## Lessons Learned Updates` sections
 The PR body must carry `Closes #<N>` (feature) or `Fixes #<N>` (bug) for the driving issue — one keyword per issue if several — so GitHub auto-closes on merge. **Exception:** a PR that only partially addresses its issue uses `Refs #<N>` or `Part of #<N>` instead, leaving the issue open for the follow-up.
 
 ```bash
-gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
+export CODEV_PR_TITLE="[Spec {{project_id}}] {{title}}"
+export CODEV_PR_BODY="$(cat <<'EOF'
 ## Summary
 [what was implemented]
 
@@ -63,8 +64,12 @@ codev/specs/{{artifact_name}}.md
 codev/reviews/{{artifact_name}}.md
 EOF
 )"
+
+{{pr_create_command}}
 ```
 
+The command above is your forge's `pr-create` concept, substituted by porch (`gh pr create` by default). It takes `CODEV_PR_TITLE` / `CODEV_PR_BODY` — optionally `CODEV_PR_BASE`, `CODEV_PR_HEAD`, `CODEV_PR_REPO` — from the environment, which is why they are exported rather than prefixed onto the command line: an inline override that spells `--title "$CODEV_PR_TITLE"` needs them set in the calling shell too. It prints `{"number": <int>, "url": "<url>"}`.
+
 ## Signals
 
 - Review document complete:

package/skeleton/protocols/aspir/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "aspir",
   "version": "1.0.0",
   "description": "ASPIR: Autonomous SPIR — Specify → Plan → Implement → Review without human approval gates",
@@ -8,6 +8,10 @@
     "required": false,
     "default_for": ["--project", "-p"]
   },
+  "context_refresh": {
+    "on_enter": ["plan", "implement", "review"],
+    "on_plan_phase_advance": true
+  },
   "phases": [
     {
       "id": "specify",

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

@@ -16,7 +16,8 @@ Open the PR, run CMAP review on it, address feedback, and hand off to the archit
 The PR body must carry `Fixes #<N>` for the driving issue — one per issue if several — so GitHub auto-closes it on merge. **Exception:** a PR that only partially addresses the issue uses `Refs #<N>` or `Part of #<N>` instead, leaving it open for the follow-up. Substitute the real number for `<N>`; leave no `{{...}}` tag or `<N>` placeholder in the committed body.
 
 ```bash
-gh pr create --title "Fix #<N>: <brief description>" --body "$(cat <<'EOF'
+export CODEV_PR_TITLE="Fix #<N>: <brief description>"
+export CODEV_PR_BODY="$(cat <<'EOF'
 ## Summary
 
 <1-2 sentence description of the bug and fix>
@@ -38,8 +39,12 @@ Fixes #<N>  <!-- Substitute <N>; use "Refs #<N>" for a partial fix -->
 - [ ] All tests pass
 EOF
 )"
+
+{{pr_create_command}}
 ```
 
+The command above is your forge's `pr-create` concept, substituted by porch (`gh pr create` by default). It takes `CODEV_PR_TITLE` / `CODEV_PR_BODY` — optionally `CODEV_PR_BASE`, `CODEV_PR_HEAD`, `CODEV_PR_REPO` — from the environment, which is why they are exported rather than prefixed onto the command line: an inline override that spells `--title "$CODEV_PR_TITLE"` needs them set in the calling shell too. It prints `{"number": <int>, "url": "<url>"}`.
+
 ## Run CMAP review
 
 BUGFIX runs its own 3-way consultation on the PR (porch does not do it for you). Dispatch all three in the background:

package/skeleton/protocols/bugfix/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "bugfix",
   "version": "1.2.0",
   "description": "Lightweight protocol for minor bugfixes using GitHub Issues",

package/skeleton/protocols/bugfix/protocol.md

@@ -27,7 +27,8 @@ refactor surrounding code, fix unrelated bugs (file separate issues), or add fea
 [Bugfix #42] Test: regression for unencoded username
 ```
 
-**PR** — open with `gh pr create`, body carrying Summary, Root Cause, Fix and Test Plan plus
+**PR** — open with the `pr-create` forge concept command the PR-phase prompt hands you (`gh
+pr create` on GitHub), body carrying Summary, Root Cause, Fix and Test Plan plus
 `Fixes #<N>` so the issue closes on merge. Run one CMAP pass (Gemini, Codex, Claude), record
 each verdict, and address or rebut every `REQUEST_CHANGES`. Notify the architect with the
 verdicts, then `porch done <id>` and wait.

package/skeleton/protocols/experiment/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "experiment",
   "version": "1.0.0",
   "description": "Disciplined experimentation with hypothesis testing",