@iceinvein/agent-skills 0.23.7 → 0.23.9

package/skills/sluice/evals/deep-plan-traces-the-example/fixture.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# A deck app where the ticket's own example fails the obvious design. The deck
+# store looks slides up by the title of their accepted version, and only the
+# canvas ever accepts one, so the smoke deck, built in chat, has no accepted
+# slides and the lookup the ticket says to reuse finds nothing. Nothing in the
+# code is wrong; the trap is in designing from which functions exist instead of
+# walking the example through the data. The README fixes where the design goes, so the graders can read it,
+# what an unaccepted slide is called, and what writes slide text, because
+# without them each is a fork the run rightly asks before writing any design.
+set -euo pipefail
+
+mkdir -p src/chat src/deck src/canvas data/decks tests docs/specs
+
+cat > package.json <<'JSON'
+{
+  "name": "decks",
+  "version": "0.9.0",
+  "type": "module",
+  "scripts": {
+    "test": "node --test \"tests/*.test.js\""
+  }
+}
+JSON
+
+cat > src/deck/store.js <<'JS'
+import { readFileSync, writeFileSync } from "node:fs";
+
+const path = (id) => new URL(`../../data/decks/${id}.json`, import.meta.url);
+
+export function loadDeck(id) {
+  return JSON.parse(readFileSync(path(id), "utf8"));
+}
+
+export function saveDeck(deck) {
+  writeFileSync(path(deck.id), JSON.stringify(deck, null, 2) + "\n");
+}
+
+// A slide's title is the title of the version the user accepted on the canvas.
+export function findSlideByTitle(deck, title) {
+  const wanted = title.trim().toLowerCase();
+  return deck.slides.find((slide) => {
+    const accepted = slide.versions[slide.accepted];
+    return accepted !== undefined && accepted.title.toLowerCase() === wanted;
+  });
+}
+JS
+
+cat > src/deck/redraft.js <<'JS'
+// Appends a new version; the canvas decides whether the user accepts it.
+export function redraftSlide(slide, draft) {
+  slide.versions.push({ title: draft.title, body: draft.body });
+  return slide.versions.length - 1;
+}
+JS
+
+cat > src/deck/draft.js <<'JS'
+// Slide text comes from the model; callers pass the completion so tests can stub it.
+export async function draftSlide(version, instruction, complete) {
+  const text = await complete(
+    `Rewrite this slide. ${instruction}\nTitle: ${version.title}\nBody: ${version.body}`,
+  );
+  const [title, ...body] = text.trim().split("\n");
+  return { title: title.replace(/^Title:\s*/, ""), body: body.join("\n").replace(/^Body:\s*/, "") };
+}
+JS
+
+cat > src/canvas/accept.js <<'JS'
+export function accept(slide, versionIndex) {
+  if (slide.versions[versionIndex] === undefined) {
+    throw new Error(`no version ${versionIndex} on slide ${slide.id}`);
+  }
+  slide.accepted = versionIndex;
+}
+JS
+
+cat > src/chat/build-deck.js <<'JS'
+export function buildDeck(id, outline) {
+  return {
+    id,
+    slides: outline.map((item, index) => ({
+      id: `s${index + 1}`,
+      accepted: null,
+      versions: [{ title: item.title, body: item.body }],
+    })),
+  };
+}
+JS
+
+cat > src/chat/router.js <<'JS'
+export function route(message) {
+  if (/^(prepare|build|make)\b.*\bslides?\b/i.test(message)) {
+    return { intent: "build-deck" };
+  }
+  return { intent: "chat" };
+}
+JS
+
+cat > data/decks/smoke.json <<'JSON'
+{
+  "id": "smoke",
+  "slides": [
+    {
+      "id": "s1",
+      "accepted": null,
+      "versions": [{ "title": "Why a pilot", "body": "Three sites asked for it." }]
+    },
+    {
+      "id": "s2",
+      "accepted": null,
+      "versions": [{ "title": "Pilot Stages", "body": "Recruit, run for six weeks, review." }]
+    },
+    {
+      "id": "s3",
+      "accepted": null,
+      "versions": [{ "title": "Next steps", "body": "Pick the sites by May." }]
+    }
+  ]
+}
+JSON
+
+cat > tests/store.test.js <<'JS'
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { findSlideByTitle } from "../src/deck/store.js";
+
+test("a slide is found by the title of its accepted version", () => {
+  const deck = { slides: [{ id: "s1", accepted: 0, versions: [{ title: "Pilot Stages" }] }] };
+  assert.equal(findSlideByTitle(deck, "pilot stages").id, "s1");
+});
+JS
+
+cat > README.md <<'MD'
+# decks
+
+Chat builds a deck (`src/chat/build-deck.js`), the canvas lets a user accept a
+slide version (`src/canvas/accept.js`), and the deck store reads and writes
+`data/decks/<id>.json`. Until a user accepts a version, a slide shows, and is
+called by, its latest one. Slide text, for a new deck or a redraft, comes from
+`draftSlide` in `src/deck/draft.js`. `data/decks/smoke.json` is the smoke deck QA runs
+tickets against. `npm test` runs the suite.
+
+## Designs
+
+A ticket's design goes in `docs/specs/<ticket>.md`, for example
+`docs/specs/DEK-12.md`, and its plan in `docs/plans/<ticket>.md`.
+MD
+touch docs/specs/.gitkeep
+
+git init --quiet
+git add -A
+git -c user.email=fixture@example.com -c user.name=fixture commit --quiet -m "decks 0.9.0"

package/skills/sluice/evals/deep-plan-traces-the-example/graders/announces-deep-channel.md

@@ -0,0 +1,12 @@
+---
+type: regex
+# The trace carries SKILL.md's own routing table, which names every channel, so
+# `contains` passes whenever the skill loads. Anchor on the two ways the agent
+# routes instead, the same ones run-stats.sh meters: a Bash call that invokes
+# `status.sh route deep` (a quoted mention, as in a grep, does not count), or the
+# words opening an assistant message or following a label such as "Sluice:".
+pattern: '"command":"(?:(?:[^"\\]|\\.)*?(?:[\s/]|\\[nt]))?status\.sh(?:\\"|'')?(?:\s|\\[nt])+route(?:\s|\\[nt])+deep(?:\s|\\[nt]|[;&|]|")|"text":"(?:[^.!?\n"]{0,100}[:=]\s*)?[\s*_#>\\]*deep channel'
+flags: i
+target: trace
+weight: 2
+---

package/skills/sluice/evals/deep-plan-traces-the-example/graders/design-written-to-docs.md

@@ -0,0 +1,5 @@
+---
+type: file_exists
+path: 'docs/specs/DEK-41.md'
+weight: 2
+---

package/skills/sluice/evals/deep-plan-traces-the-example/graders/no-source-edit.md

@@ -0,0 +1,11 @@
+---
+type: tool_used
+# The run plans and stops for sign-off, so no Edit may land under src/ or
+# tests/. Bash is left out of the case's tools, so these two are the only ways
+# code could change.
+tool: Edit
+input_match: '"file_path"\s*:\s*"(?:[^"]*/)?(?:src|tests)/'
+min: 0
+max: 0
+weight: 2
+---

package/skills/sluice/evals/deep-plan-traces-the-example/graders/no-source-write.md

@@ -0,0 +1,11 @@
+---
+type: tool_used
+# The run plans and stops for sign-off, so no Write may land under src/ or
+# tests/. Bash is left out of the case's tools, so these two are the only ways
+# code could change.
+tool: Write
+input_match: '"file_path"\s*:\s*"(?:[^"]*/)?(?:src|tests)/'
+min: 0
+max: 0
+weight: 2
+---

package/skills/sluice/evals/deep-plan-traces-the-example/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-plan-traces-the-example/graders/spec-has-a-trace.md

@@ -0,0 +1,7 @@
+---
+type: regex
+pattern: '^#{2,3}\s*Trace\b'
+flags: m
+target: { source: file, path: docs/specs/DEK-41.md }
+weight: 2
+---

package/skills/sluice/evals/deep-plan-traces-the-example/graders/stopped-for-signoff.md

@@ -0,0 +1,8 @@
+---
+type: llm
+---
+
+The agent was asked to plan a ticket that spans the chat router, the deck store and the redraft path.
+
+PASS if the final message hands a written design back for sign-off: it says where the design was written and asks for approval, or otherwise makes clear it is waiting before any code is written.
+FAIL if the final message reports implementation work as done, moves straight into building, or presents the design as settled with no sign-off asked for.

package/skills/sluice/evals/deep-plan-traces-the-example/graders/trace-finds-no-accepted-slide.md

@@ -0,0 +1,27 @@
+---
+type: llm
+focus: { source: file, path: docs/specs/DEK-41.md }
+weight: 3
+---
+
+This is the design for a ticket whose example is "Redraft the Pilot Stages
+slide to lead with the pilot outcome" on the smoke deck. In the repo,
+`findSlideByTitle` matches only on the title of a slide's accepted version,
+only the canvas ever sets `accepted`, and every slide in
+`data/decks/smoke.json` has `"accepted": null`. So the lookup the ticket says
+to reuse finds no slide for the ticket's own example.
+
+Judge the section under the design's Trace heading for the walk, and the rest
+of the design only for the lookup it settles on.
+
+PASS if the Trace section quotes the ticket's example, walks it through the
+smoke deck's actual data, and records there that its slides have no accepted
+version (so the existing lookup returns nothing), and the design builds the
+slide lookup around that, consistent with the
+README (an unaccepted slide is called by its latest version): for example,
+matching the accepted version's title when there is one and the latest
+version's otherwise.
+FAIL if there is no Trace section, if the accepted-slide finding appears only
+outside it, if the design reuses `findSlideByTitle` or the accepted version as
+it stands, or if the accepted state is mentioned only as a general risk
+without saying what the smoke deck holds.

package/skills/sluice/evals/deep-plan-traces-the-example/prompt.md

@@ -0,0 +1,17 @@
+---
+name: deep-plan-traces-the-example
+description: A deep plan whose ticket example contradicts the obvious design. Pins a Trace section in the spec that walks the example through the fixture's real data before sign-off.
+tags: [routing, deep, write]
+max_turns: 25
+timeout_seconds: 900
+allowed_tools: [Read, Glob, Grep, Skill, Write]
+expected_outcome: Announces the deep channel, writes docs/specs/DEK-41.md with a Trace section that runs the ticket's sentence against the smoke deck, finds its slides have no accepted version, designs around that, and stops for sign-off without code.
+---
+
+Plan DEK-41 for us.
+
+> Let people revise a single slide from chat. Example, on the smoke deck:
+> "Redraft the Pilot Stages slide to lead with the pilot outcome" should redraft
+> that slide and leave the rest alone. The chat router needs a revise intent;
+> finding the slide and saving the redraft should reuse what the deck store and
+> the redraft path already do.

package/skills/sluice/evals/rules.json

@@ -31,7 +31,8 @@
       "origin": "docs/specs/2026-08-07-sluice-design.md",
       "cases": [
         "deep-plan-across-subsystems",
-        "deep-plan-asks-the-fork"
+        "deep-plan-asks-the-fork",
+        "deep-plan-traces-the-example"
       ]
     },
     {
@@ -63,7 +64,8 @@
       "origin": "docs/specs/2026-08-07-sluice-design.md",
       "cases": [
         "deep-plan-across-subsystems",
-        "deep-plan-asks-the-fork"
+        "deep-plan-asks-the-fork",
+        "deep-plan-traces-the-example"
       ]
     },
     {
@@ -74,6 +76,38 @@
         "deep-plan-asks-the-fork"
       ]
     },
+    {
+      "id": "deep-design-traces-the-example",
+      "states": "SKILL.md: Deep channel",
+      "origin": "commit:7decf60",
+      "cases": [
+        "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,154 @@ 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
+they fill) can be sound on paper and still fail the request's own example,
+and nothing after it notices: per-task reviews read each task against its own
+text, and the hunt runs once every task is done. So walk the request through
+the system as it stands before you draft, and give the design a `## Trace`
+section that records the walk (in the plan file under plan mode, carried into
+the spec on approval):
+
+1. **The example, verbatim.** Quote the sentence, command or scenario the
+   request gives. Where it gives none, write the acceptance criterion as one
+   concrete case and say that you did.
+2. **Through the real data.** Follow that case step by step through the rows,
+   files or fixtures it would touch, as they exist now rather than as the
+   design assumes them: read the record, run the query, open the fixture, and
+   cite what each step read. "A deck built in chat has no accepted slides" is
+   a fact one read away, and a design keyed on accepted slides is wrong without
+   it.
+3. **What each reused path requires and writes.** For every function the
+   design reuses, its preconditions and its side effects, read from the code
+   and not from its name. Run the example a second time where the request
+   implies a repeat (a redraft of a redraft, an edit after an edit), because
+   what the first pass wrote is what the second pass reads.
+4. **What the walk ruled out.** Each place it contradicted the obvious design
+   (the reuse the request suggests, the first shape that came to mind), and
+   what the design does instead. An empty list is a result, not a skipped
+   step.
+
+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
@@ -492,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