stageflow 0.33.0 → 0.36.0

package/dist/workshop/workshopTranscriptTurn.js

@@ -0,0 +1,46 @@
+import { mutationSnapshotsFromProposals, } from "./sessionMutations.js";
+export function assistantTranscriptTextFromEvents(events) {
+    const parts = [];
+    for (const event of events) {
+        if (event.type === "message" && event.role === "assistant") {
+            parts.push(event.text);
+        }
+    }
+    return parts.join("\n\n").trim();
+}
+export function proposalPayloadsFromEvents(events) {
+    const proposals = [];
+    for (const event of events) {
+        if (event.type === "proposal") {
+            proposals.push(event.proposal);
+        }
+    }
+    return proposals;
+}
+export function transcriptMessagesForTurn(userMessage, attachments, events, options) {
+    const messages = [
+        {
+            role: "user",
+            text: userMessage,
+            ...(attachments.length > 0 ? { attachments: [...attachments] } : {}),
+        },
+    ];
+    for (const event of events) {
+        if (event.type === "message" && event.role !== "assistant") {
+            messages.push({ role: event.role, text: event.text });
+        }
+    }
+    const assistantText = assistantTranscriptTextFromEvents(events);
+    const proposals = proposalPayloadsFromEvents(events);
+    const mutations = proposals.length > 0
+        ? mutationSnapshotsFromProposals(proposals, options?.autoApply === true)
+        : [];
+    if (assistantText.length > 0 || mutations.length > 0) {
+        messages.push({
+            role: "assistant",
+            text: assistantText,
+            ...(mutations.length > 0 ? { mutations } : {}),
+        });
+    }
+    return messages;
+}

package/examples/README.md

@@ -14,7 +14,7 @@ Upgrading older YAML: [`sf migrate-yaml`](../docs/cli-reference.md#sf-migrate-ya
 
 - **Route `if`** — `detect-changes` emits `author_diagrams` and skips `author-diagrams` when the PR diff has no diagram-relevant types
 - **Multi-type output** — one pipeline authors 1–5 Archify diagram specs (`architecture`, `workflow`, `sequence`, `dataflow`, `lifecycle`)
-- **Skill binding** — `skill: archify` on the pipeline stage entry; GHA provisions the skill via `sf skills install`
+- **Skill binding** — `skill: archify` on the stage file; GHA provisions the skill via `sf skills install`
 - **Deterministic handoff** — agents emit JSON specs; GHA runs `sf envelope get --format handoff` and Archify `deliver` outside the agent
 - **Real automation** — [`.github/workflows/archify-pr-diagrams.yml`](../.github/workflows/archify-pr-diagrams.yml) posts sticky PR comments with browser-viewable HTML artifacts
 

package/examples/archify-on-pr/README.md

@@ -10,7 +10,7 @@ for GHA to deliver as HTML.
 |------|------|
 | `archify-on-pr.pipeline.yaml` | detect-changes Route `if` → author-diagrams; `verify` + `on_verify_fail` on detect |
 | `detect-changes.yaml` | Thin copy/emit from `ci-context.json` → `changes.json` + envelope |
-| `author-diagrams.yaml` | Writes `{type}.spec.json` per selected type (skill: archify on pipeline entry) |
+| `author-diagrams.yaml` | Writes `{type}.spec.json` per selected type (`skill: archify` on the stage file) |
 | `archify-on-pr.task.yaml` | Task bound at run time |
 | `../../scripts/prepare-ci-context.sh` | Deterministic PR/git context + diagram type selection before `sf run` |
 | `../../scripts/validate-detect-envelope.mjs` | Verify helper: `changes.json` / envelope match `ci-context.json` |

package/examples/archify-on-pr/archify-on-pr.pipeline.yaml

@@ -16,4 +16,3 @@ stages:
       include_failed_checks: true
   - id: author-diagrams
     uses: ./author-diagrams.yaml
-    skill: archify

package/examples/archify-on-pr/author-diagrams.yaml

@@ -1,4 +1,5 @@
 id: author-diagrams
+skill: archify
 system_prompt: |
   Author Archify diagram specs for every diagram type selected by detect-changes.
 

package/examples/channels-smoke/README.md

@@ -0,0 +1,12 @@
+# Channels smoke test
+
+Two stages, one channel each: `send-email` sends one email (AgentMail) and then `send-text` sends one text (iMessage via Photon), through the connections on the Connections page. A stage can use one channel, so the two are separate stages. Nothing is sent until you start a run.
+
+1. Connect AgentMail and iMessage on the Connections page. The stage expects the connection ids `agentmail` and `imessage`; if yours differ, edit `connection:` in the two stage files.
+2. Pin your recipients: in `send-email.yaml` replace `to: [change-me@example.invalid]` with your email, and in `send-text.yaml` replace `to: "+10000000000"` with your phone in E.164 form (for example `+14155550123`). On a Free or Pro Photon project the phone must be a project user, and that person must have texted their assigned Photon line once, or the send is rejected.
+3. Change `model:` to one you have a provider for.
+4. Run `sf validate` on the pipeline, then open `channels-smoke` in the console and start it with `channels-smoke-task`. The run checks both connections live before the stage starts.
+
+The Claude agent backend does not provide `send_message`; use a Pi model (the default).
+
+The email subject is `Stageflow channels test`. The agent cannot change recipients, and declaring a second channel on either stage is rejected. A message that may have been sent is never resent: if a call returns `CHANNEL_SEND_OUTCOME_UNKNOWN`, check the provider before running again.

package/examples/channels-smoke/channels-smoke.pipeline.yaml

@@ -0,0 +1,11 @@
+id: channels-smoke
+stages:
+  - id: send-email
+    entry: true
+    uses: ./send-email.yaml
+    replay_safe: false
+    route:
+      - to: send-text
+  - id: send-text
+    uses: ./send-text.yaml
+    replay_safe: false

package/examples/channels-smoke/channels-smoke.task.yaml

@@ -0,0 +1,3 @@
+id: channels-smoke-task
+goal: Send one test email and one test text message through the connected channels.
+constraints: Send exactly one message per channel. Do not resend an uncertain submission.

package/examples/channels-smoke/send-email.yaml

@@ -0,0 +1,32 @@
+id: send-email
+# cursor/auto needs CURSOR_API_KEY on the host. Use another model if you prefer.
+model: cursor/auto
+# A stage uses one channel. Pin the recipient here: the agent can only send to it and cannot change it.
+# `connection` is the id shown on the Connections page.
+channels:
+  - connection: agentmail
+    to: [change-me@example.invalid]
+    operations: [send]
+io:
+  input:
+    schema:
+      type: object
+      additionalProperties: true
+  output:
+    schema:
+      type: object
+      required: [email]
+      properties:
+        email: { type: string, enum: [sent, failed] }
+      additionalProperties: false
+system_prompt: |
+  Send one test email, then report the result.
+  Call send_message once with operationKey "smoke-email", subject "Stageflow channels test"
+  and text "Hello! This email was sent by a Stageflow test pipeline."
+  The recipient is fixed by configuration; never try to choose or change it.
+  If the call is repeated, use the same operationKey and the same content.
+  Never resend an uncertain submission (code CHANNEL_SEND_OUTCOME_UNKNOWN) with a different key.
+  Do not send messages through shell commands or any other tool.
+  Write a short receipt via write_stage_artifact. Do not include secrets.
+  When finished, call emit_stage_envelope exactly once with payload.email set to "sent" or "failed".
+  If the send failed, use status failure.

package/examples/channels-smoke/send-text.yaml

@@ -0,0 +1,31 @@
+id: send-text
+model: cursor/auto
+# One channel per stage. The recipient is a phone number in E.164 form. On a Free or Pro Photon
+# project they must be a project user who has texted their assigned line once.
+channels:
+  - connection: imessage
+    to: "+10000000000"
+    operations: [send]
+io:
+  input:
+    schema:
+      type: object
+      additionalProperties: true
+  output:
+    schema:
+      type: object
+      required: [text]
+      properties:
+        text: { type: string, enum: [sent, failed] }
+      additionalProperties: false
+system_prompt: |
+  Send one test text message, then report the result.
+  Call send_message once with operationKey "smoke-text" and text
+  "Hello! This text was sent by a Stageflow test pipeline."
+  The recipient is fixed by configuration; never try to choose or change it.
+  If the call is repeated, use the same operationKey and the same content.
+  Never resend an uncertain submission (code CHANNEL_SEND_OUTCOME_UNKNOWN) with a different key.
+  Do not send messages through shell commands or any other tool.
+  Write a short receipt via write_stage_artifact. Do not include secrets.
+  When finished, call emit_stage_envelope exactly once with payload.text set to "sent" or "failed".
+  If the send failed, use status failure.

package/examples/conditional-fork/branch-a.yaml

@@ -3,7 +3,7 @@ system_prompt: |
   You are branch-a. Call emit_stage_envelope exactly once with status success,
   a short summary that acknowledges branch-a ran, and artifacts []. Do not call
   ask_operator.
-model: anthropic/claude-sonnet-4-5
+model: cursor/composer-2-5
 io:
   input:
     schema:

package/examples/conditional-fork/decide.yaml

@@ -29,7 +29,8 @@ io:
   output:
     schema:
       type: object
-      required: [branch]
+      required:
+        - branch
       properties:
         branch:
           type: string

package/examples/feature-loop/{implement.yaml → feature-implement.yaml}

@@ -1,4 +1,4 @@
-id: implement
+id: feature-implement
 system_prompt: |
   You are one sequential implementation clone among others. Work the way
   a compound-engineering ce-work run would: execute only your assigned

package/examples/feature-loop/feature-loop.pipeline.yaml

@@ -65,14 +65,14 @@ stages:
     clone_cap: 8
     clone_mode: parallel
     route:
-      - to: plan
+      - to: feature-plan
     on_verify_fail:
       mode: repair
       max_attempts: 3
       retry_safety: idempotent
       include_failed_checks: true
-  - id: plan
-    uses: ./plan.yaml
+  - id: feature-plan
+    uses: ./feature-plan.yaml
     route:
       - to: align
     on_verify_fail:
@@ -85,14 +85,14 @@ stages:
     clone_cap: 8
     clone_mode: sequential
     route:
-      - to: implement
+      - to: feature-implement
     on_verify_fail:
       mode: repair
       max_attempts: 3
       retry_safety: idempotent
       include_failed_checks: true
-  - id: implement
-    uses: ./implement.yaml
+  - id: feature-implement
+    uses: ./feature-implement.yaml
     route:
       - to: verify
     on_verify_fail:
@@ -103,14 +103,14 @@ stages:
   - id: verify
     uses: ./verify.yaml
     route:
-      - to: review
+      - to: feature-review
     on_verify_fail:
       mode: repair
       max_attempts: 3
       retry_safety: idempotent
       include_failed_checks: true
-  - id: review
-    uses: ./review.yaml
+  - id: feature-review
+    uses: ./feature-review.yaml
     route:
       - to: address-feedback
     on_verify_fail:
@@ -123,7 +123,7 @@ stages:
     route:
       - to: publish
       - type: loop
-        to: review
+        to: feature-review
         max_replays: 2
         on_max_replays: wait_for_human
         replay_session: new_session

package/examples/feature-loop/{plan.yaml → feature-plan.yaml}

@@ -1,4 +1,4 @@
-id: plan
+id: feature-plan
 system_prompt: |
   You are one planning clone among others. Write an implementation-ready
   plan for only the story in your assignment envelope. Work the way a

package/examples/feature-loop/{review.yaml → feature-review.yaml}

@@ -1,4 +1,4 @@
-id: review
+id: feature-review
 system_prompt: |
   Review the entire implementation as one change — every story's edits
   together, not per-story. Work the way a compound-engineering

package/examples/feedback-loop/{implement.yaml → feedback-implement.yaml}

@@ -1,4 +1,4 @@
-id: implement
+id: feedback-implement
 system_prompt: |
   Produce the work described by the upstream plan envelope.
   Keep the deliverable short (a brief outline or draft).

package/examples/feedback-loop/feedback-loop-wait-human.pipeline.yaml

@@ -1,23 +1,23 @@
 id: feedback-loop-wait-human
 stages:
-  - id: plan
+  - id: feedback-plan
     entry: true
     route:
-      - to: implement
-    uses: ./plan.yaml
-  - id: implement
+      - to: feedback-implement
+    uses: ./feedback-plan.yaml
+  - id: feedback-implement
     route:
-      - to: review
-    uses: ./implement.yaml
-  - id: review
+      - to: feedback-review
+    uses: ./feedback-implement.yaml
+  - id: feedback-review
     route:
       - to: submit
       - type: loop
-        to: implement
+        to: feedback-implement
         max_replays: 1
         on_max_replays: wait_for_human
         replay_session: resume
-    uses: ./review.yaml
+    uses: ./feedback-review.yaml
   - id: submit
     uses: ./submit.yaml
     replay_safe: false

package/examples/feedback-loop/feedback-loop.pipeline.yaml

@@ -1,23 +1,23 @@
 id: feedback-loop
 stages:
-  - id: plan
+  - id: feedback-plan
     entry: true
     route:
-      - to: implement
-    uses: ./plan.yaml
-  - id: implement
+      - to: feedback-implement
+    uses: ./feedback-plan.yaml
+  - id: feedback-implement
     route:
-      - to: review
-    uses: ./implement.yaml
-  - id: review
+      - to: feedback-review
+    uses: ./feedback-implement.yaml
+  - id: feedback-review
     route:
       - to: submit
       - type: loop
-        to: implement
+        to: feedback-implement
         max_replays: 2
         on_max_replays: require_continue
         replay_session: resume
-    uses: ./review.yaml
+    uses: ./feedback-review.yaml
   - id: submit
     uses: ./submit.yaml
     replay_safe: false

package/examples/feedback-loop/{plan.yaml → feedback-plan.yaml}

@@ -1,4 +1,4 @@
-id: plan
+id: feedback-plan
 system_prompt: |
   Create a short plan for the task goal.
   List the sections you will produce and any open questions.

package/examples/feedback-loop/{review.yaml → feedback-review.yaml}

@@ -1,4 +1,4 @@
-id: review
+id: feedback-review
 system_prompt: |
   Review the upstream work against the task goal.
   On success you MUST include feedback_loop in emit_stage_envelope:

package/examples/generic-fan-in/{research.yaml → fan-in-research.yaml}

@@ -1,4 +1,4 @@
-id: research
+id: fan-in-research
 system_prompt: |
   You are the research branch of a diamond join. Follow these steps exactly:
 

package/examples/generic-fan-in/generic-fan-in-accepted.pipeline.yaml

@@ -3,14 +3,14 @@ stages:
   - id: clarify
     entry: true
     route:
-      - to: research
+      - to: fan-in-research
       - to: validation
     uses: ./clarify.yaml
-  - id: research
+  - id: fan-in-research
     route:
       - to: synthesize
         on: [succeeded, failed, skipped]
-    uses: ./research.yaml
+    uses: ./fan-in-research.yaml
   - id: validation
     route:
       - to: synthesize

package/examples/generic-fan-in/generic-fan-in.pipeline.yaml

@@ -3,13 +3,13 @@ stages:
   - id: clarify
     entry: true
     route:
-      - to: research
+      - to: fan-in-research
       - to: validation
     uses: ./clarify.yaml
-  - id: research
+  - id: fan-in-research
     route:
       - to: synthesize
-    uses: ./research.yaml
+    uses: ./fan-in-research.yaml
   - id: validation
     route:
       - to: synthesize

package/examples/hello-world/{research.yaml → hello-research.yaml}

@@ -1,4 +1,4 @@
-id: research
+id: hello-research
 system_prompt: |
   Summarize the task goal for the given topic and list open questions.
   The topic arrives as task input (and as this stage's io.input payload).

package/examples/hello-world/hello.pipeline.yaml

@@ -1,4 +1,4 @@
 id: hello
 stages:
-  - id: research
-    uses: ./research.yaml
+  - id: hello-research
+    uses: ./hello-research.yaml

package/examples/mcp-hitl-tour/{review.yaml → mcp-hitl-review.yaml}

@@ -1,4 +1,4 @@
-id: review
+id: mcp-hitl-review
 system_prompt: |
   Review brief.md against the task goal.
   On every success you MUST emit feedback_loop send_back — never continue:

package/examples/mcp-hitl-tour/mcp-hitl-tour.pipeline.yaml

@@ -39,9 +39,9 @@ stages:
   - id: polish
     uses: ./polish.yaml
     route:
-      - to: review
-  - id: review
-    uses: ./review.yaml
+      - to: mcp-hitl-review
+  - id: mcp-hitl-review
+    uses: ./mcp-hitl-review.yaml
     route:
       - to: ship
       - type: loop

package/examples/oss-issue-contribution/oss-explain-fix.yaml

@@ -1,4 +1,5 @@
 id: oss-explain-fix
+skill: ce-explain
 system_prompt: |
   Compose fix-explainer.html teaching the operator how the verified working-tree
   change fixes the issue, grounded in real quoted diff lines. This stage is a

package/examples/oss-issue-contribution/oss-explain-issue.yaml

@@ -1,4 +1,5 @@
 id: oss-explain-issue
+skill: ce-explain
 system_prompt: |
   Produce one self-contained teaching artifact, issue-explainer.html, that
   explains this issue from the real checkout. This stage is a side teaching

package/examples/oss-issue-contribution/oss-issue-contribution.pipeline.yaml

@@ -13,7 +13,6 @@ stages:
       include_failed_checks: true
   - id: oss-explain-issue
     uses: ./oss-explain-issue.yaml
-    skill: ce-explain
     on_verify_fail:
       mode: repair
       max_attempts: 3
@@ -85,7 +84,6 @@ stages:
       include_failed_checks: true
   - id: oss-explain-fix
     uses: ./oss-explain-fix.yaml
-    skill: ce-explain
     on_verify_fail:
       mode: repair
       max_attempts: 3

package/examples/stageflow.yaml

@@ -21,6 +21,7 @@ catalog:
     - mcp-hitl-tour
     - feature-loop
     - ship-feature
+    - triggers-readiness
   tasks:
     - generic-fan-in
     - stage-mcp
@@ -42,9 +43,14 @@ catalog:
     - mcp-hitl-tour
     - feature-loop
     - ship-feature
+    - triggers-readiness
+  triggers:
+    - triggers
+    - triggers-readiness/triggers
   patterns:
     pipeline: "*.pipeline.yaml"
     task: "*.task.yaml"
+    trigger: "*.trigger.yaml"
   exclude:
     - route-wiring-smoke-test/rejected
     - stage-mcp/stage-mcp-dead.pipeline.yaml

package/examples/triggers/sample-github-pr.trigger.yaml

@@ -0,0 +1,12 @@
+id: sample-github-pr
+pipeline: hello
+task: my-task
+kind: event
+enabled: false
+event:
+  source: github.pull_request
+  match:
+    action: opened
+  config:
+    repo: tejasghutukade/software-factory
+    secretRef: GITHUB_TOKEN

package/examples/triggers/sample-inbox-email.trigger.yaml

@@ -0,0 +1,14 @@
+id: sample-inbox-email
+pipeline: hello
+task: my-task
+kind: event
+enabled: false
+event:
+  source: email.message
+  match:
+    subject: Invoice
+  config:
+    host: imap.example.com
+    port: 993
+    user: notifications@example.com
+    secretRef: EMAIL_PASSWORD

package/examples/triggers/sample-manual-hello.trigger.yaml

@@ -0,0 +1,5 @@
+id: sample-manual-hello
+pipeline: hello
+task: my-task
+kind: manual
+enabled: false

package/examples/triggers/sample-nightly-hello.trigger.yaml

@@ -0,0 +1,8 @@
+id: sample-nightly-hello
+pipeline: hello
+task: my-task
+kind: schedule
+enabled: false
+schedule:
+  cron: "0 2 * * *"
+  timezone: America/New_York

package/examples/triggers/sample-signed-webhook.trigger.yaml

@@ -0,0 +1,11 @@
+id: sample-signed-webhook
+pipeline: hello
+task: my-task
+kind: event
+enabled: false
+event:
+  source: webhook
+  config:
+    secretRef: WEBHOOK_SECRET
+    header: x-hub-signature-256
+    scheme: hex

package/examples/triggers-readiness/README.md

@@ -0,0 +1,48 @@
+# Triggers readiness smoke catalog
+
+Self-contained catalog for [Triggers readiness](../../docs/triggers-readiness.md). One trigger per checklist row, all targeting the minimal `readiness` pipeline.
+
+| Trigger id | Kind | Default `enabled` | How to test |
+|------------|------|-------------------|-------------|
+| `readiness-manual` | manual | **true** | Triggers → **Fire** (or `sf trigger fire --run readiness-manual` via API id) |
+| `readiness-schedule` | schedule | false | Enable in UI; cron `*/5 * * * *` UTC; needs Host scheduler |
+| `readiness-github-pr` | event (`github.pull_request`) | false | Set `event.config.repo`, enable; needs `GITHUB_TOKEN` on Host |
+| `readiness-webhook` | event (`webhook`) | false | Set `WEBHOOK_SECRET` on Host, enable; `POST /api/triggers/readiness-webhook/webhook` |
+| `readiness-email` | event (`email.message`) | false | Edit IMAP `config`, set `EMAIL_PASSWORD`, enable; restart Host after create |
+| `readiness-dynamic-manual` | manual (no `task`) | false | UI **Fire** disabled; `sf trigger fire readiness-dynamic-manual --task-inline '{"id":"t","goal":"Dynamic smoke"}'` |
+
+## Validate and run pipeline (no trigger)
+
+From the repository root:
+
+```bash
+sf validate --strict \
+  --pipeline examples/triggers-readiness/readiness.pipeline.yaml \
+  --task examples/triggers-readiness/readiness.task.yaml
+sf run \
+  --pipeline examples/triggers-readiness/readiness.pipeline.yaml \
+  --task examples/triggers-readiness/readiness.task.yaml
+```
+
+## Docker Compose
+
+The image copies this tree to `/opt/stageflow/catalog/triggers-readiness` and registers it via `STAGEFLOW_ENSURE_PROJECT_ROOTS`. After `docker compose up --build -d`, open **Triggers** — you should see six `readiness-*` triggers.
+
+Optional `.env` for event triggers:
+
+```bash
+GITHUB_TOKEN=…          # readiness-github-pr
+WEBHOOK_SECRET=…        # readiness-webhook (use a long random string)
+EMAIL_PASSWORD=…        # readiness-email (after you point config at a real mailbox)
+```
+
+Webhook smoke (replace secret and use the trigger id from the console if namespaced):
+
+```bash
+BODY='{"hello":"triggers"}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')
+curl -sS -X POST "http://127.0.0.1:3847/api/triggers/readiness-webhook/webhook" \
+  -H "Content-Type: application/json" \
+  -H "x-hub-signature-256: $SIG" \
+  -d "$BODY"
+```

package/examples/triggers-readiness/readiness-emit.yaml

@@ -0,0 +1,18 @@
+id: readiness-emit
+system_prompt: |
+  You are a trigger smoke-test stage. Reply with one short acknowledgment, then call emit_stage_envelope once with
+  status: success, a non-empty summary, artifacts: [], and payload: { "trigger_test": true }.
+io:
+  input:
+    schema:
+      type: object
+      additionalProperties: true
+  output:
+    schema:
+      type: object
+      required:
+        - trigger_test
+      properties:
+        trigger_test:
+          type: boolean
+      additionalProperties: false

package/examples/triggers-readiness/readiness.pipeline.yaml

@@ -0,0 +1,4 @@
+id: readiness
+stages:
+  - id: readiness-emit
+    uses: ./readiness-emit.yaml

package/examples/triggers-readiness/readiness.task.yaml

@@ -0,0 +1,6 @@
+id: readiness-task
+goal: Acknowledge a triggers-readiness smoke run
+context: Fired from the triggers-readiness catalog bundle (Docker or examples/)
+constraints: One stage only; emit a success envelope
+input:
+  source: triggers-readiness