flow-workflows 0.81.0 → 0.82.0

package/adapters/opencode/commands/flow-feat-ship.md

@@ -22,6 +22,37 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 
 Closes the feature: commit, push, MR/PR (assigned per `git.assignee`, squash per `git.squash`, sections per `git.request_sections`) and an optional offer to consolidate knowledge.
 
+**In `unattended`** (flow-core §2.1) this command asks nothing, and it is the only place that run
+pushes. Each place it would ask:
+
+- **The MR/PR itself (§3–§4)** — `autonomy.unattended_ship: draft` → skip the confirmation and
+  create it **as draft** with the §2 content (§4.1 says how); never merge it, never mark it ready.
+  The body gains one line saying an unattended run opened it and nobody confirmed its brief.
+  Empty or `stop` → nothing is pushed: question `ship`, the §3 preview as the question, and the run
+  ends; a person ships it from a session of their own. Pre-deploy SQL in the branch → question
+  `migration`, whatever `unattended_ship` says.
+- **The §1 tree check** — `reviewed_sha` or `validated_sha` behind `HEAD` with more than tests →
+  re-run what is behind, **once per MR/PR**: the review on the delta, then `validate`. First record
+  `{ "key": "unattended:ship-recheck", "default": "mr <n>", "phase": "ship" }` in
+  `meta.json.defaults_used[]` — the record, not the context, is what remembers it; an entry with this
+  MR/PR's `n` already there → `blocked`, whatever the sha. Tracked changes this run's own phases left uncommitted → commit them
+  as WIP first (a WIP commit is `auto`'s to make) and check again · **blocking TODO/FIXME (§1)** →
+  continue and list them in the body.
+- **Posting anything else** — the performance comment (§4.3), a contract handoff (§6.3) — → not
+  posted; the numbers go in the body, the handoff stays `pending`.
+- **The offers and surveys (§5, §5.1, §5.2, §5.5, §6.4, §6.4bis)** → `Later`; nothing written outside
+  the work folder.
+- **"Was it merged?" (§6.1)** → not merged; `meta.json` as §6.1 says for an unmerged MR/PR. **The
+  parent merged first (§6.2.1)** → blocked, never force-push. **Train continuation (§6.2)** → not
+  started: one MR/PR per unattended run.
+- **At Close** write the stop file with `reason: "done"`, `mr_url`, and — with `mrs` still pending —
+  `detail` naming the next MR/PR and what it waits on (its `depends_on` merged, then
+  `/flow-feat-build`). It is the last thing the run does.
+
+**In every mode**, criteria `07-validation.md` marks `not-verified-unattended` go into the body under
+`## Not verified — needs a human`, with what to do for each. The §3 preview shows that section like
+any other, and the person reading it is the check the run could not do.
+
 ## 1. Pre-flight
 
 - Read `meta.json` and `00-summary.md`; open in full only the `Brief MR/PR #N` of `05-implementation.md`, the `## Summary`/blockers of `06-review.md` and `07-validation.md`. (flow-core §5)
@@ -133,7 +164,7 @@ Determine whether the branch modifies the database (migrations, mappings/schema,
 
 ## 3. Show the user and wait for confirmation (MANDATORY)
 
-**Never skip this step, even when the content seems obvious.** Hard gate in every mode.
+**Never skip this step, even when the content seems obvious.** Hard gate in every mode — in `unattended`, the unattended paragraph above decides it.
 
 Print to the user in this exact format:
 
@@ -174,7 +205,14 @@ git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null   # must NOT be
 - Train mode (`stacked_on` ≠ null) → the MR/PR must target that parent branch, not the main base.
 
 ### 4.1 Create MR/PR
-Only here — with the content approved in §3 — invoke `Skill commit-commands:commit-push-pr` passing **the final title and description**. The skill must not re-ask for the content; if it does, answer with what was confirmed. Any push it does must be `git push -u origin HEAD` (own branch), never to the base branch.
+**A draft (`unattended`, flow-core §2.1) — read this first: it replaces the invocation below.** Do
+**not** invoke `commit-push-pr`, and do not use the plain CLI fallback below: both open a normal
+MR/PR. Commit, `git push -u origin HEAD`, and create it with the forge CLI and its draft flag
+(`gh pr create --draft`, `glab mr create --draft`, the equivalent elsewhere), assignee and squash as
+below. The forge refusing a draft → `blocked` with its message; never retried without the flag.
+Then record the URL, as the paragraph after the bullets says.
+
+Otherwise, only here — with the content approved in §3 — invoke `Skill commit-commands:commit-push-pr` passing **the final title and description**. The skill must not re-ask for the content; if it does, answer with what was confirmed. Any push it does must be `git push -u origin HEAD` (own branch), never to the base branch.
 
 - `git.assignee` not empty → assign to that user. `git.squash` `true` → enable squash-before-merge.
 - `commit-push-pr` skill unavailable → commit and push manually and create the MR/PR with the `git.cli` CLI from `FLOW.md` — always with the content confirmed in §3.
@@ -467,7 +505,7 @@ Read `meta.json.conventions_candidates[]` (flow-core §8). **No entries with `st
 
 ### 6.4ter Defaults that were used (one line, no question)
 
-`meta.json.defaults_used[]` non-empty → **one line** in the Close: how many empty `FLOW.md` keys this
+`meta.json.defaults_used[]` non-empty (keys prefixed `unattended:` not counted) → **one line** in the Close: how many empty `FLOW.md` keys this
 work resolved with their default, and that `/flow-doctor` lists which ones and prints the line to
 paste. Never a list here, and never a question: in `guided`/`auto` not asking is the contract
 (flow-core §0, §2), and in `manual` the phases already offered what they were allowed to offer.

package/adapters/opencode/commands/flow-feat-start.md

@@ -25,6 +25,20 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 - **Given** — an identifier in `tracker.prefix` format from `FLOW.md` → *ticket mode* (§2 reads it).
 - **Empty** — *ticket-less mode*: do **not** stop or demand a ticket. Draft a ticket from the conversation just held (§2.5), as `/flow-feat-ship` builds the MR/PR body from the work log. Ask for a one-liner only if there is no conversation to draft from.
 
+**In `unattended`** (flow-core §2.1) this command asks nothing; each place it would ask resolves as
+that table says. Here: a ticket is required — empty, or a tracker read that fails, ends the run
+`blocked` (there is no conversation to draft from and nobody to paste it) · uncommitted changes or a
+branch other than the main one (§5.1) → `blocked`: the runner owns the checkout · cross-repo scope
+(§3.5) → only the repos the ticket names · below-XS (§4) → open the work · `git.worktree: ask`
+(§5.0) → in place · §5.5's linked branch → skipped, it pushes a branch and nothing is pushed before
+`ship` · the tracker transition (§6.5) → as `auto`. **Clarifying questions (§2.1 precedence, §3)
+wait until the branch and the work folder exist** — create them (§5, §6) first, write the questions
+into `01-context.md` under "Decisions clarified at start" as open, then question `clarify` with all
+of them in one stop. Whoever picks the work up is asked them by the next phase, first (flow-core
+§2.1).
+A `blocked` before the folder exists still has the stop file: its path does not depend on the folder
+(flow-core §2.1).
+
 ## 1. Pre-flight
 
 - Read the effective FLOW configuration per flow-core §0; neither base nor active overlay → each

package/adapters/opencode/commands/flow-feat-validate.md

@@ -151,12 +151,17 @@ Verify `needs-manual` criteria **together with the user**, one or a few at a tim
    - **Blocked** → status `unproven`; record why. Does not pass the gate.
 4. Repeat until every `needs-manual` criterion is `proven-manually`, or the user decides to stop (the rest stay `unproven`, which blocks advancing in §7).
 
+**In `unattended`** there is nobody to run the check (flow-core §2.1): each `needs-manual` criterion
+gets status `not-verified-unattended` with what a person must do to verify it, and that status does
+**not** block §7 — the MR/PR can only be a draft, and `ship` lists these criteria in its body under
+"Not verified — needs a human". A criterion §3.5 could have driven and did not is still `unproven`.
+
 ## 5. Manual edge cases
 
 If the feature has UI or critical flows:
 - Payments → test with the test cards or credentials the provider publishes for its sandbox (and the harness skill for that provider, if installed).
 - Workers/queues → make sure no jobs are stuck in dead-letter. Stuck jobs that are not yours: do not touch them here.
-- Migrations → run `quality.db_update` from `FLOW.md` (if defined); verify no unexpected schema difference with the comparison command the project uses.
+- Migrations → run `quality.db_update` from `FLOW.md` (if defined; in `unattended`, never — a migration to apply is question `migration`, flow-core §2.1); verify no unexpected schema difference with the comparison command the project uses.
 
 ## 6. Output
 
@@ -210,11 +215,14 @@ Write `.claude/work/<TICKET>/07-validation.md`:
 ## 7. Close
 
 - **Do not advance `phase`** if tests are red, regressions are found, or **any acceptance criterion is `unproven`** (no test demonstrably asserts it, and neither §3.5 nor the user confirmed it). The criterion→test mapping is part of the gate — the same "do not advance on red" rule. The user resolves the gap (add the missing test, fix the implementation, or finish the manual verification) and returns to `/flow-feat-validate`.
-- Suite green **and** every acceptance criterion `proven-by-test`, `proven-by-agent` or `proven-manually` → `phase = "validate"`, add to `phases_done`. **Multi-MR/PR work** → also add `validate` to the current `in_progress` MR/PR's own `phases_done` (its `mrs[]` entry) — the per-MR/PR marker `/flow-feat-ship §1` gates on. Suggest `/flow-feat-ship`.
+- Suite green **and** every acceptance criterion `proven-by-test`, `proven-by-agent` or `proven-manually` (in `unattended`, also `not-verified-unattended`, §4) → `phase = "validate"`, add to `phases_done`. **Multi-MR/PR work** → also add `validate` to the current `in_progress` MR/PR's own `phases_done` (its `mrs[]` entry) — the per-MR/PR marker `/flow-feat-ship §1` gates on. Suggest `/flow-feat-ship`.
 - **Record *what* you validated**, in the same write and only when the phase advances: `validated_sha` = `git rev-parse HEAD`, work-level and in this MR/PR's `mrs[]` entry. `/flow-feat-ship §1` reads it to tell "the suite passed here" from "the suite passed on something else".
 - **Unchecked edge cases and open risks become `followups[]` entries** (flow-core §7) before advancing — see the output template above.
 - **Stage what the validation taught** (`knowledge.stage` set; silence by default): a mutation that stayed green, a disguise the scenario wore, a fixture that could not produce the case — findings about how this codebase is tested, not about this diff. Same rule and evidence line as the review's Close.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
-- **Autonomy handoff — this one stops in every mode, `auto` included.** `ship` pushes and opens the MR/PR: a hard gate in every mode, so do **not** chain into it. Stop here and propose `/flow-feat-ship` with a single `AskUserQuestion` (recommended option by default), invoking it only when the user confirms. This is the deliberate end of the unattended run.
+- **Autonomy handoff — this one stops in every mode, `auto` included.** `ship` pushes and opens the MR/PR: a hard gate in every mode, so do **not** chain into it. Stop here and propose `/flow-feat-ship` with a single `AskUserQuestion` (recommended option by default), invoking it only when the user confirms. This is the deliberate end of a run in `auto`.
+  **In `unattended`** (flow-core §2.1): the phase advanced → chain into `/flow-feat-ship`, which
+  decides from `autonomy.unattended_ship` between a draft MR/PR and a question. It did not advance
+  (red suite, a criterion `unproven`) → `blocked`, naming what failed; never chain.
 
-In `guided`/`auto` this is, together with the brief in `/flow-feat-build §2`, **the only stop of the whole MR/PR** — everything between them ran unattended. It carries the **full stop header** and the body answers, in this order: what is green, what this MR/PR proves and what it does not, and what shipping it takes. Assume the user has read none of the build and review.
+In `guided`/`auto` this is, together with the brief in `/flow-feat-build §2`, **the only stop of the whole MR/PR** — everything between them ran without a person. It carries the **full stop header** and the body answers, in this order: what is green, what this MR/PR proves and what it does not, and what shipping it takes. Assume the user has read none of the build and review.

package/adapters/opencode/commands/flow-init.md

@@ -96,9 +96,10 @@ review, not a questionnaire. Then, and only then, five questions:
    in the confirmation screen, not a question.
 3. **Autonomy** (`autonomy.mode`): `manual` *(Recommended)* — stops at each decision, only recommends
    the next command; `guided` — resolves low-risk decisions and chains phases, asks at the real ones;
-   `auto` — also resolves the rest with recorded defaults. Explain the hard gates that stop in every
-   mode and the list of what `guided`/`auto` never ask (both in the `~/.claude/flow/CORE.opencode.md` §2), so
-   `auto` is genuinely unattended between the brief and `ship`. Editable any time. Empty = `manual`.
+   `auto` — also resolves the rest with recorded defaults. Explain the hard gates that stop in these
+   three modes and the list of what `guided`/`auto` never ask (both in the `~/.claude/flow/CORE.opencode.md` §2),
+   so `auto` runs without a stop between the brief and `ship`. Do not offer `unattended`: it is for a
+   runner, written by hand where only the runner reads it. Editable any time. Empty = `manual`.
 4. **The quality commands as one block** (`quality.test`, `test_one`, `static_analysis`, `style_fix`,
    `db_update`, `db_diff`) — confirm or edit what §2 found, all in one question, each may stay empty
    (= auto-discover at the moment it is needed). Several suites chain into `test` with `&&`.

package/adapters/opencode/commands/flow-work-query.md

@@ -24,7 +24,7 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 
 Invoked by `/flow-feat-review` and `/flow-bug-review` (duel over the diff), `/flow-work-respond` (a reviewer objected to a query), `/flow-feat-design` (access paths), `/flow-feat-build`, `/flow-feat-validate`. Invoke directly for any doubt outside them (chat question, comment on an open MR/PR, a year-old query).
 
-**Autonomy.** Modes as in flow-core §2. The duel, challenger count and whether to measure are flow mechanics — never a question, in any mode. **Hard gates — stop and ask, in every mode:** (1) **creating, seeding or dropping any database, schema or table**, including a throwaway one (§4) — show exact commands and target, never a database the project uses; (2) **any DDL** on a real database (index, column, collation) — the flow's schema gate; (3) editing code (output is a verdict, not a patch); (4) posting anything to an MR/PR or ticket.
+**Autonomy.** Modes as in flow-core §2. The duel, challenger count and whether to measure are flow mechanics — never a question, in any mode. **Hard gates — stop and ask, in every mode:** (1) **creating, seeding or dropping any database, schema or table**, including a throwaway one (§4) — show exact commands and target, never a database the project uses; (2) **any DDL** on a real database (index, column, collation) — the flow's schema gate; (3) editing code (output is a verdict, not a patch); (4) posting anything to an MR/PR or ticket. **In `unattended`** (flow-core §2.1) (1) and (2) are never done: the verdict is schema-only and says so; (3) and (4) do not apply, this command never edits or posts.
 
 ## 1. Resolve the subject
 

package/adapters/opencode/commands/flow-work-resume.md

@@ -20,7 +20,11 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, au
 
 **Panel words are closed** — `mark`: `done` · `current` · `pending` · `wait` · `block` · `info`; `style`: `normal` · `dim` · `title` · `accent` · `ok` · `warn` · `error`. Anything else is dropped by the reader in silence: the panel still paints, and nobody is told.
 
-Use when returning to a work after a break (next morning, another session).
+Use when returning to a work after a break (next morning, another session) — including a work an
+unattended run left waiting on a person (flow-core §2.1).
+
+**In `unattended`** this command asks nothing: recap, name the next step, end. It is how a person
+reads where the run got to, not how the run continues.
 
 ## 1. Detection
 
@@ -43,6 +47,7 @@ Last updated:   <updated_at>
 Notes:          <meta.notes>
 Cross-repo:     <meta.related_repos entries not "done", as "repo: scope"; or "—">
 Ticket thread:  <new since <updated_at>: <n> comment(s) that change the work — detailed below · or "nothing new" · or "not read">   (line only in ticket mode, from §2.5)
+Unattended:     <from `.claude/work/stop.json` when its `work` is this one: `question` → the gate and the question, verbatim, with its options · `blocked` → the detail · `running` → "a run is working in <phase>, or died there, at <at>" · `done` → the MR/PR · `picked_up` → omit the line>   (line only when that file names this work)
 ```
 
 - `MR/PRs:` and `Waves:` from `meta.json.mrs` (same format as `/flow-work-status §2`). `∥` = can run in parallel, `→` = waits for the previous wave to merge.
@@ -84,6 +89,7 @@ With what is new (there is already work on disk):
 
 ## 4. Next step
 
+- A pending `question` in the `Unattended:` line → say that the next phase will ask it first (flow-core §2.1); the next step itself comes from `phase` as always.
 - Suggest the concrete command from `phase` and `size`. Interrupted phase (e.g. `build` with an empty artifact) → suggest rerunning it with `/flow-feat-build` or `/flow-bug-fix`.
 - §2.5 found something new → let it inform the suggestion (a contract that arrived after you left may mean rerunning `design` rather than continuing `build`); say why in one line.
 - `meta.json.related_repos` entries not `done` → remind that a **sibling repo still has a pending part** (`<repo>: <scope>`, plus `contract not handed over` when its `contract_handoff` is `pending`); suggest `/flow-feat-start <TICKET>` there. flow only reminds; it never scans or touches the other repo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-workflows",
-  "version": "0.81.0",
+  "version": "0.82.0",
   "description": "Guided feat/bug workflows (start→ship), post-deploy monitoring and multi-agent code review, stack-agnostic. Each repo uses a shared FLOW.md plus optional harness overlay.",
   "type": "module",
   "bin": {

package/plugins/flow/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "flow",
   "displayName": "Flow — guided dev workflows",
   "description": "Guided feat/bug workflows (start→ship), post-deploy monitoring and multi-agent code review, stack-agnostic. Each repo uses a shared FLOW.md plus optional harness overlay.",
-  "version": "0.81.0",
+  "version": "0.82.0",
   "author": {
     "name": "Alberto Vioque",
     "email": "mashware@gmail.com"

package/plugins/flow/CHANGELOG.md

@@ -5,6 +5,28 @@ plugin and is what `/flow:news` reads to show you what changed since your previo
 
 The canonical, richest notes live in the [GitHub Releases](https://github.com/mashware/flow-workflows/releases).
 
+## v0.82.0 — Nobody at the terminal, and the run still gets somewhere  ·  2026-09-29
+
+**In short**
+- **A new autonomy mode, `unattended`, for runs nobody watches** — a script, a container, a headless
+  CLI. It behaves like `auto` and never asks. Before, such a run stopped for good at the first hard
+  gate: the brief, a serious review finding, `ship`, or any question left in prose for nobody.
+- **It goes as far as it can without a person, and says exactly where it needs one.** The business
+  brief is written down and travels in the MR/PR body. `ship` opens a **draft** MR/PR only with
+  `autonomy.unattended_ship: draft` — never merged, never marked ready, never force-pushed. A
+  migration, serious review findings, a product decision or a doubt about the ticket end the run with
+  the question and its options in `.claude/work/stop.json`; a checkout or ticket the run cannot use
+  ends it as `blocked`. Nothing that protects the repo is approved in silence.
+- **A runner reads one file.** `.claude/work/stop.json` says `running` while a phase works (left
+  behind = the run crashed), then `question`, `blocked` or `done` with the MR/PR. While a question is
+  pending no new unattended run goes past it. A person picks the work up in their own session:
+  `/flow:work:resume` shows the question, the next phase asks it first, and the file then says
+  `picked_up`. Keep `unattended` in a FLOW file only the runner's environment reads.
+- **One MR/PR per run**, and only when written by hand: `unattended` is never inferred from a
+  headless harness, `/flow:init` does not offer it, and `manual`, `guided` and `auto` are unchanged.
+
+Asked for in #168. Continuing a run automatically from an answer is not in this release.
+
 ## v0.81.0 — The review stopped contradicting itself  ·  2026-09-26
 
 **In short**

package/plugins/flow/examples/FLOW.template.md

@@ -89,7 +89,7 @@ Branch and Pull/Merge Request conventions.
 ## autonomy
 How much the flow advances on its own vs. stopping to ask you.
 
-- `mode:`             # `manual` (default) | `guided` | `auto`. Empty = `manual`.
+- `mode:`             # `manual` (default) | `guided` | `auto` | `unattended`. Empty = `manual`.
                       #   manual — every phase stops at each decision point and, at the end, proposes the
                       #            next command as a one-click confirmation (you accept to advance, it is
                       #            never typed for you and never runs without your confirmation).
@@ -99,7 +99,12 @@ How much the flow advances on its own vs. stopping to ask you.
                       #            automatically (no advance confirmation).
                       #   auto   — as guided, plus auto-resolves the remaining decision points with sensible
                       #            (recorded) defaults, chaining phases without pausing.
-                      # HARD GATES stop and ask in EVERY mode, no exceptions: any push or MR/PR (ship),
+                      #   unattended — as auto, for a run nobody watches (script, container, headless CLI):
+                      #            never asks; each hard gate is recorded, becomes a draft MR/PR, or ends
+                      #            the run with a question in .claude/work/stop.json for a runner to
+                      #            post and a person to pick up. One MR/PR per run. Only when set explicitly —
+                      #            in a FLOW file only the runner's environment reads.
+                      # HARD GATES stop and ask in manual/guided/auto, no exceptions: any push or MR/PR (ship),
                       # branch creation with an ambiguous base, DB schema changes/migrations, a review
                       # with high-severity findings, and the business brief confirmed just before the
                       # first edit in `build`/`fix`.
@@ -107,6 +112,10 @@ How much the flow advances on its own vs. stopping to ask you.
                       # (panels, challengers, how many reviewers), WIP commits, continuing a train when
                       # the train's next MR/PR in `guided`/`auto`, size confirmation, and anything already decided
                       # and recorded — only new contradicting evidence reopens a settled decision.
+- `unattended_ship:`  # What `ship` does in `unattended`: `draft` | `stop`. Empty = `stop`.
+                      #   draft — push the work branch and open the MR/PR as draft; never merge, never ready.
+                      #   stop  — nothing is pushed; ship ends the run with a question in stop.json.
+                      # Read only when mode is `unattended`.
 
 ## quality
 Repo commands for quality gates, whatever the stack — `make test`, `./gradlew test`, `dotnet test`,
@@ -256,7 +265,7 @@ subagent ignores the value and the step says so once, in one line.
               #   brings back status plus evidence — job names, exit codes, log tail, run URL — and never
               #   rules on it: triage and the merge verdict stay on the main thread whatever this says.
               #   Empty = falls back to `agents`, then to what the command runs on, and the dispatch says so
-              #   in one line — an unattended wait is the one place an unpriced default runs longest.
+              #   in one line — an unwatched wait is the one place an unpriced default runs longest.
 
 **Three keys, one per kind of subagent — not one per kind of step.** There used to be five —
 `study`, `code`, `test`, `review` — named after phases. They promised a granularity no harness