diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md index 560646d0858..64726551354 100644 --- a/docs/upstream/aihero-course.md +++ b/docs/upstream/aihero-course.md @@ -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:` 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:` 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 diff --git a/plugins/planning/.claude-plugin/plugin.json b/plugins/planning/.claude-plugin/plugin.json index c8124ed2415..aa6af30bfc5 100644 --- a/plugins/planning/.claude-plugin/plugin.json +++ b/plugins/planning/.claude-plugin/plugin.json @@ -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", diff --git a/plugins/planning/CHANGELOG.md b/plugins/planning/CHANGELOG.md index 7c3b6553f4e..31b4d46397a 100644 --- a/plugins/planning/CHANGELOG.md +++ b/plugins/planning/CHANGELOG.md @@ -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` 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 diff --git a/plugins/planning/scripts/check-open-questions.sh b/plugins/planning/scripts/check-open-questions.sh index f020a6b6abe..6d3dc3c4056 100755 --- a/plugins/planning/scripts/check-open-questions.sh +++ b/plugins/planning/scripts/check-open-questions.sh @@ -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 [--brief ] +# bash check-open-questions.sh --ledger [--brief ] [--procedure] # bash check-open-questions.sh --help # # Register row shape (inside the ledger's `## Open-question register` section): @@ -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 ` 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= open= deferred= blocked= withdrawn= answered= superseded= brief= status=` +# `registered= open= deferred= blocked= withdrawn= answered= superseded= brief= status= procedure=` set -uo pipefail @@ -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 } @@ -172,6 +198,10 @@ while [[ $# -gt 0 ]]; do brief_named=1 shift ;; + --procedure) + procedure_on=1 + shift + ;; *) die_ungradeable "unknown argument: $1" ;; @@ -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 @@ -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:]]}"}" + 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 >= 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. @@ -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" @@ -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")" + 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 diff --git a/plugins/planning/scripts/check-open-questions.test.sh b/plugins/planning/scripts/check-open-questions.test.sh index b1115cc2f27..0bb4048d67f 100755 --- a/plugins/planning/scripts/check-open-questions.test.sh +++ b/plugins/planning/scripts/check-open-questions.test.sh @@ -643,6 +643,136 @@ expect_stdout "clean verdict places superseded after answered" "answered=1 super # 45. The ungradeable line carries the field too, in the same position. expect_stdout "ungradeable verdict carries superseded=0" "answered=0 superseded=0 brief=unchecked status=ungradeable" --ledger "$noreg" +# 46. --procedure: a clean, contiguous, fully-resolved ledger passes and says so. +proc_clean="$( + mkledger <<'EOT' +- Q1 | answered | round 1 | Who writes? | admin +- Q2 | withdrawn | round 2 | What format? | no longer needed +EOT +)" +expect_exit "--procedure clean ledger -> 0" 0 --ledger "$proc_clean" --procedure +expect_stdout "--procedure clean ledger reports procedure=ok" "status=clean procedure=ok" --ledger "$proc_clean" --procedure + +# 47. Omitting the flag is explicit, and the same ledger's exit code is unchanged. +expect_stdout "omitted --procedure reports procedure=unchecked" "status=clean procedure=unchecked" --ledger "$proc_clean" + +# 48. A round gap fails: round 3 present, round 2 missing. +proc_gap="$( + mkledger <<'EOT' +- Q1 | answered | round 1 | Who writes? | admin +- Q2 | answered | round 3 | What format? | html +EOT +)" +expect_exit "--procedure round gap -> 1" 1 --ledger "$proc_gap" --procedure +expect_stdout "--procedure round gap reports procedure=fail" "status=incomplete procedure=fail" --ledger "$proc_gap" --procedure +if [[ "$(stderr_of --ledger "$proc_gap" --procedure)" == *"round 2 has no register row"* ]]; then pass "--procedure names the missing round"; else fail "--procedure names the missing round"; fi +expect_exit "round gap without --procedure -> 0" 0 --ledger "$proc_gap" + +# 49. Rounds must start at 1. +proc_start="$( + mkledger <<'EOT' +- Q1 | answered | round 2 | Who writes? | admin +EOT +)" +expect_exit "--procedure rounds not starting at 1 -> 1" 1 --ledger "$proc_start" --procedure + +# 50. A round field that is not `round ` fails. +proc_badround="$( + mkledger <<'EOT' +- Q1 | answered | first | Who writes? | admin +EOT +)" +expect_exit "--procedure malformed round field -> 1" 1 --ledger "$proc_badround" --procedure + +# 51. An empty resolution fails for every retired status, missing field included. +for retired in answered deferred withdrawn blocked; do + proc_empty="$( + mkledger < 1" 1 --ledger "$proc_empty" --procedure +done +proc_nofield="$( + mkledger <<'EOT' +- Q1 | answered | round 1 | Who writes? +EOT +)" +expect_exit "--procedure missing resolution field -> 1" 1 --ledger "$proc_nofield" --procedure +expect_exit "empty resolution without --procedure -> 0" 0 --ledger "$proc_nofield" +proc_pipe="$( + mkledger <<'EOT' +- Q1 | answered | round 1 | Which output | JSON or XML? | +EOT +)" +proc_huge="$( + mkledger <<'EOT' +- Q1 | answered | round 100000000000 | Who writes? | admin +EOT +)" +expect_exit "--procedure huge round number fails fast -> 1" 1 --ledger "$proc_huge" --procedure +expect_exit "--procedure pipe in question with empty resolution -> 1" 1 --ledger "$proc_pipe" --procedure +proc_pipe_ok="$( + mkledger <<'EOT' +- Q1 | answered | round 1 | Which output | JSON or XML? | JSON +EOT +)" +expect_exit "--procedure pipe in question with a resolution -> 0" 0 --ledger "$proc_pipe_ok" --procedure + +# 52. An open row has no resolution yet; --procedure does not fail it, and status stays open. +proc_open="$( + mkledger <<'EOT' +- Q1 | open | round 1 | Who writes? | +EOT +)" +expect_stdout "--procedure leaves an open row's empty resolution alone" "status=open procedure=ok" --ledger "$proc_open" --procedure + +# 53. With --brief, every template section must be present. +proc_brief_full="$TMP/proc-brief-full.md" +cat >"$proc_brief_full" <<'EOT' +## Brief + +### TLDR +- x + +### Goal +x + +### Constraints +- x + +### Acceptance criteria +- x + +### Captured assumptions +- x + +### Out-of-scope +- x + +### Deferred questions +- Q1: x + +## Plan +EOT +proc_brief_short="$TMP/proc-brief-short.md" +grep -v -e '^### Out-of-scope' "$proc_brief_full" >"$proc_brief_short" +proc_retired="$( + mkledger <<'EOT' +- Q1 | deferred | round 1 | Who writes? | post-V1 +EOT +)" +expect_exit "--procedure --brief with every section -> 0" 0 --ledger "$proc_retired" --brief "$proc_brief_full" --procedure +expect_exit "--procedure --brief missing Out-of-scope -> 1" 1 --ledger "$proc_retired" --brief "$proc_brief_short" --procedure +if [[ "$(stderr_of --ledger "$proc_retired" --brief "$proc_brief_short" --procedure)" == *"out[- ]of[- ]scope"* ]]; then pass "--procedure names the missing Brief section"; else fail "--procedure names the missing Brief section"; fi +expect_exit "Brief missing a section without --procedure -> 0" 0 --ledger "$proc_retired" --brief "$proc_brief_short" +proc_brief_plan="$TMP/proc-brief-plan.md" +{ cat "$proc_brief_short"; printf '\n### Out-of-scope\n- x\n'; } >"$proc_brief_plan" +expect_exit "--procedure --brief section only under ## Plan -> 1" 1 --ledger "$proc_retired" --brief "$proc_brief_plan" --procedure + +# 54. Ungradeable stays exit 2 and reports procedure=unchecked. +expect_stdout "ungradeable with --procedure reports procedure=unchecked" "status=ungradeable procedure=unchecked" --ledger "$noreg" --procedure +expect_exit "--procedure alone without a ledger -> 2" 2 --procedure if [[ "$fails" -ne 0 ]]; then printf '\n%d test(s) failed.\n' "$fails" >&2 exit 1 diff --git a/plugins/planning/skills/audit-answers/SKILL.md b/plugins/planning/skills/audit-answers/SKILL.md index 0c6ee325f3c..4180d480c52 100644 --- a/plugins/planning/skills/audit-answers/SKILL.md +++ b/plugins/planning/skills/audit-answers/SKILL.md @@ -102,7 +102,7 @@ Present the triaged result: the collapsed CONFIRMED block, the real questions, a | When | Skill | How it composes | |---|---|---| -| Produce the answers to validate | `/planning:interview` | Writes the Brief / general summary / ledger this consumes; the human confirmation round hands back to its stop/handoff path | +| Produce the answers to validate | `/planning:interview` | Writes the Brief / general summary / ledger this consumes; the human confirmation round hands back to its stop/handoff path. Its Step 3 recap and `--procedure` check show the user the Q&A and that the procedure ran; this skill adversarially re-validates the answers, and neither composes nor duplicates the other | | Evidence discipline each validator applies | `/planning:devils-advocate` | Its evidence-backed, no-recall, fresh-eyes discipline is cited, not duplicated | | Plan the implementation | `/planning:plan` | Downstream: the confirmed Brief feeds planning, exactly as a hand-answered interview's would | diff --git a/plugins/planning/skills/interview/SKILL.md b/plugins/planning/skills/interview/SKILL.md index 5d03cf94027..d0a793b1f37 100644 --- a/plugins/planning/skills/interview/SKILL.md +++ b/plugins/planning/skills/interview/SKILL.md @@ -367,6 +367,15 @@ Exit 1 (a row is `open` or `superseded-by-plan`) and exit 2 (ungradeable) both H **Confirmation gate (`me` and `auto`):** an empty frontier is necessary but not sufficient. Before persisting the contract or handing off, restate the shared understanding and get the user's explicit confirmation that it is reached. Do not act on the interview's output until they confirm. `lock` is exempt: invoking it IS the confirmation (its STOP-on-gap rule still applies). +**Recap and procedure check (`me` and `auto`).** Before asking for confirmation, the restatement carries a Q&A recap: one line per `Q` in the ledger's `## Open-question register`, shaped `Q : ()`, generated from the register on disk, never from the transcript, so it survives a compaction. Then run the procedure check beside the register gate, ledger only, and cite its exit code and `procedure=` field as the evidence that the procedure ran, never your own account of it: + +```bash +bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-open-questions.sh" \ + --ledger //interview-checklist.md --procedure +``` + +A non-zero exit HALTS the confirmation request; stderr names each defect (a round missing from the register, a retired row with no resolution). Fix the ledger and re-run. It checks only what a file can show. Not checked, and not implied by a green exit or by the recap: whether the Step 1 survey grounded the questions, whether the domain was classified, whether register rows were written at ask-time rather than answer-time, and whether the frontier was recomputed between rounds. `/planning:audit-answers` adversarially re-validates the answers; the recap shows the user the Q&A and the check shows the procedure ran, and neither composes nor duplicates it. A run with no register skips both. + **`me` mode tightening:** "captured as named assumption" is NOT a valid stop for a *consequential* branch. Drive it to a decision (a decision MAY be "defer to post-V1", but it must be explicit and surfaced, never silent). The stop condition is an **empty decision-tree ledger** plus the confirmation gate. Not a question count. ### Step 4. Persist the contract @@ -396,7 +405,7 @@ land (for example a repo-sweep step commit). Skip the Step 4 `--brief` cross-che PLAN.md holds `## Brief` + `## Plan` sections. `/planning:interview` writes only the Brief section; the Plan section stays empty until `/planning:plan` fills it. -**Cross-check the Brief once it exists.** Immediately after writing it, re-run the register gate with `--brief //PLAN.md`. This run proves every `deferred` and `blocked` row actually reached `### Deferred questions`, which the Step 3 run could not check because the file was not written yet. It matches on the `Q` id, so each deferred entry must lead with one. A non-zero exit means the Brief is missing a question the ledger retired: fix the Brief, do not retire the row. A general session writes no Brief and skips this. +**Cross-check the Brief once it exists.** Immediately after writing it, re-run the register gate with `--procedure --brief //PLAN.md`. This run proves every `deferred` and `blocked` row actually reached `### Deferred questions`, and that the Brief carries all seven template headings (TLDR, Goal, Constraints, Acceptance criteria, Captured assumptions, Out-of-scope, Deferred questions); the Step 3 run could not check either because the file was not written yet. It matches on the `Q` id, so each deferred entry must lead with one. A non-zero exit means the Brief is missing a question the ledger retired or a template heading: fix the Brief, do not retire the row. A general session writes no Brief and skips this. If a PLAN.md Brief exists and user chose **revise**, edit the Brief in-place. If **start fresh**, append a dated scope-change note to the top of the Brief capturing why before rewriting. Never silently overwrite, and let the commit message carry the pivot rationale. @@ -456,7 +465,7 @@ the recommendation from this summary. | A question needs something built to react to | `/prototype:explore-directions` (look and feel) or `/prototype:pressure-test` (logic, state, data shape) (if installed) | Mid-interview detour: confirm scope and checkpoint, build the throwaway, react to it, return and answer in one line | | Plan the implementation | `/planning:plan` | Reads PLAN.md Brief + explore + research findings | | Stress-test the plan | `/planning:devils-advocate` | Adversarial pass on `/planning:plan` output | -| Validate the interview's answers via agents | `/planning:audit-answers` | Fresh validators challenge each answer in the filled ledger (hand-answered or auto-accepted); only the doubtful ones return as human questions | +| Validate the interview's answers via agents | `/planning:audit-answers` | Fresh validators challenge each answer in the filled ledger (hand-answered or auto-accepted); only the doubtful ones return as human questions. The Step 3 recap and `--procedure` check show the Q&A and that the procedure ran; this re-validates the answers, and neither duplicates the other | | Record a decision that earns an ADR | `/architecture:record-decision` (if installed) | Owns ADR convention discovery, the no-convention offer-and-defer, and the write; without it the interview writes to the declared convention or defers | | Pause and resume later | `/session-flow:handoff` (if installed) | Captures session state, distinct from the Brief (mid-task pause vs pre-execution intent) | diff --git a/plugins/planning/skills/interview/context/loop.md b/plugins/planning/skills/interview/context/loop.md index b78e4b12e6a..d2a95d166ab 100644 --- a/plugins/planning/skills/interview/context/loop.md +++ b/plugins/planning/skills/interview/context/loop.md @@ -295,22 +295,22 @@ The ladder, in order: ### Gate before locking -The register is bookkeeping, so it gets a mechanical check rather than a promise. It runs **twice**, because the two things it proves become checkable at different moments: +The register is bookkeeping, so it gets a mechanical check rather than a promise. It runs **twice**, because the two things it proves become checkable at different moments. Both runs carry `--procedure`, which checks what the ledger file can show about the procedure (contiguous rounds, a resolution on every retired row) and, with `--brief`, that the Brief has its seven template headings: ```bash # Step 3, before the contract is persisted. The Brief does not exist yet. bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-open-questions.sh" \ - --ledger //interview-checklist.md + --ledger //interview-checklist.md --procedure # Step 4, immediately after writing the Brief (engineering sessions only). bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-open-questions.sh" \ - --ledger //interview-checklist.md \ + --ledger //interview-checklist.md --procedure \ --brief //PLAN.md ``` Passing `--brief` at Step 3 would name a file Step 4 has not written yet, and the gate exits 2 on a named-but-missing `--brief`, so a first-time interview would deadlock before it could persist anything. A general session writes no Brief and runs only the first form. -Exit 0 = clean; exit 1 = a row is `open` or `superseded-by-plan` (do not lock the contract, do not hand off; resolve or explicitly retire an `open` row; a `superseded-by-plan` row leaves only on the user's reply to it, see "Superseded by plan"); exit 2 = ungradeable (missing ledger, missing register, malformed row, unknown status, duplicate or gapped `Q`, or a `deferred`/`blocked` row the Brief never records), which is treated as a halt, never as a pass. On the Step 4 run a missing question means the **Brief** is incomplete: fix the Brief, never retire the row to quiet the gate. +Exit 0 = clean; exit 1 = a row is `open` or `superseded-by-plan` (do not lock the contract, do not hand off; resolve or explicitly retire an `open` row; a `superseded-by-plan` row leaves only on the user's reply to it, see "Superseded by plan"), or `--procedure` found a defect (a round missing from the register, a retired row with no resolution, or on the Step 4 run a missing Brief template heading; stderr names each one, so fix the ledger or Brief and re-run); exit 2 = ungradeable (missing ledger, missing register, malformed row, unknown status, duplicate or gapped `Q`, or a `deferred`/`blocked` row the Brief never records), which is treated as a halt, never as a pass. On the Step 4 run a missing question means the **Brief** is incomplete: fix the Brief, never retire the row to quiet the gate. **The acceptance-criteria coverage prompt is not a registered question, and not a gap in the record either.** It carries no decision, so it writes no row and never reaches this gate; a run whose only question was that prompt has no register and skips the gate rather than failing it ungradeable. The exemption is that one prompt and no other: a real question asked alongside it registers at ask-time and brings the gate into scope exactly as it always did. Step 4's "Acceptance criteria" guidance owns the prompt itself. diff --git a/plugins/planning/skills/interview/context/surface.md b/plugins/planning/skills/interview/context/surface.md index 5c2f1bfca8c..7e4b44e077f 100644 --- a/plugins/planning/skills/interview/context/surface.md +++ b/plugins/planning/skills/interview/context/surface.md @@ -151,7 +151,7 @@ The event stream sends a `ping` every 15 seconds while idle. The page re-fetches On the page surface, SKILL.md Step 3's confirmation gate runs through the page: -1. Restate the shared understanding with a `restate` op: `goal`, `constraints`, `decisions`, `acceptance`, `deferred`, and `planningOwned` (the decisions the interview hands to `/planning:plan` to make). The page's summary screen shows it with Confirm and Something's off. +1. Restate the shared understanding with a `restate` op: `goal`, `constraints`, `decisions`, `acceptance`, `deferred`, and `planningOwned` (the decisions the interview hands to `/planning:plan` to make). The page's summary screen shows it with Confirm and Something's off. The restatement carries the same register-sourced recap as Step 3: one line per `Q` (`Q : ()`), in `decisions`, generated from `round.sh export-ledger --out '/ledger-export.md'`, never from the transcript. The ledger's register lags the page until wrap-up writes the export into it, so replace its rows with the export first, as Wrap-up step 1 does, then run the Step 3 procedure check and cite its exit code. 2. Wait for a `confirm-understanding` event. `alt: confirm` whose `contentRev` equals the current restatement `rev` passes the gate: `handle` it. The server refuses a Confirm on an older `rev` as stale, so a passing event always names the current restatement. 3. `alt: off` means the gate has not passed. `note-reply` to its `text` with its `seq`, fix the understanding (re-ask or revise questions as needed), and post a new `restate`; the page shows the new one unconfirmed. diff --git a/plugins/planning/skills/interview/evals/evals.json b/plugins/planning/skills/interview/evals/evals.json index 7cb51d2ab49..bdcbdb021b8 100644 --- a/plugins/planning/skills/interview/evals/evals.json +++ b/plugins/planning/skills/interview/evals/evals.json @@ -177,14 +177,14 @@ "id": 14, "name": "register-gate-halts-before-the-contract-locks", "prompt": "/planning:interview — we've covered enough, write the brief for the audit-log retention work.", - "expected_output": "The skill runs scripts/check-open-questions.sh twice. At Step 3, before the contract is persisted, it passes --ledger ONLY — PLAN.md does not exist yet, and the gate exits 2 on a named-but-missing --brief. Then, immediately after Step 4 writes the Brief, it re-runs with --brief to prove every deferred/blocked row reached `### Deferred questions`, matched on the leading Q id. A non-zero exit halts either time: exit 1 means a question is still `open`, exit 2 means the register could not be graded (missing register, malformed row, gapped or leading-zero Q numbering, a retired row the Brief never records). Neither is a pass — the skill resolves or explicitly retires the row, or fixes the Brief, and re-runs rather than locking the contract over a failing check. A run that asked no question wrote no register and skips the gate entirely.", + "expected_output": "The skill runs scripts/check-open-questions.sh twice, citing the exit code each time. At Step 3, before the contract is persisted, it passes --ledger and --procedure but no --brief — PLAN.md does not exist yet, and the gate exits 2 on a named-but-missing --brief. Then, immediately after Step 4 writes the Brief, it re-runs with --procedure --brief to prove every deferred/blocked row reached `### Deferred questions`, matched on the leading Q id, and that the Brief carries all seven template headings. A non-zero exit halts either time: exit 1 means a question is still `open`, exit 2 means the register could not be graded (missing register, malformed row, gapped or leading-zero Q numbering, a retired row the Brief never records). Neither is a pass — the skill resolves or explicitly retires the row, or fixes the Brief, and re-runs rather than locking the contract over a failing check. A run that asked no question wrote no register and skips the gate entirely.", "files": [], "expectations": [ - "The Step 3 run passes --ledger only; --brief is NOT named before Step 4 has written PLAN.md", - "The gate re-runs with --brief immediately after the Brief is written, in an engineering session", + "The Step 3 run passes --ledger and --procedure; --brief is NOT named before Step 4 has written PLAN.md", + "The gate re-runs with --procedure --brief immediately after the Brief is written, in an engineering session", "Exit 1 halts the lock and the still-open question is resolved or explicitly retired first", - "Exit 2 (ungradeable) is treated as a halt, never as a pass; on the Step 4 run a missing question means the Brief is fixed, not the register row retired", - "A general session writing no Brief runs only the ledger-only form, and a run that asked no question skips the gate rather than failing it" + "Exit 2 (ungradeable) is treated as a halt, never as a pass; on the Step 4 run a missing question or a missing Brief template heading means the Brief is fixed, not the register row retired", + "A general session writing no Brief runs only the Step 3 form (no --brief), and a run that asked no question skips the gate rather than failing it" ] }, { diff --git a/plugins/planning/skills/interview/templates/checklist.md b/plugins/planning/skills/interview/templates/checklist.md index b02c3d2c9ac..0a79bd474ff 100644 --- a/plugins/planning/skills/interview/templates/checklist.md +++ b/plugins/planning/skills/interview/templates/checklist.md @@ -8,7 +8,7 @@ Copy into `//interview-checklist.md` (default `.work/`; - [ ] Step 1.5: Auto-detect (default action only). If intent already crisp from survey, route to direct synthesis (skip Q&A loop) - [ ] Step 2: Drive the frontier-rounds loop. Each round asks every settled-prerequisite question as one numbered set in **inline prose** (`AskUserQuestion` only via the `use_ask_user_question` opt-in; `lock` synthesizes without Q&A); order rounds by blast radius; restate decided/open after each round - [ ] Step 2 exit: Assumption sweep (`me` and `auto` with a register, the `auto` Mixed path included; not `lock`). Once the frontier is empty, a fresh-context sub-agent inventories undecided details, hidden defaults, contradictions, and hedged or free-text rows; each becomes a register row at the next `Q` or a stated fact, and an `open` row returns the run to Step 2 (`context/assumption-sweep.md`) -- [ ] Step 3: Recognize the stop condition. The open-question register grades clean (`check-open-questions.sh` exits 0; skipped only when the run asked no question at all and so wrote no register), the frontier is empty (every unknown the task depends on resolved or captured as a named assumption) AND user has confirmed the restated shared understanding (`me`/`auto`; `lock` is exempt, since invoking it IS the confirmation) +- [ ] Step 3: Recognize the stop condition. The open-question register grades clean (`check-open-questions.sh` exits 0; skipped only when the run asked no question at all and so wrote no register), the frontier is empty (every unknown the task depends on resolved or captured as a named assumption) AND user has confirmed the restated shared understanding, which opens with the register recap and cites the `--procedure` check's exit code (`me`/`auto`; `lock` is exempt, since invoking it IS the confirmation) - [ ] Step 4: Persist the contract. Engineering: write the PLAN.md Brief section with goal + constraints + acceptance criteria + captured assumptions; general: write the shared-understanding summary, never a Brief (`me` mode: persist each answer incrementally as it locks in, so a handoff at any round boundary loses nothing) - [ ] Step 5: Hand off. Engineering: recommend the next skill (exploration/research for engineering-internal; chain after `/planning:prd` for product-driven); general: deliver the summary and stop, no pipeline handoff. Both: recommend model / effort / advisor per the live-doc-sourced session-config guidance (never a pinned model name). Engineering configures the **downstream execution session** it hands off to; general/terminal configures the **current/next session**, applied now (nothing downstream exists), first surfaced early, post-survey, so it could shape the rounds themselves; here refresh it and, if raised only now, offer to re-evaluate the result under the raised config @@ -42,11 +42,11 @@ Gate twice, and a non-zero exit halts either time: ```bash # Step 3, before locking the contract (the Brief is not written yet). bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-open-questions.sh" \ - --ledger //interview-checklist.md + --ledger //interview-checklist.md --procedure # Step 4, right after writing the Brief (engineering sessions only). bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-open-questions.sh" \ - --ledger //interview-checklist.md \ + --ledger //interview-checklist.md --procedure \ --brief //PLAN.md ``` diff --git a/plugins/planning/tests/interview-defenses.test.sh b/plugins/planning/tests/interview-defenses.test.sh index 7070d3d6d3f..60527303410 100755 --- a/plugins/planning/tests/interview-defenses.test.sh +++ b/plugins/planning/tests/interview-defenses.test.sh @@ -497,7 +497,7 @@ pin_section "loop.md open-question register section is unchanged (it binds gaps "$LOOP" \ "## The open-question register" \ "## Step 3. Recognize the stop condition" \ - "208d7359e732ab49d6db93cd94f4245f468a06821768a53658fa177db110901c" + "afe8b87d549aef867adb49301d892e0814f13b98cef0c3d49f2479a92183eb77" # loop.md carries TWINS of two SKILL.md lines that are byte-pinned there: the # confirmation-gate exemption ("`lock` is exempt … its STOP-on-gap rule still applies") in # Step 3, and the `USER-RESERVED` arbiter guidance in Step 4. A twin with no pin is a @@ -524,11 +524,13 @@ pin_section "SKILL.md Step 1 section is unchanged (a preamble here reads as gove # The `scope` persist path also returns each `deferred` and `blocked` row with its arbiter # and tells the caller to stop and ask on a `Blocked:` or `USER-RESERVED` line. That carries the # never-disappears rule into a path with no Brief; the ledger and the register gate are as before. +# The Brief cross-check also passes `--procedure`, which only adds a check on the Brief's +# template headings; it retires no row and relaxes no rule. pin_section "SKILL.md Step 4 section is unchanged (the Brief's assumption machinery lives here)" \ "$SKILL" \ "### Step 4. Persist the contract" \ "### Step 5. Hand off" \ - "402e1ba5e8f1fda8446446a70e8cd11a30a18814998563155c278943b834a1ce" + "405223026ec44f285049ee3dabfd653819e84fb66f0e128aec40344b86503a3e" pin_section "SKILL.md Step 1.5 section is unchanged (auto-guard + unattended + \`lock\` routing live here)" \ "$SKILL" \ "### Step 1.5. Auto-detect (default action only)" \ @@ -559,11 +561,14 @@ pin_section "SKILL.md Action Router section is unchanged (the \`lock\` row and i "## Action Router" \ "## Stance: supportive, depth-first, opinionated" \ "0fbfcb797f606a548d8f46e1c97be4f63fdbeb33f8bfee1dd369f5d71a7ea17c" +# Re-pinned for the recap and procedure-check paragraph after the confirmation gate. It adds a +# requirement before confirmation is asked (a register-sourced recap and a cited exit code) and +# names what stays unchecked; the gate line, its `lock` exemption, and the halt rules are unchanged. pin_section "SKILL.md Step 3 section is unchanged (the confirmation-gate exemption lives here)" \ "$SKILL" \ "### Step 3. Recognize the stop condition" \ "### Step 4. Persist the contract" \ - "2d102b7a9f56349e6f105d5eab1e31581d577b06fd39834ad1a01a899784e4c3" + "8912973d4c0d98d78b60510b96d5c930a15224be21f088320940bcba318b0059" pin_section "SKILL.md \"does NOT do\" section is unchanged (the fudge prohibition lives here)" \ "$SKILL" \ "## What this skill does NOT do" \ @@ -848,6 +853,25 @@ pin "SKILL.md sweeps for assumptions before Step 3" "$SKILL" \ "**Sweep for assumptions before Step 3.**" pin "SKILL.md: a sweep that adds an open row returns the run to Step 2" "$SKILL" \ "Step 3 is reached when a sweep adds no \`open\` row" +pin "SKILL.md: the confirmation restatement carries a recap generated from the register on disk" "$SKILL" \ + "generated from the register on disk, never from the transcript, so it survives a compaction" +pin "SKILL.md: each recap line carries the question text, not only its id and resolution" "$SKILL" \ + "shaped \`Q : ()\`" +pin "SKILL.md: the Step 4 cross-check names the seven Brief template headings it requires" "$SKILL" \ + "the Brief carries all seven template headings" +pin "SKILL.md: the procedure check is cited by exit code, not by the model's account" "$SKILL" \ + "cite its exit code and \`procedure=\` field as the evidence that the procedure ran, never your own account of it" +pin "SKILL.md: a non-zero procedure exit halts the confirmation request" "$SKILL" \ + "A non-zero exit HALTS the confirmation request" +pin "SKILL.md: Step 3 names the model-judgment items the procedure check does not verify" "$SKILL" \ + "whether the Step 1 survey grounded the questions, whether the domain was classified, whether register rows were written at ask-time rather than answer-time, and whether the frontier was recomputed between rounds" +pin "SKILL.md: the recap and audit-answers neither compose nor duplicate each other" "$SKILL" \ + "neither composes nor duplicates it" +pin "audit-answers: states its relationship to the interview's recap and procedure check" "$AUDIT" \ + "neither composes nor duplicates the other" +pin "surface.md: the restate op carries the same register-sourced recap" \ + "$PLUGIN_DIR/skills/interview/context/surface.md" \ + "The restatement carries the same register-sourced recap as Step 3" pin "loop.md defines the constraint ledger row shape" "$LOOP" \ "\`- C | confirmed|inherited | | \`" pin "loop.md defines a process change" "$LOOP" \