flow-workflows 0.80.0 → 0.82.0

package/adapters/codex/skills/flow-feat-build/SKILL.md

@@ -31,9 +31,9 @@ Implementation phase. Code is written here.
 - `size` XS/S: may start without a design — ask the user for a 2-3 line note on what will be done and save it as a minimal `03-design.md`. No MR/PR plan (always 1 MR/PR).
 - **If `meta.json.mrs` has more than one entry**: pick the **startable** MR/PR — the `pending` one with the **lowest `n` whose `depends_on` are all `merged`**. Dependencies still `pending`/`in_progress` → not startable, even with a low `n`. (No `wave`/`depends_on` — an older plan — → "first pending by `n`".)
   - **Parallel siblings**: startable `pending` MRs/PRs in the **same `wave`** with no dependency between them can be built in parallel or as a train. `manual`: let the user choose which to take now (default: lowest `n`); `guided`/`auto`: take the lowest `n`, record the choice. Mark the chosen one `in_progress`.
-  - All `merged` → warn: feature is done, nothing to build.
-  - Some `pending` but **none** startable → start nothing: tell the user which MR/PR must merge to unlock the next wave, and stop.
-  - **Train/stacked**: this MR/PR needs its own branch stacked on the previous one — do **not** keep committing on the previous MR/PR's branch. `$flow-feat-ship §6.2` creates and links it when it chains here; if you arrived directly and are still on the previous branch, create it now per `$flow-feat-start §5` (explicit base = the previous MR/PR's branch, `--no-track`, worktree per `git.worktree`) and, for `tracker.tool: gh`, the linked-branch step `$flow-feat-start §5.5`. Record `stacked_on` in `meta.json`. The train does **not** wait for the previous MR/PR to merge.
+  - All `merged` → warn: feature is done, nothing to build (in `unattended`: `done`, `detail` saying so).
+  - Some `pending` but **none** startable → start nothing: tell the user which MR/PR must merge to unlock the next wave, and stop. In `unattended`: `blocked`, the detail naming it.
+  - **Train/stacked** (never in `unattended`: there the startable MR/PR gets a **new branch of its own** from `git.default_base`, created as `$flow-feat-start §5.2` (in place) or `§5.4` (worktree) says — `git.worktree: always` → worktree, `off`/empty/`ask` → in place; base `git.default_base`, already decided, so §5.1 asks nothing; `--no-track`, no linked remote branch — and never commits onto a previous MR/PR's branch; flow-core §2.1): this MR/PR needs its own branch stacked on the previous one — do **not** keep committing on the previous MR/PR's branch. `$flow-feat-ship §6.2` creates and links it when it chains here; if you arrived directly and are still on the previous branch, create it now per `$flow-feat-start §5` (explicit base = the previous MR/PR's branch, `--no-track`, worktree per `git.worktree`) and, for `tracker.tool: gh`, the linked-branch step `$flow-feat-start §5.5`. Record `stacked_on` in `meta.json`. The train does **not** wait for the previous MR/PR to merge.
 
 ## 2. Business brief (before typing)
 
@@ -63,6 +63,12 @@ Rules for writing it:
 
 In `auto` this is one of the only two stops per MR/PR (`guided` adds the plan of §2.0ter on a big one), so it carries the **full stop header** (flow-core §3) — ticket, size, phase, `MR #<n> of <N>`, plan state — followed by the brief.
 
+In `unattended` (flow-core §2.1) nobody is there to answer: write the brief, mark it
+`recorded (unattended)` under its heading, record the site in `meta.json.defaults_used[]`, and build.
+The gate's purpose moves to the draft MR/PR, whose body carries the brief for the person who reads it.
+**A schema change or migration is still a question** (`migration`): before writing the first line
+of one → stop file, end the run. A person continues from there.
+
 **The brief travels inside the question** (flow-core §3): the user reads it in the prompt they are answering, never by opening `05-implementation.md`. Write the file, run whatever you need, and *then* open the gate — **nothing runs between the brief and the question**, because a tool call after it is what lets a terminal fold the brief into one collapsed line, and the gate is answered blind. Options:
 - **Yes, proceed** → start building.
 - **No, something is extra or missing** → the user clarifies, adjust the brief, ask again. **Do not touch code** until the brief is confirmed.
@@ -186,7 +192,7 @@ said in one line, never silently skipped. `manual` → offer it with `AskUserQue
 premise that X before building on it?"). `guided`/`auto` → run it and record it; it is flow
 machinery, not a decision.
 
-**The verdict, and the rule that makes it worth running.** **Refuted** → the brief or the design is
+**The verdict, and the rule that makes it worth running** (in `unattended`, *Refuted* ends the run as `blocked`, flow-core §2.1). **Refuted** → the brief or the design is
 wrong, not the code: stop, say what fell, and go back (§2.4 for a brief, `$flow-feat-design` for a
 contract) rather than patching around it. **Holds** → one row in §3 with what was read. **Unsettled
 stays unsettled** — the same rule as the query duel's *no number, no win*: it is recorded as an open
@@ -256,7 +262,7 @@ Warning thresholds:
 - **Real lines > `lines_est * 1.5`**, or
 - **Real files > `files_est + 2`**.
 
-If either is exceeded, **pause** and ask the user with `AskUserQuestion` (options, in this order):
+If either is exceeded, **pause** and ask the user with `AskUserQuestion` (options, in this order — in `unattended`, take option 2 and record it):
 
 1. **Cut here (recommended if the current piece is coherent)**. What is built so far stays as this MR/PR; what remains — the §2.0ter steps still pending, or what is left of `04-mr-plan.md` where that step was skipped — goes into a new one inserted in `meta.json.mrs` right after. Zero code wasted.
 2. **Continue and record the overrun**. When the cut would be artificial. Note the deviation in `05-implementation.md` to calibrate `$flow-feat-plan` on future tickets.
@@ -283,7 +289,7 @@ slip under a threshold buys itself the review a smaller change had earned.
 
 ### 2.4 Does something fall outside the brief?
 
-If during the build the temptation arises to add something **not in the §2 brief** ("while I'm here…", "this test would also cover X…", "this rename would improve Y…"), **pause before doing it** and ask the user with `AskUserQuestion`:
+If during the build the temptation arises to add something **not in the §2 brief** ("while I'm here…", "this test would also cover X…", "this rename would improve Y…"), **pause before doing it** and ask the user with `AskUserQuestion` (in `unattended`: *No, leave it out*, recorded):
 - **Yes, add it to the brief** — update the brief in `05-implementation.md` and continue. (If the addition is large, consider §2.3: it could trigger a MR/PR cut.)
 - **No, leave it out** — note it in the "Ideas for separate tickets" section of `05-implementation.md` **and append it to `meta.json.followups[]`** as `kind: "out-of-scope"`, `source: "build"` (flow-core §7): the section keeps it in context, the record is what survives the archive. **Only when it clears the bar of flow-core §7** — a named subject, a path that has actually been seen, and waiting costing more than doing it now; short of that the artifact section keeps it and `followups[]` never sees it. Continue with the original brief.
 

package/adapters/codex/skills/flow-feat-design/SKILL.md

@@ -24,10 +24,16 @@ Read `~/.claude/flow/CORE.codex.md` first (shared rules: `FLOW.md` step 0, model
 
 Technical design phase. **Still no production code is written.** Opens the option space first (M/L), then designs the approach that was chosen. Output: a plan the next step executes.
 
+**In `unattended`** (flow-core §2.1) this command asks nothing. Panel and approach choice run as in
+`auto` · questions the options surfaced (§1.5.5) or an acceptance criterion that is ambiguous (§9) →
+question `clarify` · a size that no longer fits (§1.5.5, §7) → record the new size · a `high`
+challenge with no response (§6) → question `design_challenge`, the findings and their options in the
+stop file · the design review (§9) → recorded as accepted, as in `auto`.
+
 ## 1. Pre-flight
 
 - Load `meta.json` by current branch. Missing → ask the user to start with `$flow-feat-start`.
-- Read `meta.json` and `00-summary.md`; open in full only `01-context.md` (ticket, decisions, contracts received), and `02-brainstorm.md` when a work started before v0.53.0 has one — its options are §1.5's output, already done. (flow-core §5)
+- Read `meta.json` and `00-summary.md`; open in full only `01-context.md` (ticket, decisions, contracts received). (flow-core §5)
 - `size` is `XS` → suggest jumping to `$flow-feat-build` and stop unless the user insists.
 
 ## 1.5 Approaches — open the option space first (M/L)
@@ -36,9 +42,6 @@ Design that starts from the first idea is design that never had a second one. **
 section; XS and S skip it** and go straight to §2 — the cost does not pay on a change whose shape is
 obvious.
 
-*(This was the `feat:brainstorm` command until v0.53.0: a command whose whole output only this one ever
-read.)*
-
 **No code, and no design yet.** The output of this section is a ranked set of options and one chosen
 approach; §3 onwards designs *that* approach.
 

package/adapters/codex/skills/flow-feat-review/SKILL.md

@@ -40,7 +40,7 @@ Mandatory review phase. **`$flow-feat-ship` cannot run without passing through h
   member runs its own `git diff` and opens the same files pays for that material once per agent, and
   a reviewer that spends its turns exploring has fewer left to review. **Any non-zero exit is a
   fallback, not a failure** — no CLI on the machine, a base that does not resolve, a network that
-  cannot reach it: read the diff from git as before and carry on, once, without retrying variants.
+  cannot reach it: read the diff from git and carry on, once, without retrying variants.
   What is not optional is the `Review path` line of §8: a round that skipped the pack and one that
   used it are indistinguishable from the artifact otherwise, which is how a phase quietly stops
   paying for itself.
@@ -69,7 +69,7 @@ Mandatory review phase. **`$flow-feat-ship` cannot run without passing through h
 
 ### 1.5 Freeze what you are about to read, and resolve what to compare it against
 
-Two questions, answered here and nowhere later: **which tree** this round reads, and **against which base**. Both used to be answered implicitly — by the checkout as it happened to stand at each moment, and by `git.default_base` always — and both answers were wrong in a way no artifact could show.
+Two questions, answered here and nowhere later: **which tree** this round reads, and **against which base**. Neither is implicit: the checkout changes while the round runs, and `git.default_base` is not always the right base.
 
 **The candidate.** A round applies its own fixes; the README's own first-minute example is *"3 reviewers, one finding — fixed"*. So "the working tree" is a different tree for the reviewer that read it first, for the skeptic that read it last, and for the `git rev-parse HEAD` taken at §9 — which by construction contains code no reviewer ever saw, and which `$flow-feat-ship §1` then compares against `HEAD` and finds equal. Resolve one revision before §2 launches anything:
 
@@ -79,11 +79,11 @@ Two questions, answered here and nowhere later: **which tree** this round reads,
 - Anchor it so it cannot be collected: `git update-ref refs/flow/candidate/<TICKET> <sha>`. A `stash create` object is unreferenced, and a candidate the `ship` gate cannot resolve is a gate that reports nothing. The ref is local, never pushed, and `$flow-feat-ship §6.5` deletes it.
 - Write `candidate_sha` to `meta.json` — work-level and in the current `mrs[]` entry — **in this pre-flight**. A candidate recorded after the reading is not a freeze.
 
-**The review base.** `reviewed_sha` already records the tree the last passing review read, and `ship` trusts it enough to stop a push — yet the review itself never read it, so a second review re-reads every line the first one cleared, and §2.0 resolves the tier on the accumulated total: a 30-line delta on a 900-line branch reviewed as the 900. Resolve:
+**The review base.** `reviewed_sha` records the tree the last passing review read, and `ship` trusts it enough to stop a push. Reading only the delta since it keeps a second review from re-reading every line the first one cleared, and keeps §2.0 from resolving the tier on the accumulated total — a 30-line delta on a 900-line branch is a 30-line review. Resolve:
 
 - The current MR/PR's `reviewed_sha` (work-level when there is no train) when it is **non-empty** and **an ancestor of the candidate** (`git merge-base --is-ancestor <sha> <candidate>`) → that is the base.
 - Otherwise `git.default_base`. A `reviewed_sha` that is not an ancestor means history was rewritten or the branch recut; say so in one line rather than producing a nonsensical delta.
-- **A first review has no `reviewed_sha` and reads the whole branch**, exactly as before. The delta path only exists after a review that passed.
+- **A first review has no `reviewed_sha` and reads the whole branch**. The delta path only exists after a review that passed.
 - `$flow-feat-review --full` ignores `reviewed_sha` and reads the branch on demand.
 - **Fall back to `git.default_base` and say why** when either holds, because a delta cannot see how it interacts with what was cleared before: the delta touches a file the previous review left a finding on, or it changes an external contract copied under `$flow-feat-build §2.0bis`.
 
@@ -97,7 +97,7 @@ Scope for every reviewer: **the candidate revision of §1.5, against the review
 
 **The CLI resolves it; you obey the output and record any deviation.** `npx flow-workflows@<version> tier --harness codex --rev <candidate_sha> --base <review base>` prints, from the config it already parses: changed lines over the §1.5 range, diff size, `meta.json.size`, **effective size** (the lower of the two), the built-in `code-review` effort with and without the sensitive-surface bump, whether the panel runs, the resolved `agents.budget_max`/`fanout_max`, whether the measurement landed **within 10% under** a threshold that changed the tier, and which `quality.sensitive_paths` globs the diff matched, with the path that matched each.
 
-Every step of that is arithmetic, and the cost of leaving it here was never mainly the tokens: `06-review.md` recorded the tier *this agent said it derived*, so a round that eyeballed the diff and a round that measured it wrote a byte-identical artifact — on the one number in this command that carries an incentive on it. Same treatment `Review path` and `Cost:` already got, for the same reason.
+Every step of that is arithmetic. A tier this agent derives itself writes the same artifact whether it measured the diff or eyeballed it — on the one number in this command that carries an incentive on it.
 
 **Copy the output verbatim** into the `Review tier` and `Effective size` lines of §8, the way `bundle --checks` copies static analysis out. A computed line, not a narrated one.
 
@@ -107,7 +107,7 @@ Every step of that is arithmetic, and the cost of leaving it here was never main
 - **Whether a matched path is a sensitive *diff*.** The bump asks what the change *does* there, not where it lives: it applies to **control flow, or the data that reaches a person, a charge or a stored record** — a new guard, a new `catch`, a changed condition, a changed value, a changed contract. It does **not** apply when the diff moves **observability alone**: a log level, a channel, a message's text, a metric, a comment. Mixed diff → not observability-only, so it bumps. **Say which of the two it was in one line**; a diff demoted here is the one place a missed defect is expensive.
 - **Query changes.** §3.6 duels every query the diff adds or modifies, at every size, whatever this section resolved — routing them through the bump buys a second opinion on prose where §3.6 buys a plan.
 
-**No CLI, or a non-zero exit → the prose fallback**, and `Review path` names it with the reason (the same contract the panel follows). Measure `git diff --shortstat <review base>...<candidate_sha>`; **≤150 → XS · 151-600 → S · 601-1500 → M · >1500 → L**; effective size = the lower of that and `meta.json.size`; `proportional` runs the built-in at **medium/high/high/xhigh** by size and the panel at M and above (at S only on a sensitive surface); the bump raises the effort one tier (medium→high→xhigh→**max**) and always runs the panel; `full` is **xhigh** plus the panel at any size, `light` is the built-in alone at **medium** with no panel, no §3 and no §6 — and a sensitive surface lifts `light` to the proportional tier for that work. The thresholds and the ladder are documented in `docs/CONFIGURATION.md`, where they can be read without being re-taught to a model on every invocation.
+**No CLI, or a non-zero exit → the prose fallback**, and `Review path` names it with the reason (the same contract the panel follows). Measure `git diff --shortstat <review base>...<candidate_sha>`; **≤150 → XS · 151-600 → S · 601-1500 → M · >1500 → L**; effective size = the lower of that and `meta.json.size`; `proportional` runs the built-in at **medium/high/high/xhigh** by size and the panel at M and above (at S only on a sensitive surface); the bump raises the effort one tier (medium→high→xhigh→**max**) and always runs the panel; `full` is **xhigh** plus the panel at any size, `light` is the built-in alone at **medium** with no panel, no §3 and no §6 — and a sensitive surface lifts `light` to the proportional tier for that work.
 
 **The diff pointing *higher* than `meta.json.size`** is worth one line in `06-review.md` (the work may be misclassified), never a heavier review. **The sensitive-surface bump is never scaled away** — a 12-line change to an authorization check still gets the panel, on a delta exactly as on a first review.
 
@@ -156,7 +156,7 @@ Launch the reviewers selected in §2.0 and **consolidate their findings into a s
 
 When both run, deduplicate overlapping correctness/simplification findings (count each once). The `review_skill` specialists (offensive/defensive security, silent failures, architecture) are not repeated in later phases.
 
-**Dedup keeps every source, not the first one.** A finding carries its **origin** from here to §8 — `built-in`, a panel role, or the pass that raised it (`§3.5`, `§3.6`, `§5`, `§5.5`) — and a finding more than one source raised lists all of them. Counted once, credited to each. Beyond the built-in and the panel this command runs four specialised passes, roughly 1 800 of its words, every one added after a real defect got through and not one able to show it still earns that cost: a finding only the idiom audit saw and a finding three sources raised say opposite things about that pass, and until now both were written identically. The `Cost:` line stopped being a headcount when `meta.json.cost[]` arrived; this is the same move for the thing those costs are spent on.
+**Dedup keeps every source, not the first one.** A finding carries its **origin** from here to §8 — `built-in`, a panel role, or the pass that raised it (`§3.5`, `§3.6`, `§5`, `§5.5`) — and a finding more than one source raised lists all of them. Counted once, credited to each: a finding only one pass saw and a finding three sources raised say opposite things about that pass, and §9 records the difference.
 
 ### 2.2 Design truth vs design rationale (do not inherit rationalizations)
 `03-design.md` goes to reviewers as context, with unequal authority:
@@ -175,7 +175,7 @@ Only what §2 does **not** already cover; skipped entirely under `light` (§2.0)
 
 ## 3.5. Completeness sweep (anti-abandonment, M/L only)
 
-Counters a reviewer abandoning a large diff early. **Only if `meta.json.size` is M or L**, and only
+Counters a reviewer abandoning a large diff early. **Only if the effective size of §2.0 is M or L**, and only
 if §2.0b's budget still covers it (it is the first phase dropped).
 
 **It runs after §2-§3 are consolidated, never in parallel with them.** The whole phase is an audit of
@@ -267,7 +267,7 @@ Findings enter the normal flow: §6, then the output. Blinded for the same reaso
 
 A filter against over-reporting, not a second review; narrow gate. Never runs under `light` (§2.0).
 
-**When it runs.** All three conditions:
+**When it runs.** All four conditions:
 
 | Condition | Threshold |
 |---|---|
@@ -276,7 +276,7 @@ A filter against over-reporting, not a second review; narrow gate. Never runs un
 | Findings | **≥ 4** ambiguous findings across §2-§5 |
 | Budget | §2.0b's budget still covers a round (§6 is the second phase dropped) |
 
-Read the real diff (`git diff --stat` against the target branch), not the recorded size.
+Read the real diff (`git diff --stat <review base>...<candidate_sha>`, §1.5), not the recorded size.
 
 When all three hold: in **`manual`**, offer it with `AskUserQuestion` ("Verify the ambiguous findings with skeptics in parallel? Discards false positives before you go fix them."). In **`guided`/`auto`, do not ask** — flow mechanics: run it and note in `06-review.md` that you did.
 
@@ -356,7 +356,7 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 ## Discarded by adversarial verification
 <only if §6 was run; list of refuted findings with reason, or "not applicable">
 <if the `fanout_max` cap left ambiguous findings unverified, list them here as "unverified (cap)">
-<if §6 did not run, one line saying which condition did not hold — size, diff size, or count>
+<if §6 did not run, one line saying which condition did not hold — size, diff size, count, or budget>
 
 ## Blockers (must-fix)
 1. [file:line] · <origin> · description + concrete proposal
@@ -379,14 +379,16 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 - Blockers → **do not advance `phase`**. Leave `phase = "build"`; the user resolves them.
 - No blockers → `phase = "review"`, add to `phases_done`. **In a multi-MR/PR work**, also add `review` to the current `in_progress` MR/PR's own `phases_done` (its `mrs[]` entry) — `$flow-feat-ship §1` gates on it per MR/PR.
 - **Record *what* you reviewed, and separately what you changed after reading it**, in the same write, work-level and — in a multi-MR/PR work — in this MR/PR's `mrs[]` entry too:
-  - `reviewed_sha` = **the candidate of §1.5**, the revision the reviewers actually read. Not `git rev-parse HEAD`, which is what it used to be and which by then holds this round's own fixes — code no reviewer saw, recorded as reviewed, and `ship` finding it equal to `HEAD` every time.
-  - `fixed_sha` = `git rev-parse HEAD` after this round's fixes, or **empty** when the round applied none. Two fields because they are two facts, and collapsing them is what hid the delta.
+  - `reviewed_sha` = **the candidate of §1.5**, the revision the reviewers actually read. Not `git rev-parse HEAD`, which by then holds this round's own fixes — code no reviewer saw, recorded as reviewed, and `ship` finding it equal to `HEAD` every time.
+  - `fixed_sha` = `git rev-parse HEAD` after this round's fixes, or **empty** when the round applied none. Two fields because they are two facts.
   - `phases_done` says a review *happened*; these say which tree, and `$flow-feat-ship §1` reads both before pushing. Written whenever the phase advances, never when it does not: a review that ended in blockers reviewed nothing that stands.
 - **Record which pass found what**, in the same write: `meta.json.review_findings[]`, one entry per finding **per source** — `{ round, origin, severity, file, discarded_by_skeptic }`, and no finding text, which stays in the artifact. `flow review --record` writes these itself when the CLI ran the panel; when the agentic panel ran, write them here from the origins §2.1 carried. `flow cost` reads them back per origin: how many findings each pass contributed, how many only it raised, and how many of those survived §6. That last number is the only evidence a pass is still earning its words.
-  **The retirement rule, written down before the data arrives** so it cannot be argued backwards later: a pass that contributes **no exclusive surviving finding across twenty reviews** is removed from this command. Zero is zero, and the decision is made against the number rather than against whoever is most attached to the pass.
-- **Stage what the review taught** (`knowledge.stage` set; silence by default). Review is where a project teaches the most and, until now, the one phase that never staged — a work with three review rounds and seventeen blockers produced zero knowledge cards because nothing asked for them while they were in context. Candidates are findings about the **domain or the codebase's real behaviour**, not about this diff: a library that does other than its name says, a test disguise that kept the suite green over a live defect, a module rule the reviewers had to cite from its own prose, a measurement. A blocker fixed here is not knowledge; *why it was written wrong* may be. Same evidence rule as `$flow-feat-design` §8 — one line of evidence per finding or it is not staged. One call per finding, one line to the user («Staged N finding(s) for `ship`»). Never `knowledge.save` here.
+- **Stage what the review taught** (`knowledge.stage` set; silence by default). Review is where a project teaches the most, and this is the only moment its findings are in context. Candidates are findings about the **domain or the codebase's real behaviour**, not about this diff: a library that does other than its name says, a test disguise that kept the suite green over a live defect, a module rule the reviewers had to cite from its own prose, a measurement. A blocker fixed here is not knowledge; *why it was written wrong* may be. Same evidence rule as `$flow-feat-design` §8 — one line of evidence per finding or it is not staged. One call per finding, one line to the user («Staged N finding(s) for `ship`»). Never `knowledge.save` here.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
 - **Record what the agents missed** (flow-core §6.7, `agents.learn` not `off`; asking nothing): for each finding that survived, the panel member or named `agents.<role>` whose category it falls in and who did not report it, and the delegated `build` agent whose code it sits in → one `meta.json.agent_lessons[]` row each, only when the lesson passes the §6.7 test. The origins §2.1 carried are what make this possible — a finding with no origin teaches nobody.
 - **Configuration this phase earned the right to ask about** (flow-core §0, `manual` only, at most one key per work, as an extra option on this same stop — never a question of its own): a `Cost:` line that went over `agents.budget_max` → `quality.review_depth`. In `guided`/`auto` neither is asked: the default is taken and recorded in `meta.json.defaults_used[]`.
 - Report findings and next step **following the stop header** (flow-core §3) **when this is a stop**; in `guided`/`auto` with a clean gate the next command runs in this same turn, so this goes to `06-review.md` and the turn opens with the call that chains — the `Cost:` line then travels to the stop the run does reach, added to that phase's own. Include it once. Body: the findings that **survived** verification and what you did with each — a blocker, an applied fix, a rejection with its reason. Corrections to the reviewers' own reports go to `06-review.md`, not here.
-- **Autonomy handoff.** Only when there are **no blockers and no unresolved high-severity findings** — with any of those, stop in every mode (hard gate). Clean: in `manual`, propose `$flow-feat-validate` with a single `AskUserQuestion` and invoke it on confirmation; in `guided`/`auto`, **chain into `$flow-feat-validate` automatically** in this same turn. Never chain into `$flow-feat-ship` from here — ship is reached through `validate`.
+- **Autonomy handoff.** Only when there are **no blockers and no unresolved high-severity findings** — with any of those, stop in every mode (hard gate; in `unattended`, see below). Clean: in `manual`, propose `$flow-feat-validate` with a single `AskUserQuestion` and invoke it on confirmation; in `guided`/`auto`, **chain into `$flow-feat-validate` automatically** in this same turn. Never chain into `$flow-feat-ship` from here — ship is reached through `validate`.
+- **In `unattended`** (flow-core §2.1), blockers or unresolved high-severity findings are question
+  `high_findings`: the surviving findings in `question`, one line each, and the run ends. A person
+  picks it up in a session of their own, where they are fixed and reviewed again.

package/adapters/codex/skills/flow-feat-ship/SKILL.md

@@ -24,6 +24,37 @@ Read `~/.claude/flow/CORE.codex.md` first (shared rules: `FLOW.md` step 0, model
 
 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)
@@ -135,7 +166,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:
 
@@ -176,7 +207,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.
@@ -469,7 +507,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/codex/skills/flow-feat-start/SKILL.md

@@ -27,6 +27,20 @@ Read `~/.claude/flow/CORE.codex.md` first (shared rules: `FLOW.md` step 0, model
 - **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/codex/skills/flow-feat-validate/SKILL.md

@@ -153,12 +153,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
 
@@ -212,11 +217,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/codex/skills/flow-init/SKILL.md

@@ -98,9 +98,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.codex.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.codex.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/codex/skills/flow-work-README/SKILL.md

@@ -85,7 +85,6 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
   "branch": "{PREFIX}XXXXX-slug",
   "size": "XS" | "S" | "M" | "L",
   "phase": "context" | "design" | "plan" | "build" | "review" | "validate" | "ship" | "investigate" | "fix" | "postmortem" | "done" | "abandoned",
-  // retired in v0.53.0 and still read from older works: "brainstorm" → treat as "context", "diagnose" → as "investigate"
   "phases_done": ["context", ...],
   "candidate_sha": "40-char sha the current review froze before reading, or ''",
   "reviewed_sha": "40-char sha the last passing review read, or ''",
@@ -118,11 +117,11 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
   ],
   "followups": [
     { "id": "F1",
-      "kind": "prevention" | "audit" | "out-of-scope" | "risk" | "edge-case" | "other-bug",
+      "kind": "prevention" | "audit" | "out-of-scope" | "risk" | "edge-case" | "other-bug" | "tooling" | "decision",
       "title": "one line, what would be done",
       "why": "one line, why it was parked and why it still matters",
       "source": "design" | "plan" | "build" | "validate" | "fix" | "postmortem",
-      "status": "proposed" | "accepted" | "in_progress" | "declined" | "done",
+      "status": "proposed" | "accepted" | "in_progress" | "declined" | "logged" | "done",
       "ticket": null, "work": null, "note": "" }
   ],
   "defaults_used": [

package/adapters/codex/skills/flow-work-query/SKILL.md

@@ -26,7 +26,7 @@ Read `~/.claude/flow/CORE.codex.md` first (shared rules: `FLOW.md` step 0, model
 
 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/codex/skills/flow-work-resume/SKILL.md

@@ -22,14 +22,17 @@ Read `~/.claude/flow/CORE.codex.md` first (shared rules: `FLOW.md` step 0, auton
 
 **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
 
 - `git branch --show-current`.
 - Search `.claude/work/` for the `meta.json` whose `branch` matches.
 - None found → ask the user for the ticket or whether to start a new one.
-- **A `phase` retired in v0.53.0** — `brainstorm` or `diagnose`, from a work started before it — is mapped, never refused: `brainstorm` → `design` (its `02-brainstorm.md` is that command's §1.5 output, already done), `diagnose` → `investigate` (its `02-diagnose.md` is that command's §1.5 output). Say which mapping you applied, in one line, and suggest the mapped command. Do not rewrite `meta.json` for it; the phase advances normally at the next Close.
 - `meta.json.worktree` non-null and the current directory is not that worktree → tell the user the work lives in a worktree and to `cd <worktree>` before continuing; run the repo-state checks below from there (`git -C <worktree> …`).
 
 ## 2. Recap
@@ -46,6 +49,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.
@@ -87,6 +91,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.