stageflow 0.25.0 → 0.30.0

package/examples/feature-loop/default-model-hierarchy.task.yaml

@@ -0,0 +1,58 @@
+id: default-model-hierarchy
+goal: >
+  Implement default model resolution across Stageflow YAML layers so a
+  model can be set once on stageflow.yaml or a pipeline and inherited by
+  stages that omit model. Resolution priority must be stage first, then
+  pipeline, then the global stageflow.yaml default. Split the work into
+  stories, plan each story, align the plans, implement them in the agreed
+  order, verify coverage, review the whole diff, address review feedback,
+  and open an operator-approved pull request.
+context: |
+  This repository is Stageflow itself (tejasghutukade/stageflow). The
+  checkout for this run is a dedicated git worktree already on branch
+  scratch/extra-workspace, tracking origin/main.
+
+  Epic (pasted — treat this block as the requirements document):
+
+  Today every stage must declare model (string). Omitting it fails load.
+  There is no pipeline-level or stageflow.yaml default for model. The
+  agent backend already resolves as stage > pipeline > global > "pi";
+  model needs the same shape of hierarchy, without reusing the agent key.
+
+  Required behavior:
+  1. Optional top-level model on stageflow.yaml (global default).
+  2. Optional top-level model on *.pipeline.yaml (pipeline default for
+     all stages in that pipeline).
+  3. Stage model remains allowed on inline stage bodies and external
+     stage YAML, but becomes optional when a higher default can fill it.
+  4. Effective resolution for each stage at load or run time:
+     stage.model ?? pipeline.model ?? stageflow.yaml model.
+     If still unset after that chain, load/run must fail with a clear
+     error — never invent a silent hardcoded model string.
+  5. Priority is always stage override, then pipeline, then global.
+
+  Likely touch points (verify against the tree; do not assume line
+  numbers): src/types/stageflowManifest.ts, src/types/pipeline.ts,
+  src/types for StageConfig, src/config/loadStageflowManifest.ts,
+  src/config load/merge pipeline helpers, src/config/loadStage.ts,
+  resolveAgentPort.ts (pattern to mirror for model, not to conflate),
+  stage worker / adapters that read stage.model, docs/yaml-catalog.md,
+  fixtures under tests/fixtures/, and any create/init surfaces that
+  currently require stage model.
+
+  Keep model (LLM id string) distinct from agent (pi | claude backend).
+
+  - Publish target: tejasghutukade/stageflow
+  - Base branch: main
+  - Head branch: the checkout's current branch (do not create or switch)
+constraints: |
+  Do not create, rename, or switch branches — the checkout is already
+  on the correct feature branch (scratch/extra-workspace).
+  Do not commit, push, or open a pull request except in publish, and
+  only after the operator accepts ship-package.md.
+  Do not expand scope past the epic. Story plans and sequential
+  implement clones must stay inside their assigned slices.
+  Do not change agent-backend resolution semantics except where
+  documentation must clarify that model and agent are separate.
+  publish_repo and base_branch must be the values named here, never guessed.
+checkout: /Users/tejasghutukade/Projects/software-factory/.worktrees/scratch/extra-workspace

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

@@ -0,0 +1,140 @@
+id: feature-loop
+schemas:
+  story-assignment:
+    type: object
+    required:
+      - story_id
+      - title
+      - epic_slice
+      - acceptance
+      - neighboring_story_ids
+      - constraints
+    properties:
+      story_id:
+        type: string
+      title:
+        type: string
+      epic_slice:
+        type: string
+      acceptance:
+        type: string
+      neighboring_story_ids:
+        type: array
+        items:
+          type: string
+      constraints:
+        type: array
+        items:
+          type: string
+  story-work:
+    type: object
+    required:
+      - story_id
+      - title
+      - plan_artifact
+      - order
+      - depends_on
+      - planned_files
+      - validation_commands
+    properties:
+      story_id:
+        type: string
+      title:
+        type: string
+      plan_artifact:
+        type: string
+      order:
+        type: integer
+        minimum: 1
+      depends_on:
+        type: array
+        items:
+          type: string
+      planned_files:
+        type: array
+        items:
+          type: string
+      validation_commands:
+        type: array
+        items:
+          type: string
+stages:
+  - id: decompose
+    uses: ./decompose.yaml
+    entry: true
+    clone_cap: 8
+    clone_mode: parallel
+    route:
+      - to: plan
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: plan
+    uses: ./plan.yaml
+    route:
+      - to: align
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: align
+    uses: ./align.yaml
+    clone_cap: 8
+    clone_mode: sequential
+    route:
+      - to: implement
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: implement
+    uses: ./implement.yaml
+    route:
+      - to: verify
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: verify
+    uses: ./verify.yaml
+    route:
+      - to: review
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: review
+    uses: ./review.yaml
+    route:
+      - to: address-feedback
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: address-feedback
+    uses: ./address-feedback.yaml
+    route:
+      - to: publish
+      - type: loop
+        to: review
+        max_replays: 2
+        on_max_replays: wait_for_human
+        replay_session: new_session
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: publish
+    uses: ./publish.yaml
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting
+    replay_safe: false

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

@@ -0,0 +1,25 @@
+id: feature-loop
+goal: >
+  Implement the epic in the requirements document named in context:
+  split it into stories, plan each story, align the plans, implement
+  them in the agreed order, verify coverage, review the whole diff,
+  address review feedback, and open an operator-approved pull request.
+context: |
+  Point this task at a real checkout already on the feature branch.
+  Name the requirements/epic path (checkout-relative), the publish
+  repository (owner/name), and the base branch.
+
+  Replace the placeholders below before running:
+
+  - Requirements/epic: <path-to-requirements.md>
+  - Publish target: <owner/repo>
+  - Base branch: main
+  - Head branch: the checkout's current branch (do not create or switch)
+constraints: |
+  Do not create, rename, or switch branches — the checkout is already
+  on the correct feature branch.
+  Do not commit, push, or open a pull request except in publish, and
+  only after the operator accepts ship-package.md.
+  Do not expand scope past the epic. Story plans and sequential
+  implement clones must stay inside their assigned slices.
+  publish_repo and base_branch must be the values named here, never guessed.

package/examples/feature-loop/implement.yaml

@@ -0,0 +1,128 @@
+id: 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
+  plan, verify it locally, do not renegotiate scope. Do not commit,
+
+  Your assignment is the clone prior envelope payload: story_id, title,
+  plan_artifact, order, depends_on, planned_files, validation_commands.
+  Clones run in sequential mode. Instance implement~1 starts first;
+  implement~N starts only after ~N-1 succeeded. Earlier clones' checkout
+  edits are already in the working tree. Do not revert, reformat, or
+  rewrite them. Do not implement neighboring stories.
+
+  Reading upstream work: the user prompt contains "Factory run
+  workspace: <absolute path>". Read plan_artifact and aligned-plans.md
+  at <Factory run workspace>/<path>. The assigned story plan outranks
+  any prose summary. That summary describes the previous stage.
+
+  Success requires real checkout edits. Put checkout-relative paths in
+  payload.changed_files. Do not put stages/.../artifacts paths there. A
+  report or map alone is a failure emit, not success.
+
+  Definition of done — every line must hold before you emit success:
+  - git diff in the checkout is non-empty relative to the tree you
+    inherited at the start of this clone (your edits on top of earlier
+    clones). The emit is rejected while you added nothing.
+  - Every changed_files entry is a repo-relative checkout path that
+    appears in git diff --name-only and is in scope of your plan.
+  - Every assigned validation_commands entry was run here, in order,
+    with its exit code recorded, and every one exited zero. all_passed
+    is true only when that is the case.
+  - implementation-report.md was written through write_stage_artifact
+    and appears in the emitted artifacts list.
+  - You did not take files owned by stories later in
+    implementation_order except unavoidable shared seams named in
+    aligned-plans.md.
+
+  1. Run git status --porcelain and git diff --stat. Treat that as the
+     inherited baseline from earlier clones.
+  2. Resolve plan_artifact against the Factory run workspace and read
+     it. If it cannot be read, emit failure — do not re-derive a plan.
+  3. If depends_on names stories whose files are missing from the
+     inherited tree, emit failure naming what is absent.
+  4. Edit only what this story's plan requires, including tests the
+     plan calls for. Match existing style. No drive-by refactors.
+  5. Run every assigned validation_commands entry in order. On failure,
+     diagnose, fix, and re-run until green or emit failure with
+     evidence.
+  6. Call write_stage_artifact with path implementation-report.md
+     containing git diff --stat against the inherited baseline, files
+     you changed, validation results, deviations from the plan, and
+     what later clones should not touch.
+  7. Emit exactly once, including implementation-report.md and
+     inherited evidence, with a payload matching the schema.
+
+  Contract violations — emit failure rather than presenting these as
+  success:
+  - Emitting success while this clone added no checkout diff.
+  - Implementing a later or neighboring story "while you are here".
+  - Reverting an earlier clone's edits.
+  - all_passed: true while any validation_commands entry was skipped
+    or non-zero.
+  - A changed_files entry under stages/.../artifacts/.
+
+  summary and payload are handed to the next stage verbatim. State
+  which story_id landed, which files changed, and that validation
+  passed. Do not repeat this stage's prohibitions in summary.
+
+  When finished, call emit_stage_envelope exactly once with status,
+  summary, artifacts, and a payload matching the schema. Your last
+  tool call in this attempt must be emit_stage_envelope. An empty
+  final message is a stage failure.
+model: cursor/auto
+timeout_ms: 3600000
+io:
+  input:
+    schema:
+      $ref: "#/schemas/story-work"
+  output:
+    schema:
+      type: object
+      required:
+        - story_id
+        - changed_files
+        - implementation_summary
+        - tests_added
+        - commands_run
+        - all_passed
+      properties:
+        story_id:
+          type: string
+        changed_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        implementation_summary:
+          type: string
+        tests_added:
+          type: array
+          items:
+            type: string
+        commands_run:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        all_passed:
+          type: boolean
+verify:
+  - id: implementation-report-declared
+    type: artifact
+    basename: implementation-report.md
+    when:
+      - emit
+  - id: implementation-report
+    type: artifact
+    path: implementation-report.md
+    nonempty: true
+    when:
+      - after
+  - id: checkout-changed
+    type: checkout_changes
+    path_fields:
+      - changed_files
+    when:
+      - after
+gate_kinds: []

package/examples/feature-loop/plan.yaml

@@ -0,0 +1,111 @@
+id: 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
+  compound-engineering ce-plan run would: research the checkout, capture
+  decisions and edit sites, do not implement. Do not edit source, commit,
+
+  Your assignment is the clone prior envelope payload: story_id, title,
+  epic_slice, acceptance, neighboring_story_ids, constraints. That slice
+  is scope. Neighboring stories are being planned in parallel — do not
+  take their files or acceptance.
+
+  Reading upstream work: the user prompt contains "Factory run workspace:
+  <absolute path>". Prior artifacts arrive as run-relative paths; read
+  each at <Factory run workspace>/<artifact path>. epic-split.md is the
+  authoritative partition. Ground the plan in checkout files the slice
+  implies, not the epic text alone.
+
+  Plan quality bar (every item in story-plan.md):
+  - Exact checkout-relative files to touch and the symbol or region at
+    each edit site.
+  - Validation commands copied from this repository's own scripts
+    (package.json or equivalent), never invented.
+  - Test coverage the story needs, named as files or commands, or an
+    explicit reason the story does not add tests.
+  - Dependencies on neighboring stories (data, types, order) called out
+    as planning facts, not as permission to implement them here.
+  - Risks and execution-time unknowns deferred to implement, not guessed.
+
+  Definition of done — every line must hold before you emit success:
+  - story-plan.md was written through write_stage_artifact and appears in
+    the emitted artifacts list.
+  - planned_files and validation_commands are non-empty, concrete, and
+    verified against the checkout.
+  - story_id and title match the assignment.
+  - The plan does not schedule work owned by neighboring_story_ids.
+
+  1. Read the assignment payload, epic-split.md, and the checkout files
+     the slice names.
+  2. Call write_stage_artifact with path story-plan.md containing the
+     approach, edit sites, validation commands, tests, neighboring
+     dependencies, and risks.
+  3. Emit exactly once, including story-plan.md and inherited evidence,
+     with a payload matching the schema. Emit failure if the slice cannot
+     be planned from the checkout (missing files, empty slice, overlap
+     you cannot resolve).
+
+  Required files must be created with write_stage_artifact. Checkout
+  write/edit does not satisfy after-phase verify.
+
+  summary and payload are handed to the next stage verbatim. State
+  outcomes and artifact pointers only: which story_id, which files, which
+  artifact holds the plan. Do not repeat this stage's prohibitions in
+  summary.
+
+  When finished, call emit_stage_envelope exactly once with status,
+  summary, artifacts, and a payload matching the schema. Your last tool
+  call in this attempt must be emit_stage_envelope. An empty final
+  message is a stage failure.
+model: cursor/auto
+timeout_ms: 3600000
+io:
+  input:
+    schema:
+      $ref: "#/schemas/story-assignment"
+  output:
+    schema:
+      type: object
+      required:
+        - story_id
+        - title
+        - planned_files
+        - validation_commands
+        - risks
+        - neighbor_dependencies
+      properties:
+        story_id:
+          type: string
+        title:
+          type: string
+        planned_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        validation_commands:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        risks:
+          type: array
+          items:
+            type: string
+        neighbor_dependencies:
+          type: array
+          items:
+            type: string
+verify:
+  - id: story-plan-declared
+    type: artifact
+    basename: story-plan.md
+    when:
+      - emit
+  - id: story-plan
+    type: artifact
+    path: story-plan.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/feature-loop/publish.yaml

@@ -0,0 +1,167 @@
+id: publish
+system_prompt: |
+  Produce one operator-approved ship-package.md, then — once the
+  operator accepts — commit, push the current branch, and open the
+  pull request in this same attempt. Do not edit source. The checkout
+  is already on the correct feature branch; never create, rename, or
+  switch branches.
+
+  Reading upstream evidence. The user prompt contains "Factory run
+  workspace: <absolute path>". Read coverage.md, review-report.md,
+  review-feedback-report.md, and aligned-plans.md at <Factory run
+  workspace>/<path>. Trust but verify address-feedback: cross-check
+  addressed_all_blocking against the latest review blocking_findings
+  and re-run cited checks rather than accepting the claim.
+
+  publish_repo and the base branch are exactly what the task names.
+  If the task does not name a target repository, emit failure instead
+  of guessing.
+
+  Definition of done, checked before you emit:
+  - ship-package.md was written through write_stage_artifact and
+    appears in the emitted artifacts list.
+  - The latest review verdict is pass, or remaining blockers were
+    addressed and a subsequent review pass recorded pass. Do not ask
+    the operator to approve known-blocking code.
+  - The operator accepted the package through artifact_backed before
+    any git/gh command runs.
+  - After accept: git add, git commit (pr_title), git push -u origin
+    <head_branch>, gh pr create against publish_repo, then gh pr view.
+  - opened is true only if gh pr view confirms the PR exists.
+  - pull-request.md was written through write_stage_artifact and
+    appears in the emitted artifacts list.
+
+  1. Read coverage, the latest review, review-feedback-report.md, and
+     git diff --name-only / git diff --stat / git rev-parse
+     --abbrev-ref HEAD in the checkout.
+  2. Call write_stage_artifact with path ship-package.md: scope, story
+     matrix, files, validation, review verdicts, remaining risks, PR
+     title and body, publish_repo, base_branch, head_branch.
+  3. Fail closed if addressed_all_blocking is false or the latest
+     review still has blockers. Emit failure with the artifact. Do not
+     run publish commands.
+  4. Otherwise ask_operator kind artifact_backed referencing the
+     package. On reject or wording changes: revise and ask again. If
+     the operator wants more code changes, emit failure.
+  5. Only after explicit accept: confirm HEAD is still head_branch,
+     then git add, git commit, git push -u origin <head_branch>,
+     gh pr create --repo <publish_repo> --base <base_branch> --head
+     <head_branch> --title <pr_title> --body <pr_body_summary>. Auth
+     is GH_TOKEN or GITHUB_TOKEN; gh is on PATH.
+  6. Confirm with gh pr view. Write pull-request.md via
+     write_stage_artifact. If a PR already exists for this branch, or
+     any command fails, emit failure and record what happened.
+  7. Emit exactly once, including ship-package.md, pull-request.md,
+     and inherited evidence, with a payload matching the schema.
+
+  After the operator accepts, immediately finish publish side effects
+  in this same attempt, write pull-request.md, then emit. Do not pause
+  after accept. Do not ask_operator for emit/schema errors.
+
+  Required files must be created with write_stage_artifact. Checkout
+  write/edit does not satisfy after-phase verify.
+
+  summary and payload are handed downstream as outcomes: readiness,
+  files, tests, publish target, PR URL. Do not repeat this stage's
+  prohibitions in summary.
+
+  When finished, call emit_stage_envelope exactly once. Your last tool
+  call in this attempt must be emit_stage_envelope (or ask_operator if
+  waiting on HITL). An empty final message is a stage failure.
+model: cursor/auto
+timeout_ms: 3600000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - addressed_all_blocking
+        - fixed_files
+        - verification_commands
+        - remaining_risks
+        - sent_back
+      properties:
+        addressed_all_blocking:
+          type: boolean
+        fixed_files:
+          type: array
+          items:
+            type: string
+        verification_commands:
+          type: array
+          items:
+            type: string
+        remaining_risks:
+          type: array
+          items:
+            type: string
+        sent_back:
+          type: boolean
+  output:
+    schema:
+      type: object
+      required:
+        - pr_title
+        - pr_body_summary
+        - tests
+        - changed_files
+        - publish_repo
+        - base_branch
+        - head_branch
+        - commands_run
+        - opened
+        - pr_url
+      properties:
+        pr_title:
+          type: string
+        pr_body_summary:
+          type: string
+        tests:
+          type: array
+          items:
+            type: string
+        changed_files:
+          type: array
+          items:
+            type: string
+        publish_repo:
+          type: string
+        base_branch:
+          type: string
+        head_branch:
+          type: string
+        commands_run:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        opened:
+          type: boolean
+        pr_url:
+          type: string
+verify:
+  - id: ship-approved
+    type: gate
+    kind: artifact_backed
+    when:
+      - emit
+      - after
+  - id: ship-package-declared
+    type: artifact
+    basename: ship-package.md
+    when:
+      - emit
+  - id: ship-package
+    type: artifact
+    path: ship-package.md
+    nonempty: true
+    when:
+      - after
+  - id: pull-request
+    type: artifact
+    path: pull-request.md
+    nonempty: true
+    when:
+      - after
+gate_kinds:
+  - artifact_backed