forgedock 1.2.0 → 1.3.0

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.

package/docs/CONFIG.md

@@ -210,6 +210,9 @@ repos:
 | `satellites[].local_path` | string | No | Absolute local path to the satellite repo's checkout |
 | `satellites[].subpaths` | map(string→string) | No | Named sub-directory paths within `local_path`, for monorepo satellites that publish multiple packages. Each key is a logical name; the value is the relative path to that package's root. Used by `/sync-ecosystem` to locate per-package version files and publish workflows. |
 | `satellites[].billing_enabled` | boolean | No | Set to `true` to run Phase 4 (Financial Integrity) of `/security-audit` against this satellite repo. Mirrors the top-level [`billing.enabled`](#billing-optional) flag but scoped per-satellite. Defaults to `false` when absent. |
+| `satellites[].trigger_on_merge` | boolean | No | When `true`, fires a cross-repo trigger when a PR merges in the parent repo and touches paths matching `trigger_paths`. Set to `false` to disable triggering for this satellite. Defaults to `true` when `trigger_paths` is present; otherwise has no effect until runtime trigger support is configured. |
+| `satellites[].trigger_paths` | list of strings | No | Path glob patterns that constrain when the trigger fires. Uses GitHub Actions glob syntax (same as `on: push: paths:`). The trigger fires only when at least one changed file matches a pattern in this list. When omitted, the trigger fires on every merge (if `trigger_on_merge: true`). |
+| `satellites[].auto_run` | boolean | No | When `true`, automatically invokes `/work-on` on the satellite issue when the cross-repo trigger fires. Requires a running Claude Code session with ForgeDock installed in the satellite repo. Advanced opt-in — defaults to `false`. Do not set to `true` unless a persistent Claude Code session is available in the satellite repo. |
 
 **Routing syntax in commands**: `<prefix>:<issue_number>` — e.g., `mcp:5`, `sdk:12`
 
@@ -609,6 +612,39 @@ Colors are grouped by semantic meaning:
 
 ---
 
+## `branding` (OPTIONAL)
+
+Controls attribution in FORGE annotation comments posted to GitHub issues and PRs by pipeline commands.
+
+When `show_attribution` is `true` (the default), every annotation comment (`FORGE:INVESTIGATOR`, `FORGE:CONTRACT`, `FORGE:BUILDER`, `FORGE:TRAJECTORY`, `FORGE:DECOMPOSED`, etc.) ends with a one-line footer:
+
+```
+> Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)
+```
+
+This follows the pattern established by Dependabot, Renovate, and similar tools. It helps new users discover the tooling when they encounter FORGE: annotations in a public thread. Set to `false` to suppress the attribution entirely.
+
+```yaml
+branding:
+  show_attribution: true
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `show_attribution` | boolean | No | `true` | When `true`, annotation comments posted by the pipeline include a one-line attribution footer. Set to `false` to suppress it entirely. Opt-out model — attribution is on by default. |
+
+**Commands that use this section**: `work-on` (all phases that post FORGE: annotation comments)
+
+**Config read pattern** (yq, with default-true fallback):
+
+```bash
+SHOW_ATTRIBUTION=$(yq '.branding.show_attribution // "true"' forge.yaml 2>/dev/null || echo "true")
+[ "$SHOW_ATTRIBUTION" = "false" ] && ATTRIBUTION_LINE="" || ATTRIBUTION_LINE="
+> Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)"
+```
+
+---
+
 ## GitHub App Install
 
 During `npx forgedock`, the installer prompts you to install the ForgeDock GitHub App (`rapiercraft-forgedock`) on your account or org.

package/docs/CURSOR.md

@@ -0,0 +1,135 @@
+# Cursor Support
+
+ForgeDock has a Cursor adapter that lets Cursor Agent mode run the ForgeDock pipeline via shell commands and the `gh` CLI.
+
+## Architecture
+
+Shared source:
+- `commands/**/*.md` remains the canonical workflow spec for all runtimes
+
+Cursor wrapper:
+- `templates/cursor/forge.mdc` — a static Cursor rules file that instructs Cursor Agent to execute pipeline phases using shell commands, `gh` CLI, and `git`
+- Users install this file into their repo's `.cursor/rules/forge.mdc`
+
+This is a static injection model, not a dynamic skill-loading mechanism. The adapter cannot replicate Claude Code's `Skill()` invocation or Codex's installed skill wrappers. Instead, it instructs the agent to read command specs directly from `commands/` and execute them using available terminal tools.
+
+## Install
+
+### Automatic (via `npx forgedock`)
+
+If your project already has a `.cursor/` directory, `npx forgedock` will detect it and automatically write `templates/cursor/forge.mdc` to `.cursor/rules/forge.mdc`:
+
+```bash
+npx forgedock
+```
+
+The installer skips this step if `.cursor/rules/forge.mdc` already exists (idempotent — never overwrites customizations).
+
+### Manual
+
+Copy the template directly:
+
+```bash
+mkdir -p .cursor/rules
+cp node_modules/forgedock/templates/cursor/forge.mdc .cursor/rules/forge.mdc
+# or, if installed globally:
+cp "$(npx forgedock which-dir)/templates/cursor/forge.mdc" .cursor/rules/forge.mdc
+```
+
+Commit the file to version control so all team members get it:
+
+```bash
+git add .cursor/rules/forge.mdc
+git commit -m "chore: add ForgeDock Cursor rules adapter"
+```
+
+## Usage
+
+### Running the Pipeline
+
+Open a Cursor Agent session and describe the pipeline task:
+
+```
+Work on GitHub issue #123 using the ForgeDock pipeline.
+Read commands/work-on.md and follow all phases.
+```
+
+The rules file will instruct Cursor Agent to:
+
+1. Load issue context from GitHub using `gh issue view`
+2. Follow the Universal Phase Dispatcher in `commands/work-on.md`
+3. Write FORGE annotations (HTML comments) to issue comments after each phase
+4. Transition `workflow:*` labels as phases complete
+5. Continue until a terminal label is set
+
+### Checking Pipeline State
+
+```bash
+# See current workflow state
+gh issue view NUMBER --json labels --jq '[.labels[].name]'
+
+# Read existing pipeline annotations
+gh api repos/OWNER/REPO/issues/NUMBER/comments \
+  --jq '.[] | select(.body | contains("FORGE:")) | {body: .body[:200]}'
+```
+
+### Continuing After a Phase
+
+Because Cursor Agent mode does not persist between invocations, start a new session and describe the resume:
+
+```
+Resume the ForgeDock pipeline for GitHub issue #123.
+Read commands/work-on.md — it will re-read GitHub state and pick up from the current label.
+```
+
+The pipeline is designed for compaction resilience — every phase re-reads GitHub state at the start, so a new Cursor Agent session picks up exactly where the previous session left off.
+
+## Limitations
+
+| Capability | Claude Code | Cursor (this adapter) |
+|------------|-------------|----------------------|
+| Skill loading | Dynamic (`~/.claude/commands/`) | Static (this rules file) |
+| Multi-phase pipeline | Automatic (single continuous session) | Manual (re-invoke agent per phase) |
+| Sub-skill invocation | `Skill("review-pr")` | Read `commands/review-pr.md` directly |
+| Session continuity | Native compaction resilience | Re-read GitHub state each invocation |
+| Tool set | Claude-native (`Bash`, `Read`, `Grep`, `Glob`, `WebFetch`) | Cursor Agent terminal tools |
+
+### Multi-Phase Pipeline
+
+The ForgeDock pipeline has 7 phases (investigate → build → review → merge → close → trajectory). Cursor Agent mode does not automatically advance through all phases in a single session. After each phase completes, you will need to start a new agent invocation and ask it to continue.
+
+The pipeline's compaction resilience handles this correctly: each invocation re-reads the issue's labels and comments, determines the current phase, and continues from there. No context is lost between sessions.
+
+### Sub-Skill Invocation
+
+When the pipeline spec calls `Skill("review-pr")` or `Skill("quality-gate")`, Cursor Agent should read the referenced command spec file directly:
+
+```bash
+cat commands/review-pr.md   # Then execute that spec
+cat commands/quality-gate.md
+```
+
+### Project Board Steps
+
+Some pipeline phases (0C: Sync to Project board) call GitHub Projects API operations. These work via `gh` CLI but require the project number and field IDs from `forge.yaml`. Verify your `forge.yaml` has the correct project configuration before running the pipeline.
+
+## Configuration
+
+ForgeDock reads `forge.yaml` for project-specific settings:
+
+```bash
+cat forge.yaml   # Review before running the pipeline
+```
+
+Key fields used by the pipeline:
+- `project.github.owner` / `project.github.repo` — GitHub repo coordinates
+- `branches.staging` — target branch for fast-lane PRs
+- `branches.main` — default branch
+
+## Reference
+
+- `commands/work-on.md` — Full pipeline spec (all phases)
+- `commands/review-pr.md` — PR review spec
+- `commands/quality-gate.md` — Pre-commit quality checks (14+ domains)
+- `docs/FORGE-PROTOCOL.md` — FORGE annotation protocol specification
+- `docs/CODEX.md` — Codex CLI adapter (dynamic skill model)