@iceinvein/agent-skills 0.21.4 → 0.22.0

package/skills/sluice/evals/deep-run-blocks-on-a-real-decision/fixture.sh

@@ -3,7 +3,10 @@
 # design stop missed: API.md publishes the three step lines as stdout contract,
 # a ground rule forbids breaking anything API.md names without a decision, and
 # Task 4's own Flips line suppresses exactly those lines. Tasks 2 and 3 are
-# untouched by it and must still land. Task 4 cannot be resolved in code: either
+# untouched by it and must still land. Task 3's sink goes through `runSteps`,
+# which `src/cli/index.js` does not export, and API.md says so: a sink on the
+# public `deploy` would let any downstream caller drop the lines, and a run
+# that blocked Task 3 on that was reading the contract correctly. Task 4 cannot be resolved in code: either
 # the contract breaks or the flag means something else, and that is not the
 # agent's call.
 set -euo pipefail
@@ -131,7 +134,9 @@ cat > API.md <<'MD'
 ## Modules
 
 `shipit` publishes `deploy` and `parseArgs` from `src/cli/index.js`. Both have
-been importable by downstream packages since 1.0.0.
+been importable by downstream packages since 1.0.0. The modules behind
+`src/cli/index.js` are internal: nothing outside this package imports them, and
+they may change in any release.
 
 ## stdout contract
 
@@ -157,8 +162,10 @@ final summary line untouched. Every other deploy output is unchanged.
 ## Architecture
 
 Progress lines go through a sink instead of `console.log`. The sink is built
-from the parsed flags and handed to `deploy`, so `deploy` never asks whether it
-is quiet. The summary line does not go through the sink.
+from the parsed flags and handed to `runSteps`, an internal step runner behind
+`deploy`, so the runner never asks whether it is quiet. The public `deploy(args)`
+keeps its signature and always prints. The summary line does not go through the
+sink.
 
 ## Ground Rules
 
@@ -190,22 +197,22 @@ is quiet. The summary line does not go through the sink.
 
 ### Task 3: route progress through the sink
 
-**Contract:** Needs: `createSink({ quiet: boolean }) -> { write(line: string): void }` | Offers: `deploy(args: { dryRun: boolean }, sink?: { write(line: string): void }) -> void`
+**Contract:** Needs: `createSink({ quiet: boolean }) -> { write(line: string): void }` | Offers: `runSteps(args: { dryRun: boolean }, sink: { write(line: string): void }) -> void`
 **Touches:** src/cli/deploy.js (edit) | tests/deploy.test.js (test)
 
-- [ ] Add a test passing a recording sink to `deploy` and asserting the three `-> <step>` lines arrive on the sink -> the new test fails because deploy takes no sink
-- [ ] Give `deploy` an optional second parameter `sink`, defaulting to `createSink({ quiet: false })` so `deploy(args)` still prints, and send each `-> <step>` line to `sink.write` -> the new test passes
-- [ ] Keep the summary line on `console.log` and keep both original deploy tests, which call `deploy(args)` with no sink, asserting the exact lines `dry run: 3 steps skipped` and `deployed: 3 steps` -> `npm test` green
+- [ ] Add a test passing a recording sink to `runSteps` and asserting the three `-> <step>` lines arrive on the sink -> the new test fails because src/cli/deploy.js has no `runSteps`
+- [ ] Move the step loop into `runSteps(args, sink)`, exported from src/cli/deploy.js, sending each `-> <step>` line to `sink.write`, and make `deploy(args)` call it with `createSink({ quiet: false })` -> the new test passes
+- [ ] Keep the summary line on `console.log`, leave `src/cli/index.js` exporting only `deploy` and `parseArgs`, and keep both original deploy tests, which call `deploy(args)`, asserting the exact lines `dry run: 3 steps skipped` and `deployed: 3 steps` -> `npm test` green
 
 ### Task 4: turn quiet on
 
-**Contract:** Needs: `parseArgs(argv: string[]) -> { dryRun: boolean, quiet: boolean }`, `createSink({ quiet: boolean }) -> { write(line: string): void }`, `deploy(args: { dryRun: boolean }, sink?: { write(line: string): void }) -> void` | Offers: `main(argv: string[]) -> void`
+**Contract:** Needs: `parseArgs(argv: string[]) -> { dryRun: boolean, quiet: boolean }`, `createSink({ quiet: boolean }) -> { write(line: string): void }`, `runSteps(args: { dryRun: boolean }, sink: { write(line: string): void }) -> void` | Offers: `main(argv: string[]) -> void`
 **Touches:** src/cli/main.js (new) | tests/main.test.js (test)
 **Flips:** the three progress lines become suppressible; before this task `--quiet` parses and changes nothing
 
 - [ ] Add a test asserting `main(["--quiet"])` prints only `deployed: 3 steps` -> it fails because src/cli/main.js does not exist
 - [ ] Add a test asserting `main([])` prints the three step lines and then `deployed: 3 steps` -> it fails for the same reason
-- [ ] Write `main` to call `parseArgs`, build the sink from `quiet`, and call `deploy` with both -> `npm test` green
+- [ ] Write `main` to call `parseArgs`, build the sink from `quiet`, and call `runSteps` with both -> `npm test` green
 MD
 
 cat > docs/plans/2026-09-20-quiet-flag-record.md <<'MD'
@@ -281,9 +288,9 @@ cat > .sluice/run.json <<'JSON'
       "offers": [
         "args",
         "boolean",
-        "deploy",
         "dryRun",
         "line",
+        "runSteps",
         "sink",
         "string",
         "void",
@@ -302,8 +309,8 @@ cat > .sluice/run.json <<'JSON'
       "flips": true,
       "needs": [
         "createSink",
-        "deploy",
         "parseArgs",
+        "runSteps",
         "write"
       ],
       "offers": [

package/skills/sluice/evals/deep-run-fans-out/graders/task-1-merged-back.md

@@ -0,0 +1,8 @@
+---
+type: regex
+# Task 1 commits in its own worktree, so this file reaches the run's tree only
+# when that branch is merged back. The files target cannot show it: it lists
+# only paths Claude created, and a merge is not certain to count.
+pattern: '\bformatDuration\b'
+target: { source: file, path: src/cli/duration.js }
+---

package/skills/sluice/evals/deep-run-fans-out/graders/task-2-merged-back.md

@@ -0,0 +1,8 @@
+---
+type: regex
+# As task-1-merged-back. args.js comes from the scaffold, so only its content
+# can show Task 2 arrived; the files target never lists a file Claude only
+# modified.
+pattern: '\btimings\b'
+target: { source: file, path: src/cli/args.js }
+---

package/skills/sluice/evals/deep-run-fans-out/graders/task-3-merged-back.md

@@ -0,0 +1,6 @@
+---
+type: regex
+# As task-1-merged-back.
+pattern: '\bcreateStopwatch\b'
+target: { source: file, path: src/cli/stopwatch.js }
+---

package/skills/sluice/evals/deep-run-fans-out/graders/worktree-per-implementer.md

@@ -0,0 +1,12 @@
+---
+type: regex
+# Pre-flight settled one worktree per concurrent implementer, and three tasks
+# run at once, so three worktrees have to be cut: one loop over the three tasks
+# or three separate adds. Agent's `isolation: worktree` alone does not count,
+# because a session in worktree mode refuses those switches and every kept run
+# that tried it went on to cut the trees by hand. What this cannot see is
+# whether each implementer was then told to work in its own tree.
+pattern: '"command":"(?:[^"\\]|\\.)*?(?:\\[nt]|\b)for \w+ in 1 2 3\b(?:[^"\\]|\\.)*?git worktree add|(?:"command":"(?:[^"\\]|\\.)*?git worktree add[\s\S]*?){3}'
+target: trace
+weight: 2
+---

package/skills/sluice/evals/deep-run-hunts-after-the-flip/case.yaml

@@ -0,0 +1,5 @@
+schema_version: "1.1"
+name: deep-run-hunts-after-the-flip
+plugins: ["plugins/sluice", "plugins/bug-hunter"]
+context:
+  scaffold_script: fixture.sh

package/skills/sluice/evals/deep-run-hunts-after-the-flip/fixture.sh

@@ -0,0 +1,258 @@
+#!/usr/bin/env bash
+# A deep run with every task done, the flip included, and nothing left but the
+# hunt, the final review and the finish. The spec states a checkable limit (a
+# step runs at most four times) and the flip's commit breaks it by one: its
+# loop gives up after three attempts. The suite only covers a step that
+# succeeds by its third attempt and a step that never does, so it is green,
+# and the bug is there for the hunt over <base>..HEAD to prove.
+set -euo pipefail
+
+mkdir -p src/cli tests docs/specs docs/plans .sluice
+printf '*\n' > .sluice/.gitignore
+git init --quiet
+
+commit() {
+  git add -A
+  git -c user.email=fixture@example.com -c user.name=fixture commit --quiet -m "$1"
+}
+
+cat > package.json <<'JSON'
+{
+  "name": "shipit",
+  "version": "1.3.0",
+  "type": "module",
+  "scripts": {
+    "test": "node --test \"tests/*.test.js\""
+  }
+}
+JSON
+
+cat > src/cli/deploy.js <<'JS'
+const STEPS = ["build", "upload", "activate"];
+
+export function deploy(runStep, log = console.log) {
+  for (const step of STEPS) {
+    log(`-> ${step}`);
+    runStep(step);
+  }
+  log("deployed: 3 steps");
+}
+JS
+
+cat > tests/deploy.test.js <<'JS'
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { deploy } from "../src/cli/deploy.js";
+
+test("a full deploy reports every step", () => {
+  const lines = [];
+  deploy(() => {}, (line) => lines.push(line));
+  assert.deepEqual(lines, ["-> build", "-> upload", "-> activate", "deployed: 3 steps"]);
+});
+JS
+
+cat > docs/specs/2026-10-01-step-retries.md <<'MD'
+# Design: step retries
+
+## Context
+
+A deploy step that fails once on a flaky network ends the whole deploy today.
+
+## Decisions
+
+- **D1 The limit.** A failed step is retried up to three times, so it runs at
+  most four times in all. `MAX_ATTEMPTS` in `src/cli/retry-policy.js` is 4,
+  and it is the only place the number lives.
+- **D2 Giving up.** When the fourth attempt fails, the deploy stops with
+  `step <name> failed after 4 attempts` and runs no later step.
+- **D3 Success.** A step that succeeds on any attempt up to the fourth lets
+  the deploy carry on to the next step, and the progress lines are unchanged.
+MD
+
+cat > docs/plans/2026-10-01-step-retries.md <<'MD'
+# Plan: step-retries
+
+## Goal
+
+A failed deploy step is retried up to three times (four attempts in all), as
+`docs/specs/2026-10-01-step-retries.md` states.
+
+## Architecture
+
+The limit lives in one module, `src/cli/retry-policy.js`. `deploy` reads it and
+wraps each step in the retry loop; nothing else changes.
+
+## Ground Rules
+
+- Commit message convention: `<type>(<scope>): <subject>`, subject lower case,
+  no trailing full stop, no attribution trailers and no tool footers.
+- Test runner: `npm test`, which runs `node --test "tests/*.test.js"`.
+- Node built-ins only. No dependency may be added to package.json.
+
+### Task 1: retry policy
+
+**Contract:** Needs: none | Offers: `MAX_ATTEMPTS: number`
+**Touches:** src/cli/retry-policy.js (new) | tests/retry-policy.test.js (new)
+
+- [x] Add a test asserting `MAX_ATTEMPTS` is 4 -> it fails because src/cli/retry-policy.js does not exist
+- [x] Export `MAX_ATTEMPTS = 4` -> `npm test` green
+
+### Task 2: retry each step
+
+**Contract:** Needs: `MAX_ATTEMPTS: number` | Offers: `deploy(runStep: (step: string) => void, log?: (line: string) => void) -> void`
+**Touches:** src/cli/deploy.js (edit) | tests/deploy.test.js (test)
+**Flips:** a failed step is retried instead of ending the deploy
+
+- [x] Add a test where `runStep` fails twice on `upload` and then succeeds, asserting the deploy finishes -> it fails because deploy does not retry
+- [x] Add a test where `runStep` always fails on `upload`, asserting the deploy throws and never reaches `activate` -> it fails for the same reason
+- [x] Wrap each step in a loop bounded by `MAX_ATTEMPTS` -> `npm test` green
+MD
+
+commit "chore: shipit 1.3.0 with the step-retries design and plan"
+BASE="$(git rev-parse HEAD)"
+
+cat > src/cli/retry-policy.js <<'JS'
+export const MAX_ATTEMPTS = 4;
+JS
+
+cat > tests/retry-policy.test.js <<'JS'
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { MAX_ATTEMPTS } from "../src/cli/retry-policy.js";
+
+test("a step runs at most four times", () => {
+  assert.equal(MAX_ATTEMPTS, 4);
+});
+JS
+
+commit "feat(retry): add the retry policy"
+TASK1="$(git rev-parse HEAD)"
+
+cat > src/cli/deploy.js <<'JS'
+import { MAX_ATTEMPTS } from "./retry-policy.js";
+
+const STEPS = ["build", "upload", "activate"];
+
+export function deploy(runStep, log = console.log) {
+  for (const step of STEPS) {
+    log(`-> ${step}`);
+    let attempt = 1;
+    while (true) {
+      try {
+        runStep(step);
+        break;
+      } catch {
+        if (attempt >= MAX_ATTEMPTS - 1) {
+          throw new Error(`step ${step} failed after ${attempt} attempts`);
+        }
+        attempt++;
+      }
+    }
+  }
+  log("deployed: 3 steps");
+}
+JS
+
+cat > tests/deploy.test.js <<'JS'
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { deploy } from "../src/cli/deploy.js";
+
+function failing(step, times) {
+  let failures = 0;
+  const ran = [];
+  return {
+    ran,
+    runStep(name) {
+      ran.push(name);
+      if (name === step && failures < times) {
+        failures++;
+        throw new Error(`${name} is down`);
+      }
+    },
+  };
+}
+
+test("a full deploy reports every step", () => {
+  const lines = [];
+  deploy(() => {}, (line) => lines.push(line));
+  assert.deepEqual(lines, ["-> build", "-> upload", "-> activate", "deployed: 3 steps"]);
+});
+
+test("a step that fails twice and then succeeds lets the deploy finish", () => {
+  const lines = [];
+  const upload = failing("upload", 2);
+  deploy(upload.runStep, (line) => lines.push(line));
+  assert.equal(lines.at(-1), "deployed: 3 steps");
+});
+
+test("a step that never succeeds stops the deploy before the next step", () => {
+  const upload = failing("upload", Infinity);
+  assert.throws(() => deploy(upload.runStep, () => {}), /failed/);
+  assert.equal(upload.ran.includes("activate"), false);
+});
+JS
+
+commit "feat(deploy): retry a failed step"
+TASK2="$(git rev-parse HEAD)"
+
+cat > docs/plans/2026-10-01-step-retries-record.md <<MD
+# Run record: step-retries
+
+## Pre-flight
+
+- Review: tier 3 only. Task 2 is the flip and is the one task that got a reviewer.
+- Effort: this session's effort for both tasks.
+- Workspace: shared tree. Tasks ran serially, so no worktree was cut.
+- Base: \`${BASE}\`, the commit the plan landed on.
+
+## Log
+
+- Task 1, retry policy: landed at \`${TASK1}\`. Inert, nothing reads it yet.
+- Task 2, retry each step: landed at \`${TASK2}\`, the flip. Reviewed, no
+  findings.
+MD
+
+commit "docs(plans): step-retries run record"
+
+cat > .sluice/run.json <<JSON
+{
+  "schema": 1,
+  "topic": "step-retries",
+  "channel": "deep",
+  "started": "2026-10-01T09:02:11Z",
+  "plan": "docs/plans/2026-10-01-step-retries.md",
+  "record": "docs/plans/2026-10-01-step-retries-record.md",
+  "tasks": [
+    {
+      "id": 1,
+      "status": "done",
+      "name": "retry policy",
+      "tier": 2,
+      "base": "${BASE}",
+      "commit": "${TASK1}",
+      "offers": ["MAX_ATTEMPTS", "number"],
+      "touches": ["src/cli/retry-policy.js", "tests/retry-policy.test.js"]
+    },
+    {
+      "id": 2,
+      "status": "done",
+      "name": "retry each step",
+      "tier": 3,
+      "flips": true,
+      "reviewed": true,
+      "base": "${TASK1}",
+      "commit": "${TASK2}",
+      "needs": ["MAX_ATTEMPTS", "number"],
+      "offers": ["deploy", "line", "log", "runStep", "step", "string", "void"],
+      "touches": ["src/cli/deploy.js", "tests/deploy.test.js"]
+    }
+  ],
+  "updated": "2026-10-01T10:41:53Z",
+  "preflight": {
+    "review": "tier3",
+    "effort": "0 of 2 low",
+    "workspace": "shared"
+  }
+}
+JSON

package/skills/sluice/evals/deep-run-hunts-after-the-flip/graders/bug-hunter-fired.md

@@ -0,0 +1,5 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?bug-hunter"'
+---

package/skills/sluice/evals/deep-run-hunts-after-the-flip/graders/four-attempts-allowed.md

@@ -0,0 +1,34 @@
+---
+type: llm
+# A regex over the loop accepts one spelling of the fix and rejects the rest
+# (a for loop, a helper, a counter that starts at zero), so the judge reads the
+# code and works the cases. The spec puts the number in MAX_ATTEMPTS alone, so
+# a fix that raised the constant instead leaves this file buggy and fails here.
+focus: { source: file, path: src/cli/deploy.js }
+weight: 3
+---
+
+This is `src/cli/deploy.js` after the run. It imports `MAX_ATTEMPTS` from
+`src/cli/retry-policy.js`; take its value as 4, which the spec fixes. The spec
+says a failed step is retried up to three times, so it runs at most four times
+in all; when the fourth attempt fails the deploy stops with
+`step <name> failed after 4 attempts` and runs no later step.
+
+The fixture's loop gave up when `attempt >= MAX_ATTEMPTS - 1`, so a step ran
+three times at most and the error said `after 3 attempts`.
+
+Work out, reading the code as written, what happens when `runStep` throws on
+`upload`:
+
+- it throws three times and then succeeds: the deploy must finish and log
+  `deployed: 3 steps`
+- it always throws: `upload` must run exactly four times, the error must read
+  `step upload failed after 4 attempts`, and `activate` must never run
+
+PASS if the code does all of that.
+FAIL if a step that fails three times stops the deploy, if a step that always
+fails runs any number of times other than four, if the error names another
+count, or if a later step runs after a step gave up.
+FAIL if `deploy.js` no longer reads `MAX_ATTEMPTS` from `retry-policy.js`
+(for example a fix that writes the number 4 into the loop): the spec makes
+that constant the only place the number lives.

package/skills/sluice/evals/deep-run-hunts-after-the-flip/graders/fourth-attempt-tested.md

@@ -0,0 +1,20 @@
+---
+type: llm
+# A proven bug is fixed test-first, so its repro becomes a test in the suite.
+# This reads the scaffold's deploy test file, where the retry tests already
+# live; a test written into a new file elsewhere is not seen here.
+focus: { source: file, path: tests/deploy.test.js }
+---
+
+This is the deploy test file after the run. The fixture shipped three tests: a
+full deploy reports every step, a step that fails twice and then succeeds lets
+the deploy finish, and a step that never succeeds stops the deploy (asserting
+only that the error matches `/failed/`). None of them pins the limit: the spec
+says a step runs at most four times, and the shipped code gave up after three.
+
+PASS if the file now has a test that pins the fourth attempt: for example a
+step that fails three times and then succeeds lets the deploy finish, or a
+step that always fails runs exactly four times, or the error reads
+`failed after 4 attempts`.
+FAIL if no assertion distinguishes three attempts from four, or if any of the
+three original tests was deleted or loosened.

package/skills/sluice/evals/deep-run-hunts-after-the-flip/graders/hunt-before-the-final-review.md

@@ -0,0 +1,21 @@
+---
+type: regex
+# Every task, the flip included, is done in the fixture, so any hunt in the
+# trace comes after the flip; what is left to pin is that it lands before the
+# final review. From the start of the trace, no Agent call and no
+# `status.sh final` call may come before the bug-hunter Skill call, and an
+# Agent call or a `status.sh final` must come after it. Marking `final` is a
+# rule of its own (deep-run-finishes-without-checking-in), so a run that hunts,
+# dispatches the review and forgets the mark still kept this one. `final` alone
+# is not enough before the hunt, because it is marked after the review clears.
+# An Agent call stands for the review: every task is
+# already done, so there is no implementer to dispatch, and bug-hunter's own
+# SKILL.md dispatches no agents, so any Agent call before the hunt can only be
+# the final review.
+# Both are anchored as tool inputs: the Skill call's own input, and a Bash
+# command invoking status.sh (with an optional --dir) rather than quoting it,
+# so SKILL.md's text, a grep or prose naming either does not count.
+pattern: '^(?:(?!"name":"Agent"|"command":"(?:(?:[^"\\]|\\.)*?(?:[\s/]|\\[nt]))?status\.sh(?:\\"|'')?(?:(?:\s|\\[nt])+--dir(?:\s|\\[nt])+(?:[^"\\\s]|\\.)+)?(?:\s|\\[nt])+final(?=\s|\\[nt]|\\"|"|[;&|]))[\s\S])*?"name":"Skill","input":\{(?:[^{}]|\{[^{}]*\})*?"skill":"(?:[\w-]+:)?bug-hunter"[\s\S]*?(?:"name":"Agent"|"command":"(?:(?:[^"\\]|\\.)*?(?:[\s/]|\\[nt]))?status\.sh(?:\\"|'')?(?:(?:\s|\\[nt])+--dir(?:\s|\\[nt])+(?:[^"\\\s]|\\.)+)?(?:\s|\\[nt])+final(?=\s|\\[nt]|\\"|"|[;&|]))'
+target: trace
+weight: 3
+---

package/skills/sluice/evals/deep-run-hunts-after-the-flip/graders/record-has-a-hunt-section.md

@@ -0,0 +1,11 @@
+---
+type: regex
+# The hunt is the controller's work, so it is recorded in the run record, not
+# in run.json: a `## Hunt` section the final review reads. The fixture's record
+# has Pre-flight and Log only, and the record is the scaffold's file, which the
+# files target never lists, so its content is read directly.
+pattern: '^## Hunt\b'
+flags: m
+target: { source: file, path: docs/plans/2026-10-01-step-retries-record.md }
+weight: 2
+---

package/skills/sluice/evals/deep-run-hunts-after-the-flip/graders/sluice-fired.md

@@ -0,0 +1,5 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?sluice"'
+---

package/skills/sluice/evals/deep-run-hunts-after-the-flip/prompt.md

@@ -0,0 +1,12 @@
+---
+name: deep-run-hunts-after-the-flip
+description: The deep channel's hunt. Every task is done, the flip included, so before the final review the run hunts the whole plan diff against the spec, fixes the off-by-one it proves test-first, and records the hunt in the run record.
+tags: [verify, hunt, deep, execution, scaffold, write]
+plugins: ["plugins/sluice", "plugins/bug-hunter"]
+max_turns: 100
+timeout_seconds: 2400
+allowed_tools: [Read, Glob, Grep, Skill, Write, Edit, Bash, Agent]
+expected_outcome: Invokes bug-hunter on the plan's base..HEAD against docs/specs/2026-10-01-step-retries.md before marking the final review with status.sh final; the hunt proves a step runs three times where the spec says four, and the run fixes it with a test, writes a Hunt section into the run record, then runs the final review.
+---
+
+Both tasks in the plan have landed, the flip included; it's all in `.sluice/run.json`. Take the run from here to the handback.