@cluesmith/codev 3.3.4 → 3.3.6

package/scripts/forge/jira/_lib.sh

@@ -0,0 +1,113 @@
+# Shared helpers for the Jira forge preset scripts (Jira Cloud via Atlassian's `acli`).
+#
+# This file is SOURCED, not executed (`. "$(dirname "$0")/_lib.sh"`), so it has
+# no shebang and defines only functions/vars. POSIX sh only — no bashisms — the
+# scripts are #!/bin/sh and forge runs them via `sh -c`. It is not a forge
+# concept: forge.ts builds presets from an explicit KNOWN_CONCEPTS allowlist, so
+# a leading-underscore file in this directory is never registered as a concept.
+#
+# Sibling-file dependency: the concept scripts that source this file need it to
+# sit next to them. A hand-copied override in `.codev/scripts/forge/jira/` must
+# copy `_lib.sh` alongside the script, or the `.` line fails.
+#
+# acli facts these helpers encode (verified against acli 1.3.39-stable):
+#   - `acli jira auth status` round-trips to the site and prints text (no
+#     --json): `Site: <host>`, `Email: <addr>`, `Authentication Type: …`.
+#   - A work item's REST `self` link names an Atlassian infrastructure host, not
+#     the site, so browser URLs are built from the site, never from `self`.
+#   - Jira rejects unbounded JQL, so every query carries a status-category
+#     clause; project scoping is optional on top of it.
+
+# Print the site's browser base URL (`https://<site>.atlassian.net`), no
+# trailing slash. Honors CODEV_JIRA_SITE (`forge.jira-site`), with or without a
+# scheme; otherwise asks acli which site it is logged into. Callers must use:
+#   SITE="$(jira_site)" || exit 1
+jira_site() {
+  if [ -n "$CODEV_JIRA_SITE" ]; then
+    _site="$CODEV_JIRA_SITE"
+  else
+    _site="$(acli jira auth status 2>/dev/null | sed -n 's/^[[:space:]]*Site:[[:space:]]*//p' | head -n 1)"
+  fi
+  _site="$(printf '%s' "$_site" | sed -e 's#^[a-zA-Z]*://##' -e 's#/*$##')"
+  if [ -z "$_site" ]; then
+    echo "jira: cannot determine the Jira site; set forge.jira-site in .codev/config.json or run: acli jira auth login" >&2
+    return 1
+  fi
+  printf 'https://%s' "$_site"
+}
+
+# Print the JQL project-scope prefix (`project = "KEY" AND `), or nothing when
+# CODEV_JIRA_PROJECT (`forge.jira-project`) is unset. The key is validated
+# rather than escaped: Jira project keys are `[A-Z][A-Z0-9_]+`, and anything
+# else is a misconfiguration that must not reach the query. Callers must use:
+#   SCOPE="$(jira_scope)" || exit 1
+jira_scope() {
+  [ -z "$CODEV_JIRA_PROJECT" ] && return 0
+  _key="$(printf '%s' "$CODEV_JIRA_PROJECT" | tr '[:lower:]' '[:upper:]')"
+  case "$_key" in
+    [A-Z]*) ;;
+    *) _key="" ;;
+  esac
+  if [ -z "$_key" ] || printf '%s' "$_key" | grep -q '[^A-Z0-9_]'; then
+    echo "jira: invalid forge.jira-project '$CODEV_JIRA_PROJECT' (expected a project key like ENG)" >&2
+    return 1
+  fi
+  printf 'project = "%s" AND ' "$_key"
+}
+
+# Fail unless CODEV_ISSUE_ID is a work item key (`KEY-123`). It is passed to
+# acli as an argument, so the check also keeps a leading `-` from being read as
+# a flag. Callers must use:  jira_require_issue_id || exit 1
+jira_require_issue_id() {
+  if [ -z "$CODEV_ISSUE_ID" ]; then
+    echo "CODEV_ISSUE_ID is not set" >&2
+    return 1
+  fi
+  if ! printf '%s' "$CODEV_ISSUE_ID" | grep -Eq '^[A-Za-z][A-Za-z0-9_]*-[0-9]+$'; then
+    echo "jira: '$CODEV_ISSUE_ID' is not a Jira work item key (expected KEY-123)" >&2
+    return 1
+  fi
+}
+
+# jq definitions shared by the JSON-emitting scripts. Prepend to a filter:
+#   jq "$JIRA_JQ_DEFS"' …filter… '
+#
+# adf_text flattens Atlassian Document Format (descriptions and comment bodies)
+# to plain text: inline text joined per block, blocks separated by blank lines,
+# list items prefixed with "- " or "N. ". Media and unknown leaf nodes drop out.
+# No markdown fidelity is attempted.
+#
+# person maps a Jira user to the contract's `{login}`. The email is preferred
+# because `user-identity` can only report the current user's email (acli
+# exposes nothing else), and the "assigned to me" filter compares the two.
+# Users who hide their email degrade to their display name.
+JIRA_JQ_DEFS='
+def adf_inline:
+  if .type == "text" then (.text // "")
+  elif .type == "hardBreak" then "\n"
+  elif .type == "mention" then (.attrs.text // "")
+  elif .type == "emoji" then (.attrs.text // .attrs.shortName // "")
+  elif .type == "inlineCard" or .type == "blockCard" then (.attrs.url // "")
+  elif (.content | type) == "array" then ([.content[] | adf_inline] | join(""))
+  else "" end;
+def adf_block:
+  if .type == "paragraph" or .type == "heading" or .type == "codeBlock" then
+    ([(.content // [])[] | adf_inline] | join(""))
+  elif .type == "bulletList" then
+    ([(.content // [])[] | "- " + ([(.content // [])[] | adf_block] | join("\n"))] | join("\n"))
+  elif .type == "orderedList" then
+    ([(.content // []) | to_entries[] | "\(.key + 1). " + ([(.value.content // [])[] | adf_block] | join("\n"))] | join("\n"))
+  elif .type == "mediaSingle" or .type == "mediaGroup" or .type == "media" or .type == "rule" then ""
+  elif (.content | type) == "array" then
+    ([.content[] | adf_block | select(. != "")] | join("\n\n"))
+  else adf_inline end;
+def adf_text:
+  if . == null then ""
+  elif type == "string" then .
+  elif type == "object" then ([(.content // [])[] | adf_block | select(. != "")] | join("\n\n"))
+  else "" end;
+def person:
+  if . == null then null else { login: (.emailAddress // .displayName // "") } end;
+def labels_of: [(.fields.labels // [])[] | { name: . }];
+def assignees_of: (if .fields.assignee then [.fields.assignee | person] else [] end);
+'

package/scripts/forge/jira/auth-status.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+# Forge concept: auth-status (Jira Cloud via acli)
+# forge-executable: acli
+# Input (optional): CODEV_JIRA_SITE — the site this workspace expects
+# Output: exit code (0 = authenticated); acli's status text on stdout
+#
+# `acli jira auth status` round-trips to the site (it fails when the site is
+# unreachable), so it is an authenticated call, not a local config read. acli
+# owns the credential (`acli jira auth login`, browser OAuth or API token);
+# codev never reads or passes a Jira token. When CODEV_JIRA_SITE is set, a login
+# to a different site is reported as unauthenticated, so `codev doctor` never
+# reports success against the wrong site.
+set -e
+
+STATUS="$(acli jira auth status 2>&1)" || {
+  printf '%s\n' "$STATUS" >&2
+  exit 1
+}
+
+if [ -n "$CODEV_JIRA_SITE" ]; then
+  WANT="$(printf '%s' "$CODEV_JIRA_SITE" | sed -e 's#^[a-zA-Z]*://##' -e 's#/*$##' | tr '[:upper:]' '[:lower:]')"
+  HAVE="$(printf '%s\n' "$STATUS" | sed -n 's/^[[:space:]]*Site:[[:space:]]*//p' | head -n 1 | tr '[:upper:]' '[:lower:]')"
+  if [ "$WANT" != "$HAVE" ]; then
+    echo "jira: acli is logged into '${HAVE:-no site}', but forge.jira-site is '$WANT'; run: acli jira auth switch" >&2
+    exit 1
+  fi
+fi
+
+printf '%s\n' "$STATUS"

package/scripts/forge/jira/issue-comment.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+# Forge concept: issue-comment (Jira Cloud via acli)
+# forge-executable: acli
+# Input: CODEV_ISSUE_ID, CODEV_COMMENT_BODY
+# Output: exit code only
+#
+# The body goes to acli as plain text through a temp file (no quoting or argv
+# length limits). acli accepts plain text or Atlassian Document Format there;
+# codev's markdown is not converted, so it renders as plain text.
+set -e
+. "$(dirname "$0")/_lib.sh"
+
+jira_require_issue_id || exit 1
+if [ -z "${CODEV_COMMENT_BODY+set}" ]; then
+  echo "CODEV_COMMENT_BODY is not set" >&2
+  exit 1
+fi
+
+BODY_FILE="$(mktemp)"
+trap 'rm -f "${BODY_FILE:?}"' EXIT
+printf '%s\n' "$CODEV_COMMENT_BODY" > "$BODY_FILE"
+
+acli jira workitem comment create --key "$CODEV_ISSUE_ID" --body-file "$BODY_FILE" >/dev/null

package/scripts/forge/jira/issue-list.sh

@@ -0,0 +1,32 @@
+#!/bin/sh
+# Forge concept: issue-list (Jira Cloud via acli)
+# forge-executable: acli
+# Input (optional): CODEV_JIRA_PROJECT (project key), CODEV_JIRA_SITE
+# Output: JSON [{number, title, url, labels, author, assignees}]
+#
+# Open = status category not Done (never status names, which are per-site).
+# `acli jira workitem search` only returns an allow-listed set of fields, none
+# of them dates, so `createdAt` is omitted: consumers treat it as unknown, and
+# the JQL orders items newest first. The limit stays at 100 because a search
+# takes ~5s per 100 items and forge commands time out at 30s.
+set -e
+. "$(dirname "$0")/_lib.sh"
+
+SCOPE="$(jira_scope)" || exit 1
+SITE="$(jira_site)" || exit 1
+
+RAW="$(acli jira workitem search \
+  --jql "${SCOPE}statusCategory != Done ORDER BY created DESC" \
+  --fields summary,status,labels,creator,assignee \
+  --limit 100 \
+  --json)"
+
+printf '%s' "$RAW" | jq --arg site "$SITE" "$JIRA_JQ_DEFS"'
+  [.[] | select(. != null and (.key | type) == "string") | {
+    number: .key,
+    title: (.fields.summary // ""),
+    url: "\($site)/browse/\(.key)",
+    labels: labels_of,
+    author: (.fields.creator | person),
+    assignees: assignees_of
+  }]'

package/scripts/forge/jira/issue-search.sh

@@ -0,0 +1,40 @@
+#!/bin/sh
+# Forge concept: issue-search (Jira Cloud via acli)
+# forge-executable: acli
+#
+# Like issue-list, but for the backlog-search webview: includes `body` (the
+# description, flattened from ADF) and honors a requested state, mapped to the
+# status category: open = not Done, closed = Done, all = any category (still a
+# bounded query, which Jira requires).
+#
+# Input (optional): CODEV_ISSUE_STATE — open|closed|all (default: open)
+#                   CODEV_JIRA_PROJECT, CODEV_JIRA_SITE
+# Output: JSON [{number, title, url, labels, author, assignees, body}]
+set -e
+. "$(dirname "$0")/_lib.sh"
+
+case "${CODEV_ISSUE_STATE:-open}" in
+  closed) STATE_CLAUSE='statusCategory = Done' ;;
+  all)    STATE_CLAUSE='statusCategory is not EMPTY' ;;
+  *)      STATE_CLAUSE='statusCategory != Done' ;;
+esac
+
+SCOPE="$(jira_scope)" || exit 1
+SITE="$(jira_site)" || exit 1
+
+RAW="$(acli jira workitem search \
+  --jql "${SCOPE}${STATE_CLAUSE} ORDER BY created DESC" \
+  --fields summary,status,labels,creator,assignee,description \
+  --limit 100 \
+  --json)"
+
+printf '%s' "$RAW" | jq --arg site "$SITE" "$JIRA_JQ_DEFS"'
+  [.[] | select(. != null and (.key | type) == "string") | {
+    number: .key,
+    title: (.fields.summary // ""),
+    url: "\($site)/browse/\(.key)",
+    labels: labels_of,
+    author: (.fields.creator | person),
+    assignees: assignees_of,
+    body: (.fields.description | adf_text)
+  }]'

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

@@ -0,0 +1,41 @@
+#!/bin/sh
+# Forge concept: issue-view (Jira Cloud via acli)
+# forge-executable: acli
+# Input: CODEV_ISSUE_ID (e.g. "ENG-123"); CODEV_JIRA_SITE (optional)
+# Output: JSON {title, body, state, url, author, createdAt, assignees, labels, milestone, comments[]}  (IssueViewResult)
+#
+# One `workitem view` call carries everything, comments included. Description
+# and comment bodies are Atlassian Document Format, flattened to plain text.
+# `state` is the status *name* (display only); open/closed decisions elsewhere
+# use the status category. Jira has no milestones; the first fix version stands
+# in (optional by contract). `url` is the browser page on the site, never the
+# REST `self` link (which names an infrastructure host).
+set -e
+. "$(dirname "$0")/_lib.sh"
+
+jira_require_issue_id || exit 1
+SITE="$(jira_site)" || exit 1
+
+RAW="$(acli jira workitem view "$CODEV_ISSUE_ID" \
+  --fields summary,description,status,creator,reporter,assignee,labels,created,comment,fixVersions \
+  --json)"
+
+printf '%s' "$RAW" | jq --arg site "$SITE" "$JIRA_JQ_DEFS"'
+  if (.key | type) != "string" then
+    error("issue not found: \(env.CODEV_ISSUE_ID)")
+  else {
+    title: (.fields.summary // ""),
+    body: (.fields.description | adf_text),
+    state: (.fields.status.name // ""),
+    url: "\($site)/browse/\(.key)",
+    author: ((.fields.creator // .fields.reporter) | person),
+    createdAt: .fields.created,
+    assignees: assignees_of,
+    labels: labels_of,
+    milestone: (if ((.fields.fixVersions // []) | length) > 0 then { title: .fields.fixVersions[0].name } else null end),
+    comments: [(.fields.comment.comments // [])[] | {
+      body: (.body | adf_text),
+      createdAt: .created,
+      author: ((.author | person) // { login: "" })
+    }]
+  } end'

package/scripts/forge/jira/recently-closed.sh

@@ -0,0 +1,81 @@
+#!/bin/sh
+# Forge concept: recently-closed (Jira Cloud via acli)
+# forge-executable: acli
+# Input (optional): CODEV_SINCE_DATE (ISO 8601), CODEV_JIRA_PROJECT, CODEV_JIRA_SITE
+# Output: JSON [{number, title, url, labels, createdAt, closedAt}]
+#
+# Closed = status category Done, never status names (names are per-site).
+#
+# `workitem search` cannot return dates, but consumers drop items without
+# `closedAt`, so each hit is fetched with `workitem view` (one key per call)
+# for `statuscategorychangedate`, with bounded parallelism. The window is small
+# (the overview asks for the last 24h) and capped at 25 hits.
+#
+# JQL date literals are day-or-minute precision in the user's Jira time zone,
+# so the query bound is the since date minus one day: a superset. The consumer
+# applies the exact cutoff against `closedAt`.
+set -e
+. "$(dirname "$0")/_lib.sh"
+
+SCOPE="$(jira_scope)" || exit 1
+SITE="$(jira_site)" || exit 1
+
+DATE_CLAUSE=""
+if [ -n "$CODEV_SINCE_DATE" ]; then
+  SINCE_DAY="$(jq -rn --arg s "$CODEV_SINCE_DATE" '
+    try (
+      $s | (if test("T") then . else . + "T00:00:00Z" end)
+         | sub("\\.[0-9]+"; "") | fromdateiso8601 - 86400 | strftime("%Y-%m-%d")
+    ) catch ($s[0:10])')"
+  # The fallback takes the input's first ten characters, so validate before it
+  # reaches the JQL, as _lib.sh validates keys.
+  if ! printf '%s' "$SINCE_DAY" | grep -Eq '^[0-9]{4}-[0-9]{2}-[0-9]{2}$'; then
+    echo "jira: invalid CODEV_SINCE_DATE '$CODEV_SINCE_DATE' (expected an ISO 8601 date)" >&2
+    exit 1
+  fi
+  DATE_CLAUSE=" AND statusCategoryChangedDate >= \"$SINCE_DAY\""
+fi
+
+HITS="$(acli jira workitem search \
+  --jql "${SCOPE}statusCategory = Done${DATE_CLAUSE} ORDER BY statusCategoryChangedDate DESC" \
+  --fields summary,status,labels \
+  --limit 25 \
+  --json)"
+
+KEYS="$(printf '%s' "$HITS" | jq -r '.[] | select(. != null) | .key | select(type == "string" and test("^[A-Za-z][A-Za-z0-9_]*-[0-9]+$"))')"
+if [ -z "$KEYS" ]; then
+  echo '[]'
+  exit 0
+fi
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "${WORK:?}"' EXIT
+
+# One file per key, so concurrent views never interleave on a shared stdout.
+# Each view writes a .part file that is renamed only on success: a failed view
+# leaves no .json, its item is emitted without dates (the consumer drops it),
+# and the warning makes that visible.
+printf '%s\n' "$KEYS" | xargs -P 6 -I {} sh -c '
+  if acli jira workitem view "$1" --fields created,statuscategorychangedate,resolutiondate --json > "$2/$1.part" 2>/dev/null; then
+    mv "$2/$1.part" "$2/$1.json"
+  else
+    echo "jira: could not fetch dates for $1" >&2
+  fi
+' _ {} "$WORK"
+
+DATES="$WORK/dates.map"
+if ls "$WORK"/*.json >/dev/null 2>&1; then
+  cat "$WORK"/*.json | jq -s 'map(select(.key != null) | { key: .key, value: .fields }) | from_entries' > "$DATES"
+else
+  echo '{}' > "$DATES"
+fi
+
+printf '%s' "$HITS" | jq --arg site "$SITE" --slurpfile dates "$DATES" "$JIRA_JQ_DEFS"'
+  [.[] | select(. != null and (.key | type) == "string") | ($dates[0][.key] // {}) as $d | {
+    number: .key,
+    title: (.fields.summary // ""),
+    url: "\($site)/browse/\(.key)",
+    labels: labels_of,
+    createdAt: $d.created,
+    closedAt: ($d.statuscategorychangedate // $d.resolutiondate)
+  }]'

package/scripts/forge/jira/user-identity.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+# Forge concept: user-identity (Jira Cloud via acli)
+# forge-executable: acli
+# Output: plain text — the logged-in account's email
+#
+# acli reports the current account only as `Email:` in `auth status` (no
+# display name or account id), so the email is the identity. The issue scripts
+# map assignees to their email for the same reason, which keeps the "assigned
+# to me" filter matching.
+set -e
+
+STATUS="$(acli jira auth status)"
+EMAIL="$(printf '%s\n' "$STATUS" | sed -n 's/^[[:space:]]*Email:[[:space:]]*//p' | head -n 1)"
+if [ -z "$EMAIL" ]; then
+  echo "jira: acli auth status reported no account email" >&2
+  exit 1
+fi
+printf '%s\n' "$EMAIL"

package/skeleton/.claude/skills/afx/SKILL.md

@@ -179,13 +179,63 @@ afx tower disconnect            # Disconnect from Codev Cloud
 
 There is NO `afx tower restart` — use `afx tower stop && afx tower start`.
 
+## afx ide
+
+Manages the Codev IDE server (VS Code server-web) that Tower forwards at `/ide/`. Tower spawns
+and owns the process; these commands drive it. Open a workspace at
+`http://localhost:4100/ide/?folder=<abs path>`.
+
+```bash
+afx ide install                 # npm i -g @cluesmith/codev-ide, then report the installed version
+afx ide start                   # Find codev-ide-server, ask Tower to spawn it (port 8200)
+afx ide start --server-path <bin>   # Use this binary instead of discovery
+afx ide start -p <port>         # Run the server on another port
+afx ide stop                    # Stop the server
+afx ide status                  # Port, PID, server path/version, extensions dir, sidebar version
+```
+
+**Discovery** (when `--server-path` is absent): `codev-ide-server` on `PATH`, then
+`@cluesmith/codev-ide` next to the running codev install, then under `npm root -g`. Nothing
+found exits 1 before Tower is contacted, naming `afx ide install` and `--server-path`.
+
+**On every start** Tower checks `codev-ide-server --version` against a minimum (an older server
+is refused with the installed version, the floor, and the upgrade command), installs the
+sidebar vsix that ships inside `@cluesmith/codev` into `~/.agent-farm/ide-extensions` (skipped
+when that version is already installed; other extensions in the directory are left alone), and
+spawns the server with `--extensions-dir` pointing there. The first start can take a minute or more.
+
+The server loads extensions only from `~/.agent-farm/ide-extensions`, so anything installed into
+its default extensions directory is no longer loaded. Install additional extensions there:
+`codev-ide-server --install-extension <id-or-vsix> --extensions-dir ~/.agent-farm/ide-extensions`.
+
+A server that is already running is never killed by `start`. If it predates the current server
+or sidebar, `start` warns: restart it with `afx ide stop && afx ide start`.
+
+There is NO `afx ide restart` and NO `afx ide upgrade`. To upgrade, run `afx ide install`, then
+`afx ide stop && afx ide start`.
+
 ## afx workspace
 
 ```bash
 afx workspace start             # Start workspace for current project
 afx workspace stop              # Stop workspace processes
+afx workspace add-architect --name <name>   # Add a named sibling architect terminal
+afx workspace remove-architect <name>       # Remove a sibling architect (cannot remove main)
+afx workspace recover           # Revive builders whose shellper died (e.g. after reboot)
 ```
 
+**Recreating a dead architect** (its process died while Tower kept the registration):
+re-add it under the SAME name, then re-init its identity:
+
+```bash
+afx workspace add-architect --name <name>
+afx send architect:<name> "/arch-init <name>"
+```
+
+Builder-to-architect affinity survives the death (builders keep their Owner), so a
+same-name re-add restores routing with no worktree impact and no builder disruption.
+`afx workspace recover` revives builders only, not architects.
+
 `afx dash` is a deprecated alias — use `afx workspace` instead.
 
 ## afx cron
@@ -220,5 +270,6 @@ afx open <file>                 # Open file in annotation viewer (NOT system ope
 afx shell                       # Spawn utility shell
 afx attach                      # Attach to running builder terminal
 afx rename <name>               # Rename current shell session
+afx decisions init              # Create the decisions file; turns on the Decisions tab
 afx architect                   # Start architect session in current terminal
 ```

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

@@ -46,12 +46,56 @@ name in a multi-architect workspace).
      (`codev/state/*.md`); never commit them. Builder `*_thread.md` files
      are the opposite: versioned, shipping with each builder PR.
 
-3. **Confirm identity + orient, then follow the state file.** In one tight
-   block, report: who you now are (name + one-line role from the banner, if
-   present), the file you read, and the current-state / open-loops summary
-   from the most recent dated section (or the file's leading content if it
-   has no dated sections). Then carry out whatever the state file says to do
-   on resume. Do not invent a new agenda — resume the one the state file
+3. **Confirm identity + orient.** In one tight block, report: who you now are
+   (name + one-line role from the banner, if present), the file you read, and
+   the current-state / open-loops summary from the most recent dated section
+   (or the file's leading content if it has no dated sections). If the banner
+   carries a `NEXT TASK` line, report both halves of it, as
+   `Next task from the owner at save time: <verbatim>  → resolved: <gloss>`
+   (omit `→ resolved: …` when the line carries no `[resolved at save: …]` gloss).
+
+4. **Start on the next task, if the banner carries one.** It is the **first
+   action of the resumed session**, ahead of the general resume agenda — the
+   owner wrote it at save time precisely so it would not have to be typed
+   again once you came back. Begin it without waiting for a further prompt.
+   - It carries the owner's authority the way any owner message does, **with
+     the standard limits unchanged**. A next task never by itself approves a
+     porch gate, merges a PR, cuts a release, restarts Tower, or performs any
+     other act that needs a per-occasion word. If the next task *is* such an
+     act, prepare it and ask for the word live: a saved instruction is an
+     instruction, not a pre-spent approval.
+   - **The gloss carries the word — for the items it names, and only them.**
+     Items named in a `[resolved at save: …]` gloss are approved for the act
+     the owner's words name: "merge them all [resolved at save: PRs #1710,
+     #1712]" means merge #1710 and #1712 without asking again. The owner gave
+     the word at save time, and the saving session pinned it to those items.
+     This narrows the rule above; it does not remove it — and a line with no
+     gloss pre-approves nothing:
+     - The act must be the one the owner's words say. **A gloss never widens
+       the verb** — "merge" does not also approve a release.
+     - **Anything not in the gloss still needs the word live.** A PR that
+       appeared after the save, an item the gloss did not name, a gate the
+       words did not mention → prepare and ask, exactly as above.
+     - Porch gates are still relayed to the builder, never run by you: the
+       gloss lets you *relay* the approval without re-asking; it does not
+       change who runs `porch approve`.
+     - Ordinary verification still applies: an approved merge still waits for
+       green CI, and a gloss item you find already merged, closed, or changed
+       is reported, not forced.
+     - **A line marked `[carried over — …]` is orientation only.** Its gloss
+       was written by an earlier cycle and carries no word: ask for it before
+       any gated act.
+   - **This does not narrow the gate rule.** The human decision was explicit
+     at save time, and the gloss is its record. What the rule forbids —
+     inferring approval from a gate notification, from silence, or from an
+     agent's own judgment — stays forbidden; a gloss is none of those.
+   - **Once you have started, delete the `NEXT TASK` line from the banner**
+     and record the pickup as a log entry (`picked up next task: <verbatim>
+     → resolved: <gloss>`, omitting `→ resolved: …` when there was no gloss).
+     A second re-init, or the next `/arch-save`, must not re-run it.
+
+5. **Then follow the state file.** Carry out whatever it says to do on
+   resume. Do not invent a new agenda — resume the one the state file
    describes.
 
 ## Saving your state (and knowing when to `/clear`)
@@ -118,9 +162,12 @@ Do not repeat it, and do not prompt for it at any other time.
 **`/arch-save` packages this whole loop**, and is the preferred path when the
 owner directs a refresh: it stops your monitors, writes the pruned state file,
 clears, and schedules `/arch-init` to bring you back — in that order, which is
-the part that matters. The save discipline above is what it performs at its
-step 3, so this section remains the source of truth for *how to write the
-file*; `/arch-save` is the source of truth for *the sequence*. The manual path
+the part that matters. It also accepts a **next task** as free text
+(`/arch-save file and spawn that issue`), which it writes into the banner as a
+`NEXT TASK` line for step 4 above to pick up. The save discipline above is
+what it performs at its step 3, so this section remains the source of truth
+for *how to write the file*; `/arch-save` is the source of truth for *the
+sequence*. The manual path
 (save → human clears → `/arch-init`) stays valid and is the fallback when
 Tower is unavailable.