Skip to content

Latest commit

 

History

History
307 lines (219 loc) · 45.4 KB

actionability-gate.md

File metadata and controls

307 lines (219 loc) · 45.4 KB

Actionability Gate

The contract that answers 「這個 issue 現在可不可以動?」 — how the routing tier is extracted from the ### Complexity Diagnosis field, how deferral is detected, where parked state lives, and the three-signal gate that idd-list / idd-all / idd-implement / idd-plan all consume. This file is the single source of truth; the four skills cite it and MUST NOT restate the rules in their own words.

Source: add-actionability-gate Spectra change (capability actionability-gate). Origin: issue-driven-development#298 → #316, surfaced from real dogfooding (2026-08-10 backlog routing). Round 2 (2026-08-15): /idd-verify --pr 318 falsified round 1's closed value domain against the real diagnosis corpus; the extraction rule below is the corrected one, validated on all 159 diagnoses in this repository. Round 3 (2026-09-07): the round-2 verify found the same failure shape on the third signal — the ### Blocking reader had been written against an unvalidated producer assumption — and found that filing not-yet-diagnosed issues under Parked misdescribed 11 of 14 open issues. Both are corrected below, each with its own frozen corpus or live-backlog measurement.

The incident this exists to prevent

On 2026-08-10 a real 22-issue backlog was routed by /idd-list. Of the 11 diagnosed issues, 8 parked/deferred/blocked ones were reported as "Actionable now". Two of them (#131, #200) carried a defer ruling the user had personally made on 2026-07-07 — following the routing would have re-opened work the user had decided to park.

The failure was silent. The table was syntactically correct, well-formatted, and carried no warning.

Root cause, in two layers

1. Mutable state in an immutable artifact

### Complexity lives in a Diagnosis comment, and Diagnosis comments are append-only (see rules/append-vs-modify.md). But "is this issue parked?" is mutable — a trigger firing should un-park it. Writing deferral qualifiers (Simple when triggered, **Spectra when triggered**(Layer 2: …)) into a frozen field created a value that could never be corrected in place, and every consumer's parser assumed the field carried one kind of information. Three consumers each invented an incompatible narrowing:

Consumer private narrowing result on Simple when triggered
idd-list ([A-Za-z-]+) silently truncated to Simple → routed a parked issue to /idd-implement
idd-all (.+?) + via-split non-tier string; matched no dispatch row and was not UNKNOWN
idd-implement same same

idd-all's UNKNOWN → abort safety net structurally could not catch this: it fires only when the regex fails entirely, never when it matches an out-of-domain value.

IDD already knew the right shape: ### Blocking is mutable, so it lives in the issue body and is maintained by idd-update. This contract applies the same reasoning to deferral.

Correction to the round-1 narrative. Round 1 claimed #136's Diagnosis comment read bare Spectra while its body read Spectra when triggered (parking lot). The "bare Spectra" was the truncating regex talking: the comment actually reads **Spectra**(Layer 2 + Layer 3 if/when triggered):… — the deferral was hiding inside the parenthetical, exactly where a suffix-only scan would miss it. The two-signals-drift argument still stands (#37, #131, #200), but #136 is evidence for scanning the whole value, not for state drift.

2. The round-1 fix over-corrected

Round 1 declared a closed value domain: the value had to be exactly one of the four tiers, optionally followed by via <source>. That rejected the producer's normal writing style. On the real corpus of 159 diagnoses in this repository:

Shape (mutually exclusive, first line of the value) Count Share
bare tier (Plan) 45 28.3 %
decorated bare tier (**Plan**) 37 23.3 %
decorated tier + same-line rationale (**Spectra** — Layer 2(…)) 41 25.8 %
plain tier + same-line rationale (Spectra(opt-out → 直接 propose)) 25 15.7 %
tier + via <source> (Plan via hard-gate) 1 0.6 %
deferral vocabulary present 9 5.7 %
no ### Complexity section 1 0.6 %

71.7 % of values are not a bare tier. Round 1 stripped decoration before matching, so it would still have refused every rationale-bearing value: 66 of 159 (41.5 %) wrongly withheld — worse than the 29 % misroute rate of the truncating regex it replaced (37 decorated values unmatched + 9 deferral values passed). Both figures are reproducible from the frozen fixture. That was verify finding CRITICAL-2 on PR #318, and it is why round 2 exists. The counts above are reproducible from the frozen fixture, not from memory.

The extraction rule — prefix tier, whole-line deferral scan

idd_parse_complexity applies these steps, in this order:

  1. Take the first non-blank line under the ### Complexity heading. The heading is anchored at line start; a ``` or ~~~ fence is not a section; the section ends at the next heading of the same or higher level; a deeper #### line is skipped.
  2. Strip leading and trailing markdown decoration (**, `, _). Decoration is presentation, not value.
  3. The stripped value must begin with one of Simple, Plan, Spectra, SDD-warranted as a whole word — longest match first, so SDD-warranted is tried before anything that could be its prefix, and a word boundary keeps Simpler from reading as Simple. That leading word is the tier. Everything after it — same-line rationale, a parenthetical, an em-dash note, a via <source> provenance suffix (Plan via Layer V, Spectra via hard-gate (sdd_bias)) — is legal and ignored for tier extraction.
  4. Scan the entire first line — not only the text after the tier — for deferral vocabulary: when triggered, parking lot, deferred, 暫緩 (case-insensitive; space, hyphen and underscore tolerant, so Parking-Lot and if/when triggered both count). A hit withholds the issue under its own reason, even though the tier prefix is valid.
Outcome exit stdout stderr
routable 0 the leading tier —
value does not begin with a tier (移入 discussion list) 3 — unparseable-complexity: <raw line>
no ### Complexity section 4 — missing-complexity
tier valid, deferral vocabulary present (Plan when triggered) 5 — deferral-marker: <raw line>

Two ordering consequences are deliberate:

  • Tier check precedes the deferral scan. 移入 discussion list(暫緩) is exit 3, not 5 — a value with no tier is a data defect first, whatever else it says.
  • Only the first line is scanned. Scanning the whole section would add two false positives on the corpus (#154 "remove deferred caveat", #137 "reuse existing deferred enum") and catch nothing new. The producer's deferral intent, when written into this field at all, sits on the value line.

On every non-zero path nothing is written to stdout. A consumer that captured a tier there could route on it — which is the incident.

Corpus validation — the regression that keeps this honest

The rule was derived from and validated against every diagnosed issue in this repository (snapshot 2026-08-15, 225 issues fetched, 159 with a ## Diagnosis comment), and that validation is a frozen regression test, not a one-off check: scripts/tests/actionability-gate/fixtures/corpus-complexity.json, asserted by scripts/tests/actionability-gate/test.sh.

exit count issues
0 routable 149 Plan 69 · Simple 41 · Spectra 39
5 deferral 9 #131 #136 #140 #143 #144 #145 #146 #157 #200
4 missing 1 #273
3 unparseable 0 —

| — no ## Diagnosis comment at all | 66 of 225 | every one is exit 4 (complexity-missing) — see the undiagnosed group below |

Every one of the 159 routes as hand-reviewed; 0 false positives. No Diagnosis comment was rewritten and no label was backfilled to get there — zero migration is a claim about this corpus, and the test is what makes it falsifiable. Read it for what it says: no existing diagnosis needs rewriting. It does not say the backlog's actionability distribution is unchanged — on the 2026-09-07 open backlog only 2 of 14 issues were routable, because 11 had never been diagnosed. That is why the display distinguishes undiagnosed from parked.

Signal 3 has its own frozen corpus — read it for what it proves. scripts/tests/actionability-gate/fixtures/corpus-blocking.json holds every ### Blocking section in the bodies of all 238 issues (55 rows, first section per issue — 54 sections under CommonMark, because #290's heading sits below an unclosed fence; hand review: 48 empty, 7 real blockers), each row with its original body and the hand review's verdict (semantic_empty). The test asserts what this paragraph claims — 48 / 7 semantically, the rule disagreeing with the hand review on exactly #1, 54 of 55 CLOSED, and each frozen section equal to what the extractor returns for its body. Feeding the bodies did not make the rule's verdicts more discriminating (the round-3 and round-4 readers agree on all 55); what it buys is that section cannot drift from what the reader actually judges. The reader agrees with the hand review on 54 of the 55; row #1 is an accepted false positive (an informational second bullet). 54 of the 55 issues are CLOSED, which the gate never evaluates — on the 2026-09-07 open backlog signal 3 decided one issue (#316 itself). So the corpus is a legitimate sample of producer style and a regression baseline; it is not proof of gate correctness on the live backlog, and #336's acceptance bar is the semantic truth (48 / 7), not the fixture's expectations. Round 2 shipped idd_blocking_section without any of this and, reading the original bodies, withheld 30 of the 48 — #316's own - (none — 可動) among them (counts measured under a UTF-8 locale). Two rival rules were measured on the same rows and rejected; their text and FP/FN counts are recorded in the helper. The placeholder rule is environment-independent; the rest of the reader is not, on purpose. Multibyte separators are alternations, never inside a bracket expression (under LC_ALL=C the round-3 rule flipped both directions), and the two placeholder greps run as LC_ALL=C command grep — C because [[:space:]] classifies U+3000 and NBSP differently per locale, command because skills source the helper in Claude Code's zsh, where grep is a ugrep shell function that ignores LC_ALL. The test pins the value (- none  is a blocker) under both locales and under a shadowing grep function. The bullet detector, the deferral grep and the awk section extractor still follow the environment — the locale and the platform: macOS's C library classifies NBSP as blank under a UTF-8 locale and glibc does not, while U+3000 is blank to grep on both (measured round 7 on macOS and on Ubuntu 24.04 with GNU grep 3.11, gawk and mawk). Measured directions: pinning the deferral grep to C makes Simple when<U+3000>triggered routable everywhere, and pinning the bullet detector to C loses a real -<U+3000> blocker after a placeholder — both refused by direction pins written with U+3000 so they hold on both platforms. The NBSP forms already take the C-locale path on Linux: Plan when<NBSP>triggered routes there, and a -<NBSP> blocker after a placeholder is not read; the test records the platform's value. (Round 6 pinned the NBSP forms; CI on ubuntu-latest failed from c006c8b on, and the round-6 verify, run on macOS only, did not see it.) Pinning the awk section extractor to C moves the measured NBSP shapes in both directions (round 7, nine shapes, against markdown-it and pandoc's CommonMark reader): toward withholding on an NBSP-indented ``` and on ##<NBSP>Next, toward clearing on `###Blocking`, on an NBSP-indented closer inside a fence and on an NBSP-led line that leaves a fence unclosed, and on `### Blocking` it clears a blocker markdown-it reads and CommonMark does not. Round 6 judged this pin harmless from two shapes; that was wrong. The `### Complexity` value's trim follows the environment too: `Plan` routes as `Plan` on macOS under UTF-8 and is unparseable under C and on Linux. All four stay as they are — structural rules are frozen (below) — and which environment and which oracle are canonical per construct is #336.

Risk posture — the label is primary, the vocabulary is a net

Deferral vocabulary is a high-precision, low-recall heuristic. It is NOT a closed enumeration and MUST NOT be "completed" by analogy — but it must not grow casually either. The two failure directions are asymmetric:

Failure Consequence Posture
miss (deferral written in words the scan does not know) the issue looks actionable — the pre-#298 behaviour, no worse acceptable; the parking-lot label is the human backstop
false positive (routable issue withheld) a hard stop on real work, with a reason that reads as authoritative unacceptable; keep the vocabulary conservative

So the rule for adding a term: corpus evidence of zero false positives, recorded in the regression fixture. Resemblance to an existing term is not evidence.

Signal 3 (### Blocking) has a different posture, and the difference matters. It is a list field written by idd-update's template - {blocker 1, or "(none)"}, model-filled, with 35+ spellings for "no blocker" in the wild. The reader therefore (a) judges each bullet — any non-placeholder bullet makes the section non-empty, so - (none) followed by - 等 … is a blocker — and (b) recognises a placeholder by its leading token (none · n/a · 無, optionally bulleted, decorated or parenthesised, followed by end of line, a closing paren or a separator — a full stop is not one, so - None. Waiting on X is a blocker), so - (none — 可動) is empty while - none of the reviewers replied yet is not. Its failure directions are not symmetric with signal 1's: a miss here is not "pre-#298 behaviour", it is a regression of #84's blocked-state surfacing; a false positive is the hard stop the table above calls unacceptable. The rule for misses, stated as a rule (both directions accepted, documented, pinned by test): the leading token decides the bullet, and only - / * bullets or the section's first line are judged. Fail-open: a placeholder token followed by a clause (- (none) but actually blocked by #86) reads as empty, and a real blocker written after a placeholder as an ordered-list item, + bullet, blockquote, table row, #### line or bare paragraph is a continuation and is not read. Fail-closed: a lead-in sentence before the first bullet is judged as the first line and reads as a blocker. The corpus has none of these shapes. The bullet class is not widened: the corpus is insensitive to it (0 of 55 rows change), so leaving it narrow is a design judgment — widening enlarges the fail-closed side — not a measured result. Only the first ### Blocking section of a body is read. Whether this field should be regex-read at all — producer contract or model judgement, first-vs-last section, and IC_R011 (c) semantics — is #336; do not extend the rule by analogy before that is decided. Fences follow CommonMark's two visibility rules, which is what GitHub renders: a fenced example is never a section, and an unclosed fence runs to the end of the body, so a section below it is not read (live instance #290 — GitHub shows its ### Blocking as code). The reader is line-based and departs from markdown-it or CommonMark in the known ways below — known, not exhaustive — each measured against markdown-it-py (and, from round 7, pandoc's CommonMark reader) and pinned by test as a documented divergence: fence length is not compared (a ```` opener is closed by the first line — either direction); indentation is not checked (a indented four or more spaces, or by a tab, opens a fence here and can hide a real blocker — fail-open); a ``` line with trailing text closes a fence here (either direction); an opener whose info string contains a backtick opens a fence that never closes (fail-open); a closer indented four or more spaces inside a fence closes it here (either direction); a fence opened on a list-item line is not seen, and its indented closer then opens one (fail-open); an HTML comment holding a fake ### Blocking is read (either direction). Round 7, measured under C.UTF-8 on macOS (the awk follows the locale and the platform — on glibc + gawk the NBSP shapes behave as under C and `### Blocking<U+3000>` is read; the pins follow the platform awk): an NBSP-indented ``` opens a fence (fail-open); `###X` and `##X` count as headings, so `###Blocking` is read (either direction) and `##Next` ends the section early (fail-open); trailing NBSP after the heading text is read and trailing U+3000 is not — here the oracles disagree, markdown-it strips both and CommonMark neither; an ATX heading indented one to three spaces, or with a closing sequence, is not read (fail-open). A fence inside a blockquote is not a divergence. On the snapshot of 2026-09-08 (243 bodies + 164 Diagnosis comments) the reader and markdown-it agree on section presence, content and verdict for all 217 sections, and no body of the 2026-10-06 snapshot contains NBSP or U+3000. Anyone who can edit the body can also delete a blocker outright, so for text the author wrote the list is an honesty statement; third-party text copied into a body (`idd-issue --from-discussion`) is held back only by its per-line `>` quoting, a prose rule today (#372). Changing any of these shapes is a structural change and is frozen (below). A body with an unclosed fence is a producer defect to detect and surface — today the reader reads it silently as "no section"; surfacing it is #336 — not something the reader patches around: round 4's "odd marker count → stop tracking fences" changed no measured verdict and exposed fenced templates as real sections, and the "still open at EOF" variant failed the same way. Change gate for this rule — the normative text is spec R9; in short: (i) a vocabulary rule (placeholder tokens and terminators, deferral vocabulary, and the locale of the greps that apply them) moves only toward withholding, unless the change is a revert or every element it adds is required by a measured corpus row the commit names; (ii) a structural rule (heading, fence, bullet and section boundaries, the Complexity trim, and the locale of the matchers that implement them) is frozen until a requirement names the oracle it converges on and the measured shapes it changes (#336). The corpus does not guarantee coverage of adversarial or edge shapes — it samples how the producer writes — so a gate keyed on corpus rows alone cannot judge a structural change. Round 6's property for (ii) ("toward the markdown_it render, never toward clearing on the corpus, the live snapshot or a direction pin") gave no determinate answer and is withdrawn; so is round 5's third form.

Mentions are not declarations — and the scan cannot tell them apart. Plan(把 parking lot 的文件敘述收斂) and Simple, no longer deferred both trip the deferral scan. The corpus has zero such values, and negation logic would open a new miss surface, so the vocabulary is left as is; the operator sees the raw line and the remedy for this class is to keep meta-discussion out of the value line.

A documented miss, kept honest. #128's Diagnosis reads Plan(觸發表)+ 未決 UX 軸 → **移入 discussion list**; its deferral ("blocked-by #86") lives only in Strategy prose. Under this rule it routes as Plan. That is the designed outcome — the gate does not parse prose — and the fixture pins #128 as actionable rather than pretending a marker exists. If it should be withheld, a human applies the label.

Where deferral state lives

State Home Mutable? Maintained by
Complexity tier ### Complexity in the Diagnosis comment no (append-only) idd-diagnose
Deferral / parked parking-lot label yes a human — see below
External blocker ### Blocking in the issue body yes idd-update

idd-diagnose SHALL NOT apply, remove, or derive the parking-lot label on the issue it is diagnosing. The label is a human ruling, and it is settable after the diagnosis was written. (Scope: the IC_R011 checkpoint that idd-diagnose runs in Step 3.6 may attach parking-lot to a newly filed sister issue when the user classifies it (b) infeasible / (c) blocked-on-external — that is a human classification landing on a different issue, and since 3.1.0 it means the new issue is born parked. blocker:infeasible / blocker:waiting were never created in any repo and are retired everywhere IC_R011 is stated.) Empirically the two signals disagree: of 11 diagnosed issues sampled on 2026-08-10, only 5 had the qualifier and the label in agreement. #37 was **Spectra** with the label applied later by a human; #131 and #200 had the qualifier with no label. They are not two spellings of one fact — they are two facts, and deriving one from the other would delete the human's ability to park an issue whose tier is perfectly clear.

The producer's rule is therefore simple: write the tier clearly, rationale welcome; if the issue is on hold, say so with the label, not in this field. The vocabulary scan exists for the 159-issue past, not as an invitation.

The three-signal gate

An issue is actionable only when all three signals are clear. Any one of them withholds it.

  ### Complexity non-routable (exit 3 / 4 / 5)  ─┐
  parking-lot label present                     ─┼─→  not actionable
  ### Blocking section non-empty                ─┘

  actionable  ⟺  none of the three holds

Reason vocabulary — a CLOSED enumeration

Exactly five values. Do NOT add a sixth by analogy:

Reason Fires when What it asks of a human
complexity-unparseable section present, value does not begin with a tier fix the Diagnosis — this is a data defect
complexity-missing no ### Complexity section run /idd-diagnose — the diagnosis never judged complexity
complexity-deferral-marker tier valid, deferral vocabulary present nothing to repair — this is a legitimate parked state; apply the label if it is not already there
parking-lot-label the issue carries the parking-lot label nothing — a human parked it
blocking-nonempty the ### Blocking section of the body is non-empty wait, or clear the blocker via idd-update

The three complexity reasons are kept distinct because the human response differs. Collapsing them into one would tell the operator to "fix" a value that is not broken.

What is deliberately NOT a signal

The - [~] disposition marker inside a Diagnosis ### Strategy checklist is NOT an input to this gate. It has an existing consumer — idd-close's checklist gate, where it means "this checklist item was deliberately skipped at close time". That is a per-item, close-time disposition. This gate asks a per-issue, routing-time question. Feeding one into the other answers a different question than the one being asked, and would collide with idd-close's established semantics.

⚠ Anyone editing - [~] handling must check idd-close first. Treating it as unused because routing ignores it will break the close gate.

The Diagnosis type — a diagnosed meeting drops the Complexity signal only (#383)

A meeting issue is a deliberation record, not a code task. Its spec (openspec/specs/meeting-issue-type/spec.md) forbids a Simple / Plan / Spectra verdict, so a meeting Diagnosis legitimately has a ### Complexity line that is a sentence (exit 3) or no section at all (exit 4). Before #383 the gate had no way to know that: every meeting issue came back complexity-unparseable or complexity-missing, and idd-all / idd-plan told the operator to "fix the Diagnosis" that was correct.

The type is therefore a gate input, and it comes from the latest trusted Diagnosis — the same author-filtered comment (OWNER / MEMBER / COLLABORATOR) the Complexity signal is read from. idd_diagnosis_type "$LATEST_DIAGNOSIS" (contract 4 in scripts/lib/actionability.sh) reads the first line of its ### Type section with the same section reader and takes the type word by the five steps of the spec: meeting(…) and **meeting** are meeting, bug / feature / refactor / docs return themselves, anything else is unknown, and an empty input — no trusted Diagnosis — is none. /idd-diagnose writes ### Type by template, so every existing meeting Diagnosis already carries it.

Not the issue label, not the issue body. Verify rounds 1–4 resolved the type from a type label or, without one, the issue body's ## Type. The body is editable by the issue author at any time, and on a public repository that is anyone. An author could switch off the Complexity signal after a maintainer's diagnosis (r4 #19), or flip the type after implement so that idd-all skipped verify and the push (r4 #35); and each round found another way to hide a ## Type from a markdown reader. Reading the type from the trusted Diagnosis closes both, together with one rule on the producer side (r5): the author filter only says who posted the Diagnosis, not where its ### Type came from, and /idd-all runs /idd-diagnose on every run. So /idd-diagnose Step 1 is instructed to write meeting only when meeting is the issue's only IDD type label, or for a body ## Type: meeting whose issue author is OWNER / MEMBER / COLLABORATOR — the same set the Diagnosis filter trusts — and never to infer meeting from content. Setting a label by hand needs triage or higher; a label that an issue form, template or workflow applies automatically was configured by a maintainer, so it carries the maintainer's intent. Under that rule an issue author outside the set cannot make an issue a meeting by editing it; a maintainer adds the label instead. Three limits: the rule is an instruction the model follows, not a code check; it governs Diagnoses written by 3.4.0 or later (an earlier /idd-diagnose copied any author's body ## Type); and it covers the four routing consumers — idd-close's meeting branch is #385. A code backstop and the older Diagnoses are tracked in #397. A maintainer who relabels an issue re-diagnoses it — the Diagnosis is the record the gate judges, for type as for Complexity.

idd_actionability_verdict takes it as an optional --diagnosis-type <value>:

--diagnosis-type Complexity signal parking-lot label ### Blocking
omitted, or bug / feature / refactor / docs / unknown / none evaluated exactly as before — the frozen corpora run without the flag and with every one of these values, and their verdicts are unchanged evaluated evaluated
meeting --complexity-exit is still required and validated (0 / 3 / 4 / 5), but it produces no reason evaluated evaluated
passed empty, value-less, or out of domain exit 2 (misuse) — —

meeting can only come from an existing trusted Diagnosis, so an undiagnosed issue stays complexity-missing → undiagnosed whatever its body says (the hole round 1 found). A diagnosed meeting issue is withheld only by the two signals whose meaning holds for it — a person parked it, or it waits on something — and the reason vocabulary above stays closed at five values. The consumers then dispatch on TYPE=meeting before any tier row: idd-all sends it to the meeting-adapted /idd-plan when attended and stops at diagnosed with an Action item when unattended; idd-plan writes the ## Meeting Plan; idd-implement refuses with a meeting-specific message; idd-list suggests /idd-plan or /idd-close. Every gate block prints the Diagnosis type on its machine line (... REASONS=%s TYPE=%s), and every later idd-all step that needs the type (the branch unwind, verify, push, the report) reads it from the trusted Diagnosis again — never from the body.

There is no meeting sentinel in Complexity. Writing meeting into the ### Complexity line would be a verdict the meeting spec forbids, and every existing meeting Diagnosis would have to be rewritten — against this gate's own "existing diagnoses require no migration". ### Type already records the type.

Default on non-routable Complexity — conservative, and always surfaced

A consumer whose ### Complexity value is non-routable for any reason SHALL report the issue as not actionable and SHALL surface the original unmodified line to the operator — except for a diagnosed meeting issue (its latest trusted Diagnosis records type meeting), whose Complexity signal the gate does not evaluate (previous section). An issue with no trusted Diagnosis is not excepted, whatever its body says.

Three things are forbidden:

  • SHALL NOT silently truncate a non-routable value to its tier prefix. That truncation is the 2026-08-10 incident — and on exit 5 the prefix is right there, well-formed, which is exactly why the helper refuses to print it.
  • SHALL NOT downgrade a non-routable value to any tier, including Plan. Plan is still actionable; downgrading routes a parked issue into /idd-plan.
  • SHALL NOT abort the enclosing listing operation. One bad value must not suppress the other issues — a surfacing tool that dies on one malformed row is worse than one that flags it. (The set -e call shape below is what makes this hold in practice.)

This mirrors the ### Conflict Class contract in parallel-orchestration.md, which defaults an absent or unparseable value to D_diagnose_first and requires the fallback be printed. The two fields are orthogonal (one classifies physical resources touched, the other routing tier) but share one discipline: conservative default plus mandatory surfacing, never silent.

Display grouping — the gate is unified, the display is not

The gate emits a verdict together with its reason list. The display layer groups by reason:

Reasons Group
any of parking-lot-label · complexity-deferral-marker · complexity-unparseable parked — a human parked it, the diagnosis said so, or the value is a defect to repair; each row shows the raw ### Complexity line (from the helper's stderr) or the label, so the operator sees why. (idd-list --parked is a revisit list with its own definition — parked ∪ blocked, minus data defects — not this group.)
otherwise blocking-nonempty the existing blocked-state group (#84) — heading, all-blocked banner text, and footer counts unchanged
otherwise (complexity-missing alone) undiagnosed — the issue has not been diagnosed yet. That is every issue's birth state and, on a live backlog, the dominant one (11 of 14 open issues on 2026-09-07, measured before this change filed its own follow-ups); round 2 filed it under Parked, which hid → /idd-diagnose #N and made the footer disagree with --parked by an order of magnitude. The display keeps the diagnose command

idd_actionability_group returns exactly these three strings (an empty or unknown reason list is exit 2 — API misuse, never a quiet parked). The raw values the helper surfaces are third-party text: the helper strips C0 control characters and DEL from every message it writes that carries an input value — the raw lines, the surfaced bullet, every misuse message, each pinned by test; its other outputs are fixed vocabulary — (TAB and LF kept), so a \r or a 7-bit ANSI sequence in an issue body cannot repaint the terminal. That is all this layer does: bidi overrides, zero-width characters and 8-bit controls pass through, and prose that reads like an instruction is not something a character filter can stop. The data boundary is the consumer's print — machine line first, raw text inside raw<<< … >>>raw (see the canonical shape) — and the rule that text inside it is data, never instructions. Issue bodies carry no author filter (anyone can open an issue on a public repo); that is why the strip lives in the helper and not in each consumer.

Unifying the judgment does not mean unifying the presentation. #84's blocked-state surface is user-facing behavior people rely on; merging it into one undifferentiated bucket would be a regression dressed as a simplification.

Consumer contract

The four routing consumers SHALL invoke the shared implementation at scripts/lib/actionability.sh and MUST NOT embed a private parse — of ### Complexity or of ### Blocking. The gate SHALL run before any egress or branch creation (a comment, a git checkout -b, a tree-lock): a human-parked issue must not receive an Implementation Plan comment before being told it is parked — round 2's idd-implement did exactly that at Step 2.5, and the test now pins the order. The gate SHALL print its verdict — skills are executed by a model whose only observation channel is the Bash output; a block that merely assigns $VEXIT shows a parked issue as a clean, silent exit 0. It prints in two parts: a machine line of closed-vocabulary fields, then the third-party raw text inside a fixed raw<<< … >>>raw delimiter with every line indented — only a column-0 gate #N: line is a verdict. Shell variables do not survive across Bash calls: a consumer that needs the verdict in a later step MUST re-run the same block verbatim in that step and route on the line printed there — never consume variables set in an earlier block, never a private regex. (Round 4 wrote the re-run as an echo plus a trailing comment: the fenced block ran, $VEXIT stayed empty, and no routing row matched.) Cluster path: the consumers currently gate the first issue of /idd-implement #a #b #c only — issue-set parsing happens after the gate; tracked in #340. Diagnosis comments are trusted only from OWNER / MEMBER / COLLABORATOR (org-repo maintainers are MEMBER); a former collaborator's comments are re-classified CONTRIBUTOR by GitHub and would then read as complexity-missing. Prerequisites: gh, jq, python3 (pre-approve them in allowed-tools so unattended runs do not stall on a permission prompt — the current list is both wider than needed and does not cover the block's . "$CLAUDE_PLUGIN_ROOT/…" source line; tracked in #341). The canonical call shape, in full, is:

# 0. Missing helper → fail loud, name the path. Never fall back to a private regex.
. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || {
    echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 regex" >&2
    exit 1
}

# 0. Issue numbers enter a REST path: digits only, or refuse. (A `?per_page=1`
#    smuggled in would silently truncate the fetch.)
case "$N" in ''|*[!0-9]*) echo "FATAL: non-numeric issue number: $N" >&2; exit 1 ;; esac

# 1. Latest Diagnosis comment — PAGINATE, and TRUST ONLY repo-affiliated authors.
#    `gh issue view --json comments` returns only the OLDEST 100 comments, so on
#    a long issue the latest diagnosis is exactly the one that gets dropped
#    (`--paginate --jq` emits one array per page; `jq -s add` folds them). On a
#    public repo any account can append a `## Diagnosis`; without the author
#    filter that comment would become signal 1. The fetch and the fold are
#    captured separately (the fold, `jq -s | python3`, is still one pipeline):
#    in a `gh … | jq -s` pipe a failed fetch hands jq empty input, jq still
#    prints `[]`, and the failure reads as "no diagnosis" — the wrong reason;
#    a failure on page 2 or later routed on an incomplete comment set.
PAGES=$(gh api "repos/$GITHUB_REPO/issues/$N/comments" --paginate \
    --jq '[.[] | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") | {body}]') \
    || { echo "FATAL: gate #$N: comment fetch failed — gate not evaluated" >&2; exit 1; }
LATEST_DIAGNOSIS=$(jq -s 'add // []' <<<"$PAGES" | python3 -c '
import json, sys, re
cs = json.load(sys.stdin)
ds = [c for c in cs if re.search(r"(?m)^## Diagnosis", c["body"])]   # line-anchored: quoted/inline mentions do not count
print(ds[-1]["body"] if ds else "")') \
    || { echo "FATAL: gate #$N: comment fold failed — gate not evaluated" >&2; exit 1; }

# 2. The other two signals — labels, and the body's ### Blocking section (via the helper).
ISSUE_JSON=$(gh issue view "$N" --repo "$GITHUB_REPO" --json labels,body) \
    || { echo "FATAL: gate #$N: issue fetch failed — gate not evaluated" >&2; exit 1; }
HAS_PARKING=$(jq -r 'if any(.labels[]; .name == "parking-lot") then "yes" else "no" end' <<<"$ISSUE_JSON")
BLOCK_LINE=$(idd_blocking_section "$(jq -r '.body // ""' <<<"$ISSUE_JSON")")
if [ -n "$BLOCK_LINE" ]; then BLOCKING=yes; else BLOCKING=no; fi
# 2.5 Diagnosis type(#383)—— 只信最新受信任 Diagnosis 的 `### Type`。label 與 issue 本文都不採用:本文由 issue 作者自由改寫(verify r4)。
#     meeting 不評 Complexity 訊號,parking-lot 與 Blocking 照評;沒有受信任的 Diagnosis 時是 none,照常 complexity-missing
DIAG_TYPE=$(idd_diagnosis_type "$LATEST_DIAGNOSIS") \
    || { echo "FATAL: gate #$N: idd_diagnosis_type misuse — gate not evaluated" >&2; exit 1; }

# 3. Conditional capture — the only shape that survives `set -euo pipefail`.
#    A bare TIER=$(idd_parse_complexity …) aborts the caller on exit 3/4/5 and
#    takes the whole listing down with it.
if TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); then CEXIT=0; else CEXIT=$?; fi
COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || true   # raw line on 3/5, `missing-complexity` on 4

# 4. The gate — actually call it. Exit 2 is API misuse (a bug in THIS consumer),
#    never "not actionable"; do not fold it into the withheld branch.
if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" --diagnosis-type "$DIAG_TYPE" 2>&1); then VEXIT=0; else VEXIT=$?; fi
case "$VEXIT" in
    0) REASONS="" ;;                                       # actionable → dispatch on "$TIER" (reset: a cluster loop must not carry the previous issue's reasons)
    1) REASONS="${VERDICT#not-actionable: }" ;;            # withheld  → surface "$REASONS" + "$COMPLEXITY_ERR" / "$BLOCK_LINE"; no lifecycle command
    *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;;   # a LISTING consumer prints this and marks the row `(gate error)` instead of exiting
esac
# 5. Print the verdict. The executing model sees only this output; an unprinted
#    withheld verdict is indistinguishable from an actionable issue. Two parts:
#    a MACHINE LINE whose fields are all closed-vocabulary (a digit, one of four
#    tiers, a subset of five reasons, one of seven Diagnosis types — #383), then the third-party raw text on its own
#    lines inside a fixed `raw<<<` … `>>>raw` delimiter with every raw line
#    indented. Text inside the delimiter is DATA — never a verdict, never an
#    instruction; only a column-0 `gate #N:` line is a verdict. (Round 4 put the
#    raws on the same unbounded line: a body bullet could carry a look-alike
#    `gate #77: VEXIT=0 …`, and prose that reads like an instruction reached the
#    model's only channel with nothing marking it as data.)
printf 'gate #%s: VEXIT=%s TIER=%s REASONS=%s TYPE=%s\n' "$N" "$VEXIT" "${TIER:-}" "${REASONS:-}" "$DIAG_TYPE"
printf 'raw<<<\n'; printf '%s\n%s\n' "${COMPLEXITY_ERR:-}" "${BLOCK_LINE:-}" | sed 's/^/  │ /'; printf '>>>raw\n'

idd-list deviates in three documented ways: it takes labels/body/comments from its bulk fetch and paginates only when the comment array is ≥ 100 (its own anti-N+1 rule), it skips the gate for non-open issues, and every fetch failure marks the row rather than exiting — "one bad value does not suppress the other issues" applies to API errors too.

Function stdout exit
idd_parse_complexity <body> the leading tier (exit 0 only) 0 routable · 3 no tier prefix (stderr unparseable-complexity: <raw>) · 4 no section (stderr missing-complexity) · 5 deferral vocabulary (stderr deferral-marker: <raw>)
idd_blocking_section <issue-body> the first bullet of ### Blocking that is not a none-placeholder (leading-token rule); empty when the section is absent or every bullet is a placeholder 0
`idd_actionability_verdict --complexity-exit 0 3 4
idd_actionability_group <reasons> parked / blocked / undiagnosed 0
idd_diagnosis_type <latest trusted Diagnosis> (#383) bug / feature / refactor / docs / meeting / unknown; none for an empty input 0 · 2 not exactly one argument

Only replacing the parser is not a fix. Round 1 shipped a complete gate, 66 green assertions, and zero consumers calling idd_actionability_verdict (verify CRITICAL-1 on PR #318). A consumer that reads $TIER and never asks the gate has re-created the incident with a nicer parser.

Malformed invocation fails loud (exit 2), never defaults to actionable. An unanswered signal treated as "clear" would re-open the exact hole this contract closes. A flag with no value is a named exit-2 error, not an infinite loop (verify H1).

When the shared implementation is missing, a consumer SHALL fail loudly and name the path — never fall back to a private parse. A silent fallback would restore the three-way divergence this file exists to prevent.

Adversary discipline (audit lenses)

Per .claude/rules/attribute-assessment.md, evaluate this interface through three lenses:

Lens Risk Mitigation
Scoundrel Smuggle deferral vocabulary after the via separator (Simple via when triggered) so a suffix-stripping parser yields a legal tier The scan covers the whole line; the suffix is not an escape hatch (fixture row 906). And in the other direction — a scoundrel who wants an issue actionable has simply declared it so under their own name in the audit trail; the label, which the gate reads independently, is the human's veto
Lazy Developer Skip a signal argument and let the gate assume "clear"; or read $TIER and skip the verdict Every argument is required and validated; missing or non-boolean input returns exit 2 with a named cause. The consumer contract above makes the verdict call part of the canonical shape, and the #318 verify history is the reminder of what happens without it
Confused Developer Answer "does this issue block others?" when asked "is this issue blocked?"; or treat exit 5 as a value to correct The flag is named --blocking-section, pointing at the artifact section being read rather than at a relationship. The three complexity reasons are distinct precisely so that complexity-deferral-marker reads as "parked", not "broken"

Out of scope

  • Evaluating whether a trigger condition has fired. Trigger conditions are prose propositions about future world state (「等 ≥3 instances」「首次 trace-stale 實害事故」). Deciding whether one has come true requires a human observing the world; it is not derivable from the repo. This gate knows only that someone declared the issue parked, never whether the parking is still warranted. That is an epistemic boundary, not a missing feature.
  • Bringing parked issues back into view. Nothing here re-surfaces an issue whose trigger has fired — tracked separately as #310 (idd-list --parked is the manual review path). This contract makes parked issues more thoroughly hidden, which makes that gap more urgent, not less.
  • Deferral expressed only in prose (Strategy bullets, Blocking rationale, comments) — see #128 above. The label is the mechanism for that.
  • - [~] handling — belongs to idd-close, see above.

See also

  • parallel-orchestration.md — the ### Conflict Class contract this one mirrors; orthogonal field, same discipline
  • rules/append-vs-modify.md — why a Diagnosis comment cannot hold mutable state
  • scripts/tests/actionability-gate/ — the incident fixture (parked-routing.json, verbatim 2026-08-10 rows plus corpus-sampled shapes), the frozen Complexity corpus (corpus-complexity.json, 159 rows) and the frozen Blocking corpus (corpus-blocking.json, 55 rows)
  • #336 — whether ### Blocking should be regex-read at all (producer contract vs model judgement); #337 — #84's blocked-label / wait-class display signals, retired from the gate path in 3.1.0
  • On enumerations. The reason vocabulary is written as a closed list with an explicit no-analogy clause because it is one: a summarizing criterion plus examples is two specifications that drift apart silently. The deferral vocabulary is deliberately not presented that way — it is a heuristic with a stated add-criterion (corpus evidence, zero false positives) — because round 1 showed what happens when a heuristic is dressed up as a domain: it rejects the data it was meant to describe.