@aion0/forge 0.9.1 → 0.9.3

package/lib/help-docs/05-pipelines.md

@@ -12,6 +12,21 @@ description: "What this workflow does"
 input:
   feature: "Feature description"      # required input fields
   priority: "Priority level (optional)"
+  # OR extended spec when you want richer Schedule UI controls:
+  #   bug_id:
+  #     description: "Mantis bug id"
+  #     type: integer        # string | integer | number | boolean | enum
+  #     required: true
+  #     default: 0
+  #   resolution:
+  #     type: enum
+  #     enum: [fixed, wont_fix, duplicate]
+  #     default: fixed
+  #   user_prompt:
+  #     description: "Focus the fix on…"
+  #     multiline: true
+  # Both forms can be mixed in the same input: block. Pipeline runtime
+  # treats every value as a string template variable regardless of type.
 vars:
   project: my-app                     # default variables
 nodes:
@@ -69,6 +84,94 @@ nodes:
 
 **Shell escaping**: Template values in shell mode are automatically escaped (single quotes `'` → `'\''`) to prevent injection.
 
+## Authoring discipline — common YAML/shell footguns
+
+Pipeline yaml mixes two languages (YAML block scalars + bash) and most of
+the production bugs we've hit live in their interaction. The 3 rules below
+prevent ~90% of them. Follow them whenever you write or modify a `mode:
+shell` node — they cost nothing and save retries.
+
+### Rule 1 — `mode: shell` prompts use `|`, never `>`
+
+YAML has two block scalar styles, and they treat newlines very differently:
+
+- **`prompt: |` (literal)** — newlines preserved verbatim. Bash receives the
+  script exactly as written. **Always use this for shell scripts.**
+- **`prompt: >` (folded)** — adjacent same-indent lines are joined into ONE
+  line separated by a single space. Only blank lines preserve real
+  newlines. In shell scripts this silently produces things like
+  `STAGE_LABEL="x" if [ ... ]; then` (two statements glued together with a
+  space), causing `syntax error near unexpected token 'fi'` at runtime.
+
+If you see an existing node using `>` that already works, leave it — it
+relies on the discipline of blank lines between every statement. But for
+any **new** node or **substantial rewrite**, use `|`. Don't sprinkle
+shell into existing `>` nodes without re-checking blank-line spacing.
+
+### Rule 2 — Don't use `eval $(echo "$X" | sed 's/^/export /')` to import env vars
+
+This idiom looks innocent but breaks the moment any value contains a space,
+colon, or hyphen — bash word-splits the joined string and tries to
+`export` each word as a separate identifier, hitting things like
+`export: 'pre-review': not a valid identifier`.
+
+Use the safer form:
+
+```bash
+while IFS='=' read -r __k __v; do
+  [[ "$__k" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] && export "$__k=$__v"
+done <<< "$VAR"
+```
+
+This reads key=value pairs line by line, accepts any value content
+(including spaces / colons / newlines), and only exports lines that have
+a valid identifier as key.
+
+### Rule 3 — Don't put `cat <<EOF` heredocs inside `$(...)` when content can contain `` ` `` or `'`
+
+Bash's `$(...)` parser scans the body for nested backticks and apostrophes
+**even when the heredoc body is quoted (`<<'EOF'`)**. If the substituted
+content has markdown code spans like `` `GroupManager.getX()` `` or
+contractions like `FortiGate's`, parsing crashes with `syntax error near
+unexpected token ')'`.
+
+Use a file detour:
+
+```bash
+__FORGE_F=/tmp/forge-something.$$
+cat <<'__FORGE_MARK_x7k9z2q4__' > "$__FORGE_F"
+{{raw:nodes.X.outputs.Y}}
+__FORGE_MARK_x7k9z2q4__
+VAR=$(< "$__FORGE_F")
+rm -f "$__FORGE_F"
+```
+
+The `cat <<EOF > file` is OUTSIDE any `$(...)`, so bash never parses the
+content. `$(< file)` reads the file as a whole, also no parsing. The
+`{{raw:...}}` template variant skips Forge's ANSI-C shell escape so
+multi-line content keeps real newlines.
+
+### Rule 4 — Prefer adding new nodes over editing existing ones
+
+If a pipeline is already working in production, prefer:
+- **Adding a new node** that runs alongside / after the working ones
+- **Composing in a new `mode: shell` block** that calls into the existing
+  outputs via `{{nodes.X.outputs.Y}}`
+
+Over:
+- Splicing new shell statements into the middle of an existing prompt
+  block (which forces the YAML scalar to be re-parsed and can trigger
+  hidden rule-1 / rule-2 problems)
+
+This keeps the blast radius of each change to one new node.
+
+### Quick mental checklist before editing any `prompt:` block
+
+1. Is this `|` or `>`? (decide indent + blank-line strategy)
+2. Are there ANY `eval ... | sed export` patterns nearby? (replace with the safer `while IFS='=' read` form)
+3. Are there `cat <<EOF` inside `$(...)`? (move to the file-detour pattern)
+4. Could I add a new node instead of modifying this one?
+
 ## Template Variables
 
 Templates use `{{...}}` syntax and are resolved before execution:
@@ -76,6 +179,74 @@ Templates use `{{...}}` syntax and are resolved before execution:
 - `{{input.xxx}}` — pipeline input values provided at trigger time
 - `{{vars.xxx}}` — workflow-level variables defined in YAML
 - `{{nodes.<node_id>.outputs.<output_name>}}` — outputs from completed nodes
+- `{{run.tmp_dir}}` — per-run scratch dir (see "Per-run scratch dir" below)
+- `{{raw:...}}` — prefix that bypasses shell-mode ANSI-C escaping (use inside quoted heredocs / files / jq stdin so multi-line content keeps real newlines)
+
+## Per-run scratch dir (`{{run.tmp_dir}}`)
+
+Each pipeline run gets a private scratch directory at:
+
+```
+<project_dir>/.forge/worktrees/pipeline-<runId>/
+```
+
+`<project_dir>` is resolved from the pipeline's `{{input.project}}` (the
+input parameter most Forge pipelines already declare). If the pipeline
+has no `input.project`, the template renders as empty string and you
+should fall back to OS `/tmp/` for scratch.
+
+**Use this instead of `/tmp/`** for any per-run scratch files. Three big
+wins over OS /tmp:
+
+1. **Per-run isolation** — different pipeline runs never collide on the
+   same file, even if both are processing the same MR / bug id.
+2. **Bulk cleanup** — the whole dir is `rm -rf`'d when GC fires; no
+   need to track individual `/tmp/foo-12345-bar` filenames.
+3. **Survives reboot** — `~/.../.forge/worktrees/` is on persistent disk;
+   OS `/tmp/` is wiped at boot, taking your failed-run forensics with it.
+
+### Lifecycle
+
+| Status | When tmp_dir is wiped |
+|---|---|
+| `done`            | Immediately when status flips (settings.pipelineTmpCleanDoneImmediate) |
+| `failed`          | After `settings.pipelineTmpKeepFailedDays` (default 3) — by background GC |
+| `cancelled`       | After `settings.pipelineTmpKeepCancelledDays` (default 3) — by background GC |
+| `running`         | Never (auto-extends as long as the pipeline is alive) |
+| (orphan, no state)| After 7 days, by background GC |
+
+GC runs every `settings.pipelineTmpGcIntervalHours` (default 6h). Run
+on demand with `forge pipeline gc [--dry-run]`.
+
+### Convention — sub-dirs per item
+
+When a pipeline processes multiple items (MRs, Mantis bugs, etc.),
+create a sub-dir per item inside `{{run.tmp_dir}}` so individual items
+are clearly isolated. Naming:
+
+| Item type | Sub-dir |
+|---|---|
+| GitLab MR    | `mr-<iid>/` |
+| Mantis bug   | `mantis-<bug_id>/` |
+| Generic id   | `<kind>-<id>/` |
+
+Even for single-item pipelines (one bug per run) use the same convention
+— makes future batch versions cleanly composable.
+
+Example (shell node):
+
+```yaml
+prompt: |
+  set -e
+  MR_DIR="{{run.tmp_dir}}/mr-${MR_IID}"
+  mkdir -p "$MR_DIR"
+  glab api ... > "$MR_DIR/meta.json"
+  glab api ... > "$MR_DIR/diff.json"
+  # ...
+```
+
+The framework creates `pipeline-<runId>/` for you; you only have to
+`mkdir -p` your own sub-dir.
 
 Node IDs can contain hyphens (e.g., `{{nodes.fetch-issue.outputs.data}}`).
 

package/lib/help-docs/13-schedules.md

@@ -0,0 +1,165 @@
+# Schedules
+
+**Schedule = a pipeline + input + trigger.** Forge runs the named pipeline with
+your input whenever the trigger fires. The pipeline is the only execution unit;
+Schedule just decides *when* to fire.
+
+**Note:** Jobs (the older subsystem) is deprecated — its UI is hidden and the
+scheduler no longer ticks. Any existing rows in the `jobs` table are inert.
+Use Schedules for all timed automation. If a pipeline needs iteration, write
+it inside the pipeline yaml using `for_each:` — Schedule just fires the
+pipeline; iteration logic stays in the workflow.
+
+## Creating a Schedule (3 steps)
+
+Open **Schedules** tab → **+ New schedule** in Forge web or extension:
+
+1. **Pick a pipeline** from the list. Each pipeline shows its description.
+2. **Fill input**. The form depends on body kind:
+   - **Pipeline** body: auto-renders from the pipeline's declared `input:`
+     block. Required fields are marked `*`. Long-form fields render as textarea.
+   - **Skill** body: a fixed two-field form — `project` (which Forge project
+     the skill runs in) and `user_prompt` (the user message sent to Claude).
+     The skill is loaded via `--append-system-prompt`.
+   - **Connector Tool** body: a JSON textarea passed verbatim as the
+     tool's input. The tool's `input_schema` (if declared) is shown
+     below the editor for reference.
+3. **Name, trigger, action**:
+   - **Trigger**:
+     - `Every N minutes` — period polling
+     - `Cron` — full cron expression (e.g. `0 9 * * 1-5` = 9am Mon-Fri)
+     - `Once at <time>` — single shot, auto-disables after firing
+     - `Manual only` — never auto-fires; user must click Run now
+   - **Action** (what to do with the body's output):
+     - `None` (default) — body self-handles its output; nothing else fires
+     - `Chat` — append the body output to a Chat session as a synthetic
+       assistant message. Configure `session_id` (pick from the dropdown)
+       and an optional `prefix`. The message header is auto-prepended with
+       the schedule name + fire time so the recipient can tell where it
+       came from.
+     - `Email` — send the body output via SMTP. Configure SMTP transport
+       once in `~/.forge/data/settings.yaml`:
+
+       ```yaml
+       smtpHost: smtp.gmail.com
+       smtpPort: 587
+       smtpSecure: false           # true for 465 (implicit TLS), false for 587 (STARTTLS)
+       smtpUser: forge@example.com
+       smtpPassword: <app-password>  # encrypted at rest
+       smtpFrom: Forge <forge@example.com>
+       ```
+
+       Per-schedule action config:
+
+       ```
+       to                 alice@example.com   (or list)
+       subject_template   "Daily bugs — {date}"
+       body_template      "{body_output}"
+       ```
+
+       Templates support `{date}` (YYYY-MM-DD) and `{body_output}`.
+       Requires `nodemailer` installed in the Forge repo
+       (`pnpm add nodemailer`).
+     - `Telegram` — post the body output via the same Telegram bot
+       Forge uses for task notifications. Reuses `telegramBotToken`
+       from Settings. `chat_id` is optional in the action config —
+       blank falls back to `settings.telegramChatId`. Optional
+       `prefix` is prepended; default `parse_mode: Markdown`.
+
+   Actions fire only when the body completes with status `done` and
+   produces non-empty output (unless `action_skip_on_empty` is false).
+   The `schedule_runs.action_status` column records `done | failed |
+   skipped` independently of the body status.
+
+## Schedule states
+
+Computed from `enabled` + inflight pipelines + last run status:
+
+| State | Meaning | UI |
+|---|---|---|
+| `idle` | Enabled, nothing running, last run OK (or never run) | green |
+| `running` | Enabled, ≥1 pipeline this schedule launched is in-flight | orange (pulsing) |
+| `last_failed` | Enabled, last run ended in failure | red |
+| `paused` | `enabled=false` | gray |
+
+A paused Schedule with inflight pipelines shows `paused` plus a count badge
+("3 still running") so you know the running work is still going even though
+no new pipelines will be triggered.
+
+## Actions
+
+The action bar adapts to current state:
+
+| Button | Effect |
+|---|---|
+| **Run now** | Manually fire — `trigger='manual'`. If something's already running, asks to cancel-and-rerun |
+| **Cancel** | Kill the in-flight pipelines this Schedule launched. Does NOT change `enabled` |
+| **Pause** | Set `enabled=false`. Running pipelines keep going |
+| **Resume** | Set `enabled=true` (only shown when paused and nothing inflight) |
+| **Stop** | Pause + Cancel in one shot — full halt |
+| **Edit** | Modify input / trigger / name. Pipeline can't be changed (create a new Schedule) |
+| **Delete** | Remove the Schedule. Optionally cancel running pipelines too |
+
+## Tracked pipelines
+
+Expanding a Schedule row shows the pipelines it has launched. Click any row to
+open the Pipeline view for node-level details. The list shows current running
+pipelines plus the most recent completed one (full history is in the pipeline
+view).
+
+## API
+
+```
+GET    /api/schedules                              list + decorate state
+POST   /api/schedules                              create
+GET    /api/schedules/<id>                         single
+PATCH  /api/schedules/<id>                         update input/trigger/name/enabled
+DELETE /api/schedules/<id>?cancel_inflight=1       remove
+
+POST   /api/schedules/<id>/run?cancel_inflight=1   manual fire
+POST   /api/schedules/<id>/cancel                  kill all inflight
+POST   /api/schedules/<id>/stop                    pause + cancel
+GET    /api/schedules/<id>/runs?limit=20           history
+
+GET    /api/pipelines/<name>/schema                input fields (for UI form)
+```
+
+## Storage
+
+- `schedules` — configuration. Key fields:
+  - `body_kind` (`pipeline | skill | connector_tool`) + `body_ref` —
+    what this schedule fires
+  - `input` (JSON) — params for the body
+  - `skills` (JSON `string[]`) — extra Forge skills attached to the
+    dispatched body. Forwarded as `--append-system-prompt` so Claude
+    sees "use /&lt;skill&gt; as appropriate"; missing skills auto-installed
+    into the target project at dispatch (same plumbing as `Job.skills`).
+    Ignored for `body_kind=connector_tool` (no Claude task spawned).
+    For `body_kind=skill`, merged with `body_ref` (de-duped).
+  - `action_kind` (`none | chat | email | telegram`) + `action_config`
+    (JSON) — what to do with the body's output. **Phase 1 only ships
+    `body_kind=pipeline` and `action_kind=none`**; other kinds land in
+    later phases.
+  - `schedule_kind` + interval/at/cron — trigger
+- `schedule_runs` — every body a Schedule has launched:
+  - `target_id` — pipeline_id (or future task/dispatch id)
+  - `status` — body status (`started / done / failed / cancelled`)
+  - `body_output` — captured body output, fed into action
+  - `action_status` — independent of body status
+
+V1 (`pipeline_schedules` / `pipeline_schedule_runs` tables, with
+`pipeline_name` column) is auto-migrated into V2 on first boot.
+
+## Scheduler tick
+
+A 60s timer runs in `lib/schedules/scheduler.ts`. Each tick:
+
+1. Reconcile any stale "started" runs against the actual pipeline JSON state
+2. For every enabled, non-manual Schedule whose `next_run_at <= now`:
+   - Advance `next_run_at` for the next firing
+   - Skip if this Schedule already has an inflight pipeline
+   - Otherwise call `startPipeline(pipeline_name, input)` and write a
+     `pipeline_schedule_runs` row
+
+No sequential / on_failure / dedup / retry logic at the Schedule level — those
+are pipeline responsibilities.

package/lib/help-docs/23-automation-states.md

@@ -0,0 +1,148 @@
+# Automation state machine — labels, comments, statuses
+
+This page documents what Forge's automation pipelines write to external
+systems (GitLab, Mantis, Teams, Forge chat). Use it as the single reference
+when wiring new schedules, triaging an MR, or auditing what Forge has
+already done.
+
+Three pipelines operate on a Mantis bug → GitLab MR pair:
+
+| Pipeline                    | Triggered by              | Touches              |
+|-----------------------------|---------------------------|----------------------|
+| `fortinet-mantis-bug-fix`   | Manual fire / Schedule    | Mantis + GitLab      |
+| `fortinet-mr-pre-review`    | Manual fire / Schedule    | GitLab               |
+| `fortinet-mr-review`        | Manual fire / Schedule    | GitLab (+ Teams)     |
+
+## Stage labels (mutually exclusive)
+
+Every pipeline marks the GitLab MR with a `forge:stage/*` label when it
+finishes. The labels are mutually exclusive — each pipeline removes the
+others before adding its own. Reading the label tells you "how far through
+the automation funnel" the MR is.
+
+| Stage label                  | Set by                       | Meaning                                                 |
+|------------------------------|------------------------------|---------------------------------------------------------|
+| `forge:stage/needs-review`   | `fortinet-mantis-bug-fix`    | MR just created by Forge; nobody has reviewed it yet.   |
+| `forge:stage/pre-reviewed`   | `fortinet-mr-pre-review`     | Forge posted an AI pre-review comment.                  |
+| `forge:stage/reviewed`       | `fortinet-mr-review`         | Forge ran a full review round (replied / labelled / closed). |
+
+**One-time setup per GitLab project:** create those three labels in the
+project's Labels page. Pipelines call `glab api ... add_labels=...`; the
+label has to exist or the API call silently fails (best-effort — no error
+escalation, just `STAGE_LABEL=failed` in the run output).
+
+## Verdict labels (orthogonal to stage labels)
+
+`fortinet-mr-review` also adds a label that describes its **decision**.
+These can co-exist with stage labels.
+
+| Verdict label          | When                                                                |
+|------------------------|---------------------------------------------------------------------|
+| `forge:fix-applied`    | Triage said ACT, Claude pushed a fix commit, MR updated.            |
+| `forge:no-fix-needed`  | Triage said SKIP (e.g. style-only review notes — no action needed). |
+| `forge:no-merge`       | Triage said CLOSE — MR is invalid; pipeline also closes the MR.     |
+
+## Per-pipeline detail
+
+### 1. `fortinet-mantis-bug-fix`
+
+Input: Mantis bug id (+ project). Walks the bug, opens a worktree on the
+target branch, runs Claude to write a fix, pushes, opens MR, then
+post-processes both sides.
+
+| Step          | Side effect                                                                                                                                                                                  |
+|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `push-and-mr` | Creates GitLab MR (or finds existing for the branch). **Sets `forge:stage/needs-review`** + removes other `forge:stage/*` labels.                                                            |
+| `mark-fixed`  | Mantis **resolution → fixed**. Status (e.g. New / Assigned / Resolved) is left untouched — reviewer of the MR decides. Best-effort via Mantis connector + `connector-tool` bridge.           |
+| `notify-mantis` | Adds a Mantis **bugnote** containing the MR URL, branch, and Claude's fix summary. Format starts with "Auto-fix applied — MR opened." and ends with `ref: autofix-<bug_id>`. Best-effort. |
+| `notify-teams` | Posts a Teams chat message to the configured user/group with MR URL + summary. Best-effort.                                                                                                |
+| `cleanup`     | Removes the temporary worktree.                                                                                                                                                              |
+
+If `push-and-mr` finds no diff to commit (Claude bailed without changes),
+`mark-fixed` skips (no resolution change), and `notify-mantis` posts a
+**"Auto-fix attempted — no fix applied"** bugnote instead. So Mantis is
+always notified one way or the other.
+
+### 2. `fortinet-mr-pre-review`
+
+Input: GitLab MR URL. Fetches metadata + diff + discussion, runs Claude
+to draft a short analysis, posts ONE comment on the MR.
+
+| Step           | Side effect                                                                                                                                                                                                         |
+|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `ingest`       | Fetches MR meta / diff / notes. **Skip detection:** finds the last Forge pre-review note (body starts with `🤖 Forge pre-review:`); if there are no new commits AND no new non-forge notes since, sets `SKIP_PRE_REVIEW=yes`. Downstream steps short-circuit. |
+| `analyze`      | Claude produces VERDICT (`ready-to-merge` / `needs-review`) + FINDINGS + REPLY DRAFT.                                                                                                                                |
+| `post-comment` | Posts one GitLab note. First line is always `**Recommendation:** ✅ Looks safe to merge.` or `**Recommendation:** ⚠️ Needs another review — <reason>.`. **Sets `forge:stage/pre-reviewed`** + removes other `forge:stage/*`. On `SKIP_PRE_REVIEW=yes`, doesn't post or touch labels. |
+| `notify-chat`  | Opens a Forge chat session seeded with the analysis (or "skipped" if skip path).                                                                                                                                    |
+
+The skip path means re-running pre-review (manually or on a schedule)
+won't spam the MR with duplicate comments. Adding any commit or non-forge
+note to the MR re-arms the pipeline.
+
+### 3. `fortinet-mr-review`
+
+Input: GitLab MR URL + reviewer notes. Triages the discussion, optionally
+fixes code + pushes, replies on the MR.
+
+| Step       | Side effect                                                                                                                                                                                                                                                                                |
+|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `ingest`   | Fetches MR + reviewer notes since last Forge reply.                                                                                                                                                                                                                                          |
+| `triage`   | Claude decides one of: `ACT` (push a fix), `SKIP` (no action), `CLOSE` (abandon the MR), `NOOP` (no new reviewer feedback, break self-reply loop).                                                                                                                                            |
+| `fix`      | (ACT only) Claude edits + commits + pushes to the MR branch.                                                                                                                                                                                                                                 |
+| `reply`    | Posts one GitLab note (`🤖 Forge: <RESULT block>`). Then: <ul><li>**Verdict label** by status: `pushed` → `forge:fix-applied`, `skipped` → `forge:no-fix-needed`, `close` → `forge:no-merge` + closes the MR.</li><li>**Stage label** (every status): `forge:stage/reviewed` + removes other `forge:stage/*`.</li></ul> |
+| `cleanup`  | Removes the temporary worktree; posts to Teams.                                                                                                                                                                                                                                              |
+
+`NOOP` doesn't touch labels or post anything — it exists purely to avoid
+the pipeline replying to its own previous reply.
+
+## Comments — who posts what
+
+Every Forge-generated comment has a recognisable prefix so you can grep /
+filter them in the MR or in Mantis:
+
+| Source                                    | Where             | Prefix                              |
+|-------------------------------------------|-------------------|-------------------------------------|
+| `fortinet-mantis-bug-fix` → notify-mantis | Mantis bugnote    | `Auto-fix applied — MR opened.` / `Auto-fix attempted — no fix applied.` (ends with `ref: autofix-<bug_id>`) |
+| `fortinet-mr-pre-review`  → post-comment  | GitLab MR note    | `🤖 Forge pre-review:`              |
+| `fortinet-mr-review`      → reply         | GitLab MR note    | `🤖 Forge:` (followed by RESULT block) |
+
+## Mantis side
+
+| What                       | Set by                                                                                                                |
+|----------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| **Resolution → fixed**     | `fortinet-mantis-bug-fix` → `mark-fixed`, only when an MR was actually created. Best-effort via Mantis connector.     |
+| Bugnote with MR + summary  | `fortinet-mantis-bug-fix` → `notify-mantis`. Always posts (one variant if MR created, another "no fix applied" variant if Claude bailed). |
+
+Mantis **status** is intentionally never auto-changed — the human reviewer
+who merges the MR decides whether the bug moves to Resolved / Closed.
+
+## Teams side
+
+Both `fortinet-mantis-bug-fix` and `fortinet-mr-review` (via their final
+`cleanup` / notify steps) send a Teams chat message with the MR URL and
+brief summary, IF the Teams connector is configured. Best-effort — Teams
+unreachable doesn't fail the pipeline.
+
+## Forge chat seeds
+
+`fortinet-mr-pre-review` → `notify-chat` opens a new Forge chat session
+seeded with the analysis + four next-step options (Approve / Request
+changes / Look closer / Nothing). The chat session id is returned so a
+Schedule action can re-use the same session or open a fresh one each run.
+
+## Quick reference — "where is this MR right now?"
+
+```
+Look at the MR's labels:
+
+  forge:stage/needs-review     → bug-fix pipeline just opened it
+  forge:stage/pre-reviewed     → AI pre-review posted; awaiting human
+  forge:stage/reviewed         → Forge did a full review round
+  (no forge:stage/* label)     → not Forge-managed, or pre-stage-label era
+
+  forge:fix-applied            → Forge pushed a fix commit in this round
+  forge:no-fix-needed          → Forge looked, decided no action
+  forge:no-merge               → Forge / triage decided to close
+```
+
+Look at the latest comment for the actual analysis / reply text.

package/lib/help-docs/CLAUDE.md

@@ -49,13 +49,13 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 | `17-connectors.md` | Connectors — independent subsystem, marketplace fetched from `forge-connectors` registry, no built-ins. Manifest schema, HTTP API, install/update flow, pre-v0.9 migration. |
 | `21-build-connector.md` | **Authoring** a custom connector — interview script, manifest template (browser / http / shell protocols), how to install locally via the Forge data dir or a zip upload. Use this when the user asks to BUILD a connector, not when they ask about an existing one. |
 | `18-chrome-mcp.md` | Connect Forge Claude Code sessions to a real Chrome via chrome-devtools-mcp — dev-time browser access for connector authoring |
-| `19-jobs.md` | Jobs — scheduled connector polls that dedup and fan out to Pipeline / Chat |
-| `20-mantis-bug-fix.md` | Mantis → Bug Fix → MR builtin pipeline (mantis-bug-fix-and-mr) |
-| `22-recipes.md` | Recipes (parameterized Job templates) + the `mr-review-fix` pipeline — gitlab_mr_url param, 4-action triage (act/skip/close/noop), GitLab label setup, per-MR vs per-comment dispatch, Marketplace ↔ local-copy split |
+| `23-automation-states.md` | Fortinet pipeline automation: GitLab MR stage labels, Mantis status flow, Teams notify policy |
 
 ## Matching questions to docs
 
 - Pipeline/workflow/DAG/YAML → `05-pipelines.md`
+- Writing / editing a pipeline YAML / "Claude wrote a node that fails with `syntax error near unexpected token`" / `prompt: >` vs `prompt: |` / `eval ... | sed export` / `cat <<EOF` inside `$()` → `05-pipelines.md` (Authoring discipline section)
+- Pipeline scratch dir / `{{run.tmp_dir}}` / per-run isolation / `/tmp/` vs `.forge/worktrees/pipeline-<id>` / pipeline GC / `forge pipeline gc` / where to put node scratch files → `05-pipelines.md` (Per-run scratch dir section)
 - Issue/PR/auto-fix → `09-issue-autofix.md` + `05-pipelines.md`
 - Telegram/notification → `02-telegram.md`
 - Tunnel/remote/cloudflare → `03-tunnel.md`
@@ -80,6 +80,6 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 - Connector/connector marketplace/install connector/forge-connectors registry/Mantis manifest → `17-connectors.md`
 - Build / author / write / create a new connector / "make me a connector for X" / custom connector → `21-build-connector.md`
 - Chrome MCP / chrome-devtools-mcp / dev-time browser / CDP / remote debugging → `18-chrome-mcp.md`
-- Job / scheduled job / connector poll / dedup / periodic fetch / Teams poll / Mantis bug poll → `19-jobs.md`
-- Mantis bug fix pipeline / mantis-bug-fix-and-mr / open MR for Mantis bug / notify Teams from pipeline / connector-tool endpoint → `20-mantis-bug-fix.md`
-- Recipe / parameterized job / "From recipe" form / mr-review-fix / MR review auto-fix / triage instructions / act vs skip vs close vs noop / forge:no-fix-needed / forge:no-merge label / gitlab_mr_url param / per-MR vs per-comment / Marketplace local-only filter → `22-recipes.md`
+- Job / scheduled job / connector poll / "Jobs tab" → tell user: **Jobs is deprecated**; use Schedules (`13-schedules.md`) instead.
+- Recipe / "From recipe" form / parameterized job → tell user: **recipes deprecated** along with Jobs; fire pipelines manually or via Schedules.
+- Mantis bug fix / fortinet-mantis-bug-fix / open MR for Mantis bug / fortinet-mr-review / pre-review / GitLab stage labels → `23-automation-states.md` (kept Fortinet pipelines)

package/lib/init.ts

@@ -178,6 +178,21 @@ export function ensureInitialized() {
   // Task runner is safe in every worker (DB-level coordination)
   time('ensureRunnerStarted', ensureRunnerStarted);
 
+  // Pipeline tmp-dir GC — scan project worktrees/pipeline-<id>/ + delete
+  // expired (failed/cancelled past retention). Interval from settings,
+  // clamped to >= 1h to avoid runaway IO. Runs in background only.
+  try {
+    const { gcPipelineTmp } = require('./pipeline-gc');
+    const { loadSettings: ls } = require('./settings');
+    const hours = Math.max(1, Number(ls().pipelineTmpGcIntervalHours) || 6);
+    setInterval(() => {
+      try {
+        const r = gcPipelineTmp();
+        if (r.removed.length) console.log(`[pipeline-gc] swept ${r.removed.length}/${r.scanned} dir(s)`);
+      } catch (e) { console.warn('[pipeline-gc] sweep failed:', (e as Error).message); }
+    }, hours * 60 * 60 * 1000);
+  } catch (e) { console.warn('[pipeline-gc] setup failed:', (e as Error).message); }
+
   // Session watcher is safe (file-based, idempotent)
   time('startWatcherLoop', startWatcherLoop);
 
@@ -189,12 +204,16 @@ export function ensureInitialized() {
     } catch {}
   });
 
-  // Jobs scheduler — periodic connector polls that fan out to pipelines / chat
-  time('jobs-scheduler', () => {
-    try {
-      const { startScheduler: startJobsScheduler } = require('./jobs/scheduler');
-      startJobsScheduler();
-    } catch (e) { console.error('[jobs-scheduler] start failed', e); }
+  // Jobs scheduler — DEPRECATED, no longer started. Backend code remains
+  // (lib/jobs/, app/api/jobs/) for reversion / data inspection only.
+  // Any rows in the `jobs` table will NOT tick. Use Schedules instead.
+
+  // Schedules scheduler — newer pure-pipeline triggers. Runs parallel to Jobs.
+  time('schedules-scheduler', () => {
+    import('./schedules/scheduler').then(({ startSchedulesScheduler }) => {
+      try { startSchedulesScheduler(); }
+      catch (e) { console.error('[schedules-scheduler] start failed', e); }
+    }).catch((e) => console.error('[schedules-scheduler] import failed', e));
   });
 
   // If services are managed externally (forge-server), skip

package/lib/jobs/recipes.ts

@@ -32,7 +32,7 @@
  * connector items yet; the scheduler later renders {{item.X}} per row.
  */
 
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import YAML from 'yaml';
 import { homedir } from 'node:os';
@@ -124,7 +124,6 @@ export function deleteRecipe(name: string): boolean {
   if (!NAME_RE.test(name)) return false;
   const path = join(recipesDir(), `${name}.yaml`);
   const altPath = join(recipesDir(), `${name}.yml`);
-  const { unlinkSync } = require('node:fs');
   if (existsSync(path)) { unlinkSync(path); return true; }
   if (existsSync(altPath)) { unlinkSync(altPath); return true; }
   return false;
@@ -283,6 +282,8 @@ export function instantiateRecipe(name: string, rawParams: Record<string, any>):
       max_per_tick: typeof rendered.max_per_tick === 'number'
         ? rendered.max_per_tick
         : (rendered.max_per_tick != null && rendered.max_per_tick !== '' ? Number(rendered.max_per_tick) : undefined),
+      concurrency_mode: rendered.concurrency_mode === 'parallel' ? 'parallel' : undefined,
+      on_failure: rendered.on_failure === 'stop' ? 'stop' : undefined,
     });
     return { ok: true, job };
   } catch (e) {