@iceinvein/agent-skills 0.23.8 → 0.23.9

package/skills/sluice/evals/rules.json

@@ -84,6 +84,30 @@
         "deep-plan-traces-the-example"
       ]
     },
+    {
+      "id": "deep-reads-the-ground-before-the-design",
+      "states": "references/deep-channel.md: The ground",
+      "origin": "docs/specs/2026-10-21-sluice-deep-alignment.md",
+      "cases": [
+        "deep-plan-reads-the-prior-spec"
+      ]
+    },
+    {
+      "id": "deep-checks-the-spec-against-the-intent",
+      "states": "references/deep-channel.md: The alignment checks",
+      "origin": "docs/specs/2026-10-21-sluice-deep-alignment.md",
+      "cases": [
+        "deep-plan-checks-the-intent"
+      ]
+    },
+    {
+      "id": "deep-checks-the-plan-against-the-spec",
+      "states": "references/deep-channel.md: The alignment checks",
+      "origin": "docs/specs/2026-10-21-sluice-deep-alignment.md",
+      "cases": [
+        "deep-plan-checks-the-plan"
+      ]
+    },
     {
       "id": "deep-stops-for-plan-and-pre-flight",
       "states": "SKILL.md: Deep channel",

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

@@ -8,6 +8,19 @@
   message convention is one of them, written out at literal value along with
   anything the repo forbids a message from carrying. An implementer arrives
   with its own defaults and will use them on anything you left unsaid.
+- A **Spec** line, `**Spec:** <path>` directly under the title, names the
+  signed-off design the plan builds. It is a line rather than a mention in
+  the Goal because `plan.sh validate` reads the spec's `### D<n>.` decisions
+  from that path, and a path written into prose gives it nothing to parse. A
+  relative path is read from the plan's repo root, as `docs/specs/...`, so
+  validate means the same thing from any directory; outside a git repo it is
+  read from the plan's own directory.
+- A **Builds** line on every task names the decisions it builds,
+  `**Builds:** D1, D3`, or `**Builds:** none, <why>` for a task such as a
+  version bump that builds none. Validate checks coverage from these lines
+  and nothing else: every decision built by some task, no task building one
+  the spec lacks. Step prose mentioning `D1` does not count, because a docs
+  task that reads its work back "against D1 to D4" builds none of them.
 - No implementer sees a neighbouring task, so each task carries a
   **Contract**, not optional: a symbol absent from it does not exist for
   whoever builds the task. `Needs` names what this task calls but another
@@ -54,18 +67,26 @@ 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, an `Effort` mark on a task the tier table
 sends to tier 3, a `Model` mark anywhere. 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.
+task number on them. It also checks the plan against its spec, and a miss
+there is an error too: a Spec line naming a readable file whose decisions are
+`### D<n>.` headings, a Builds line on every task of `D<n>` ids or
+`none, <why>`, every decision built and none invented. Each message says what
+to fix, and names the task where one is at fault, so read them as validate
+prints 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>
+**Spec:** <path to the signed-off design>
 ## Ground Rules
 - <exact value>
 ### Task N: <name>
 **Contract:** Needs: <sig> | Offers: <sig>
 **Touches:** <path> (new) | <path> (edit) | <path> (test)
+**Builds:** <D<n>, ..., or none and why>
 **Flips:** <what changes, from what, or omit>
 **Review:** <reason, or omit>
 **Effort:** <low, and why the work is mechanical, or omit>
@@ -118,6 +139,10 @@ 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.
+The outcomes of the intent check and the plan check sit among those opening
+rows, each with its finding count and what came of them: both ran before the
+record existed, so they are held until it opens, as pre-flight's answers are,
+and written in with them.
 
 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
@@ -183,6 +208,58 @@ on it, 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.
 
+## The ground
+
+Read the repo before you walk anything through it. A prior spec often settles
+the very fork you were about to ask about, and "anything you can settle from
+the repo is not that fork" only holds once the repo has been read: until then
+every fork looks like your partner's, and every pattern looks like yours to
+invent. So the ground comes first, then the trace, then the fork question,
+then the draft.
+
+Ask for three things, each cited by path:
+
+1. **Prior designs.** Specs and plans under the repo's spec and plan
+   directories that touch the same subsystems or files, and what each settled
+   that the new design must build on, supersede or leave alone.
+2. **The code beside the path.** How the nearest similar feature is built (its
+   shape, where its state lives, how it is tested), so the design matches the
+   repo rather than inventing a pattern beside it.
+3. **Stated constraints.** Repo instructions, CI gates, the test runner and its
+   conventions, and release steps that the design or its plan will answer to.
+
+Dispatch it as a read-only Explore agent where the harness has one, for the
+reason the reviewer is dispatched: the file dumps fill its context instead of
+yours, and you only need what it concluded. Where there is no dispatch, it is
+your own read, with the same three questions. Either way the findings go into
+the spec's `## Context`, one line each with the path it came from, so the
+intent check and every later reader can see what the design was built on and
+go and look.
+
+A design whose `## Context` cites no earlier spec, when one covers the same
+scripts, is the gap this section exists to close. Read for it rather than
+assuming there is none.
+
+The spec has a fixed shape, because the intent check reads it by section:
+
+```
+# Design: <topic>
+## Intent
+## Context
+## Decisions
+### D1. <title>
+## Out of scope
+## Trace
+```
+
+`## Intent` holds the request quoted verbatim, each question asked through
+`AskUserQuestion` with the answer it got, and a table mapping each ask to the
+`D<n>` decisions that deliver it, or to `## Out of scope` with the reason.
+Decisions are headed `### D<n>. <title>`, which is what `plan.sh validate`
+reads. Out of scope is its own section and never a numbered decision, because
+a decision is something a task builds, and one no task could build would fail
+the plan's coverage check for being honest.
+
 ## The trace
 
 A design written from the shape of the code (which functions exist, which slots
@@ -212,15 +289,73 @@ the spec on approval):
    what the design does instead. An empty list is a result, not a skipped
    step.
 
-Walking first is also what puts a fork where **The design stop and plan mode**
-wants it: one the walk turns up only your partner can settle is asked before
-the design is written, and the trace goes into the design with the answer.
+The order is the ground, the walk, the fork, the draft. Walking after the
+ground and before the fork is what puts a fork where **The design stop and
+plan mode** wants it: one the walk turns up only your partner can settle is
+asked before the design is written, and the trace goes into the design with
+the answer.
 
 The trace is what the sign-off is signing: a design without the section is
 incomplete, however good the rest reads. It is not a prototype and not a hunt;
 anything that only shows at runtime (routing, timing, a renderer) stays with
 the hunt after the flip.
 
+## The alignment checks
+
+A spec can mention every ask and deliver none of them, and a plan can cite
+every decision and build half of one. Its author reads past both, because the
+author knows what was meant. So each of the two stops gets a fresh reader
+first: a dispatch with fresh context on this session's model and effort,
+never downshifted, as with the final review, since a cheaper reader is the one
+that misses a gap in meaning.
+
+**The intent check runs before sign-off**, once the draft and its trace are
+written and before `ExitPlanMode` or the prose stop. Send it the path the
+design is drafted at, the harness's plan file under plan mode and the spec
+file otherwise, and ask it to read the design's `## Intent` section by that
+name, then:
+
+- Does each ask in `## Intent` reach a decision that actually delivers it, not
+  one that merely mentions it?
+- Is any decision traceable to no ask, an addition nobody asked for?
+- Is any ask dropped, or moved to Out of scope without a reason?
+- Does the design honour every answer recorded in `## Intent` and every
+  constraint in `## Context`?
+
+Run it before the stop rather than after because a partner who signs first
+signs a spec whose gaps were not yet known. On a redraft after the stop, run
+it again only if a decision changed, since the map is what it reads.
+
+**The plan check runs after `plan.sh validate` is clean and before
+pre-flight**'s questions, with the spec and plan paths both in the brief:
+
+- Does each task citing `D<n>` actually build what `D<n>` says? Across its
+  tasks, is each decision covered whole rather than in part?
+- Does any task build something listed in Out of scope, or a shape the Trace
+  ruled out?
+- Do the Ground Rules contradict a constraint in the spec's Context?
+- Does the `Flips` task turn on what the spec says turns on?
+
+Validate has already settled what a parser can, so this reader is spent on
+what it cannot: whether the words of a task do what the words of a decision
+say.
+
+Fix each finding you agree with, in the draft for the intent check and in the
+plan for the plan check, before the stop; the spec is signed by the time the
+plan check runs, so nothing it finds edits the spec.
+What you dispute goes into that stop's message, one line each, so your partner
+signs with the disagreements in view rather than finding them later. The
+sign-off message says the intent check ran, how many findings it returned and
+how many were fixed; a stop that says nothing about it reads the same as one
+where it never ran. After the plan check's fixes, re-run `plan.sh validate`,
+because a fix to a Builds line is exactly what validate checks and the check
+it passed was on the plan before the fix. Both outcomes go into the run
+record's opening rows when it opens, for the reason that section gives.
+
+Without dispatch there is no fresh reader to send. Say so at the stop and ask
+the same questions yourself, as **When dispatch is unavailable** says for
+review: your own read is weaker, and your partner should know it was yours.
+
 ## Pre-flight
 
 Design signed off, plan written, nothing built yet. Before Task 1, stop once
@@ -530,7 +665,9 @@ who will carry it out, only your partner's read of work you will do yourself.
 Task isolation is gone, so
 `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.
+review was buying. The alignment checks fall back to your own read of the
+same questions, and you say so at the stop, so the sign-off is not mistaken
+for one a fresh reader cleared.
 
 One thing does not change: the work still owes a review. Reading your own diff
 is not one, and the table below still names which tasks needed the stronger

package/skills/sluice/scripts/plan.sh

@@ -13,6 +13,11 @@
 #
 # 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.
+# Besides the plan's own skeleton, it reads the spec the plan's **Spec:** line
+# names (a relative path from the plan's repo root, or from the plan's own
+# directory outside a repo) and checks every "### D<n>." decision
+# there is built by some task's **Builds:** line, and that no task builds one the
+# spec does not have.
 # import seeds the run state's task rows from the plan, so the ids, names, the
 # flip, the effort marks and the tiers come from the file rather than from a
 # dozen hand-typed commands. It is safe to re-run: a status, a review mark or a
@@ -57,10 +62,19 @@ usage() {
 # 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='
-BEGIN { SEP = sprintf("%c", 31) }
+BEGIN {
+	SEP = sprintf("%c", 31)
+	# The one form a Builds line takes, said once for every message that asks for it.
+	BUILDS_HINT = "write D<n>, or none, <why>"
+}
 
 function trim(s) { gsub(/^[ \t]+|[ \t]+$/, "", s); return s }
 
+# Single-quoted for system(). The quote is built rather than written because
+# this program is itself a single-quoted shell string, and an embedded quote
+# becomes '"'"' because a backslash in a gsub replacement differs between awks.
+function shq(s,    q) { q = sprintf("%c", 39); gsub(q, q "\"" q "\"" q, s); return q s q }
+
 # Symbols on one side of a Contract line. The two sides are read differently
 # because a mistake costs differently on each.
 #
@@ -145,6 +159,17 @@ fenced { next }
 
 /^# Plan:/ { has_title = 1 }
 
+# Before the first task only: a Spec line inside a task is that task naming a
+# file, not the plan naming its design.
+ntasks == 0 && /^\*\*Spec:\*\*/ {
+	spec_path = trim(substr($0, length("**Spec:**") + 1))
+	# Older plans write the path as code with prose after it, so a backticked
+	# span is the path and the rest is commentary.
+	if (match(spec_path, /`[^`]+`/)) spec_path = trim(substr(spec_path, RSTART + 1, RLENGTH - 2))
+	has_spec = 1
+	next
+}
+
 /^## / {
 	in_rules = (tolower($0) ~ /^## ground rules/) ? 1 : 0
 	if (in_rules) has_rules_heading = 1
@@ -249,6 +274,27 @@ in_rules && /^- / { nrules++ }
 	next
 }
 
+/^\*\*Builds:\*\*/ {
+	has_builds[cur] = 1
+	body = trim(substr($0, length("**Builds:**") + 1))
+	# Validate-only, like the spec coverage below: a plan that imported before
+	# Builds lines existed must not be refused over one it cannot parse.
+	if (body == "") {
+		if (check_spec) finding("error", "task " cur " has an empty Builds line; " BUILDS_HINT)
+		next
+	}
+	if (tolower(body) ~ /^none([ \t,.;:]|$)/) next
+	n = split(body, parts, /[, \t]+/)
+	for (i = 1; i <= n; i++) {
+		# Authors write the line as prose, so "D2." closing a sentence is D2.
+		sub(/[.;:]+$/, "", parts[i])
+		if (parts[i] == "") continue
+		if (parts[i] ~ /^D[0-9]+$/) builds[cur] = builds[cur] " " parts[i]
+		else if (check_spec) finding("error", "task " cur " Builds " parts[i] ", which is not a decision id; " BUILDS_HINT)
+	}
+	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 }
@@ -323,6 +369,62 @@ END {
 		}
 	}
 
+	# Gated, because only validate reads the spec. Import is run from wherever
+	# the run state lives, so a relative Spec path need not resolve there, and a
+	# plan already validated should not be refused over it.
+	if (check_spec) {
+		spec_file = spec_path
+		if (spec_path != "" && spec_path !~ /^\//) spec_file = ENVIRON["SLUICE_SPEC_BASE"] "/" spec_path
+		if (!has_spec) {
+			finding("error", "no **Spec:** line, so nothing ties the plan to the design it builds")
+		} else if (spec_path == "") {
+			# Checked before the read: getline on an empty filename is a fatal
+			# awk error, which would surface as the plan being unreadable.
+			finding("error", "the **Spec:** line names no path")
+		} else if (system("test -e " shq(spec_file)) != 0) {
+			finding("error", "**Spec:** names " spec_path ", which does not exist")
+		} else if (system("test -d " shq(spec_file)) == 0) {
+			# Asked before the read: BSD awk aborts on getline from a directory,
+			# which would surface as the plan being unreadable.
+			finding("error", "**Spec:** names " spec_path ", which is a directory, not a file")
+		} else if ((getline line < spec_file) < 0) {
+			finding("error", "**Spec:** names " spec_path ", which exists but cannot be read")
+		} else {
+			# The first line is already in hand from the existence probe above.
+			sfenced = 0; ndec = 0
+			do {
+				if (line ~ /^[ \t]*```/) { sfenced = 1 - sfenced; continue }
+				if (sfenced || line !~ /^### D[0-9]+\./) continue
+				match(line, /D[0-9]+/)
+				d = substr(line, RSTART, RLENGTH)
+				if (!(d in decision)) { decision[d] = 1; dec_order[++ndec] = d }
+			} while ((getline line < spec_file) > 0)
+			close(spec_file)
+			if (ndec == 0)
+				finding("error", "the spec " spec_path " has no \"### D<n>.\" decisions, so no task can say which one it builds")
+		}
+		for (i = 1; i <= ntasks; i++) {
+			id = order[i]
+			if (!(id in has_builds)) {
+				# An error, not a warning: `none, <why>` is how a task says it
+				# builds nothing, so a task without the line has left it unsaid.
+				finding("error", "task " id " has no Builds line; " BUILDS_HINT)
+				continue
+			}
+			n = split(builds[id], cited, " ")
+			for (j = 1; j <= n; j++) {
+				if (cited[j] == "") continue
+				built[cited[j]] = 1
+				if (ndec > 0 && !(cited[j] in decision))
+					finding("error", "task " id " Builds " cited[j] ", which the spec does not have")
+			}
+		}
+		if (ntasks > 0)
+			for (i = 1; i <= ndec; i++)
+				if (!(dec_order[i] in built))
+					finding("error", "spec decision " dec_order[i] " is built by no task")
+	}
+
 	for (p in owners) {
 		n = split(owners[p], who, " ")
 		if (n < 2) continue
@@ -389,8 +491,17 @@ END {
 # 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 plan="$1" check_spec="${2-0}" raw
+	# A relative Spec path names a file from the plan's repo root, the way plans
+	# write it (docs/specs/...), so validate means the same thing from any cwd.
+	# Outside a repo there is no root, and the plan's own directory stands in.
+	# CDPATH is cleared because a cd it steers prints where it went, which would
+	# land in plan_dir. The base reaches awk through the environment: a -v value
+	# has its backslash escapes processed, and a path may hold a backslash.
+	local plan_dir spec_base
+	plan_dir="$(CDPATH= cd -- "$(dirname -- "$plan")" && pwd)" || { err "could not read $plan"; exit 4; }
+	spec_base="$(git -C "$plan_dir" rev-parse --show-toplevel 2>/dev/null)" || spec_base="$plan_dir"
+	raw="$(SLUICE_SPEC_BASE="$spec_base" awk -v check_spec="$check_spec" "$PARSER" "$plan")" || { err "could not read $plan"; exit 4; }
 
 	local summary
 	summary="$(printf '%s\n' "$raw" | grep "^summary$SEP" | head -1)"
@@ -421,7 +532,7 @@ case "$SUB" in
 		shift
 		[ $# -eq 0 ] || { err "unknown argument: $1"; exit 4; }
 
-		parse_plan "$PLAN"
+		parse_plan "$PLAN" 1
 
 		head="$(basename "$PLAN"): $(plural "$NTASKS" task)"
 		[ "$FLIP" != "0" ] && head="$head, flip at task $FLIP"

package/skills/sluice/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "sluice",
-  "version": "0.27.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 nine 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), lists every live deep run and routed fast or main session on the machine in one board.sh view (drawn once, watched, or as JSON), 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. Two Stop hooks hold a handback: one refuses a tree that moved since its last recorded check, the other refuses a changed existing test not proven to fail on the session's starting code (or recorded with a reason). Claude Code only; stands down where the superpowers pipeline governs the repo.",
+  "version": "0.28.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 nine rules as one-liners in the router and the full treatment in references read only on friction. Deep runs read the repo before designing, map the spec's intent to its decisions, and check spec against intent and plan against spec with a fresh reader, with plan.sh validate enforcing that every decision is covered. 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), lists every live deep run and routed fast or main session on the machine in one board.sh view (drawn once, watched, or as JSON), 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. Two Stop hooks hold a handback: one refuses a tree that moved since its last recorded check, the other refuses a changed existing test not proven to fail on the session's starting code (or recorded with a reason). Claude Code only; stands down where the superpowers pipeline governs the repo.",
   "author": "iceinvein",
   "type": "prompt",
   "tools": [