Skip to content
Merged
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
8 changes: 8 additions & 0 deletions docs/upstream/aihero-course.md
Original file line number Diff line number Diff line change
Expand Up @@ -274,6 +274,14 @@ the chain record's "course side UNVERIFIED" caveat on the clear step.
| Ungrillable question → prototype detour (upstream fires it mid-grilling: "stop grilling… build the throwaway version… come back and answer in one line") | Absent from the interview (grep-confirmed by both audit validators); our route exists only downstream (wayfind / plan / brainstorm) | **ADOPT** (delivered) | Chain audit finding, upstream-repo-grounded. Filed: [#2998](https://github.com/melodic-software/claude-code-plugins/issues/2998); delivered by [#3045](https://github.com/melodic-software/claude-code-plugins/pull/3045) — `interview` now carries the detour in "Mid-interview composition" (routing look-and-feel to `/prototype:explore-directions`, logic/state/data-shape to `/prototype:pressure-test`) plus a **Needs-an-artifact** arm in the `context/loop.md` categorization taxonomy; planning 0.32.0. As-of 2026-08-19 |
| Plan-mode-off while grilling | Beyond upstream's taste point, a mechanical edge the audit surfaced: the ask-time register write is load-bearing and plan mode's read-only enforcement blocks it | **ADOPT** (delivered) | Includes reconciling `planning:plan`'s clarifying-rounds-in-plan-mode sentence with the lane 4 asset-rush doctrine. Filed: [#2998](https://github.com/melodic-software/claude-code-plugins/issues/2998); delivered by [#3045](https://github.com/melodic-software/claude-code-plugins/pull/3045) — the gotcha lands in `interview/context/gotchas.md`, and `plan`'s plan-mode round is now scoped to a scoping confirm with substantive rounds routed to `/planning:interview` outside plan mode; planning 0.32.0. As-of 2026-08-19 |
| Provenance correction (adjacent, from the chain audit) | SSOT PR-#532 row | **CORRECTED in SSOT** | The row's "ADR 3-gate + glossary purity are house additions" claim is contradicted on current upstream main (`domain-modeling` carries both near-identically); annotated as convergent-or-derived, direction unverifiable. As-of 2026-08-18 |
| Round template separates consecutive questions with a horizontal rule `---` (upstream commit `85f83d3f`) | `interview` round shape is the per-question block in SKILL.md "Relentless mode" (`Q<N>:` lead, recommendation, `Basis:`, alternatives); no rule between blocks | **REJECT** (cosmetic, not adopted) | The only change to `grilling/SKILL.md` between `068b6e0` and `3cca18b3`; it alters no behavior. Each of our blocks opens with its own `Q<N>:` lead and ends in an Alternatives list, and a rule directly under a line of text renders as a heading in Markdown, so the marker adds a rendering hazard for a break the blocks already carry. Reopen if a user reports rounds running together. As-of 2026-09-29 |

Re-fetch as-of 2026-09-29: `mattpocock/skills` HEAD `3cca18b3` (2026-09-04). The `grilling` and
`grill-me` skill bodies differ from the `068b6e0` baseline only by the round-template separator,
graded in the last table row above. The closure language is still a stop-condition declaration plus
a confirmation gate, so the PARITY grading of the "Done when the frontier is empty" row stands.
Upstream still has no Q&A recap and no procedure validation, so the house sign-off recap and the
`check-open-questions.sh` procedure checks have no upstream counterpart to compare.

House decisions recorded alongside the rows (Q36-Q37 this run; chain audit 2026-08-18): no term
adoption for the loop name (mapping recorded instead — see the term-adoption section); the
Expand Down
2 changes: 1 addition & 1 deletion plugins/planning/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "planning",
"version": "0.47.12",
"version": "0.48.0",
"userConfig": {
"surface": {
"type": "string",
Expand Down
11 changes: 11 additions & 0 deletions plugins/planning/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,17 @@
All notable changes to the `planning` plugin are documented here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.

## [0.48.0] - 2026-09-29

### Added

- **`interview` Step 3 sign-off recap.** Before the confirmation request in `me` and `auto` modes, the restatement carries one line per `Q<N>` naming its status, question text and resolution, generated from the ledger's open-question register rather than the transcript, so it survives a compaction. The recap extends the existing confirmation gate instead of adding an Action Router action or a separate skill: the user already confirms at that gate, the register already holds the data, and the digest-pinned Action Router stays unchanged ([#3941](https://github.com/melodic-software/claude-code-plugins/issues/3941)).
- **`check-open-questions.sh --procedure`** checks what a ledger file can show about the procedure: rounds appear contiguously in the register and every retired row carries a resolution. With `--brief` it also requires all seven Brief template headings, so the Step 4 cross-check halts on a Brief missing one. The Step 3 gate and the Step 4 Brief cross-check cite its exit code and `procedure=` field. The skill names what stays unchecked: survey grounding, domain classification, ask-time register writes and frontier recomputation.

### Changed

- `interview` and `audit-answers` each state their relationship: the recap and `--procedure` check show the Q&A and that the procedure ran, `audit-answers` adversarially re-validates the answers, and neither composes nor duplicates the other.

## [0.47.12] - 2026-09-30

### Fixed
Expand Down
138 changes: 131 additions & 7 deletions plugins/planning/scripts/check-open-questions.sh
Original file line number Diff line number Diff line change
Expand Up @@ -17,16 +17,19 @@
# was silently dropped after being written; a question never written at all is
# out of reach of any file-based check and is the skill's contract to keep.
#
# Exit 0 = every registered question is resolved (register is clean)
# Exit 0 = every registered question is resolved (register is clean) and, with
# --procedure, the procedure checks below pass
# Exit 1 = at least one question is still `open` or `superseded-by-plan` (the
# contract is not locked)
# contract is not locked), or --procedure found a procedure defect
# (the register is gradeable but the interview did not complete its
# own procedure; fix the ledger or Brief and re-run)
# Exit 2 = ungradeable: no ledger, no register section, a duplicate register or
# deferred-questions heading, an unterminated fenced block, an empty
# register, a malformed row, an unknown status, a duplicate or
# non-contiguous Q id, or a named `--brief` that is missing
#
# Usage:
# bash check-open-questions.sh --ledger <interview-checklist.md> [--brief <PLAN.md>]
# bash check-open-questions.sh --ledger <interview-checklist.md> [--brief <PLAN.md>] [--procedure]
# bash check-open-questions.sh --help
#
# Register row shape (inside the ledger's `## Open-question register` section):
Expand All @@ -47,13 +50,35 @@
# headings and fences are not graded, so a stray fence in an unrelated section
# of a large planning document cannot fail a clean register.
#
# --procedure is OPT-IN and adds checks a script can derive from the ledger, so
# a caller that omits it keeps every verdict and exit code above unchanged:
# - round numbers in the register rows run contiguously from 1 (a `round`
# field that is not `round <N>` with N >= 1 counts as a defect)
# - every `answered`, `deferred`, `withdrawn` and `blocked` row carries a
# non-empty resolution (the fifth field)
# - with --brief, the Brief holds every section of the literal Brief template:
# TLDR, Goal, Constraints, Acceptance criteria, Captured assumptions,
# Out-of-scope, Deferred questions (headings only; content is not graded)
# Each defect is named on stderr. Without --procedure the verdict says
# `procedure=unchecked`, the same convention as `brief=unchecked`. A gradeable
# register with a procedure defect exits 1 with `status=incomplete` (`open` when
# a row is also unresolved); ungradeable stays exit 2 with `procedure=unchecked`.
# With --procedure the named Brief is always read, so an unterminated fence in
# it is ungradeable even when the register retired nothing.
#
# What stays a model judgment and is NOT checked here: whether the Step 1
# survey genuinely grounded the questions, whether the domain was classified,
# whether the register was written at ask-time rather than answer-time, and
# whether the frontier was recomputed between rounds. A file written after the
# fact looks identical to one written at ask-time.
#
# Fenced blocks (``` or ~~~) are documentation in both files. A fence closes
# only on a line of the same character at least as long as its opener with
# nothing else on it, so a four-backtick fence can quote a three-backtick
# example and a `~~~` line inside a backtick fence is content.
#
# Output (stdout, greppable):
# `registered=<n> open=<n> deferred=<n> blocked=<n> withdrawn=<n> answered=<n> superseded=<n> brief=<ok|unchecked> status=<clean|open|ungradeable>`
# `registered=<n> open=<n> deferred=<n> blocked=<n> withdrawn=<n> answered=<n> superseded=<n> brief=<ok|unchecked> status=<clean|open|incomplete|ungradeable> procedure=<ok|unchecked|fail>`

set -uo pipefail

Expand Down Expand Up @@ -141,10 +166,11 @@ extract_section() {
ledger=""
brief=""
brief_named=0
procedure_on=0

die_ungradeable() {
echo "error: $1" >&2
echo "registered=0 open=0 deferred=0 blocked=0 withdrawn=0 answered=0 superseded=0 brief=unchecked status=ungradeable"
echo "registered=0 open=0 deferred=0 blocked=0 withdrawn=0 answered=0 superseded=0 brief=unchecked status=ungradeable procedure=unchecked"
exit 2
}

Expand Down Expand Up @@ -172,6 +198,10 @@ while [[ $# -gt 0 ]]; do
brief_named=1
shift
;;
--procedure)
procedure_on=1
shift
;;
*)
die_ungradeable "unknown argument: $1"
;;
Expand Down Expand Up @@ -231,6 +261,9 @@ superseded=0
seen_ids=" "
deferred_ids=""
expected=1
rounds_seen=" "
max_round=0
proc_problems=""

# What counts as a CANDIDATE register row, defined once. The fenced branch and
# the live branch below both test it, and they must agree: a shape skipped as
Expand Down Expand Up @@ -311,6 +344,27 @@ while IFS= read -r line; do
expected=$((expected + 1))

registered=$((registered + 1))

# Fields after the id: status | round | question | resolution. The resolution
# is the text after the last `|`, so a `|` inside the question cannot make an
# empty resolution look filled; a row with no question and resolution
# fields has none.
after_status="${rest#*|}"
round_field="${after_status%%|*}"
round_field="${round_field#"${round_field%%[![:space:]]*}"}"
round_field="${round_field%"${round_field##*[![:space:]]}"}"
resolution="${after_status#*|}"
if [[ "$resolution" == *"|"* ]]; then resolution="${resolution##*|}"; else resolution=""; fi
resolution="${resolution#"${resolution%%[![:space:]]*}"}"
resolution="${resolution%"${resolution##*[![:space:]]}"}"
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
if [[ "$round_field" =~ ^[Rr]ound[[:space:]]+([1-9][0-9]*)$ ]]; then
round_num="${BASH_REMATCH[1]}"
rounds_seen="$rounds_seen$round_num "
[[ "$round_num" -gt "$max_round" ]] && max_round="$round_num"
else
proc_problems="$proc_problems$id: round field is not 'round <N>' (N >= 1): '$round_field'"$'\n'
fi

# Statuses match case-insensitively without a subprocess per row (a `tr` fork
# costs over a second per row on a loaded Windows host). nocasematch, not
# ${var,,}, because macOS /bin/bash is 3.2; scoped so no other match sees it.
Expand All @@ -330,6 +384,12 @@ while IFS= read -r line; do
;;
*) die_ungradeable "unknown status '$status_field' in row: $line ($where)" ;;
esac
case "$status_field" in
answered | deferred | withdrawn | blocked)
[[ -n "$resolution" ]] || proc_problems="$proc_problems$id: $status_field row has an empty resolution"$'\n'
;;
*) ;;
esac
shopt -u nocasematch
done <<<"$section"

Expand Down Expand Up @@ -393,12 +453,76 @@ elif [[ "$brief_named" -eq 1 ]]; then
brief_state="ok"
fi

procedure_state="unchecked"
if [[ "$procedure_on" -eq 1 ]]; then
# Contiguous rounds never exceed the row count, so bound the walk there: a
# mistyped round number fails fast instead of iterating to it.
round_limit="$max_round"
if [[ "$max_round" -gt "$registered" ]]; then
round_limit="$registered"
proc_problems="${proc_problems}highest round $max_round exceeds the $registered registered question(s); rounds must run contiguously from 1"$'\n'
fi
for ((round_num = 1; round_num <= round_limit; round_num++)); do
case "$rounds_seen" in
*" $round_num "*) ;;
*) proc_problems="${proc_problems}round $round_num has no register row (rounds must run contiguously from 1; highest is $max_round)"$'\n' ;;
esac
done

if [[ "$brief_named" -eq 1 ]]; then
# A PLAN.md holds `## Brief` + `## Plan`: a heading under `## Plan` must not
# satisfy a template section the Brief lacks, so grade only the lines from
# the `## Brief` heading to the next level-2 heading. A file with no
# `## Brief` heading is graded whole.
brief_lo=0
brief_hi=999999999
brief_h2="$(heading_matches '^##[[:space:]]' "$brief")"
brief_h2_status=$?
if [[ "$brief_h2_status" -eq 4 ]]; then
die_ungradeable "unterminated fenced block in: $brief (every heading after it is hidden; close the fence)"
elif [[ "$brief_h2_status" -ne 0 ]]; then
die_ungradeable "could not read the headings of: $brief"
fi
brief_lo="$(printf '%s\n' "$brief_h2" | awk -F'\t' 'tolower($2) ~ /^##[[:space:]]+brief[[:space:]]*$/ { print $1; exit }')"
if [[ -n "$brief_lo" ]]; then
brief_hi="$(printf '%s\n' "$brief_h2" | awk -F'\t' -v lo="$brief_lo" '$1 > lo { print $1; exit }')"
brief_hi="${brief_hi:-999999999}"
else
brief_lo=0
fi
for section_pattern in 'tl;?dr' 'goal' 'constraints' 'acceptance criteria' \
'captured assumptions' 'out[- ]of[- ]scope' 'deferred questions'; do
section_matches="$(heading_matches "^#+[[:space:]]+${section_pattern}[[:space:]]*\$" "$brief")"
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
section_status=$?
if [[ "$section_status" -eq 4 ]]; then
die_ungradeable "unterminated fenced block in: $brief (every heading after it is hidden; close the fence)"
elif [[ "$section_status" -ne 0 ]]; then
die_ungradeable "could not read the headings of: $brief"
fi
section_matches="$(printf '%s\n' "$section_matches" | awk -F'\t' -v lo="$brief_lo" -v hi="$brief_hi" '$1 > lo && $1 < hi')"
[[ -n "$section_matches" ]] || proc_problems="${proc_problems}Brief is missing the section matching '$section_pattern'"$'\n'
done
fi

if [[ -n "$proc_problems" ]]; then
procedure_state="fail"
printf 'procedure: %s\n' "${proc_problems%$'\n'}" >&2
else
procedure_state="ok"
fi
fi

verdict="registered=$registered open=$open_count deferred=$deferred blocked=$blocked withdrawn=$withdrawn answered=$answered superseded=$superseded brief=$brief_state"

if [[ $((open_count + superseded)) -gt 0 ]]; then
echo "$verdict status=open"
echo "$verdict status=open procedure=$procedure_state"
exit 1
fi

if [[ "$procedure_state" == "fail" ]]; then
echo "$verdict status=incomplete procedure=fail"
exit 1
fi

echo "$verdict status=clean"
echo "$verdict status=clean procedure=$procedure_state"
exit 0
Loading