@iceinvein/agent-skills 0.8.4 → 0.9.0

package/dist/cli/index.js

@@ -21,12 +21,14 @@ var __toESM = (mod, isNodeMode, target) => {
   }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: __accessProp.bind(mod, key),
-        enumerable: true
-      });
+  if (mod && typeof mod === "object" || typeof mod === "function") {
+    for (let key of __getOwnPropNames(mod))
+      if (!__hasOwnProp.call(to, key))
+        __defProp(to, key, {
+          get: __accessProp.bind(mod, key),
+          enumerable: true
+        });
+  }
   if (canCache)
     cache.set(mod, to);
   return to;
@@ -35,7 +37,7 @@ var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports,
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // node_modules/cli-width/index.js
-var require_cli_width = __commonJS((exports, module) => {
+var require_cli_width = __commonJS(function(exports, module) {
   module.exports = cliWidth;
   function normalizeOpts(options) {
     const defaultOpts = {
@@ -75,7 +77,7 @@ var require_cli_width = __commonJS((exports, module) => {
 });
 
 // node_modules/mute-stream/lib/index.js
-var require_lib = __commonJS((exports, module) => {
+var require_lib = __commonJS(function(exports, module) {
   var Stream = __require("stream");
 
   class MuteStream extends Stream {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Install agent skills into AI coding tools",
   "author": "iceinvein",
   "license": "MIT",

package/skills/index.json

@@ -281,9 +281,9 @@
   },
   {
     "name": "sluice",
-    "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries seven rules as one-liners in the router and the full treatment in references read only on friction, and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Claude Code only; stands down where the superpowers pipeline governs the repo.",
+    "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries seven rules as one-liners in the router and the full treatment in references read only on friction. Checks the finished plan with plan.sh validate rather than trusting it to memory, seeds the run state from it, keeps a deep run's task breakdown in .sluice/run.json so a statusline segment and one status command can answer where the run is, and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Claude Code only; stands down where the superpowers pipeline governs the repo.",
     "type": "prompt",
-    "version": "0.7.0"
+    "version": "0.10.0"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/sluice/SKILL.md

@@ -90,6 +90,16 @@ Design to `docs/specs/YYYY-MM-DD-<topic>.md`, plan to
 `docs/plans/YYYY-MM-DD-<topic>.md`, unless the repo has a convention or
 your partner states a preference. Get the design signed off before code.
 
+Take the design stop through the harness's plan mode where there is one. Its
+gate is enforced rather than requested and it holds edits shut while it is open,
+so nothing gets built against a design nobody signed. It carries the first stop
+only; pre-flight still wants answers, and an approval is not one.
+
+The run's state goes in `.sluice/run.json`, written a command at a time by
+`scripts/status.sh`. That is what makes the breakdown readable from outside the
+session running it: a statusline segment while it runs, `status.sh show` after a
+compaction, and neither costing your partner a turn to ask. `references/status.md`
+
 **Read `references/deep-channel.md` before you write the plan.** It carries the
 plan format, the pre-flight questions, the run record, the dispatch rules and
 the review tiers, and none of those are derivable from what is on this page.
@@ -112,6 +122,7 @@ plan:
 **Touches:** <path> (new) | <path> (edit) | <path> (test)
 **Flips:** <what changes, from what, or omit>
 **Review:** <reason, or omit>
+**Model:** <cheaper model, and why the work is mechanical, or omit>
 - [ ] <action> -> <proof>
 ```
 
@@ -130,19 +141,21 @@ task that turns the new behaviour on with `Flips`. Then a late re-baseline,
 re-blessed snapshots, regenerated fixtures, attributes to that one point
 instead of to the branch at large.
 
-Pre-flight rides in that same stop: which flagged tasks get a reviewer, and
-whether the work runs in a worktree. Ask them as choices with the counts in
-them, never as a paragraph, then end the turn. Task 1 opens on their next
+Pre-flight rides in that same stop: which flagged tasks get a reviewer, which
+mechanical ones the plan marked for a cheaper model, and whether the work runs
+in a worktree. Ask them as choices with the counts in them, never as a
+paragraph, then end the turn. Task 1 opens on their next
 instruction, and an answer that already carries one is that instruction. A
 session that dispatches only when asked has not ruled dispatch out, it has made
 this question the place to ask; genuine unavailability is the tool not being
 there at all, which `references/deep-channel.md` handles separately. Review that
 turns out to be missing is only actionable while the plan can still change.
 
-Both answers go into the run record before Task 1's first edit, each with the
-reason it went that way. Those rows are what discharge pre-flight, not the
-approval: one reply arrives for two obligations, so a "yes" with no rows behind
-it signed off the plan and nothing else.
+All three answers go into `run.json` and the run record before Task 1's first
+edit, the answer in the first and the reason in the second. Those rows are what
+discharge pre-flight, not the approval: one reply arrives for several
+obligations, so a "yes" with no rows behind it signed off the plan and nothing
+else.
 
 Three from that file that catch people out: concurrent implementers need a
 worktree each and the flip runs alone, review is tiered rather than automatic,

package/skills/sluice/references/deep-channel.md

@@ -20,6 +20,16 @@
   corrupted concurrent run.
 - A **Review** field may name why the task needs the stronger tier (auth,
   data, money, concurrency); the table below decides otherwise.
+- A **Model** field may put the task on a cheaper model, and says why the work
+  is mechanical: the Contract is exact, the tests it has to satisfy already
+  exist, and nothing in it turns on judgment. Omit it and the task runs on this
+  session's model, so the marked tasks are the exceptions rather than the rule.
+  Anything the table below sends to tier 3 is disqualified, `Flips` with it:
+  those are the tasks where being wrong is expensive, and the saving is not
+  worth pricing against that. Mark it here rather than deciding at dispatch,
+  because whether a task is mechanical is fixed the moment its Contract and
+  Touches are written, and pre-flight is the last point your partner can price
+  it.
 - **Order the plan so the inert tasks come first.** A task is inert when it
   adds capability, config, a schema or a code path that nothing reads yet:
   landing it changes no observable behaviour, so it is safe to land alone and
@@ -36,6 +46,16 @@
   the instruction out again in full. "TBD" is another. So is naming a type
   or a function that no task in the plan ever creates.
 
+**Run `scripts/plan.sh validate <plan>` on the finished plan, before pre-flight.**
+Most of what this section asks for needs no judgement to check: a `Needs` no
+task `Offers`, a "TBD", a step deferring to a neighbour, a missing `Contract`,
+a plan with no flip or two of them, a `Model` mark on a task the tier table
+sends to tier 3. Those come back as errors with the task number on them. The
+warnings are the judgement calls left to you: a step with no proof, a `Needs`
+satisfied only by a later task, two tasks whose `Touches` overlap. Reading the
+plan yourself catches these on a good day, and the point of a check is the
+other kind of day.
+
 ```
 # Plan: <topic>
 ## Ground Rules
@@ -45,6 +65,7 @@
 **Touches:** <path> (new) | <path> (edit) | <path> (test)
 **Flips:** <what changes, from what, or omit>
 **Review:** <reason, or omit>
+**Model:** <cheaper model, and why the work is mechanical, or omit>
 - [ ] <action> -> <proof>
 ```
 
@@ -61,14 +82,31 @@ Split it. A plan with none is not a `deep` plan: nothing in it does anything.
 ## The run record
 
 A `deep` run outlives its own context, so what it learns has to sit on disk
-rather than in the session. Open one file for the run before pre-flight and
-write it as you go. It holds what a stranger resuming tomorrow would need and
-you would otherwise be recalling: the base each task was dispatched from, each
-task with its status and its commits, both answers pre-flight settled, review
-and workspace alike, with the reason each one went that way, and any finding
-belonging to a task other than the one that surfaced it. Those pre-flight rows
-come first and open the file, because they are also what says the stop happened
-at all.
+rather than in the session. That lands in two files, and which one a thing goes
+in follows from who has to read it.
+
+`.sluice/run.json` holds the state that moves: each task with its status, base
+and commit, its tier, its `Model` mark and its `Flips` line, and the answers
+pre-flight settled. `scripts/status.sh` writes and reads it, and
+`references/status.md` carries the commands and the statusline segment that
+makes a run visible without anyone asking. Open it with `init` when you open the
+record, seed the rows with `scripts/plan.sh import <plan>` rather than typing a
+command per task, then flip each task as it moves. Import is safe to re-run: it
+sets names, model marks and the flip, and leaves a status already recorded
+alone, so resuming after a compaction cannot rewind the run.
+
+The record is the other file, and it holds what a status cannot: the reason
+review went the way it did, the reason a task was downshifted, the reason the
+workspace answer went that way, any finding belonging to a task other than the
+one that surfaced it, and whatever else a stranger resuming tomorrow would need
+and could not derive. **It no longer carries task rows with statuses in them.**
+Status written in both places drifts, and once it has there are two answers and
+nothing to say which is stale.
+
+Pre-flight lands in both, which is the one deliberate overlap: `run.json` holds
+the answer, so the file can say whether the stop happened at all, and the record
+holds the reason, so a reader can tell whether it should have gone that way.
+Those rows come first and open the record for the same reason they always did.
 
 Where it goes follows the repo if the repo has a convention, and
 `docs/plans/YYYY-MM-DD-<topic>-record.md` if it does not. It belongs to you
@@ -77,16 +115,47 @@ task's `Touches` names it, and you commit it yourself alongside the plan.
 Assembling it at handback defeats it: a record written from memory is memory,
 which is the one thing the file exists to replace.
 
-A file only outlives compaction if you go back to it. Read it before the next
-dispatch whenever this session has been summarised, and treat what it says over
-what you remember, including where the two agree. Each task closes by writing
-its commit into the record, which means asking the implementer to report the
-SHA it committed and putting that in the row rather than deriving it later.
+A file only outlives compaction if you go back to it. Run `status.sh show` and
+read the record before the next dispatch whenever this session has been
+summarised, and treat what they say over what you remember, including where the
+two agree. Each task closes by writing its commit into `run.json`, which means
+asking the implementer to report the SHA it committed and passing it to
+`status.sh task <id> --status done --commit <sha>` rather than deriving it later.
+
+## The design stop and plan mode
+
+The design stop is a stop because a plan written against the wrong design wastes
+a plan's worth of work. Sluice enforced it with a sentence, "a stop ends your
+turn", which is the weakest gate available in a harness that has a real one.
+
+Claude Code's plan mode is the real one. `EnterPlanMode` needs your partner's
+consent to enter, `ExitPlanMode` will not proceed without their approval, and
+edits are held shut in between, so the design cannot be quietly built against
+while it is still a draft. Take the design stop through it.
+
+What that changes: the design gets drafted in the plan file the harness names,
+and `ExitPlanMode` is the sign-off rather than a paragraph asking for one.
+
+What it does not replace is pre-flight. That stop wants three answers, and an
+approval is not an answer to any of them, so it stays where it is, after plan
+mode has exited and the plan is written. One enforced gate does not collapse two
+stops into one; it only makes the first of them hold.
+
+**The harness's plan file is not the artifact.** It belongs to the mode and not
+to the run. On approval, write the design to `docs/specs/YYYY-MM-DD-<topic>.md`,
+the plan to `docs/plans/YYYY-MM-DD-<topic>.md`, and open the run record and
+`run.json`. Those are the durable files, the ones a session resuming next week
+reads, and none of them is the one you drafted in.
+
+Where plan mode is unavailable, the prose stop is what you have and it is the
+same stop: end the turn on the design and let the next instruction start the
+plan. Nothing else about this section changes, because the obligation was never
+the mode's, only the enforcement was.
 
 ## Pre-flight
 
 Design signed off, plan written, nothing built yet. Before Task 1, stop once
-and settle two things with your partner. Ask them as questions with options,
+and settle three things with your partner. Ask them as questions with options,
 not as a paragraph they have to reply to in prose: what you are after is a
 decision, and a wall of considerations asks them to extract the decision from
 it first.
@@ -103,11 +172,18 @@ your sign-off and Task 1 begins.
 **Review.** Name the tasks the table below sends to a reviewer, each with the
 trigger that qualified it, and say how many of the rest skip with a ledger
 line. Then offer the choice: dispatch a reviewer at each of them, dispatch
-only at the stronger-model tier, or hand back with those tasks listed as
+only at tier 3, or hand back with those tasks listed as
 review outstanding. The options are what makes the cost legible.
 "Four of nine need a reviewer" is a decision your partner can price; "I will
 review where appropriate" is not.
 
+**Model.** The plan already marked which tasks are mechanical, so this is a
+ratification rather than a fresh judgment, and it carries the count: six of
+nine on the cheaper model and three on this session's, take it, put everything
+on the session model, or name the exceptions. The count is what your partner
+prices. "I will use the cheaper model where it fits" prices nothing, and it
+also arrives after the tokens are spent.
+
 **Workspace, commits and concurrency.** One worktree for the plan, one per
 concurrent implementer, or straight onto the current branch; and with it who
 commits, each agent committing its own task as it finishes or agents leaving
@@ -137,9 +213,10 @@ is the declared schedule the dispatch rules reject.
 If one of the two has only one live answer, say which and ask the other. A stop
 down to a single question is still a stop.
 
-**Write the answers into the run record before Task 1's first edit.** Both of
-them, each with the reason it went that way. This is what discharges pre-flight,
-rather than the approval you got, and the distinction is the whole point: a stop
+**Write the answers down before Task 1's first edit.** Both files:
+`status.sh preflight` for the answers, the run record for the reason each one
+went that way. That pair is what discharges pre-flight, rather than the
+approval you got, and the distinction is the whole point: a stop
 that carries the plan and pre-flight together has one reply for two obligations,
 so a bare "yes" satisfies the plan and leaves no trace either way of the
 questions. Rows in a file leave that trace. If Task 1 is about to open and the
@@ -166,10 +243,15 @@ Derive the sets at dispatch rather than writing wave numbers into the plan. A
 declared schedule is wrong the moment one task lands late or comes back with a
 blocking finding. A derived one just recomputes.
 
-- One line per task in the run record, marked in progress then complete as it
+- One row per task in `run.json`, flipped to `active` and then `done` as it
   moves. That state outlives compaction; your memory doesn't.
 - Each task goes to a fresh agent with that task's text and nothing else.
   What this session accumulated is yours to hold, not theirs.
+- **Label the dispatch `T<n>: <task name>`.** The harness lists running agents
+  under whatever label the dispatch gave them, so labelled by task that list
+  reads as the plan and labelled anything else it reads as a row of anonymous
+  agents. It costs nothing and it is the only place a partner can see which
+  task is in flight without asking.
 - **Fan out wherever the graph allows.** Work that does not write is always
   safe and always parallel: investigations, searches and reviewers, one agent
   per question, all in one message so they run at once.
@@ -201,8 +283,11 @@ blocking finding. A derived one just recomputes.
   authoring a message for a diff you did not write means reading that diff,
   which is the context dispatch exists to keep out of this session. Pre-flight
   can overturn it for a given run.
-- Match model to task: cheap for mechanical work, stronger for judgment
-  and final review.
+- **The plan and pre-flight decide the model, not the moment of dispatch.** A
+  task with no `Model` line goes out on this session's, and a downshift that
+  was neither marked nor ratified is a saving your partner never agreed to.
+  Reviewers are the other half of that rule: a review never runs below the
+  model that built the task, so a downshifted task's reviewer comes back up.
 
 A per-task commit is not an integration event. `references/finish.md` owns
 push, PR and merge, none of which happen here, and a standing instruction to
@@ -225,8 +310,8 @@ Three things change. The plan stops being a brief for strangers and becomes
 your own worklist, so its stop is no longer buying alignment with the agents
 who will carry it out, only your partner's read of work you will do yourself.
 Task isolation is gone, so
-the run record now carries all of the state that outlives compaction and
-matters more, not less. And fresh context is unavailable, which was the entire thing
+`run.json` and the record now carry all of the state that outlives compaction
+and matter more, not less. And fresh context is unavailable, which was the entire thing
 review was buying.
 
 One thing does not change: the work still owes a review. Reading your own diff
@@ -259,8 +344,15 @@ and it fails by printing success rather than by erroring.
 | 0 | Created files only, executable tests exist and pass, Contract matches | No dispatch. Read the commit stat yourself. |
 | 1 | Modified existing code, or later tasks build on it | One reviewer dispatch |
 | 2 | No executable test covers it: prose, config, docs | One reviewer dispatch; a stat cannot confirm the words are right |
-| 3 | Auth, data, money, concurrency, or the plan flags it | One reviewer dispatch, stronger model |
-| 3 | Carries the `Flips` line | One reviewer dispatch, stronger model |
+| 3 | Auth, data, money, concurrency, or the plan flags it | One reviewer dispatch; the task may not be downshifted |
+| 3 | Carries the `Flips` line | One reviewer dispatch; the task may not be downshifted |
+
+No tier buys a bigger model, because a plan that downshifted nothing has every
+agent on the same one, and a tier promising something stronger would be
+promising what is already in use. What a tier buys is a dispatch. The one model
+rule that holds across all of them is that a review never runs below the model
+that built the task, so tiers 1 and 2 over a downshifted task come back up to
+this session's.
 
 A task matching more than one row takes the highest tier of them. Tier is the
 number, not the row order and not which shape sounds more serious. A task that
@@ -279,8 +371,8 @@ a reviewer writes nothing, so it collides with nothing. The final review is
 the only one that waits, because it is the only one that needs everything to
 have landed.
 
-Record the base against that task in the run record when you dispatch, before
-the agent's first commit lands. Recovering it afterwards is archaeology, and the
+Record the base against that task with `status.sh task <id> --base <sha>` when
+you dispatch, before the agent's first commit lands. Recovering it afterwards is archaeology, and the
 answer you will guess at is `HEAD~1`, which `references/review.md` already
 names as the standing mistake.
 
@@ -323,8 +415,9 @@ absorb into the next task's brief.
 ## The final review
 
 It covers cross-task integration and everything the record accumulated, not
-lines a per-task review already cleared. It is a dispatch, on the stronger
-model, and it gets the whole-plan diff and the deferred findings as a list.
+lines a per-task review already cleared. It is a dispatch, on this session's
+model and never a downshifted one, and it gets the whole-plan diff and the
+deferred findings as a list.
 
 Size the brief to what it is actually carrying, and say which of two things it
 is. After nine per-task reviews cleared, it is an integration check. When

package/skills/sluice/references/status.md

@@ -0,0 +1,110 @@
+# Run state
+
+The plan says what the tasks are. The run record says why each decision went
+the way it did. Neither answers "where is this right now" to anything but a
+model reading prose, which is why a `deep` run is invisible from outside the
+session that is running it: your partner has to ask, and asking costs a turn
+and gets an answer from memory.
+
+`.sluice/run.json` is that answer in a form something else can read. One file
+per tree, holding only what changes as the run moves.
+
+```
+bash <skill-dir>/scripts/status.sh init --topic <t> --channel deep \
+     --plan docs/plans/<date>-<topic>.md --record docs/plans/<date>-<topic>-record.md
+bash <skill-dir>/scripts/status.sh task 3 --name "adapter seam" --tier 1 --model cheap
+bash <skill-dir>/scripts/status.sh task 3 --status active --base 75014c9
+bash <skill-dir>/scripts/status.sh task 3 --status done --commit 2c7f261
+bash <skill-dir>/scripts/status.sh preflight --review "tier 3 only" --model "6 of 9 cheap" \
+     --workspace "one worktree per implementer"
+bash <skill-dir>/scripts/status.sh show
+bash <skill-dir>/scripts/status.sh close
+```
+
+`--dir <path>` reads another tree, which is what the statusline uses. Statuses
+are `todo`, `active`, `review`, `done` and `blocked`. A new id needs `--name`;
+after that every call is a bare flip, so keeping it current costs one command
+per transition rather than a paragraph. `close` archives the run under
+`.sluice/archive/` and frees the tree for the next one.
+
+A command that cannot finish leaves the state exactly as it found it, so a
+failed `task` never costs you the rows already in the file. Two argument rules
+follow from that being worth guaranteeing: a value beginning with `--` is
+rejected rather than accepted as a value, and a flag with no value at all is
+rejected rather than taking the next flag as one.
+
+Gitignore `.sluice/`. It is working state, and everything durable in it lands
+somewhere else anyway: the commits are in git and the reasons are in the record,
+which is the file that does get committed.
+
+Open it with `init` when you open the run record, at the same point and for the
+same reason, then seed the rows with `plan.sh import <plan>` rather than a
+command per task. The ids, names, the flip, the `Model` marks and the one tier
+the plan settles are all fixed the moment the plan is written and are already in
+the file, so typing them again is transcription with a chance of error in it.
+
+Re-importing is safe and is the right move after the plan changes. It refreshes
+names, the flip and the tier, and it leaves a status or a ratified model already
+recorded alone, so resuming after a compaction cannot rewind the run.
+
+## What goes where
+
+**`run.json` owns status. The record owns why.** A status written into both
+drifts, and the moment it does there are two answers and no way to tell which
+is stale. So the record stops carrying task rows with statuses in them and
+carries what a status cannot hold: the reason review went the way it did, the
+reason a task was downshifted, a finding that belongs to a task other than the
+one that surfaced it, and what a stranger resuming tomorrow would need and
+could not derive.
+
+Pre-flight answers land in both, and that is deliberate rather than an
+exception: `run.json` holds the answer so the file can say whether the stop
+happened, the record holds the reason so a reader can tell whether it should
+have gone that way. Those are different claims.
+
+## Reading it back
+
+`show` prints the whole run: channel, topic, how many tasks are done, the plan
+and record paths, the pre-flight answers, and a row per task with its base,
+commit, tier and model. Run it after compaction instead of reconstructing the
+run from what you remember, and run it in the message that hands the work back,
+where "four of nine, task five blocked" is a fact your partner can act on.
+
+`show --json` is the same state for another reader. `line` is the one-line form,
+and it exits 0 in silence on a missing run, unreadable state or a missing jq,
+because its caller is a status bar with nowhere to put an error.
+
+## Statusline
+
+This is the part that makes a run visible without anyone asking. The segment
+goes in the Claude Code statusline command, keyed off the state file existing so
+a session with no run in flight spawns nothing:
+
+```bash
+sluice_line=""
+if [ -n "$cwd" ] && [ -f "$cwd/.sluice/run.json" ]; then
+  for sluice_sh in "$cwd/.claude/skills/sluice/scripts/status.sh" \
+                   "$HOME/.claude/skills/sluice/scripts/status.sh"; do
+    [ -f "$sluice_sh" ] || continue
+    sluice_line=$(bash "$sluice_sh" line --dir "$cwd" 2>/dev/null)
+    break
+  done
+fi
+[ -n "$sluice_line" ] && printf ' %s' "$sluice_line"
+```
+
+`$cwd` is `workspace.current_dir` from the JSON the harness sends on stdin. It
+renders as `sluice deep 4/9 ▸T5`, or `!T5` where a task is blocked, which is
+the one state worth colouring as a warning rather than as progress.
+
+A run that is only visible to the session running it is a run your partner
+cannot redirect. That is the same argument the channel announcement makes, and
+the statusline is where it holds for the hour after the announcement scrolled
+away.
+
+## Friction
+
+"I know which task I'm on." You do, until this session is summarised. The file
+costs one command per transition and is the only thing in the run that survives
+that, and a plan whose progress lives in one context window is a plan nobody
+outside that window can read.

package/skills/sluice/scripts/plan.sh

@@ -0,0 +1,399 @@
+#!/usr/bin/env bash
+# sluice plan tooling: the parts of the plan format that a reader can check
+# without judgement.
+#
+# `references/deep-channel.md` is 21KB read once, at the point the plan is
+# written, and relied on from memory for the rest of the run. Most of what it
+# asks for is not a matter of taste: a Needs no task Offers, a "TBD", a step
+# deferring to another task, a plan with no flip or two. Those are checkable, so
+# they should be checked rather than remembered.
+#
+#   plan.sh validate <plan.md>
+#   plan.sh import <plan.md> [--dir <path>] [--force]
+#
+# validate prints one line per finding. An error means the plan cannot be
+# dispatched as written; a warning is a judgement call left to its author.
+# import seeds the run state's task rows from the plan, so the ids, names, the
+# flip, the model marks and the one tier the plan settles come from the file
+# rather than from a dozen hand-typed commands. It is safe to re-run: a status or
+# a ratified model already recorded is left alone.
+#
+# Exit: 0 no errors, 2 errors found, 4 bad arguments, 5 jq missing (import only).
+
+set -uo pipefail
+
+err() { echo "plan.sh: $*" >&2; }
+
+usage() {
+	echo "usage:" >&2
+	sed -n '/^#   plan.sh validate/,/^# Exit:/p' "$0" | sed 's/^# \{0,2\}//' >&2
+}
+
+# The parser. Emits tab-separated rows on stdout:
+#   summary <task count> <flip task or 0>
+#   error|warn  <message>
+#   task  <id>  <name>  <tier 3 or ->  <model 1|0>  <flips 1|0>
+#
+# Only tier 3 is derivable from the plan: Flips and a Review flag are the two
+# triggers the plan itself settles. The rest turn on task shape and stay for the
+# tier table to decide.
+#
+# One pass, line-oriented, because the plan format is a strict skeleton rather
+# than free markdown. Fenced blocks are skipped: a plan carries signatures and
+# commands in them, and a `- [ ]` inside a fence is an example, not a step.
+PARSER='
+function trim(s) { gsub(/^[ \t]+|[ \t]+$/, "", s); return s }
+
+# Symbols on one side of a Contract line. The two sides are read differently
+# because a mistake costs differently on each.
+#
+# Supply (Offers) is generous: every identifier in the half goes on offer, so a
+# return shape spelled `parsePlan(path) -> `PlanDoc`` puts PlanDoc on offer as
+# well as parsePlan, which is what the format asks for when it says both sides
+# are spelled out whole. An extra symbol on offer costs nothing.
+#
+# Demand (Needs) is strict, because an extra symbol here is a false error:
+# backticked names and signatures only, falling back to the leading identifier
+# of each comma-separated part when the half carries neither.
+function symbols(half, out, generous,   count, rest, tok, lower, n, parts, i, chunk) {
+	lower = half
+	gsub(/`/, "", lower)
+	lower = tolower(trim(lower))
+	if (lower == "" || lower == "none" || lower == "-" || lower == "n/a") return 0
+	count = 0
+
+	if (generous) {
+		rest = half
+		gsub(/`/, " ", rest)
+		while (match(rest, /[A-Za-z_][A-Za-z0-9_]*/)) {
+			out[++count] = substr(rest, RSTART, RLENGTH)
+			rest = substr(rest, RSTART + RLENGTH)
+		}
+		return count
+	}
+
+	rest = half
+	while (match(rest, /`[^`]*`/)) {
+		chunk = substr(rest, RSTART + 1, RLENGTH - 2)
+		rest = substr(rest, RSTART + RLENGTH)
+		if (match(chunk, /[A-Za-z_][A-Za-z0-9_]*/))
+			out[++count] = substr(chunk, RSTART, RLENGTH)
+	}
+	rest = half
+	gsub(/`/, "", rest)
+	while (match(rest, /[A-Za-z_][A-Za-z0-9_]*\(/)) {
+		tok = substr(rest, RSTART, RLENGTH - 1)
+		out[++count] = tok
+		rest = substr(rest, RSTART + RLENGTH)
+	}
+	if (count == 0) {
+		rest = half
+		gsub(/`/, "", rest)
+		n = split(rest, parts, /[,;]/)
+		for (i = 1; i <= n; i++)
+			if (match(parts[i], /[A-Za-z_][A-Za-z0-9_]*/))
+				out[++count] = substr(parts[i], RSTART, RLENGTH)
+	}
+	return count
+}
+
+function finding(sev, msg) { out[++nout] = sev "\t" msg }
+
+/^[ \t]*```/ { fenced = 1 - fenced; next }
+fenced { next }
+
+/^# Plan:/ { has_title = 1 }
+
+/^## / {
+	in_rules = (tolower($0) ~ /^## ground rules/) ? 1 : 0
+	if (in_rules) has_rules_heading = 1
+	# A section after the last task belongs to the plan, not to that task. Left
+	# set, cur attributes its prose and any checkbox in it to a task that ended
+	# several headings ago.
+	cur = 0
+	next
+}
+
+/^### Task / {
+	in_rules = 0
+	s = substr($0, 10)
+	colon = index(s, ":")
+	if (colon == 0) { finding("error", "a task heading has no name: " $0); next }
+	id = trim(substr(s, 1, colon - 1))
+	if (id !~ /^[0-9]+$/) { finding("error", "a task heading is not numbered: " $0); next }
+	id = id + 0
+	if (id in seen) {
+		finding("error", "task " id " appears twice; a repeated number makes the dependency order unreadable")
+	}
+	seen[id] = 1
+	order[++ntasks] = id
+	name[id] = trim(substr(s, colon + 1))
+	cur = id
+	next
+}
+
+in_rules && /^- / { nrules++ }
+
+# Everything below belongs to a task, so a field outside one is a field nobody
+# reads.
+!cur { next }
+
+# Scanned over every line of a task body, and deliberately ahead of the field
+# and step rules: those end in `next`, so a check placed after them never sees a
+# step, which is exactly where a "TBD" turns up.
+{
+	if ($0 ~ /TBD/)
+		finding("error", "task " cur ": \"TBD\" is not an instruction")
+	if (tolower($0) ~ /same as (task|step)/)
+		finding("error", "task " cur ": \"same as ...\" defers to a task its implementer never sees")
+}
+
+/^\*\*Contract:\*\*/ {
+	has_contract[cur] = 1
+	body = substr($0, length("**Contract:**") + 1)
+	oi = index(body, "Offers:")
+	if (oi > 0) { nh = substr(body, 1, oi - 1); oh = substr(body, oi + 7) }
+	else { nh = body; oh = "" }
+	ni = index(nh, "Needs:")
+	if (ni > 0) nh = substr(nh, ni + 6)
+	sub(/\|[ \t]*$/, "", nh)
+
+	delete syms
+	n = symbols(nh, syms, 0)
+	for (i = 1; i <= n; i++) needs[cur] = needs[cur] " " syms[i]
+
+	delete syms
+	n = symbols(oh, syms, 1)
+	for (i = 1; i <= n; i++) {
+		if (!(syms[i] in offered_by) || cur < offered_by[syms[i]]) offered_by[syms[i]] = cur
+	}
+	next
+}
+
+/^\*\*Touches:\*\*/ {
+	has_touches[cur] = 1
+	body = substr($0, length("**Touches:**") + 1)
+	n = split(body, parts, /\|/)
+	for (i = 1; i <= n; i++) {
+		p = parts[i]
+		sub(/\([^)]*\)[ \t]*$/, "", p)
+		p = trim(p)
+		if (p == "") continue
+		# Accumulated rather than assigned: with three tasks on one path,
+		# reporting a single pair leaves the reader serialising two of them and
+		# still running the third alongside.
+		if (index(" " owners[p] " ", " " cur " ") == 0)
+			owners[p] = owners[p] (owners[p] == "" ? "" : " ") cur
+	}
+	next
+}
+
+/^\*\*Flips:\*\*/ { has_flips[cur] = 1; nflips++; flips_list = flips_list (flips_list == "" ? "" : ", ") cur; next }
+/^\*\*Review:\*\*/ { has_review[cur] = 1; next }
+/^\*\*Model:\*\*/  { has_model[cur] = 1; next }
+
+/^- \[[ xX]\]/ {
+	nsteps[cur]++
+	# Counted rather than reported here. One warning per step turns a plan
+	# written before the proof convention into forty identical lines, and the
+	# errors underneath them stop being read.
+	if (index($0, "->") == 0) noproof[cur]++
+	next
+}
+
+END {
+	if (!has_title) finding("warn", "no \"# Plan: <topic>\" heading, so the file does not say what it plans")
+
+	if (!has_rules_heading || nrules == 0)
+		finding("error", "no Ground Rules with entries; an implementer arrives with its own defaults and uses them on anything left unsaid")
+
+	if (ntasks == 0) {
+		finding("error", "no tasks, so there is nothing to dispatch")
+	} else {
+		for (i = 1; i <= ntasks; i++) {
+			id = order[i]
+			if (id != i)
+				finding("error", "tasks are not numbered 1.." ntasks " in sequence: task " id " sits where " i " should")
+		}
+		for (i = 1; i <= ntasks; i++) {
+			id = order[i]
+			if (!(id in has_contract))
+				finding("error", "task " id " has no Contract, so a symbol absent from it does not exist for whoever builds it")
+			if (!(id in has_touches))
+				finding("error", "task " id " has no Touches, and concurrency is derived from it")
+			if (!(id in nsteps))
+				finding("error", "task " id " has no steps")
+			else if (id in noproof)
+				finding("warn", "task " id ": " noproof[id] " of " nsteps[id] " steps have no proof after ->, so nothing says they worked")
+			if ((id in has_model) && (id in has_flips))
+				finding("error", "task " id " carries Flips and a Model mark; the flip is tier 3 and may not be downshifted")
+			if ((id in has_model) && (id in has_review))
+				finding("error", "task " id " is flagged for Review and carries a Model mark; a tier 3 task may not be downshifted")
+		}
+
+		if (nflips == 0)
+			finding("error", "no task carries Flips, so nothing in the plan turns anything on")
+		else if (nflips > 1)
+			finding("error", "two or more tasks carry Flips (" flips_list "); a plan with more than one holds that many branches of work")
+
+		for (i = 1; i <= ntasks; i++) {
+			id = order[i]
+			n = split(needs[id], want, " ")
+			for (j = 1; j <= n; j++) {
+				sym = want[j]
+				if (sym == "" || ((id "\t" sym) in reported)) continue
+				reported[id "\t" sym] = 1
+				if (!(sym in offered_by))
+					finding("error", "task " id " Needs " sym ", which no task Offers")
+				else if (offered_by[sym] > id)
+					finding("warn", "task " id " Needs " sym ", offered only by the later task " offered_by[sym])
+			}
+		}
+	}
+
+	for (p in owners) {
+		n = split(owners[p], who, " ")
+		if (n < 2) continue
+		list = who[1]
+		for (i = 2; i <= n; i++) list = list (i == n ? " and " : ", ") who[i]
+		finding("warn", "tasks " list " " (n == 2 ? "both" : "all") " touch " p ", so they cannot run at the same time")
+	}
+
+	flip = 0
+	for (i = 1; i <= ntasks; i++) if (order[i] in has_flips) { flip = order[i]; break }
+	print "summary\t" ntasks "\t" flip
+	for (i = 1; i <= nout; i++) print out[i]
+	for (i = 1; i <= ntasks; i++) {
+		id = order[i]
+		tier = ((id in has_flips) || (id in has_review)) ? "3" : "-"
+		print "task\t" id "\t" name[id] "\t" tier "\t" ((id in has_model) ? 1 : 0) "\t" ((id in has_flips) ? 1 : 0)
+	}
+}
+'
+
+# Runs the parser and splits its output into the shell. Sets: NTASKS, FLIP,
+# FINDINGS (newline-separated sev\tmsg), TASKROWS (newline-separated), NERR,
+# NWARN.
+parse_plan() {
+	local plan="$1" raw
+	raw="$(awk "$PARSER" "$plan")" || { err "could not read $plan"; exit 4; }
+
+	local summary
+	summary="$(printf '%s\n' "$raw" | grep '^summary	' | head -1)"
+	NTASKS="$(printf '%s' "$summary" | cut -f2)"
+	FLIP="$(printf '%s' "$summary" | cut -f3)"
+	FINDINGS="$(printf '%s\n' "$raw" | grep -E '^(error|warn)	' || true)"
+	TASKROWS="$(printf '%s\n' "$raw" | grep '^task	' || true)"
+	NERR="$(printf '%s\n' "$FINDINGS" | grep -c '^error	' || true)"
+	NWARN="$(printf '%s\n' "$FINDINGS" | grep -c '^warn	' || true)"
+}
+
+# "1 error" / "2 errors", so the header does not read as a template.
+plural() { [ "$1" = "1" ] && echo "$1 $2" || echo "$1 $2s"; }
+
+SUB="${1-}"
+[ $# -gt 0 ] && shift
+if [ -z "$SUB" ]; then
+	usage
+	exit 4
+fi
+
+case "$SUB" in
+	validate)
+		PLAN="${1-}"
+		[ -n "$PLAN" ] || { err "validate needs a plan path"; exit 4; }
+		[ -f "$PLAN" ] || { err "no such plan: $PLAN"; exit 4; }
+		shift
+		[ $# -eq 0 ] || { err "unknown argument: $1"; exit 4; }
+
+		parse_plan "$PLAN"
+
+		head="$(basename "$PLAN"): $(plural "$NTASKS" task)"
+		[ "$FLIP" != "0" ] && head="$head, flip at task $FLIP"
+		if [ "$NERR" = "0" ] && [ "$NWARN" = "0" ]; then
+			echo "$head, no errors"
+			exit 0
+		fi
+		[ "$NERR" != "0" ] && head="$head, $(plural "$NERR" error)"
+		[ "$NWARN" != "0" ] && head="$head, $(plural "$NWARN" warning)"
+		[ "$NERR" = "0" ] && head="$head, no errors"
+		echo "$head"
+		echo
+		# Errors before warnings. Within each, the parser's own order, which
+		# follows the file.
+		{ printf '%s\n' "$FINDINGS" | grep '^error	' || true
+		  printf '%s\n' "$FINDINGS" | grep '^warn	' || true
+		} | while IFS="$(printf '\t')" read -r sev msg; do
+			[ -n "$sev" ] || continue
+			printf '  %-5s  %s\n' "$sev" "$msg"
+		done
+
+		[ "$NERR" = "0" ] || exit 2
+		;;
+
+	import)
+		PLAN="${1-}"
+		[ -n "$PLAN" ] || { err "import needs a plan path"; exit 4; }
+		[ -f "$PLAN" ] || { err "no such plan: $PLAN"; exit 4; }
+		shift
+
+		DIR="$PWD" FORCE=""
+		while [ $# -gt 0 ]; do
+			case "$1" in
+				--dir)
+					if [ $# -lt 2 ] || [ -z "${2-}" ]; then err "--dir needs a path"; exit 4; fi
+					case "$2" in --*) err "--dir needs a path, but the next argument is the flag $2"; exit 4 ;; esac
+					DIR="$2"; shift 2 ;;
+				--force) FORCE=1; shift ;;
+				*) err "unknown flag: $1"; exit 4 ;;
+			esac
+		done
+
+		command -v jq >/dev/null 2>&1 || { err "jq is required"; exit 5; }
+		STATUS="$(dirname "$0")/status.sh"
+		[ -f "$STATUS" ] || { err "status.sh not found beside this script"; exit 4; }
+
+		parse_plan "$PLAN"
+
+		# A plan with errors in it is a plan nobody should be running yet, so
+		# importing one would seed a run against work that has to change first.
+		if [ "$NERR" != "0" ]; then
+			if [ -n "$FORCE" ]; then
+				err "$PLAN has $(plural "$NERR" error); importing anyway because --force was passed"
+			else
+				err "$PLAN has $(plural "$NERR" error); fix them or re-run with --force (plan.sh validate lists them)"
+				exit 2
+			fi
+		fi
+
+		[ "$NTASKS" != "0" ] || { err "$PLAN has no tasks to import"; exit 2; }
+
+		# The plan marks that a task is mechanical; pre-flight ratifies which model
+		# it actually runs on, and that answer lives in run.json. Re-import must
+		# not replace it with the placeholder, so the ids already carrying a model
+		# are read first and skipped.
+		HAS_MODEL=" $(bash "$STATUS" show --json --dir "$DIR" 2>/dev/null |
+			jq -r '[.tasks[]? | select(.model != null) | .id] | join(" ")' 2>/dev/null) "
+
+		printf '%s\n' "$TASKROWS" | while IFS="$(printf '\t')" read -r _ id name tier model flips; do
+			[ -n "${id:-}" ] || continue
+			set -- task "$id" --name "$name" --dir "$DIR"
+			[ "$flips" = "1" ] && set -- "$@" --flips
+			[ "$tier" != "-" ] && [ -n "$tier" ] && set -- "$@" --tier "$tier"
+			case "$HAS_MODEL" in
+				*" $id "*) ;;
+				*) [ "$model" = "1" ] && set -- "$@" --model cheap ;;
+			esac
+			bash "$STATUS" "$@" || exit 1
+		done || exit 1
+		imported="$NTASKS"
+
+		echo "imported $(plural "$imported" task) from $(basename "$PLAN")"
+		;;
+
+	*)
+		err "unknown subcommand: $SUB"
+		usage
+		exit 4
+		;;
+esac

package/skills/sluice/scripts/status.sh

@@ -0,0 +1,365 @@
+#!/usr/bin/env bash
+# sluice run state: the task breakdown, in a form something other than a
+# language model can read.
+#
+# The prose run record still holds the reasons and the cross-task findings.
+# This file holds only what changes as the run moves, so a statusline, a
+# resumed session or a reader who never saw the plan can answer "where is
+# this" without parsing markdown.
+#
+#   status.sh init --topic <t> --channel <c> [--plan <p>] [--record <p>] [--force]
+#   status.sh task <id> [--name <n>] [--status <s>] [--base <sha>]
+#                       [--commit <sha>] [--tier 0-3] [--model <m>] [--flips]
+#   status.sh preflight [--review <t>] [--model <t>] [--workspace <t>]
+#   status.sh show [--json]
+#   status.sh line
+#   status.sh close
+#
+# --dir <path> selects the tree to read (default: $PWD). State lives at
+# <dir>/.sluice/run.json and closed runs at <dir>/.sluice/archive/.
+#
+# Exit: 0 ok, 1 the state could not be written, 2 no live run, 3 a run is
+# already live, 4 bad arguments, 5 jq missing, 6 the state file is unreadable.
+# `line` is exempt and always exits 0 in silence, because a statusline renders
+# on every keystroke and has nowhere to put an error.
+#
+# A flag value may not begin with `--`: unchecked, an omitted value silently
+# becomes the next flag and the field holds a flag name.
+
+set -uo pipefail
+
+STATUSES="todo active review done blocked"
+CHANNELS="bypass fast main deep"
+
+err() { echo "status.sh: $*" >&2; }
+
+usage() {
+	echo "usage:" >&2
+	sed -n '/^#   status.sh init/,/^# 5 jq missing/p' "$0" | sed 's/^# \{0,2\}//' >&2
+}
+
+# A flag's value has to be checked before `shift 2`, not after. Bash refuses to
+# shift when fewer than two arguments remain and returns non-zero instead, and
+# with no `set -e` the flag loop then spins forever: $# stops decreasing and the
+# loop condition stays true. Runs in the current shell rather than a subshell so
+# its exit is the script's.
+need_value() { # <flag> <remaining $#> <candidate>
+	if [ "$2" -lt 2 ]; then
+		err "$1 needs a value"
+		exit 4
+	fi
+	case "$3" in
+		--*) err "$1 needs a value, but the next argument is the flag $3"; exit 4 ;;
+	esac
+}
+
+# A word from a space-separated set. Keeps validation in one place so every
+# rejection reads the same and names the offending value.
+in_set() {
+	local needle="$1" hay="$2" w
+	for w in $hay; do [ "$w" = "$needle" ] && return 0; done
+	return 1
+}
+
+# --dir may arrive anywhere in the line, so it is stripped before the
+# subcommand's own flag loop ever sees it.
+DIR="$PWD"
+ARGS=()
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--dir)
+			need_value --dir $# "${2-}"
+			[ -n "$2" ] || { err "--dir needs a path"; exit 4; }
+			DIR="$2"
+			shift 2
+			;;
+		*)
+			ARGS+=("$1")
+			shift
+			;;
+	esac
+done
+set -- "${ARGS[@]+"${ARGS[@]}"}"
+
+SUB="${1-}"
+[ $# -gt 0 ] && shift
+if [ -z "$SUB" ]; then
+	usage
+	exit 4
+fi
+
+STATE="$DIR/.sluice/run.json"
+ARCHIVE="$DIR/.sluice/archive"
+
+# `line` swallows everything: a missing jq, unreadable state, no run at all.
+# Any of those printing would put permanent clutter in the status bar.
+if [ "$SUB" = "line" ]; then
+	[ $# -eq 0 ] || { err "line takes no arguments"; exit 4; }
+	command -v jq >/dev/null 2>&1 || exit 0
+	[ -f "$STATE" ] || exit 0
+	jq -r '
+		([.tasks[]? | select(.status == "done")] | length) as $done
+		| [ "sluice",
+		    (.channel // "?"),
+		    "\($done)/\(.tasks | length)",
+		    ([.tasks[]? | select(.status == "active") | "▸T\(.id)"] | first // empty),
+		    ([.tasks[]? | select(.status == "blocked") | "!T\(.id)"] | first // empty)
+		  ] | join(" ")
+	' "$STATE" 2>/dev/null || exit 0
+	exit 0
+fi
+
+command -v jq >/dev/null 2>&1 || { err "jq is required"; exit 5; }
+
+require_run() {
+	[ -f "$STATE" ] || { err "no run is live in $DIR (start one with: status.sh init)"; exit 2; }
+}
+
+# Distinct from a missing jq, which is exit 5: reported as that, a corrupt state
+# file sends the reader off to install a tool they already have.
+require_readable() {
+	jq -e . "$STATE" >/dev/null 2>&1 || {
+		err "cannot parse $STATE (repair it, or archive it with: status.sh close)"
+		exit 6
+	}
+}
+
+# Written through a temporary file so an interrupted write cannot leave the
+# run state half-serialised, which would read as a corrupted run rather than
+# as a failed command.
+#
+# The candidate is checked before it is installed, because the failure to guard
+# against is an empty one rather than a malformed one: `cat` succeeds on empty
+# stdin, so a jq that died upstream of this feeds it nothing, and installing
+# nothing atomically is still a wipe of the one file in the run that outlives
+# compaction. A command that cannot finish leaves the state as it found it.
+write_state() {
+	local tmp="$STATE.tmp.$$"
+	cat >"$tmp"
+	if [ ! -s "$tmp" ] || ! jq -e . "$tmp" >/dev/null 2>&1; then
+		rm -f "$tmp"
+		err "refusing to write $STATE: the update produced no valid state, so the existing state is unchanged"
+		exit 1
+	fi
+	mv "$tmp" "$STATE" || { rm -f "$tmp"; err "could not replace $STATE"; exit 1; }
+}
+
+case "$SUB" in
+	init)
+		TOPIC="" CHANNEL="" PLAN="" RECORD="" FORCE=0
+		while [ $# -gt 0 ]; do
+			case "$1" in
+				--topic) need_value --topic $# "${2-}"; TOPIC="$2"; shift 2 ;;
+				--channel) need_value --channel $# "${2-}"; CHANNEL="$2"; shift 2 ;;
+				--plan) need_value --plan $# "${2-}"; PLAN="$2"; shift 2 ;;
+				--record) need_value --record $# "${2-}"; RECORD="$2"; shift 2 ;;
+				--force) FORCE=1; shift ;;
+				*) err "unknown flag: $1"; exit 4 ;;
+			esac
+		done
+		[ -n "$TOPIC" ] || { err "init needs --topic"; exit 4; }
+		[ -n "$CHANNEL" ] || { err "init needs --channel"; exit 4; }
+		in_set "$CHANNEL" "$CHANNELS" || { err "unknown channel: $CHANNEL (one of: $CHANNELS)"; exit 4; }
+
+		if [ -f "$STATE" ] && [ "$FORCE" -eq 0 ]; then
+			live="$(jq -r '.topic // "?"' "$STATE" 2>/dev/null || echo "?")"
+			err "a run is already live (topic: $live); pass --force to replace it"
+			exit 3
+		fi
+
+		mkdir -p "$DIR/.sluice"
+		jq -n \
+			--arg topic "$TOPIC" \
+			--arg channel "$CHANNEL" \
+			--arg started "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+			--arg plan "$PLAN" \
+			--arg record "$RECORD" '
+			{schema: 1, topic: $topic, channel: $channel, started: $started}
+			+ (if $plan == "" then {} else {plan: $plan} end)
+			+ (if $record == "" then {} else {record: $record} end)
+			+ {tasks: []}
+		' | write_state
+		;;
+
+	task)
+		ID="${1-}"
+		[ $# -gt 0 ] && shift
+		case "$ID" in
+			"" ) err "task needs an id"; exit 4 ;;
+			*[!0-9]* | 0 ) err "task id must be a positive integer, got: $ID"; exit 4 ;;
+		esac
+
+		NAME="" STATUS="" BASE="" COMMIT="" TIER="" MODEL="" FLIPS=false
+		while [ $# -gt 0 ]; do
+			case "$1" in
+				--name) need_value --name $# "${2-}"; NAME="$2"; shift 2 ;;
+				--status) need_value --status $# "${2-}"; STATUS="$2"; shift 2 ;;
+				--base) need_value --base $# "${2-}"; BASE="$2"; shift 2 ;;
+				--commit) need_value --commit $# "${2-}"; COMMIT="$2"; shift 2 ;;
+				--tier) need_value --tier $# "${2-}"; TIER="$2"; shift 2 ;;
+				--model) need_value --model $# "${2-}"; MODEL="$2"; shift 2 ;;
+				--flips) FLIPS=true; shift ;;
+				*) err "unknown flag: $1"; exit 4 ;;
+			esac
+		done
+
+		if [ -n "$STATUS" ]; then
+			in_set "$STATUS" "$STATUSES" || { err "unknown status: $STATUS (one of: $STATUSES)"; exit 4; }
+		fi
+		if [ -n "$TIER" ]; then
+			case "$TIER" in
+				0|1|2|3) ;;
+				*) err "tier must be 0, 1, 2 or 3, got: $TIER"; exit 4 ;;
+			esac
+		fi
+
+		require_run
+		require_readable
+
+		# A row with no name is a number nobody can act on, so a new id has to
+		# bring one. An existing id does not, which is what makes every later
+		# call a bare status flip.
+		#
+		# A read that failed is not the same answer as "the id is known", so the
+		# count is checked rather than compared: unchecked, an empty result skips
+		# the guard the way a hit would.
+		known="$(jq --argjson id "$ID" '[.tasks[]? | select(.id == $id)] | length' "$STATE" 2>/dev/null)"
+		case "$known" in
+			'' | *[!0-9]*) err "could not read the task list from $STATE"; exit 6 ;;
+		esac
+		if [ "$known" = "0" ] && [ -z "$NAME" ]; then
+			err "task $ID is new here, so it needs --name"
+			exit 4
+		fi
+
+		patch="$(jq -n \
+			--arg name "$NAME" --arg status "$STATUS" --arg base "$BASE" \
+			--arg commit "$COMMIT" --arg tier "$TIER" --arg model "$MODEL" \
+			--argjson flips "$FLIPS" '
+			{}
+			+ (if $name   == "" then {} else {name: $name} end)
+			+ (if $status == "" then {} else {status: $status} end)
+			+ (if $base   == "" then {} else {base: $base} end)
+			+ (if $commit == "" then {} else {commit: $commit} end)
+			+ (if $tier   == "" then {} else {tier: ($tier | tonumber)} end)
+			+ (if $model  == "" then {} else {model: $model} end)
+			+ (if $flips then {flips: true} else {} end)
+		')"
+
+		jq --argjson id "$ID" --argjson patch "$patch" '
+			.tasks = (
+				if any(.tasks[]?; .id == $id)
+				then [.tasks[] | if .id == $id then . + $patch else . end]
+				else .tasks + [{id: $id, status: "todo"} + $patch]
+				end
+			)
+			| .tasks |= sort_by(.id)
+		' "$STATE" | write_state
+		;;
+
+	preflight)
+		REVIEW="" MODEL="" WORKSPACE=""
+		while [ $# -gt 0 ]; do
+			case "$1" in
+				--review) need_value --review $# "${2-}"; REVIEW="$2"; shift 2 ;;
+				--model) need_value --model $# "${2-}"; MODEL="$2"; shift 2 ;;
+				--workspace) need_value --workspace $# "${2-}"; WORKSPACE="$2"; shift 2 ;;
+				*) err "unknown flag: $1"; exit 4 ;;
+			esac
+		done
+		if [ -z "$REVIEW$MODEL$WORKSPACE" ]; then
+			err "preflight needs at least one of --review, --model, --workspace"
+			exit 4
+		fi
+		require_run
+		require_readable
+
+		jq --arg review "$REVIEW" --arg model "$MODEL" --arg workspace "$WORKSPACE" '
+			.preflight = ((.preflight // {})
+				+ (if $review    == "" then {} else {review: $review} end)
+				+ (if $model     == "" then {} else {model: $model} end)
+				+ (if $workspace == "" then {} else {workspace: $workspace} end))
+		' "$STATE" | write_state
+		;;
+
+	show)
+		JSON=0
+		while [ $# -gt 0 ]; do
+			case "$1" in
+				--json) JSON=1; shift ;;
+				*) err "unknown flag: $1"; exit 4 ;;
+			esac
+		done
+		require_run
+		require_readable
+
+		if [ "$JSON" -eq 1 ]; then
+			jq . "$STATE"
+			exit 0
+		fi
+
+		# Header and rows are laid out from the same widths, so the two cannot
+		# drift apart, and an over-long value is clipped with a marker rather
+		# than silently reading as the whole value.
+		jq -r '
+			def dash: if . == null or . == "" then "-" else . end;
+			def cell($w): tostring
+				| if length > $w then .[0:$w - 1] + "…"
+				  else . + (" " * ($w - length))
+				  end;
+			def row($c): "  " + ([($c[0] | cell(3)), ($c[1] | cell(8)), ($c[2] | cell(29)),
+			                      ($c[3] | cell(9)), ($c[4] | cell(9)), ($c[5] | cell(4)),
+			                      $c[6]] | join(" "));
+			([.tasks[]? | select(.status == "done")] | length) as $done
+			| ["sluice \(.channel) · \(.topic) · \($done)/\(.tasks | length) done"]
+			+ ["plan        \(.plan | dash)"]
+			+ ["record      \(.record | dash)"]
+			+ ["pre-flight  " + (
+				if (.preflight // {} | length) == 0 then "not recorded"
+				else [(.preflight | to_entries[] | "\(.key)=\(.value)")] | join("; ")
+				end)]
+			+ [""]
+			+ [row(["id", "status", "task", "base", "commit", "tier", "model"])]
+			+ [ .tasks[]?
+				| (if .flips then "  FLIPS" else "" end) as $flips
+				| row([.id, .status, (.name | dash), (.base | dash),
+				       (.commit | dash), (.tier | dash), (.model | dash)]) + $flips
+			  ]
+			| .[]
+		' "$STATE"
+		;;
+
+	close)
+		[ $# -eq 0 ] || { err "close takes no arguments"; exit 4; }
+		require_run
+
+		# Deliberately not `require_readable`. The parse error every other
+		# subcommand raises names close as the way out, so close is the one
+		# command that has to accept state nothing else will touch: it moves the
+		# file aside intact rather than leaving it wedged in the tree.
+		started="$(jq -r '.started // empty' "$STATE" 2>/dev/null)"
+		topic="$(jq -r '.topic // empty' "$STATE" 2>/dev/null)"
+		stamp="$(printf '%s' "$started" | tr -cd '0-9TZ')"
+		slug="$(printf '%s' "${topic:-run}" | tr -cs 'A-Za-z0-9._-' '-')"
+		[ -n "$stamp" ] || stamp="unknown"
+		mkdir -p "$ARCHIVE"
+
+		# The archive holds the only copy of a closed run, and two runs sharing a
+		# start second and a topic name the same file. mv would leave one of them,
+		# so the name gets a suffix rather than the earlier run being silently
+		# dropped.
+		dest="$ARCHIVE/$stamp-$slug.json"
+		n=2
+		while [ -e "$dest" ]; do
+			dest="$ARCHIVE/$stamp-$slug-$n.json"
+			n=$((n + 1))
+		done
+		mv "$STATE" "$dest"
+		;;
+
+	*)
+		err "unknown subcommand: $SUB"
+		usage
+		exit 4
+		;;
+esac

package/skills/sluice/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "sluice",
-  "version": "0.7.0",
-  "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries seven rules as one-liners in the router and the full treatment in references read only on friction, and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Claude Code only; stands down where the superpowers pipeline governs the repo.",
+  "version": "0.10.0",
+  "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries seven rules as one-liners in the router and the full treatment in references read only on friction. Checks the finished plan with plan.sh validate rather than trusting it to memory, seeds the run state from it, keeps a deep run's task breakdown in .sluice/run.json so a statusline segment and one status command can answer where the run is, and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Claude Code only; stands down where the superpowers pipeline governs the repo.",
   "author": "iceinvein",
   "type": "prompt",
   "tools": [