forgedock 1.2.0 → 1.4.0

package/commands/work-on/investigate.md

@@ -263,8 +263,8 @@ gh api repos/{GH_REPO}/issues/{NUMBER}/comments --jq '.[] | {id: .id, body: .bod
 ```
 
 **Resume logic**:
-- If `<!-- FORGE:INVESTIGATOR -->` comment exists AND `<!-- INVESTIGATION:COMPLETE -->` is present in the SAME comment → investigation already complete, EXIT (return existing verdict to caller)
-- If `<!-- FORGE:INVESTIGATOR -->` comment exists BUT `<!-- INVESTIGATION:COMPLETE -->` is ABSENT → investigation was interrupted, delete the partial comment and restart:
+- If `<!-- FORGE:INVESTIGATOR -->` comment exists AND (`<!-- INVESTIGATION:COMPLETE -->` OR `<!-- INVESTIGATION:INVALID -->`) is present in the SAME comment → investigation already complete, EXIT (return existing verdict to caller). `INVESTIGATION:INVALID` is the terminal sentinel Phase 1C emits for an INVALID verdict (see Phase 1C below) — it is just as much a completion marker as `INVESTIGATION:COMPLETE`, not an "interrupted" state.
+- If `<!-- FORGE:INVESTIGATOR -->` comment exists BUT NEITHER `<!-- INVESTIGATION:COMPLETE -->` NOR `<!-- INVESTIGATION:INVALID -->` is present → investigation was interrupted, delete the partial comment and restart:
   ```bash
   gh api repos/{GH_REPO}/issues/comments/{COMMENT_ID} -X DELETE
   ```
@@ -355,10 +355,25 @@ bash {REPO_PATH}/scripts/code-index.sh query --domain {DOMAIN_LABEL} --repo-path
 
 ## Phase 1C: Post Investigation Comment
 
-The comment MUST include `<!-- INVESTIGATION:COMPLETE -->` at the very end, AFTER all required sections are present. This marker signals the investigation finished successfully.
+The comment MUST include a terminal sentinel at the very end, AFTER all required sections are present. **The sentinel is conditional on the resolved Verdict — it is NOT always `<!-- INVESTIGATION:COMPLETE -->`:**
+
+- **Verdict is INVALID** → close with `<!-- INVESTIGATION:INVALID -->`. This is a distinct, already-wired-up terminal marker: `bin/engine/phases.mjs`'s `detectOutcome` for the `investigate` phase checks for it explicitly (ahead of `INVESTIGATION:COMPLETE`) and routes to `terminalReason: "invalid"`; `bin/hooks/interactive-engine.mjs`'s `PHASE_MARKERS` table also already treats it as terminal. Emitting `INVESTIGATION:COMPLETE` for an INVALID verdict is what previously caused every completed investigation to read as `{verdict: "CONFIRMED"}` regardless of actual outcome — do NOT regress this (forge#2350).
+- **Verdict is CONFIRMED or PARTIAL** → close with `<!-- INVESTIGATION:COMPLETE -->` as before (PARTIAL still routes to `ready-to-build` in Phase 1D — only INVALID gets the distinct terminal sentinel).
+
+Compute the sentinel once, before building the comment body:
+
+```bash
+if [ "{VERDICT}" = "INVALID" ]; then
+  INVESTIGATION_SENTINEL="<!-- INVESTIGATION:INVALID -->"
+else
+  INVESTIGATION_SENTINEL="<!-- INVESTIGATION:COMPLETE -->"
+fi
+```
 
 **CODEC PATH (forge#1727)**: Construct the annotation body via the protocol codec — do NOT hand-roll the `<!-- FORGE:INVESTIGATOR -->` header. Use `forge-annotation.sh write INVESTIGATOR --field ...` or `node packages/protocol/src/cli.js emit INVESTIGATOR --field ...` to produce the opening tag and completion sentinel. Fill in the Markdown body sections below. The full pattern:
 
+**Caveat (forge#2368)**: `packages/protocol/src/types.js`'s `INVESTIGATOR.completionSentinel` is a single fixed value (`'INVESTIGATION:COMPLETE'`) and `packages/protocol/src/emit.js` appends it unconditionally — the codec does NOT currently support the verdict-conditional sentinel selection described above, and cannot emit `INVESTIGATION:INVALID`. Using the CODEC PATH for an INVALID-verdict investigation would silently regress the forge#2350 fix (every investigation would again read as `{verdict: "CONFIRMED"}`). Until the codec is extended to support a verdict-conditional sentinel, the hand-rolled block above/below (using the `${INVESTIGATION_SENTINEL}` variable computed above) is the authoritative path for Phase 1C — do not use the CODEC PATH for this annotation.
+
 ```bash
 # Build the annotation body via codec (escaping and sentinel handled by codec)
 ANNOTATION_BODY=$(node packages/protocol/src/cli.js emit INVESTIGATOR \
@@ -368,6 +383,7 @@ ANNOTATION_BODY=$(node packages/protocol/src/cli.js emit INVESTIGATOR \
   --field "Task Type={TASK_TYPE}" \
   --field "Decomposition Assessment={YES|NO} — {reason}")
 # ANNOTATION_BODY now has opening tag + required fields + INVESTIGATION:COMPLETE sentinel.
+# NOTE: the codec's sentinel is fixed — do not use this path when Verdict=INVALID (see caveat above).
 # Append the Markdown body sections to it before posting.
 ```
 
@@ -450,9 +466,11 @@ ACCEPTANCE_CHECK: id=ac-4 type=command target="grep -qE '(>= ?2|2\+)' commands/o
 
 **Skipping**: if the issue has no verifiable acceptance criteria and none can be derived from the recommendation, emit a single sentinel: `ACCEPTANCE_CHECK: id=ac-skip type=skipped target="none" matcher="none" description=No machine-checkable criteria available — human review required`
 ${ANNOTATION_LINK_FOOTER}
-<!-- INVESTIGATION:COMPLETE -->"
+${INVESTIGATION_SENTINEL}"
 ```
 
+**Do not hardcode `<!-- INVESTIGATION:COMPLETE -->` as the closing line.** The closing line MUST be the `${INVESTIGATION_SENTINEL}` variable computed above — it resolves to `<!-- INVESTIGATION:INVALID -->` for an INVALID verdict and `<!-- INVESTIGATION:COMPLETE -->` otherwise. `INVESTIGATION:COMPLETE` and `INVESTIGATION:INVALID` are mutually exclusive within a single posted comment — never emit both.
+
 ---
 
 ## Phase 1C.5: Create Knowledge Gist

package/commands/work-on/remediate.md

@@ -20,6 +20,8 @@ argument-hint: "[PR number] [--issue N] [--repo GH_REPO] [--gh-flag GH_FLAG] [--
 
 **Scope note**: This mode owns exactly one gap — re-driving a `needs-human` PR's own remediation. It does NOT implement the `needs-human` sub-label taxonomy (#1815's scope) and it does NOT edit `review-pr.md`'s Phase 8 guard (forge#1810) — that guard's existing safe-default (`workflow:awaiting-merge` on any clean re-review of a previously-escalated PR) is reused as-is; this file only adds a bar-check *after* that guard has already fired.
 
+**Engine coverage** (forge#2379): this subcommand's `command` name (`work-on/remediate`) and completion marker (`FORGE:REMEDIATION:COMPLETE`, including the `**Re-gate outcome**` field Phase M8 posts below) are now registered in the headless engine's phase table — `RESERVED_TYPES.REMEDIATION` in `packages/protocol/src/types.js`, `remediate` in `packages/protocol/src/phases.js`'s `PHASE_IDS`/`PHASE_MARKERS`, and a matching `remediate` entry in `bin/engine/phases.mjs`'s `PHASES` array (`entryCondition`: review committed + `terminalReason: "needs-human"`; `detectOutcome` maps each re-gate outcome to the right terminal reason). **Known limitation, documented in that engine entry's own comment**: a single continuous `runIssue()` walk cannot reach this phase today — `review`'s `"blocked"` outcome and the needs-human divergence guard both terminate the run before `remediate`'s `entryCondition` is ever evaluated. This subcommand therefore continues to run exactly as documented above — as its own separate top-level entry point — until a follow-up issue live-wires the engine to reconstruct state from GitHub for a dedicated remediation run.
+
 ---
 
 ## Inputs

package/commands/work-on/review.md

@@ -47,10 +47,49 @@ gh pr list {GH_FLAG} --head {BRANCH} --json number,state,url 2>/dev/null
 ```
 
 **Resume check**:
-- If PR already exists AND is OPEN → skip to Phase R3 (invoke /review-pr)
+- If PR already exists AND is OPEN → run the **HEAD-unchanged re-review guard** below before proceeding to Phase R3
 - If PR already exists AND is MERGED → return `REVIEW_RESULT: status: ALREADY_MERGED`
 - If no `<!-- FORGE:BUILDER -->` comment exists → EXIT with `REVIEW_RESULT: status: BLOCKED`, blocker: "FORGE:BUILDER comment not found — implement phase may not have completed"
 
+**HEAD-unchanged re-review guard** (MANDATORY when a PR already exists and is OPEN) <!-- Added: forge#2243 --> — a PR whose most recent review verdict was CHANGES REQUESTED must not be resubmitted for a full domain-agent review fan-out if nothing has changed since that verdict. `/review-pr` records the exact commit it reviewed in its verdict comment (`CHANGES REQUESTED: commit {sha} — ...`, see `commands/review-pr.md` Phase 8/9); compare that recorded sha against the PR's current `headRefOid`:
+
+```bash
+# NOTE: the CHANGES REQUESTED verdict is posted via `gh pr review --comment` (see
+# commands/review-pr.md Phase 7B) — that creates a PullRequestReview, which surfaces under
+# the `reviews` field, NOT `comments` (issue/PR comments are a separate GraphQL object).
+# Query both --json reviews and --json comments (same combined-read pattern already used in
+# work-on.md's REVIEW_BODIES/REVIEW_PRESENT checks) so this guard works regardless of which
+# GitHub object type carries the verdict text.
+LAST_VERDICT=$(gh pr view {PR_NUMBER} {GH_FLAG} --json reviews,comments \
+  --jq '([.reviews[] | {body, created_at: (.submittedAt // "")}] + [.comments[] | {body, created_at: (.createdAt // "")}]) | map(select(.body | test("CHANGES REQUESTED: commit "))) | sort_by(.created_at) | last | .body // ""' 2>/dev/null)
+LAST_VERDICT_SHA=$(echo "$LAST_VERDICT" | grep -oE 'CHANGES REQUESTED: commit [0-9a-f]+' | grep -oE '[0-9a-f]+$' | head -1)
+CURRENT_SHA_SHORT=$(gh pr view {PR_NUMBER} {GH_FLAG} --json headRefOid --jq '.headRefOid' 2>/dev/null | cut -c1-7)
+
+if [ -n "$LAST_VERDICT_SHA" ] && [ "$LAST_VERDICT_SHA" = "$CURRENT_SHA_SHORT" ]; then
+  echo "HEAD unchanged since last CHANGES REQUESTED verdict ($LAST_VERDICT_SHA) — skipping re-review."
+  # No DRY_RUN/governor guard here — consistent with every other gh issue comment/edit call
+  # already in this file (e.g. the Push Failed / Push Blocked sections below), none of which
+  # are gated either. This is a report-and-stop action (blocks re-review, does not merge or
+  # delete anything), same risk class as those pre-existing calls.
+  REREVIEW_SKIP_BODY=$(cat <<SKIP_EOF
+## Re-Review Skipped — HEAD Unchanged
+
+PR #{PR_NUMBER}'s HEAD (${CURRENT_SHA_SHORT}) has not changed since the last CHANGES REQUESTED verdict. Re-running /review-pr would re-review byte-identical code and reproduce the same verdict — this is a pure waste of a full domain-agent fan-out.
+
+The PR is already needs-human (or will be shortly, if this is the first time this guard has fired for it). Progress here now depends on remediation (fix the findings, push a new commit, re-review) rather than another raw review submission. If running under /orchestrate, item 6.4 in phase-4-execution.md auto-dispatches remediation for any needs-human-gated issue, including this one (see forge#2243) — no manual action should be needed. If running standalone, invoke /work-on {PR_NUMBER} --remediate --issue {NUMBER} directly.
+
+<!-- FORGE:REREVIEW_SKIPPED -->
+SKIP_EOF
+)
+  gh issue comment {NUMBER} {GH_FLAG} --body "$REREVIEW_SKIP_BODY" # <!-- allowlist:check-command-side-effects -->
+  gh issue edit {NUMBER} {GH_FLAG} --add-label needs-human 2>/dev/null || true # <!-- allowlist:check-command-side-effects -->
+  # Return REVIEW_RESULT: status: BLOCKED — do not invoke /review-pr again on unchanged HEAD
+  exit 1
+fi
+```
+
+If `LAST_VERDICT_SHA` is empty (no prior CHANGES REQUESTED verdict found) or differs from the current HEAD (a new commit was pushed since the last verdict — e.g. by remediation), proceed normally to Phase R3.
+
 ---
 
 ## Phase R1: Pre-Push Ancestry Guard

package/commands/work-on.md

@@ -247,6 +247,8 @@ Extract project prefix and issue number. If `next`/`pick`: list open issues sort
 
 ### 0A.1: Remediation Mode Detection (`--remediate`) <!-- Added: forge#1813 -->
 
+**Engine coverage** (forge#2379): `remediate` is now a registered phase in the headless engine's phase table (`packages/protocol/src/phases.js`, `bin/engine/phases.mjs`) — see `commands/work-on/remediate.md`'s own "Engine coverage" note for the current, documented limitation (a single continuous headless `runIssue()` walk cannot yet reach it; this prose-layer standalone-invocation path below remains the only way `remediate` actually runs today).
+
 **Check first, before any other Phase 0 routing** — if `$ARGUMENTS` contains `--remediate`, this is NOT a normal issue-pipeline invocation. The first positional argument is a **PR number**, not an issue number:
 
 ```bash
@@ -524,9 +526,9 @@ a hard dependency.
 
 ## Phase 1: Investigation
 
-**Skip if**: `<!-- FORGE:INVESTIGATOR -->` exists with `<!-- INVESTIGATION:COMPLETE -->` in the SAME comment.
+**Skip if**: `<!-- FORGE:INVESTIGATOR -->` exists with `<!-- INVESTIGATION:COMPLETE -->` OR `<!-- INVESTIGATION:INVALID -->` in the SAME comment. `INVESTIGATION:INVALID` is the terminal sentinel Phase 1C emits for an INVALID verdict (see 1C below) — it signals investigation completion just as much as `INVESTIGATION:COMPLETE` does, not an interrupted state.
 
-**Partial investigation**: If investigator comment exists BUT `<!-- INVESTIGATION:COMPLETE -->` is ABSENT → investigation was interrupted. Delete the partial comment and restart:
+**Partial investigation**: If investigator comment exists BUT NEITHER `<!-- INVESTIGATION:COMPLETE -->` NOR `<!-- INVESTIGATION:INVALID -->` is present → investigation was interrupted. Delete the partial comment and restart:
 ```bash
 COMMENT_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .id')
@@ -686,9 +688,18 @@ Use `forge.yaml → review.tech_stack` and the issue domain labels to identify e
 
 ### 1C: Post investigation comment
 
-The comment MUST include `<!-- INVESTIGATION:COMPLETE -->` at the very end.
+The comment MUST include a terminal sentinel at the very end. **The sentinel is conditional on the resolved Verdict — it is NOT always `<!-- INVESTIGATION:COMPLETE -->`:**
+
+- **Verdict is INVALID** → close with `<!-- INVESTIGATION:INVALID -->`. This is a distinct, already-wired-up terminal marker: `bin/engine/phases.mjs`'s `detectOutcome` for the `investigate` phase checks for it explicitly (ahead of `INVESTIGATION:COMPLETE`) and routes to `terminalReason: "invalid"`; `bin/hooks/interactive-engine.mjs`'s `PHASE_MARKERS` table also already treats it as terminal. Emitting `INVESTIGATION:COMPLETE` for an INVALID verdict is what previously caused every completed investigation to read as `{verdict: "CONFIRMED"}` regardless of actual outcome — do NOT regress this (forge#2350).
+- **Verdict is CONFIRMED or PARTIAL** → close with `<!-- INVESTIGATION:COMPLETE -->` as before (PARTIAL still routes to `ready-to-build` below — only INVALID gets the distinct terminal sentinel).
 
 ```bash
+if [ "{VERDICT}" = "INVALID" ]; then
+  INVESTIGATION_SENTINEL="<!-- INVESTIGATION:INVALID -->"
+else
+  INVESTIGATION_SENTINEL="<!-- INVESTIGATION:COMPLETE -->"
+fi
+
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
 ## Investigation Report
 
@@ -728,9 +739,11 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
 **{YES|NO}** — {reason}
 {if YES: proposed sub-issues with titles and dependencies}
 
-<!-- INVESTIGATION:COMPLETE -->"
+${INVESTIGATION_SENTINEL}"
 ```
 
+**Do not hardcode `<!-- INVESTIGATION:COMPLETE -->` as the closing line.** The closing line MUST be the `${INVESTIGATION_SENTINEL}` variable computed above — it resolves to `<!-- INVESTIGATION:INVALID -->` for an INVALID verdict and `<!-- INVESTIGATION:COMPLETE -->` otherwise. `INVESTIGATION:COMPLETE` and `INVESTIGATION:INVALID` are mutually exclusive within a single posted comment — never emit both.
+
 ### 1D: Correction capture (MANDATORY — run before label update)
 
 Before routing, scan all non-agent comments for correction signals from the repository owner. Correction signals are owner comments that contain phrases like "no, use", "actually use", "use X instead", "not X, use Y", or "wrong branch". If found, write the correction to `forge.yaml → learned:` and emit a `FORGE:LEARNED` annotation.
@@ -890,6 +903,8 @@ gh issue close {NUMBER} {GH_FLAG} --comment "Closing as invalid: {reason from in
 
 ## Phase 2: Decomposition (Conditional)
 
+**Engine coverage** (forge#2379): this phase's dispatch target (`work-on/decompose`) is now a real phase in the headless engine's phase table — `decompose` in `packages/protocol/src/phases.js`/`bin/engine/phases.mjs`, live-wired so `investigate`'s `DECOMPOSE:YES` outcome hands off to it instead of terminating the run in place. This prose Phase 2 remains the interactive/prose dispatch path; the engine path is the headless equivalent, both invoking the same `commands/work-on/decompose.md` subcommand.
+
 **Skip if**: Already decomposed, is a sub-issue, or investigation says decompose: NO.
 
 **Trigger if**: Investigation assessment says YES — 2+ signals match (at least 1 Strong): multiple task types, 3+ service groups, phased requirements, 6+ files across directories.

package/docs/AIDER.md

@@ -0,0 +1,264 @@
+# Aider Support
+
+ForgeDock has an additive Aider-native install path. The goal is to give Aider
+users access to the ForgeDock pipeline without regressing the existing Claude
+Code or Codex setups.
+
+## Architecture
+
+Shared source:
+- `commands/**/*.md` remains the workflow spec for all runtimes
+
+Claude Code wrapper:
+- `install.sh` (or `npx forgedock`) symlinks command files into `~/.claude/commands/`
+
+Codex wrapper:
+- `install-codex.sh` generates namespaced skills in `~/.codex/skills/`
+
+**Aider wrapper** (this document):
+- `install-aider.sh` writes `~/.aider-forge.md` — a conventions file Aider
+  loads at session start via `--read`
+- The conventions file provides runtime mapping rules and entry point references
+- Aider reads ForgeDock command specs on demand with `/read $FORGE_HOME/commands/x.md`
+
+This is intentionally a conventions-file architecture, not a duplicate command
+tree. The shared `commands/` directory remains the single source of truth.
+
+## Install
+
+### Option A — standalone bash installer
+
+```bash
+cd /path/to/forgedock
+./install-aider.sh
+```
+
+This writes `~/.aider-forge.md` with ForgeDock conventions and runtime mapping
+rules.
+
+### Option B — via npx forgedock
+
+If you already use `npx forgedock` for Claude Code:
+
+```bash
+npx forgedock
+```
+
+When `aider` is detected on your PATH, `npx forgedock` writes `~/.aider-forge.md`
+as an additional install step. No existing Claude Code files are affected.
+
+## Usage
+
+### Per-session (command line)
+
+```bash
+aider --read ~/.aider-forge.md
+```
+
+### Always-on (`.aider.conf.yml`)
+
+Add to your project's `.aider.conf.yml`:
+
+```yaml
+read:
+  - ~/.aider-forge.md
+```
+
+Or to `~/.aider.conf.yml` for global application across all projects.
+
+### Loading a pipeline command
+
+Once Aider has the conventions file loaded, load a command spec on demand:
+
+```
+/read /path/to/forgedock/commands/work-on.md
+```
+
+Then follow the command spec step by step, using `/run` for all shell
+operations.
+
+## Tool Translation Rules
+
+ForgeDock command specs reference Claude Code-specific tools. Translate them
+to Aider equivalents:
+
+| Claude Code | Aider equivalent | Notes |
+|-------------|-----------------|-------|
+| `Skill("work-on", args="123")` | `/read $FORGE_HOME/commands/work-on.md` | Load the spec and execute it |
+| `Skill("review-pr", args="456")` | `/read $FORGE_HOME/commands/review-pr.md` | Load the spec and execute it |
+| `Skill("quality-gate")` | `/read $FORGE_HOME/commands/quality-gate.md` | Load the spec and execute it |
+| `Bash("git status")` | `/run git status` | Direct shell execution |
+| `Read("path/to/file")` | Read the file directly | Aider's native file read |
+| `Grep(pattern, path)` | `/run rg 'pattern' path` | Use `rg` (ripgrep) |
+| `Glob("**/*.md")` | `/run find . -name "*.md"` | Shell find |
+| `WebFetch(url)` | `/run curl -s url` | curl or wget |
+| `Agent(...)` / `Task(...)` | Continue the sub-task yourself | No sub-agent support; inline it |
+| `EnterWorktree(path)` | `/run cd path` then use `/run` | Work in worktree directory |
+
+### Nested Skill references
+
+When a command spec calls `Skill("x")` or references another command:
+
+```
+# Load the referenced command spec manually:
+/read $FORGE_HOME/commands/x.md
+```
+
+Map command names to file paths:
+- `Skill("work-on")` → `commands/work-on.md`
+- `Skill("review-pr")` → `commands/review-pr.md`
+- `Skill("quality-gate")` → `commands/quality-gate.md`
+- `Skill("orchestrate")` → `commands/orchestrate.md`
+
+## GitHub Operations
+
+All FORGE annotations are written to GitHub issue/PR comments via the `gh`
+CLI. Use `/run gh ...` for every GitHub operation.
+
+### Label management
+
+```bash
+/run gh issue edit 123 -R OWNER/REPO --add-label "workflow:investigating"
+/run gh issue edit 123 -R OWNER/REPO --remove-label "workflow:investigating"
+```
+
+### Reading existing annotations
+
+```bash
+/run gh api repos/OWNER/REPO/issues/123/comments \
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
+```
+
+### Writing a FORGE annotation comment
+
+```bash
+/run gh issue comment 123 -R OWNER/REPO --body "<!-- FORGE:INVESTIGATOR -->
+## Investigation Report
+
+**Verdict**: CONFIRMED
+...
+<!-- INVESTIGATION:COMPLETE -->"
+```
+
+For multi-line comment bodies, write the content to a temp file first:
+
+```bash
+cat > /tmp/comment.md << 'EOF'
+<!-- FORGE:INVESTIGATOR -->
+## Investigation Report
+...
+<!-- INVESTIGATION:COMPLETE -->
+EOF
+/run gh issue comment 123 -R OWNER/REPO --body "$(cat /tmp/comment.md)"
+```
+
+### Creating a PR
+
+```bash
+/run gh pr create -R OWNER/REPO \
+  --base staging \
+  --head feat/my-branch-123 \
+  --title "feat: description (#123)" \
+  --body "$(cat /tmp/pr_body.md)"
+```
+
+## Worktrees
+
+ForgeDock uses git worktrees to isolate branch work. Create one with:
+
+```bash
+/run git fetch origin
+/run git worktree add .claude/worktrees/feat-my-feature-123 \
+  -b feat/my-feature-123 origin/staging
+```
+
+Work inside the worktree for all file edits and commits. Aider's `/run`
+commands execute in the worktree directory if you `cd` to it:
+
+```bash
+/run cd /path/to/repo/.claude/worktrees/feat-my-feature-123
+```
+
+Or pass the path explicitly in each command:
+
+```bash
+/run git -C /path/to/repo/.claude/worktrees/feat-my-feature-123 status
+```
+
+## FORGE Annotation Protocol
+
+Every pipeline stage writes a structured annotation to GitHub. Key rules:
+
+1. **Idempotency**: Check for existing annotations BEFORE starting a phase.
+   Do not re-run a completed phase.
+2. **Compaction resilience**: Write annotations AFTER completing each
+   significant step. GitHub is the persistent state layer.
+3. **Restart partial annotations**: If an annotation exists without its
+   `:COMPLETE` sentinel, delete it and restart the phase.
+4. **Respect label state**: Labels track workflow state. Read and set them
+   at each phase boundary.
+
+### Label state machine
+
+```
+workflow:investigating
+    → workflow:ready-to-build   (investigation complete)
+    → workflow:building         (build started)
+    → workflow:in-review        (PR created)
+    → workflow:merged           (PR merged) [TERMINAL]
+
+workflow:invalid                [TERMINAL]
+workflow:decomposed             [TERMINAL]
+needs-human                     [TERMINAL]
+```
+
+Stop the pipeline when any terminal label is set.
+
+## Feasibility Analysis
+
+Aider is the highest-feasibility non-Claude agent for ForgeDock because:
+
+| Capability | Requirement | Aider support |
+|-----------|-------------|---------------|
+| Load instruction files | `--read` flag / `.aider.conf.yml` | Native |
+| Execute shell commands | `gh`, `git`, `rg` via shell | `/run` command |
+| Read/write files | File editing | Native |
+| GitHub API | `gh` CLI | Via `/run gh ...` |
+| Multi-step workflows | Follow sequential instructions | Supported |
+| Compaction resilience | Re-read GitHub state at phase start | Supported (via `/run gh ...`) |
+
+**Limitation**: Aider has no native sub-agent/parallel task model (`Agent(...)`,
+`Task(...)`). Phase 3 parallel context gathering (`FORGE:CONTEXT`) and
+multi-agent review (`review-pr-agents.md`) must be executed sequentially.
+For the orchestrate command (`/orchestrate`), run one issue at a time or
+use separate Aider sessions per issue.
+
+## Trust and Configuration
+
+Aider does not have a project trust model. Once `~/.aider-forge.md` is loaded,
+all operations in that session have access to shell execution via `/run`.
+
+**Security note**: ForgeDock's shell operations are limited to `gh`, `git`,
+`rg`, `find`, and standard POSIX tools. The conventions file does not execute
+arbitrary code at load time — it only provides instruction text.
+
+## Usage Notes
+
+- Use `--read ~/.aider-forge.md` on every session, or add it to
+  `.aider.conf.yml` for automatic loading.
+- Load command specs on demand with `/read $FORGE_HOME/commands/x.md` —
+  do not load all commands at once.
+- Keep `CLAUDE.md` and `AGENTS.md` aligned with ForgeDock conventions;
+  Aider and Claude Code can differ at the wrapper layer but not on FORGE
+  workflow invariants (annotation format, label state machine, branch
+  naming, worktree conventions).
+- For pipeline stages that post FORGE annotations, always write the body
+  to a temp file before passing to `gh issue comment` to avoid shell
+  quoting issues with multi-line content.
+
+## Reference
+
+- [FORGE Protocol spec](FORGE-PROTOCOL.md) — annotation format, label state machine, conformance tests
+- [Codex adapter](CODEX.md) — parallel reference for OpenAI Codex CLI
+- [Pipeline commands](../commands/) — shared workflow specs (authoritative for all runtimes)
+- [`install-aider.sh`](../install-aider.sh) — installer script

package/docs/AUTOPILOT-CRON.md

@@ -0,0 +1,130 @@
+# Autopilot Cron Mode — GitHub Actions Setup
+
+Run [`/autopilot`](../commands/autopilot.md) on a schedule so your repo gets better while you sleep.
+
+---
+
+## Quick Start
+
+1. **Copy the workflow template** into your repo:
+
+   ```bash
+   mkdir -p .github/workflows
+   curl -o .github/workflows/forgedock-autopilot.yml \
+     https://raw.githubusercontent.com/RapierCraftStudios/ForgeDock/milestone/developer-experience-distribution/templates/github-actions/forgedock-autopilot.yml
+   ```
+
+2. **Add your Anthropic API key** as a repository secret:
+   - Go to: `Settings → Secrets and variables → Actions → New repository secret`
+   - Name: `ANTHROPIC_API_KEY`
+   - Value: your key from [console.anthropic.com](https://console.anthropic.com)
+
+3. **Commit the workflow file** — GitHub Actions picks it up automatically.
+
+That's it. The workflow runs every Monday at 9 AM UTC in `recon` mode (safe, read-only).
+
+---
+
+## Modes
+
+### `recon` (default — safe)
+
+Runs [`/autopilot --recon-only`](../commands/autopilot.md):
+
+- Pulls signals: production health, CI/CD, issue backlog, analytics
+- Creates GitHub issues for findings
+- **No branches, no PRs, no code changes**
+
+This is the default for scheduled runs. Safe to enable immediately.
+
+### `fix` (explicit opt-in)
+
+Runs [`/autopilot --fix --limit N`](../commands/autopilot.md):
+
+- Everything in `recon` mode, plus:
+- Picks up the top N open issues and runs `/work-on` on each
+- Creates branches and PRs targeting `staging` (never `main`)
+- **Requires explicit selection** — not available on scheduled runs without editing the workflow
+
+To enable `fix` mode on a scheduled run, edit the `Resolve autopilot arguments` step in the workflow and change the default `MODE` to `fix`.
+
+To run `fix` mode on demand, use the **Run workflow** button on GitHub Actions and select `fix` from the mode dropdown.
+
+---
+
+## Permissions
+
+The workflow requires these GitHub token permissions (already set in the template):
+
+| Permission | Required for |
+|------------|-------------|
+| `contents: write` | Creating branches and pushing commits (`fix` mode) |
+| `issues: write` | Creating and labeling issues (both modes) |
+| `pull-requests: write` | Creating PRs (`fix` mode) |
+
+`GITHUB_TOKEN` is provided automatically — no extra setup needed.
+
+---
+
+## Adjusting the Schedule
+
+The default cron runs every Monday at 9 AM UTC. To change it, edit the `cron` line:
+
+```yaml
+on:
+  schedule:
+    - cron: '0 9 * * 1'   # Monday 9 AM UTC
+    # - cron: '0 8 * * *'  # Daily at 8 AM UTC
+    # - cron: '0 9 1 * *'  # Monthly on the 1st
+```
+
+Cron syntax: `minute hour day-of-month month day-of-week`. Use [crontab.guru](https://crontab.guru) to verify expressions.
+
+---
+
+## Changing the Fix Limit
+
+The `limit` input controls how many issues are picked up per run in `fix` mode (default: 3). To change the default for manual runs, edit the `default` value under `inputs.limit` in the workflow file.
+
+---
+
+## Non-Interactive Confirmation Bypass
+
+`/autopilot` Phase 4B normally requires interactive user confirmation before running `/work-on` on any issues. In GitHub Actions (a non-interactive environment), this gate is bypassed automatically when the `CI` environment variable is `true` — which is always the case in GHA.
+
+**The `workflow_dispatch` mode input serves as the human opt-in.** When you select `fix` and click **Run workflow**, you are explicitly approving the fix run. For scheduled runs, the mode embedded in the workflow YAML is your standing approval.
+
+This bypass is narrow: it only skips Phase 4B's interactive prompt. All other safety rules in `/autopilot` remain in force — `needs-human` issues are never picked up, milestone issues are excluded, and the `FIX_LIMIT` cap is always enforced.
+
+---
+
+## Cost Estimates
+
+| Mode | Typical token usage | Approximate cost |
+|------|--------------------|--------------------|
+| `recon` | ~5,000–15,000 tokens | ~$0.02–$0.05/run |
+| `fix` (1 issue) | ~50,000–150,000 tokens | ~$0.15–$0.45/run |
+| `fix` (3 issues) | ~150,000–450,000 tokens | ~$0.45–$1.35/run |
+
+Estimates based on `claude-sonnet-4` pricing ($3.00/M input, $15.00/M output). Actual usage varies by issue complexity and codebase size.
+
+To control costs, keep `mode: recon` for scheduled runs and use `fix` mode only on demand.
+
+---
+
+## Frequently Asked Questions
+
+**Will this merge code to `main`?**
+No. `/autopilot` (and `/work-on`) never merge to `main`. All PRs target `staging` or a milestone branch. You deploy when ready.
+
+**What if an autopilot run fails?**
+The workflow exits with a non-zero status. GitHub sends a notification email (configurable). The run is logged in the Actions tab. No partial state is left — issues are only created after a full recon cycle.
+
+**Can I run this in a private repo?**
+Yes. `GITHUB_TOKEN` has full access to your repo. Only the Anthropic API key is external.
+
+**Can I use this with Codex / OpenAI models?**
+No. `/autopilot` requires Claude Code CLI, which runs Anthropic models. The `ANTHROPIC_API_KEY` is mandatory.
+
+**What does `/autopilot` do if there are open P0 issues?**
+It skips normal recon and immediately routes to `fix` mode targeting the P0 issues, regardless of the selected mode. P0 always takes priority.