@iceinvein/agent-skills 0.14.0 → 0.15.0

package/dist/cli/index.js

@@ -296,6 +296,9 @@ function validateManifest(data) {
     if (a.claudeHookDirective !== undefined && typeof a.claudeHookDirective !== "string") {
       return { ok: false, error: "'activation.claudeHookDirective' must be a string" };
     }
+    if (a.claudeHookScript !== undefined && typeof a.claudeHookScript !== "string") {
+      return { ok: false, error: "'activation.claudeHookScript' must be a string" };
+    }
   }
   return { ok: true, manifest: d };
 }
@@ -425,12 +428,17 @@ function runScript(scriptPath, cwd) {
   });
   return { ok: result.exitCode === 0, code: result.exitCode ?? 1 };
 }
-function matchesSkillDirective(hook, skillName) {
+function shq(s) {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+function matchesSkillDirective(hook, skillName, directive) {
   if (hook.skill !== undefined)
     return hook.skill === skillName;
+  if (directive !== undefined && hook.command.includes(`echo ${shq(directive)}`))
+    return true;
   return hook.command.includes(`Activate ${skillName} skill`);
 }
-async function wireSessionStartHook(settingsPath, skillName, directive) {
+async function wireSessionStartHook(settingsPath, skillName, directive, scriptPath) {
   let settings = {};
   if (existsSync2(settingsPath)) {
     settings = await Bun.file(settingsPath).json();
@@ -439,12 +447,50 @@ async function wireSessionStartHook(settingsPath, skillName, directive) {
     settings.hooks = {};
   if (!settings.hooks.SessionStart)
     settings.hooks.SessionStart = [];
-  const command = `echo '${directive}'`;
+  const command = scriptPath ? `echo ${shq(directive)}; if [ -f ${shq(scriptPath)} ]; then bash ${shq(scriptPath)}; fi` : `echo ${shq(directive)}`;
+  const legacy = `echo ${shq(directive)}`;
+  let adopted = false;
+  let custom = false;
+  let changed = false;
   for (const group of settings.hooks.SessionStart) {
+    const kept = [];
     for (const hook of group.hooks ?? []) {
-      if (matchesSkillDirective(hook, skillName))
-        return;
+      if (!matchesSkillDirective(hook, skillName, directive)) {
+        kept.push(hook);
+        continue;
+      }
+      const plain = hook.skill !== undefined || hook.command === legacy;
+      if (!plain) {
+        custom = true;
+        kept.push(hook);
+        continue;
+      }
+      if (adopted) {
+        changed = true;
+        continue;
+      }
+      adopted = true;
+      if (hook.command !== command || hook.skill !== skillName) {
+        hook.command = command;
+        hook.skill = skillName;
+        changed = true;
+      }
+      kept.push(hook);
+    }
+    if (kept.length !== (group.hooks ?? []).length)
+      group.hooks = kept;
+  }
+  settings.hooks.SessionStart = settings.hooks.SessionStart.filter((group) => !group.hooks || group.hooks.length > 0);
+  if (adopted || custom) {
+    if (custom && !adopted && scriptPath) {
+      console.warn(`${skillName}: a hand-edited SessionStart hook already carries its directive, so it was left as is and ${scriptPath} was not wired; add it to that entry yourself if you want it.`);
     }
+    if (changed) {
+      mkdirSync(dirname(settingsPath), { recursive: true });
+      await Bun.write(settingsPath, JSON.stringify(settings, null, 2) + `
+`);
+    }
+    return;
   }
   settings.hooks.SessionStart.push({
     hooks: [{ type: "command", command, skill: skillName }]
@@ -453,15 +499,17 @@ async function wireSessionStartHook(settingsPath, skillName, directive) {
   await Bun.write(settingsPath, JSON.stringify(settings, null, 2) + `
 `);
 }
-async function unwireSessionStartHook(settingsPath, skillName) {
+async function unwireSessionStartHook(settingsPath, skillName, directive) {
   if (!existsSync2(settingsPath))
     return;
   const settings = await Bun.file(settingsPath).json();
   const sessionStart = settings.hooks?.SessionStart;
   if (!sessionStart)
     return;
+  const legacy = directive === undefined ? undefined : `echo ${shq(directive)}`;
+  const ours = (h) => matchesSkillDirective(h, skillName, directive) && (h.skill !== undefined || legacy === undefined || h.command === legacy);
   const filteredGroups = sessionStart.map((group) => ({
-    hooks: (group.hooks ?? []).filter((h) => !matchesSkillDirective(h, skillName))
+    hooks: (group.hooks ?? []).filter((h) => !ours(h))
   })).filter((group) => group.hooks.length > 0);
   if (filteredGroups.length === 0) {
     delete settings.hooks.SessionStart;
@@ -529,7 +577,9 @@ var claudeAdapter = {
     }
     if (activation === "global" && manifest.activation?.claudeHookDirective) {
       const settingsPath = join2(cwd, ".claude/settings.json");
-      await wireSessionStartHook(settingsPath, manifest.name, manifest.activation.claudeHookDirective);
+      const script = manifest.activation.claudeHookScript;
+      const scriptPath = script && config.bundleRoot ? join2(cwd, config.bundleRoot, script) : undefined;
+      await wireSessionStartHook(settingsPath, manifest.name, manifest.activation.claudeHookDirective, scriptPath);
       if (!installed.includes(".claude/settings.json")) {
         installed.push(".claude/settings.json");
       }
@@ -594,7 +644,7 @@ var claudeAdapter = {
     }
     if (manifest.activation?.claudeHookDirective) {
       const settingsPath = join2(cwd, ".claude/settings.json");
-      await unwireSessionStartHook(settingsPath, manifest.name);
+      await unwireSessionStartHook(settingsPath, manifest.name, manifest.activation.claudeHookDirective);
     }
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.14.0",
+  "version": "0.15.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. 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.",
+    "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, one status command and a SessionStart hook can answer where the run is (the hook prints a live run at every session start, compaction included), 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.15.0"
+    "version": "0.16.0"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/sluice/SKILL.md

@@ -30,8 +30,11 @@ back to you and the run never left your hands.
 
 Name the channel and the signal that actually routed you there. The strings above
 are examples, not fixed copy, and a channel with a two-part signal should say
-which part applied. `bypass` says nothing at all, because a question that gets
-announced stops being a question.
+which part applied. One thing is fixed: the words `<channel> channel` open the
+message or follow a label such as `Sluice:`, because the meter finds the run by
+them and an announcement worded otherwise reports as `not announced`. `bypass`
+says nothing at all, because a question that gets announced stops being a
+question.
 
 **`root-cause`, `finish`, `meter` and `show-or-say` are not channel-assigned.**
 The code misbehaving triggers the first: a bug report, a red test, behaviour you
@@ -157,10 +160,16 @@ 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
+Four from that file that catch people out: concurrent implementers need a
 worktree each and the flip runs alone, review is tiered rather than automatic,
-and a `deep` run that cannot dispatch has to replace the review tier with
-something, not quietly ship without one.
+a `deep` run that cannot dispatch has to replace the review tier with
+something, not quietly ship without one, and the run ends: `status.sh final`
+when the plan's own review clears, `status.sh close` once the work is no longer
+yours to act on, after a local merge, when the branch is left as it stands, or
+when an open PR lands, not when it opens. A run left open reads as live to the
+statusline and blocks the next one. The SessionStart hook prints a live run at every session start,
+compaction and resume included, so a run you did not start is one you were
+shown, not one you have to remember.
 
 ## Conflicts
 

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

@@ -253,10 +253,18 @@ declared schedule is wrong the moment one task lands late or comes back with a
 blocking finding. A derived one just recomputes, which is the whole reason `ready`
 reads the run state rather than the plan: it sees what has actually landed.
 
-- 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.
+- One row per task in `run.json`, and you are the one who flips it; an
+  implementer reports, it does not write the run state. `active` at dispatch,
+  which records the base as the HEAD of the tree the command is pointed at
+  unless you pass `--base`. `review` when the task's commit is in and its
+  reviewer has gone out: the paths stay held, because a finding may send the
+  implementer back into them. `done --commit <sha> --reviewed` when the review
+  clears, or `done --commit <sha>` alone for a tier 0 task, which was owed a
+  stat read and no dispatch, and for a task whose dispatch pre-flight declined;
+  the debt count counts the second kind and not the first. That state outlives
+  compaction; your memory doesn't.
+- Each task goes to a fresh agent carrying the brief below and nothing this
+  session accumulated. What you hold 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
@@ -307,6 +315,31 @@ commit only when asked is about that outward-facing act. The plan's sign-off
 is the asking. Nothing a task commits reaches anywhere your partner has not
 already agreed to, so the instruction is satisfied rather than excepted.
 
+## The dispatch brief
+
+An implementer sees its task and nothing else, so anything it has to obey that
+is not in the task text has to be in the brief. The rules it would otherwise
+never meet are the ones this skill spends the most words on, and an agent that
+never loaded the skill follows none of them by default. The brief carries, in
+this order:
+
+- **Ground Rules**, verbatim from the plan. They bind every task and are
+  repeated in none, so the brief is where they reach the implementer.
+- **The task**, whole: heading, Contract, Touches, Flips, steps.
+- **The implementer contract**, five lines that are the same for every task:
+  the test comes first and is watched failing before the code
+  (`references/test-first.md`, one paragraph of it, not a pointer the agent
+  cannot follow); nothing outside `Touches` is edited; the commit stages only
+  the paths in `Touches`, never `git add -A`; the reply reports the commit SHA
+  and names any behaviour left untested and why; and `.sluice/` is not written,
+  the run state being yours to flip.
+- **The label**, `T<n>: <task name>`, on the dispatch itself.
+
+Leave out how you got here. The design, the record, the other tasks and this
+session's reasoning are what dispatch exists to keep out of the implementer's
+context, and a brief that carries them has spent the fresh context it was
+buying.
+
 ## When dispatch is unavailable
 
 Separate two cases first. A session where dispatch is off unless your partner
@@ -409,10 +442,12 @@ 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 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.
+The base is recorded when the task goes `active`: the flip takes the HEAD of
+the tree it is pointed at, `--dir` if you passed one and the tree you issued it
+from otherwise, so point it at the tree the implementer is cut from, or pass
+`--base <sha>` where that differs. 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.
 
 **A finding surviving two rounds may be a defect in the criterion, not the
 work.** Before a third round, ask whether any output could satisfy it. A
@@ -452,6 +487,14 @@ absorb into the next task's brief.
 
 ## The final review
 
+It runs once every task is `done` and every per-task review is back, and it
+comes before `references/finish.md` starts: the suite run there is the last
+check before the three options, and a review that lands after it would be
+reviewing a tree the suite never saw. Mark it with `status.sh final` when it
+clears, so `show` and `close` report it done rather than pending; the per-task
+marks cannot stand in for it, because they count dispatches the tier table owed
+and this one is owed by the plan as a whole.
+
 It covers cross-task integration and everything the record accumulated, not
 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

package/skills/sluice/references/finish.md

@@ -5,6 +5,10 @@ in every channel. A commit made in passing during `fast` channel work is
 not one of those: the branch as a whole has to be about to leave your
 hands.
 
+In `deep`, the final review comes before this file starts, and its verdict is
+in hand or it is not: `references/deep-channel.md` owns it. Nothing here
+dispatches a review; this is where what the reviews found gets said.
+
 Start here: run every test the project has, not a sample of them. A red
 result stops the process; there is no menu after a failure. A pass from
 earlier in the session doesn't count: the tree has changed since, and
@@ -30,6 +34,32 @@ After a local merge, run the whole suite again over the merged tree before
 deleting anything. A failure there stops the cleanup; you haven't pushed
 anything yet, so you can still walk it back.
 
+## The handback message
+
+The parts are owned by three references and read as one message, so this is
+the one list of them. In order:
+
+1. The suite's result, as it printed, with the command that produced it.
+2. The ledger, `scripts/run-stats.sh --tests "<that result>"`, pasted
+   unedited. `references/meter.md`
+3. In `deep`, `status.sh show`, pasted, so "four of nine, task five blocked,
+   two unreviewed, final review pending" is on the page rather than in your
+   account of it. `references/status.md`
+4. One clause on review: dispatched and clear, dispatched with findings still
+   open, or not dispatched and why. In `deep` that clause covers the per-task
+   tiers and the final review separately, because the debt count carries one
+   and not the other.
+5. The three options, and nothing after them.
+
+A `deep` run closes when the work stops being yours to act on: after a local
+merge and its re-run of the suite, or when your partner leaves the branch where
+it stands. While a PR is open it stays live, because the review comments come
+back as work on those same tasks and the rows are where that work is tracked;
+it closes when the PR lands. `status.sh close` archives the state and prints
+one line saying what it archived, and that line goes in your reply. A run left
+open blocks the next `init` and renders a finished plan in the statusline as a
+live one, which is how a run comes to sit at 0/9 for three weeks.
+
 While a PR is open, the workspace survives: it is where the review
 comments get answered, and tearing it down means rebuilding it the moment
 the first one arrives. Discarding needs an explicit, confirmed ask from

package/skills/sluice/references/meter.md

@@ -1,7 +1,8 @@
 # Meter the run
 
 Run `scripts/run-stats.sh` as part of the message that hands the work back,
-and paste its output into that message unedited:
+and paste its output into that message unedited; `references/finish.md` says
+where in that message it sits:
 
 ```
 bash <skill-dir>/scripts/run-stats.sh --tests "<what the suite actually printed>"

package/skills/sluice/references/status.md

@@ -20,6 +20,7 @@ bash <skill-dir>/scripts/status.sh preflight --review "tier 3 only" --model "6 o
      --workspace "one worktree per implementer"
 bash <skill-dir>/scripts/status.sh show
 bash <skill-dir>/scripts/status.sh ready
+bash <skill-dir>/scripts/status.sh final
 bash <skill-dir>/scripts/status.sh line --full
 bash <skill-dir>/scripts/status.sh close
 ```
@@ -30,7 +31,29 @@ run as the tree it was cut from. 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.
+`.sluice/archive/`, prints one line saying what it archived, progress, review
+debt and whether the final review landed, and frees the tree for the next one.
+
+The controller writes every row. An implementer reports its SHA in its reply
+and touches nothing under `.sluice/`; the brief in `references/deep-channel.md`
+says so to it. `active` is the dispatch, `review` is the commit in and a
+reviewer out, with the task's paths still held because a finding may send the
+implementer back into them, and `done` is the end: with `--reviewed` when a
+review cleared it, without when the tier owed one and pre-flight declined it,
+which is the row the debt count counts.
+
+A task going `active` with no `--base` takes the HEAD of the tree the command
+is pointed at, `--dir` if given and the current tree otherwise, once; a base
+already on the row is kept. Pass `--base` when the implementer's tree is
+neither.
+
+Every write stamps `updated`. Past a day since the last one, `show` and the
+statusline both say how long the run has sat idle, because a finished plan
+whose run was never closed looks exactly like a live one otherwise, and it
+blocks the next `init`.
+
+`final` records that the plan's final review cleared. `show` reports it
+pending until then, and `close` says which it was.
 
 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
@@ -54,17 +77,23 @@ the plan seeded would be absent from every implementer, `init` there would
 start a second run nothing else reads, and the worktree would take that state
 with it when it went.
 
-So every command anchors on the main worktree of whatever tree it is pointed
-at, and one run covers the set. The statusline renders the same run in every
-window, a flip made by an implementer lands where the controller is watching,
-and `init` from a worktree reports the run that is already live rather than
-replacing it. A submodule anchors on its own checkout, not the superproject's,
-and a directory that is no git work tree keeps its run exactly where it sits.
+So a tree with no run of its own anchors on the main worktree of its set, and
+the set's run covers it: the statusline renders the controller's run in every
+implementer's window, and a flip issued from any of those trees lands where
+every other one is watching. A tree's own run comes first, though. `init`
+always lands in the tree it is given, and every other command reads that
+tree's state when it has one, so two sessions working independently in two
+worktrees of one repo each keep their own run and neither is shown the
+other's. Anchored unconditionally, as this once was, the first `init` in the
+set took over every other session's statusline and refused every other `init`.
+A submodule anchors on its own checkout, not the superproject's, and a
+directory that is no git work tree keeps its run exactly where it sits.
 
 One file for several writers is one file to contend on, so `init`, `task`,
-`preflight` and `close` take a lock first: four implementers each flipping
-their own row would otherwise have the later write built on a snapshot taken
-before the earlier one landed, dropping that row without saying so. The lock
+`preflight`, `final` and `close` take a lock first: two flips issued at the
+same moment from different trees would otherwise have the later write built on
+a snapshot taken before the earlier one landed, dropping that row without
+saying so. The lock
 carries its holder's pid, so a killed run is broken through rather than waited
 out. Reads take nothing, state being installed through a rename, which is what
 keeps `line` cheap enough to render on.
@@ -108,8 +137,9 @@ 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
+and record paths, how long it has sat idle once that passes a day, the review
+debt, the final review, 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.
 
@@ -184,6 +214,26 @@ establishes is what the tasks after it are checked against.
 Derive the wave here rather than writing wave numbers into the plan. A declared
 schedule is wrong the moment one task lands late; this recomputes.
 
+What a wave of several means is read off the pre-flight workspace answer: an
+answer containing "per implementer", "per concurrent implementer", "each
+implementer" or "worktree each" prints "a worktree each", any other recorded
+answer prints "serial, one at a time in the shared tree", and no answer prints
+neither. It is a match on words, not a reading of the sentence, so record the
+answer in one of those phrases when worktrees were bought and in none of them
+when they were not.
+
+## On session start
+
+`scripts/session-start.sh` is the SessionStart hook a global install wires,
+after the routing directive. On startup, resume, clear and compact it runs
+`show` against the tree the session opened in, a subdirectory or a linked
+worktree included since `show` anchors on the main worktree, and prints the
+run when there is one, with one sentence more: after a compaction, resume or
+clear, that the record is to be read before the next dispatch; on a fresh
+start, that a run not being continued was left open and wants `close`. A tree
+with no run prints nothing. The reading-back rule above still stands; this is
+the harness doing it at the one moment memory has just been cut.
+
 ## Statusline
 
 This is the part that makes a run visible without anyone asking. Give it rows of
@@ -240,6 +290,9 @@ because the mapping from state to colour belongs next to the state. A caller tha
 coloured the line itself would have to re-derive each cell's meaning from its
 glyph, which is the same fact stored twice.
 
+Past a day since the last write the first row gains `· idle 2d1h`, so a run
+nobody closed reads as one.
+
 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

package/skills/sluice/scripts/session-start.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# SessionStart hook: show a live sluice run to the session that just opened.
+#
+# A deep run outlives the context window that started it. The prose asks the
+# model to run `status.sh show` after a compaction, and that is the one rule with
+# nothing but memory behind it, in the one moment memory has just been cut. So
+# the harness does the asking: on startup, resume, clear and compact this prints
+# the run, and on a tree with no run it prints nothing.
+#
+# Reads the harness's session JSON on stdin for `cwd` and `source`, falling back
+# to $PWD when there is none. Always exits 0: a hook that fails is noise in a
+# session that has not started yet.
+
+set -uo pipefail
+
+here="$(cd "$(dirname "$0")" && pwd)"
+STATUS="$here/status.sh"
+
+# Bounded, and skipped on a terminal: the harness closes stdin after the JSON,
+# but a hook that inherits an open, silent stdin would otherwise never return,
+# and a hook that never returns holds the session start with it. Read a byte at
+# a time: on a timeout bash 3.2, which is what macOS ships, discards whatever
+# the interrupted read had gathered where bash 4 keeps it, and a byte read
+# whole before the timeout is kept by both, trailing newline or not.
+input=""
+if [ ! -t 0 ]; then
+	while IFS= read -r -n 1 -t 2 c; do
+		if [ -z "$c" ]; then input="$input
+"; else input="$input$c"; fi
+	done
+fi
+cwd="$PWD"
+source=""
+if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
+	got="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null || true)"
+	[ -n "$got" ] && cwd="$got"
+	source="$(printf '%s' "$input" | jq -r '.source // empty' 2>/dev/null || true)"
+fi
+
+# No gate of its own beyond the directory existing: status.sh anchors on the
+# main worktree of whatever tree it is given, which is what lets a session
+# opened in a subdirectory or a linked worktree find the run, and on a tree
+# with no run it exits 2 in silence. Once per session start, that is cheap.
+[ -d "$cwd" ] || exit 0
+[ -f "$STATUS" ] || exit 0
+
+shown="$(bash "$STATUS" show --dir "$cwd" 2>/dev/null)" || exit 0
+[ -n "$shown" ] || exit 0
+
+echo "A sluice run is live in this tree. Its state, from .sluice/run.json:"
+echo
+echo "$shown"
+echo
+case "$source" in
+	compact | resume | clear)
+		echo "This session's context was summarised, resumed or cleared. Read the run record before the next dispatch and trust the two files over what you remember."
+		;;
+	*)
+		echo "If this run is not the work you were asked to continue, it was left open: close it with status.sh close before starting another."
+		;;
+esac
+exit 0

package/skills/sluice/scripts/status.sh

@@ -15,6 +15,7 @@
 #   status.sh preflight [--review <t>] [--model <t>] [--workspace <t>]
 #   status.sh show [--json]
 #   status.sh ready
+#   status.sh final
 #   status.sh line [--full]
 #   status.sh close
 #
@@ -92,18 +93,29 @@ if [ -z "$SUB" ]; then
 	exit 4
 fi
 
-# A linked worktree is another view of the same run, not a new one. The run
-# directory ignores itself, so `git worktree add` never carries it across: read
-# from the tree it was called in, the run a plan seeded is absent from every
-# implementer created after that plan, and an `init` there lands a rival state
-# file that dies with the worktree. Every tree in a set anchors on the main
-# worktree instead, which is the one path all of them agree on.
+# A tree's own run comes first, and only a tree with none reads the set's. Two
+# layouts share this script and pull opposite ways. A deep run plans in the main
+# tree and cuts implementer worktrees after the plan: the run directory ignores
+# itself, so `git worktree add` never carries it across, and read from the tree
+# it was called in the run would be absent from every implementer. Those trees
+# hold no run of their own, so they anchor on the main worktree, the one path
+# the set agrees on. Independent sessions, one per worktree, each start a run
+# where they sit: anchored unconditionally, the first `init` in the set took
+# over every other session's statusline and refused every other `init`. So
+# `init` always lands in the tree it was given, and every other command reads
+# the tree's own state when it has one.
 #
 # `git worktree list` names the main worktree first. A submodule names its own
 # checkout there rather than the superproject's, which is what keeps a
 # submodule's run beside its own working tree, and a directory that is no git
 # work tree at all is left exactly as it was given.
-if [ "$(git -C "$DIR" rev-parse --is-inside-work-tree 2>/dev/null)" = "true" ]; then
+#
+# The tree the command was issued from, kept apart from the anchored one: a
+# base defaulted at dispatch is the HEAD of the tree the implementer is about to
+# be cut from, which in a worktree set is not always the main worktree's.
+ORIG_DIR="$DIR"
+if [ "$SUB" != "init" ] && [ ! -f "$DIR/.sluice/run.json" ] \
+	&& [ "$(git -C "$DIR" rev-parse --is-inside-work-tree 2>/dev/null)" = "true" ]; then
 	MAIN_TREE="$(git -C "$DIR" worktree list --porcelain 2>/dev/null | sed -n '1s/^worktree //p')"
 	if [ -n "${MAIN_TREE:-}" ] && [ -d "$MAIN_TREE" ]; then
 		DIR="$MAIN_TREE"
@@ -200,11 +212,23 @@ if [ "$SUB" = "line" ]; then
 		            else "◷ \($m / 60 | floor)h\($m % 60)m"
 		            end
 		     end) as $clock
+		# Idle is the time since the last write, and it only shows once it passes
+		# a day: a run in progress is written every few minutes, so a day of
+		# silence is a run that was forgotten or finished without being closed. A
+		# run written before `updated` existed falls back to `started`.
+		| ((.updated // .started // "" | try fromdateiso8601 catch 0) as $u
+		   | if $u == 0 then ""
+		     else (($now - $u) / 3600 | floor) as $h
+		          | if $h < 24 then ""
+		            else "idle \($h / 24 | floor)d\($h % 24)h"
+		            end
+		     end) as $idle
 		| ( paint("1;96"; "⧗") + " "
 		    + ([ paint("1;96"; (.channel // "?")),
 		         paint("2"; (.topic // ""))
 		       ] | join_parts)
 		    + (if $clock == "" then "" else "   " + paint("2"; $clock) end)
+		    + (if $idle == "" then "" else " " + paint("2"; "·") + " " + paint("33"; $idle) end)
 		  ),
 		  # The flip is drawn as a rule before its task: everything left of it is
 		  # inert and safe to leave landed, everything right of it is not. That is
@@ -260,15 +284,21 @@ mk_dir() { # <directory to create under .sluice>
 # 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.
+#
+# Every write stamps `updated`, which is what lets a reader tell a run that is
+# moving from one that was left behind: `started` only says how old it is.
 write_state() {
-	local tmp="$STATE.tmp.$$"
+	local tmp="$STATE.tmp.$$" stamped="$STATE.stamped.$$"
 	cat >"$tmp"
-	if [ ! -s "$tmp" ] || ! jq -e . "$tmp" >/dev/null 2>&1; then
-		rm -f "$tmp"
+	# One jq does both the check and the stamp: it fails on malformed input and
+	# writes nothing on empty input, and either leaves the candidate unfit.
+	if ! jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" 'if type != "object" then error("state is not an object") else .updated = $now end' "$tmp" >"$stamped" 2>/dev/null || [ ! -s "$stamped" ]; then
+		rm -f "$tmp" "$stamped"
 		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; }
+	rm -f "$tmp"
+	mv "$stamped" "$STATE" || { rm -f "$stamped"; err "could not replace $STATE"; exit 1; }
 }
 
 # One state file now serves a whole worktree set, so two implementers can flip
@@ -410,6 +440,20 @@ case "$SUB" in
 			exit 4
 		fi
 
+		# The base is cheap to know at dispatch and archaeology afterwards, and
+		# the guess it gets recovered as is HEAD~1. So a task going active with
+		# no base takes the HEAD of the tree the command was issued from, once:
+		# a base already on the row was a decision and a second flip keeps it.
+		if [ "$STATUS" = "active" ] && [ -z "$BASE" ]; then
+			has_base="$(jq --argjson id "$ID" '[.tasks[]? | select(.id == $id and .base != null)] | length' "$STATE" 2>/dev/null)"
+			case "$has_base" in
+				'' | *[!0-9]*) err "could not read the task list from $STATE"; exit 6 ;;
+			esac
+			if [ "$has_base" = "0" ]; then
+				BASE="$(git -C "$ORIG_DIR" rev-parse --short HEAD 2>/dev/null || true)"
+			fi
+		fi
+
 		patch="$(jq -n \
 			--arg name "$NAME" --arg status "$STATUS" --arg base "$BASE" \
 			--arg commit "$COMMIT" --arg tier "$TIER" --arg model "$MODEL" \
@@ -494,7 +538,7 @@ case "$SUB" in
 		# 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 '
+		jq -r --argjson now "$(date -u +%s)" '
 			def dash: if . == null or . == "" then "-" else . end;
 			def cell($w): tostring
 				| if length > $w then .[0:$w - 1] + "…"
@@ -505,11 +549,24 @@ case "$SUB" in
 			                      $c[6]] | join(" "));
 			([.tasks[]? | select(.status == "done")] | length) as $done
 			| ["sluice \(.channel) · \(.topic) · \($done)/\(.tasks | length) done"]
-			+ ["plan        \(.plan | dash)"]
-			+ ["record      \(.record | dash)"]
+			+ ["plan          \(.plan | dash)"]
+			+ ["record        \(.record | dash)"]
+			# Past a day since the last write the run is idle, and that is said
+			# here because a stale run blocks the next init and nothing else
+			# would name it.
+			# A run written before `updated` existed falls back to `started`,
+			# which is the case the line was added for.
+			+ ((.updated // .started // "" | try fromdateiso8601 catch 0) as $u
+			   | if $u == 0 then []
+			     else (($now - $u) / 3600 | floor) as $h
+			          | if $h < 24 then []
+			            else ["idle          \($h / 24 | floor)d\($h % 24)h since the last write"]
+			            end
+			     end)
 			+ (([.tasks[]? | select(.status == "done" and (.tier // 0) >= 1 and (.reviewed // false) == false)] | length) as $debt
-			   | if $debt == 0 then [] else ["unreviewed  \($debt) done, owed a review the tier table promised"] end)
-			+ ["pre-flight  " + (
+			   | if $debt == 0 then [] else ["unreviewed    \($debt) done, owed a review the tier table promised"] end)
+			+ ["final review  " + (if .final_review then "done" else "pending" end)]
+			+ ["pre-flight    " + (
 				if (.preflight // {} | length) == 0 then "not recorded"
 				else [(.preflight | to_entries[] | "\(.key)=\(.value)")] | join("; ")
 				end)]
@@ -558,9 +615,18 @@ case "$SUB" in
 			    "no contract graph in the run state.",
 			    "re-run `plan.sh import <plan>` to record Needs, Offers and Touches."
 			  else
+			    # What a wave of several means depends on what pre-flight bought:
+			    # worktrees per implementer run it at once, anything else runs it
+			    # one at a time, and an answer never recorded says neither.
 			    (
 			      "\($ready | length) ready now"
-			      + (if ($ready | length) > 1 then " · a worktree each" else "" end)
+			      + (if ($ready | length) > 1 then
+			           (.preflight.workspace // "") as $ws
+			           | if $ws == "" then ""
+			             elif ($ws | test("per (concurrent )?implementer|each implementer|worktree each"; "i")) then " · a worktree each"
+			             else " · serial, one at a time in the shared tree"
+			             end
+			         else "" end)
 			    ),
 			    ($ready[] | "  T\(.id)  \(.name // "" | pad(38))\((.touches // []) | join(", "))"),
 			    # A shared path is what rules two ready tasks out of the same wave,
@@ -586,11 +652,36 @@ case "$SUB" in
 		' "$STATE"
 		;;
 
+	final)
+		[ $# -eq 0 ] || { err "final takes no arguments"; exit 4; }
+		require_run
+		take_lock
+		require_readable
+
+		# The per-task marks count dispatches the tier table owed. The final
+		# review is owed by the plan as a whole, so it is a fact about the run
+		# rather than a row, and `show` reports it pending until this lands.
+		jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '.final_review = $now' "$STATE" | write_state
+		;;
+
 	close)
 		[ $# -eq 0 ] || { err "close takes no arguments"; exit 4; }
 		require_run
 		take_lock
 
+		# Said once, as the run leaves: a close that archives six unreviewed
+		# tasks and no final review in silence lets those facts leave with it.
+		# Best effort on state nothing else will parse, which is why it is not
+		# allowed to stop the archive.
+		summary="$(jq -r '
+			([.tasks[]? | select(.status == "done")] | length) as $done
+			| ([.tasks[]? | select(.status == "done" and (.tier // 0) >= 1 and (.reviewed // false) == false)] | length) as $debt
+			| [ "closed \(.topic // "run"): \($done)/\(.tasks | length) done",
+			    (if $debt > 0 then "\($debt) unreviewed" else empty end),
+			    "final review \(if .final_review then "done" else "pending" end)"
+			  ] | join(" · ")
+		' "$STATE" 2>/dev/null || true)"
+
 		# 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
@@ -612,7 +703,11 @@ case "$SUB" in
 			dest="$ARCHIVE/$stamp-$slug-$n.json"
 			n=$((n + 1))
 		done
-		mv "$STATE" "$dest"
+		mv "$STATE" "$dest" || { err "could not archive $STATE"; exit 1; }
+		# The summary needs parseable state and close is the one command that
+		# does not, so an unreadable run still gets a line naming where it went.
+		[ -n "$summary" ] || summary="closed $(basename "$dest"): state was unreadable, no summary"
+		echo "$summary"
 		;;
 
 	*)

package/skills/sluice/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "sluice",
-  "version": "0.15.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.",
+  "version": "0.16.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, one status command and a SessionStart hook can answer where the run is (the hook prints a live run at every session start, compaction included), 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": [
@@ -28,6 +28,7 @@
       "global"
     ],
     "default": "global",
-    "claudeHookDirective": "Before acting on a request that changes code, pick a sluice channel and state which one."
+    "claudeHookDirective": "Before acting on a request that changes code, pick a sluice channel and state which one.",
+    "claudeHookScript": "scripts/session-start.sh"
   }
 }