Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion scripts/super-board-deps.sh
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,10 @@
# { "40": { "number": 40, "title": "…", "state": "OPEN",
# "blockers": [32,36], "openBlockers": [32],
# "parseable": true, "humanGated": false, "runnable": false, "why": "",
# "needsYou": false, "needsYouDone": false } }
# "acItems": 3, "needsYou": false, "needsYouDone": false } }
#
# `acItems` — real acceptance-criteria items in the body (placeholders and an
# empty section count 0). The wave planner never picks a Ready card at 0.
#
# `needsYou` — the newest Block comment carries the 🙋 reason tag, or the issue
# has the `needs-you` label: a human-only command is waiting (block-template.md).
Expand Down Expand Up @@ -147,6 +150,28 @@ echo "$ISSUES" | jq --arg only "$ONLY" '
| map(select(.value | test("Reason tag:[^\n]*🙋"))) | last | .key ) // null;
def needs_you: (label_names | index("needs-you") != null) or (needs_at != null);

# Real acceptance criteria: bullets under an `Acceptance Criteria` heading, up to
# the next heading, that are not a placeholder. A heading over nothing, or over
# the line a filer appends for lint to replace, is zero: the builder would have
# nothing to test against. The wave planner gates Ready cards on this.
def placeholder:
(length < 8) or test("not written|placeholder|\\bTBD\\b|\\bTODO\\b|^<.*>$|^…$|^\\.\\.\\.$"; "i");
# A sub-heading inside the section (`### Desktop`) does not end it; a heading at
# the same level or above does.
def ac_items:
reduce ((. // "") / "\n")[] as $l ({at: null, n: 0};
if ($l | test("^#{1,6}[ \t]")) then
($l | capture("^(?<h>#+)").h | length) as $lv
| if ($l | test("^#{1,3}[ \t]+acceptance criteria[ \t]*$"; "i")) then .at = $lv
elif .at != null and $lv <= .at then .at = null
else . end
elif .at != null and ($l | test("^[ \t]*[-*][ \t]+"))
and ($l | sub("^[ \t]*[-*][ \t]+(\\[[ xX]\\][ \t]*)?"; "") | gsub("^[ \t_*]+|[ \t_*]+$"; "")
| placeholder | not) then
.n += 1
else . end)
| .n;


( [ .[] | .number ] ) as $open
| ( if $only == "" then null else ($only / "," | map(tonumber)) end ) as $filter
Expand Down Expand Up @@ -188,6 +213,7 @@ echo "$ISSUES" | jq --arg only "$ONLY" '
humanGated: $p.human_gated,
runnable: ($p.parseable and ($p.human_gated | not) and (($stillOpen | length) == 0)),
why: $p.why,
acItems: ($i.body | ac_items),
needsYou: ($i | needs_you),
needsYouDone: false }
]
Expand Down
25 changes: 21 additions & 4 deletions scripts/super-board-wave-plan.sh
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,11 @@
# reported in `stranded`; the orchestrator checks its branch and worktree and
# moves it back to Ready, keeping the branch.
#
# NO CRITERIA, NO BUILD. A Ready card labelled `needs-ac` (a filer found no real
# acceptance criteria), or whose graph entry counts zero criteria items, is never
# picked: the builder would have nothing to test against. It is reported in `flag`
# for `super-board lint`, and left in Ready.
#
# LABEL ROUTING (v3.0.0). One board shape for every project; a card's label picks
# its lane. Three labels: `qa`, `bug`, `feature`. A Ready card labelled `qa` skips
# the Builder and goes straight to the Tester (lane "qa"); every other Ready card,
Expand Down Expand Up @@ -145,6 +150,10 @@ echo "$ITEMS" | jq --argjson cols "$COLUMNS" --argjson cap "$MAX_WORKERS" --argj
else "build" end;
# Unknown to the graph (closed, or beyond the fetch limit) is not "free".
def free($n): (dep($n) | if . == null then false else .runnable end);
# No real acceptance criteria: the filer labelled it `needs-ac`, or the graph
# counted zero criteria items. The builder would have nothing to test against.
# An entry without acItems (an older graph) is not held on that ground.
def no_ac($c): ($c.labels | index("needs-ac")) or ((dep($c.number).acItems // 1) == 0);

[ .items[]
| select(.content.type == "Issue")
Expand All @@ -158,8 +167,8 @@ echo "$ITEMS" | jq --argjson cols "$COLUMNS" --argjson cap "$MAX_WORKERS" --argj
# spends its slots on the work closest to Done.
| [ $cols[] as $c | $all[] | select(.status == $c and $c != "Ready") ] as $flight

# Ready: only the ones the graph says are actually free.
| [ $all[] | select(.status == "Ready") | select(free(.number)) ] as $ready
# Ready: only the ones the graph says are actually free, and have criteria.
| [ $all[] | select(.status == "Ready") | select(free(.number)) | select(no_ac(.) | not) ] as $ready

# Downstream-first, so work already begun finishes before new work starts.
| ($flight + $ready) as $picked
Expand Down Expand Up @@ -188,10 +197,18 @@ echo "$ITEMS" | jq --argjson cols "$COLUMNS" --argjson cap "$MAX_WORKERS" --argj

# Cards the graph could not read. Left where they are, reported so the
# orchestrator can ask for the line to be fixed.
flag: [ $all[]
# Ready cards with no real acceptance criteria are flagged too: lint writes
# them (and removes `needs-ac`), then the next wave picks the card.
flag: ([ $all[]
| select(.status as $s | ["Ready","Blocked"] | index($s))
| select(dep(.number) != null and (dep(.number).parseable | not))
| { number, title, why: (dep(.number) | .why) } ],
| { number, title, why: (dep(.number) | .why) } ]
+ [ $all[]
| select(.status == "Ready" and no_ac(.))
| { number, title,
why: (if (.labels | index("needs-ac"))
then "labelled needs-ac: filed with no acceptance criteria — run super-board lint to write them, then remove the label"
else "no acceptance criteria items (empty section or placeholders only) — run super-board lint to write them" end) } ]),

# Building with no claim between waves = no live worker. Back to Ready.
stranded: [ $all[] | select(.status == "Building") | { number, title } ] }'
52 changes: 44 additions & 8 deletions scripts/super-review-file-refactor.sh
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,13 @@
# warning; unavailable required evidence or an unknown write outcome pauses the
# run (79) while preserving any issue already created. No mutation is retried.
#
# A card with real acceptance criteria lands in Ready; one without lands in Backlog.
# A bare note has had no human eyes on it; auto-promoting it to Ready would feed the
# build lane work nobody asked for. It waits for `super-board lint` like any other
# unrefined ticket.
# A card with real acceptance criteria lands in Ready; one without lands in Backlog
# with the `needs-ac` label, even when --column Ready is passed. "Real" means at
# least one item under `## Acceptance Criteria` that is not a placeholder: an empty
# section or a `- [ ] TBD` is not criteria. A bare note has had no human eyes on it;
# auto-promoting it to Ready would feed the build lane work nobody asked for, and the
# builder would have nothing to test against. It waits for `super-board lint`, which
# writes the criteria and removes the label; the wave planner never picks it before.
#
# Usage:
# super-review-file-refactor.sh --config <config.json> \
Expand Down Expand Up @@ -105,14 +108,46 @@ fi
#
# A card with real acceptance criteria is buildable, so it goes to `Ready` and the
# next wave takes it. A card without them is a note, and `Ready` feeds the Builder
# lane directly — so it goes to the holding column and waits for `super-board
# lint` like any other unrefined ticket.
# lane directly — so it goes to the holding column, labelled `needs-ac`, and waits
# for `super-board lint` like any other unrefined ticket. An explicit --column
# Ready does not override that: criteria nobody wrote cannot be built against.
#
# A heading is not criteria. Cards were filed with an empty section, or with only
# a placeholder item, and reached Ready; the builder had nothing to test against.
# Same rule as `acItems` in super-board-deps.sh, which the wave planner reads.
#
# This used to be an unconditional `Backlog`, which was wrong twice over: it fed
# nothing to the loop even when the card was ready, and on a board with no
# `Backlog` column it produced cards with no Status at all.
if [ -z "$COLUMN" ]; then
if grep -qiE '^## +Acceptance criteria *$' "$BODY_FILE"; then COLUMN="Ready"; else COLUMN="Backlog"; fi
AC_ITEMS=$(python3 - "$BODY_FILE" <<'PY'
import re, sys
at, n = None, 0
for line in open(sys.argv[1], encoding="utf-8").read().splitlines():
h = re.match(r"^(#{1,6})[ \t]", line)
if h:
if re.match(r"^#{1,3}[ \t]+acceptance criteria[ \t]*$", line, re.I):
at = len(h[1])
elif at is not None and len(h[1]) <= at:
at = None
continue
if at is None or not re.match(r"^[ \t]*[-*][ \t]+", line):
continue
text = re.sub(r"^[ \t]*[-*][ \t]+(\[[ xX]\][ \t]*)?", "", line).strip(" \t_*")
if len(text) < 8 or re.search(r"not written|placeholder|\bTBD\b|\bTODO\b|^<.*>$|^…$|^\.\.\.$", text, re.I):
continue
n += 1
print(n)
PY
)
NEEDS_AC=0
if [ "${AC_ITEMS:-0}" -gt 0 ]; then
[ -n "$COLUMN" ] || COLUMN="Ready"
else
NEEDS_AC=1
if [ "$COLUMN" = "Ready" ]; then
echo "note: no acceptance criteria items — filing to Backlog with needs-ac, not Ready" >&2
fi
[ -n "$COLUMN" ] && [ "$COLUMN" != "Ready" ] || COLUMN="Backlog"
fi

# --- create -----------------------------------------------------------------
Expand Down Expand Up @@ -169,6 +204,7 @@ trap 'rm -f "$BODY_TMP"' EXIT

LABELS=("refactor" "source:review" "strength:${STRENGTH}")
if [ -n "$AREA" ]; then LABELS+=("area:${AREA}"); fi
if [ "$NEEDS_AC" -eq 1 ]; then LABELS+=("needs-ac"); fi

# Labels may not exist yet on a fresh repo. Create them best-effort; `gh issue
# create` hard-fails on an unknown label, which would lose the finding entirely.
Expand Down
5 changes: 4 additions & 1 deletion skills/super-board/references/lint.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,10 @@

**Where it runs:** current Claude Code session. Interactive. Single-pass.
**Purpose:** clarify issues so a headless worker won't hallucinate. Every
active-pipeline issue must have testable acceptance criteria.
active-pipeline issue must have testable acceptance criteria. Cards labelled
`needs-ac` (filed mid-run with no real criteria) are always flagged: write the
criteria, then remove the label. The wave planner skips them until then, and also
skips any Ready card whose criteria section is empty or placeholders only.

All clarifications are saved to GitHub via `gh issue edit` /
`gh issue comment` — **no local file writes** during the per-issue loop.
Expand Down
2 changes: 1 addition & 1 deletion skills/super-board/references/run-workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,7 @@ Repeat until a done condition or halt gate fires:
cards to `Review` solely to review the changed head and post a fresh human request;
clear their stale `needs-you:done` display labels. They have no approval to merge.
Comment on flagged cards asking for their
`## Blocked by` line to be fixed, and return every stranded Building card to
`## Blocked by` line or their acceptance criteria (`needs-ac`) to be fixed, and return every stranded Building card to
`Ready` (below). Swept, resumed, approval-refresh and stranded cards are NOT in this pass's
`cards`; they join the next wave.

Expand Down
6 changes: 4 additions & 2 deletions skills/super-board/references/run.md
Original file line number Diff line number Diff line change
Expand Up @@ -713,8 +713,10 @@ Before planning any wave, `super-board-wave-plan.sh` reports five lists the orch
Move it to **Review** and remove stale `needs-you:done` display labels. The Reviewer
reviews the new code and lets the gate produce a new pinned request, then returns
it to **Blocked** for a fresh human reply. This is not an approved resume.
- **`flag`** — cards whose `## Blocked by` section could not be parsed. Leave them where they are
and comment asking for the line to be fixed, quoting the `why`. Never guess: a card treated as
- **`flag`** — cards whose `## Blocked by` section could not be parsed, and Ready cards with no
real acceptance criteria (labelled `needs-ac`, or an empty / placeholder-only section; never
built). Leave them where they are and comment asking for the line or the criteria to be fixed
(`super-board lint`), quoting the `why`. Never guess: a card treated as
free on an unreadable line gets built against a base that does not have what it needs.

**Why the sweep exists.** `Blocked` used to be terminal. A card parked naming the issue it waited
Expand Down
5 changes: 5 additions & 0 deletions skills/super-board/references/writing-standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,11 @@ status alert.
| `## Risk` | 🟢/🟡/🔴 level + one line | yes |
| `## Blocked by` | `- #N — why` bullets, or exactly `- None.` | yes |

An empty `## Acceptance Criteria` section, or one holding only placeholders (`TBD`,
`<checkable outcome>`, a filer's "Not written" line), counts as no criteria. A filer files
such a card to Backlog labelled `needs-ac`; the wave planner never picks it and flags it
for `super-board lint`, which writes the criteria and removes the label.

When an unsettled design triggers [design preflight](design-preflight.md), retain the
approved choice and short rationale in the existing Context, or link its applicable
spec/ADR there. Keep the same sections. Lint saves only the exact issue edit the user approves.
Expand Down
23 changes: 22 additions & 1 deletion tests/test-deps.sh
Original file line number Diff line number Diff line change
Expand Up @@ -113,4 +113,25 @@ get 28 '.needsYouDone == false' || fail "#28: a 'done' before the 🙋 block mus
get 26 '.runnable == false' || fail "#26: done goes through resume, never the Ready sweep"
get 2 '.needsYou == false and .needsYouDone == false' || fail "an ordinary card is not needsYou"

echo "PASS: test-deps.sh (18 scenarios)"
# 19 — acItems counts real acceptance criteria, so the planner never picks a card
# the builder has nothing to test against. A heading over nothing, or over a
# placeholder the filer appended, is zero. Missing section is zero too.
AC_FIX=$(jq -n --arg bd $'## Blocked by\n\n- None.\n' '[
{number:30, title:"real", state:"OPEN", body:("## Acceptance Criteria\n\n- [ ] Saving twice keeps one row\n- [x] The list shows it\n\n" + $bd)},
{number:31, title:"empty", state:"OPEN", body:("## Acceptance Criteria\n\n" + $bd)},
{number:32, title:"placeholder", state:"OPEN", body:("## Acceptance criteria\n\n- [ ] _Not written by the Reviewer that filed this. Run `super-board lint`_\n- [ ] TBD\n- [ ] <checkable outcome>\n\n" + $bd)},
{number:33, title:"none", state:"OPEN", body:$bd},
{number:34, title:"next section", state:"OPEN", body:("## Acceptance Criteria\n\n## Notes\n- [ ] this is not a criterion at all\n\n" + $bd)},
{number:35, title:"sub-headings", state:"OPEN", body:("## Acceptance Criteria\n\n### Desktop\n- [ ] The table fits at 1440 wide\n\n" + $bd)}]')
AC_OUT=$("$DEPS" --from <(echo "$AC_FIX"))
ac() { echo "$AC_OUT" | jq -r --arg n "$1" '.[$n].acItems'; }
[ "$(ac 30)" = 2 ] || fail "#30 has two real criteria, got $(ac 30)"
[ "$(ac 31)" = 0 ] || fail "#31: an empty section is no criteria, got $(ac 31)"
[ "$(ac 32)" = 0 ] || fail "#32: placeholders are no criteria, got $(ac 32)"
[ "$(ac 33)" = 0 ] || fail "#33: no section is no criteria, got $(ac 33)"
[ "$(ac 34)" = 0 ] || fail "#34: the section stops at the next heading, got $(ac 34)"
[ "$(ac 35)" = 1 ] || fail "#35: a sub-heading inside the section does not end it, got $(ac 35)"
echo "$AC_OUT" | jq -e '.["31"].runnable == true' >/dev/null \
|| fail "acItems must not change runnable: the planner gates on it, the graph does not"

echo "PASS: test-deps.sh (19 scenarios)"
32 changes: 32 additions & 0 deletions tests/test-file-refactor.sh
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,38 @@ case "$(cat "$GH_LOG")" in
*) ok "a bare note never falls back into Ready" ;;
esac

echo "── no real acceptance criteria → needs-ac, Backlog"
# A card filed with an empty or placeholder-only criteria section reached Ready,
# the planner picked it, and the builder had nothing to test against. A heading
# is not criteria: only an item that is not a placeholder counts.
labels_of() { grep '^issue create' "$GH_LOG" | grep -oE -- '--label [^ ]+' | sed 's/--label //' | tr '\n' ' '; }
no_ready() { case "$(cat "$GH_LOG")" in *opt_Ready*) bad "$1" "no opt_Ready" "found it" ;; *) ok "$1" ;; esac; }
no_label() { case "$(labels_of)" in *needs-ac*) bad "$1" "no needs-ac" "$(labels_of)" ;; *) ok "$1" ;; esac; }

DEDUPE_HIT="" run --config "$WORK/config.json" --title "Bare note" --body-file "$WORK/bare.md" --fingerprint "ac|bare" >/dev/null
has "a bare note is labelled needs-ac" "$(labels_of)" "needs-ac"

printf '## Problem\nP.\n\n## Context\n- **Where:** `src/x.ts`\n\n## Fix\nF.\n\n## Acceptance Criteria\n\n## Risk\n🟢 **Low** · one file.\n' > "$WORK/emptyac.md"
DEDUPE_HIT="" run --config "$WORK/config.json" --title "Empty AC" --body-file "$WORK/emptyac.md" --fingerprint "ac|empty" >/dev/null
has "an empty criteria section is labelled needs-ac" "$(labels_of)" "needs-ac"
has "an empty criteria section lands in Backlog" "$(cat "$GH_LOG")" "opt_Backlog"
no_ready "an empty criteria section never lands in Ready"

for ph in "_Not written by the Reviewer that filed this. Run \`super-board lint\` on this card_" "TBD" "<checkable outcome>" "…"; do
printf '## Problem\nP.\n\n## Context\n- **Where:** `src/x.ts`\n\n## Fix\nF.\n\n## Acceptance Criteria\n\n- [ ] %s\n' "$ph" > "$WORK/phac.md"
DEDUPE_HIT="" run --config "$WORK/config.json" --title "Placeholder AC" --body-file "$WORK/phac.md" --fingerprint "ac|ph" >/dev/null
has "placeholder '${ph:0:20}' is labelled needs-ac" "$(labels_of)" "needs-ac"
no_ready "placeholder '${ph:0:20}' never lands in Ready"
done

DEDUPE_HIT="" run --config "$WORK/config.json" --title "Forced" --body-file "$WORK/phac.md" --fingerprint "ac|forced" --column Ready >/dev/null
no_ready "--column Ready cannot override missing criteria"
has "says why it ignored --column Ready" "$(cat "$WORK/err")" "needs-ac"

DEDUPE_HIT="" run --config "$WORK/config.json" --title "Real AC" --body-file "$WORK/full.md" --fingerprint "ac|real" >/dev/null
has "real criteria still land in Ready" "$(cat "$GH_LOG")" "opt_Ready"
no_label "real criteria are not labelled needs-ac"

echo "── degradation (must never fail the review)"
# A board with NO holding column at all: warn loudly, because a status-less card
# sits in a No Status group nobody opens. Observed for real on 2026-08-20, where
Expand Down
Loading