@iceinvein/agent-skills 0.23.7 → 0.23.9

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.26.1",
-  "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": [