/nd: next ai:design PR to rule on — next_design tool + command

[thedavidmeister]

Closes #220

/nd — the next ai:design PR for the human to rule on, third sibling of /nr and /ncc.

next_design MCP tool (pr-review-report-rs/src/main.rs)

Mirrors next_ready's discipline exactly, with next_close_candidate's ordering argument where it transfers:

• Typed result off the shared enumeration machinery: the same gh search prs --label + org_owner_args() shape presentable_queue uses (never a checks qualifier — the measured 93-vs-203 lesson), archived repos withheld before the per-PR fetch and counted (next_close_candidate offers flags from archived repos, where no ruling can be written #206), drafts and human:*-overridden PRs excluded through the same has_human_override predicate the ai:ready queue reads.
• limit refused out of range rather than clamped (next_design_limit, 1..=3, default 1), same wording shape as next_ready_limit.
• Oldest question first (design_order_key: raising-comment timestamp, ties broken by PR ref) — flag_order_key's FIFO argument transfers whole: no cost signal exists, and the label parks the PR outside every AI actor's queue, so FIFO bounds the limbo.
• The question carried from the trusted comment that raised it: the vetter's record-verdict design note (Reviewed <sha>: design, close-candidate twin excluded by its own token) or the producer's flag-design note (Design-question:), most-recent-wins, author-gated through trusted_comments so a spoofed marker raises nothing. question.source is the typed discriminant; a vetter-raised question reports sha/atHead, a producer-raised one reports null rather than a bool asserting a comparison nothing performed.
• Truncation flagged like noteTruncated (note/noteBytes/noteTruncated at a 2,600-byte cap), with the full per-field byte-cap + compile-time budget guarantee both siblings carry (ND_* constants, const _: () = assert!(...)).
• Withheld rows are visible: counts.noQuestion + a capped list for labelled PRs with no trusted raising comment (the design twin of CcGate::NoFlag), fetchErrors likewise.

Wired through the same seams as the siblings: McpProfile::Human tool list, mcp_all_tools entry (narrows: limit), McpCall::NextDesign, validate_call, mcp_exec, minimal_args, and the pinned counts (21 tools, six narrowing).

plugins/human-fsm/commands/nd.md

Modeled on nr.md/ncc.md — same register, LIMIT convention, refusal-relay language, typed-reads/no-shell contract, and second-opinion posture. The raised question is a claim to check (issue → diff → tree via pr_context / pr_checkout), with three findings, each a different deliverable: a genuine question (presented with the code-constrained option space and a recommendation), already answered (the pointer IS the finding), or misrouted (stated with what the correct state would have been).

Written against the post-#219 state (#219, ruled): the exit it points at is the design ruling that routes the PR immediately back to the producer as ai:reject + the answer as the trusted work order, one call. human:design and every park spelling appear nowhere in it.

Grant pinned by test (nd_grants_the_queue_the_pr_the_source_and_the_lens): next_design, pr_context, pr_checkout, clone_release + Skill, Read.

Plugin release

plugins/human-fsm/.claude-plugin/plugin.json and .claude-plugin/marketplace.json bumped 0.11.0 → 0.14.0 in lockstep; descriptions now name the third read. The three doc surfaces listing the human profile (CLAUDE.md, README.md, plugins/human-fsm/README.md) updated to the three-inbox shape.

Version coordination — this PR should merge LAST of the three human-fsm bumps in flight. Three open PRs bump the plugin from 0.11.0, and two cannot ship one version string: /plugin detects updates by comparing version STRINGS, so the second to land under a duplicate version would serve new content under a version installers have already seen. The claims are distinct and monotonic in merge order:

Merge order	PR	Version
1	#224 (human:design deletion)	0.12.0
2	#227 (/nm)	0.13.0
3	this PR	0.14.0

If this lands earlier than that order, its version must be re-bumped past whatever main then carries — a lower or equal number against main is the same stale-content bug, and the version hygiene job's lockstep + bump checks are what catch it.

The stronger reason to merge last is SEMANTIC, not the version string. nd.md and the next_design tool description both describe the post-#219 exit: answering routes the PR back as ai:reject + the work order in one call, with no parked spelling and no waiting state. main does not implement that yet — today /design writes human:design and takes --rework | --park. If this PR lands before #224, plugin 0.14.0 ships a command whose stated exit its own ruling command does not perform: /nd would tell the human the answer sends the PR back to the producer, and /design would park it under a label the FSM still has. The version ordering is a consequence of that dependency, not the reason for it.

Coordination hazard — the /design row of plugins/human-fsm/README.md. #224 rewrites that row (it deletes the human:design / --park prose); this PR reformats the surrounding table and the paragraphs under it. The conflict is guaranteed. 224's version of that row wins — resolving toward this side would restore the human:design and --park prose #219 deleted, which is the exact regression the deletion PR exists to prevent. Take 224's row verbatim; only the /nd row and the three-inbox prose come from here.

Tests

Mirror next_ready's: limit guard boundaries (default/null/1/max, refusals at 0, max+1, -1, "2", 1.5), row shape for both sources, empty-queue answer, truncation flag, prefix-of-ranked-order paging, adversarial byte-budget page, measured fixed allowances, question-source provenance (spoofed author, adjacent trusted comments, most-recent-wins), and the population query pinned as a value. Conformance: design_open_prs_args registered in every_org_wide_enumeration_withholds_archived_repos as a PURE argv builder whose live caller withholds.

Coordination note: based on main; the #219 deletion PR and the #130 stateDescriptors PR are in flight in the same file — this PR touches neither's paths (no human:design machinery, no human-queue emission); on conflict, main gets merged in.

QA

• Discriminating tests: 19 in next_design_tests — the limit guard, the row shape for both question sources, the empty-queue answer, the truncation flag, prefix-of-ranked-order paging, the adversarial byte budget, the measured fixed allowances, the population query as a value, and (added in review) an_archived_repo_hit_is_withheld_from_the_population_and_counted, every_withheld_hit_class_is_named_rather_than_filtered_away, a_withheld_hit_is_both_counted_and_named, the_counts_partition_the_whole_population, the_claim_in_force_is_the_array_tail_not_the_newest_timestamp — plus the extended pins (the_human_profile_is_exactly_read_the_subject_and_rule_on_it, every_shipped_command_carries_its_frontmatter, nd_grants_the_queue_the_pr_the_source_and_the_lens, tool-count/narrows counts, and the two new positive pins inside every_org_wide_enumeration_withholds_archived_repos). Each fails on base because the functions, the tool and nd.md do not exist there.
• Mutations applied (each alone against the committed tree, whole-binary suite, then restored) — 8/8 killed:
  • next_design_fetch: nd_population(...) -> (arr.clone(), Vec::new()), i.e. the next_close_candidate offers flags from archived repos, where no ruling can be written #206 withholding deleted -> KILLED by every_org_wide_enumeration_withholds_archived_repos (this is the mutant that SURVIVED before this round; it is the reason the population filter is now a named, pinned, unit-tested function)
  • nd_population body gutted to (hits, Vec::new()) -> KILLED by an_archived_repo_hit_is_withheld_from_the_population_and_counted
  • nd_apply_hit: draft counted but not pushed to the withheld list -> KILLED by a_withheld_hit_is_both_counted_and_named (survived first pass; the fold was extracted from the network function and tested to kill it)
  • nd_hit_class: has_human_override arm removed -> KILLED by every_withheld_hit_class_is_named_rather_than_filtered_away
  • last_design_question .next_back() -> .next() -> KILLED by the_claim_in_force_is_the_array_tail_not_the_newest_timestamp + the_question_is_the_most_recent_trusted_raising_comment
  • next_design_limit out-of-range arm -> clamp instead of refuse -> KILLED by the_page_size_defaults_to_one_and_is_refused_outside_its_range
  • next_design_row "noteTruncated" -> hardcoded false -> KILLED by an_oversized_question_is_clipped_and_says_so
  • last_design_question: trusted-author filter dropped -> KILLED by a_spoofed_marker_from_an_untrusted_author_raises_nothing
• Oracle: fixture comments are built by the REAL writers (verdict_comment for the vetter's Reviewed <sha>: design, state_comment("ai:design", …) for the producer's Design-question:), so expected note bodies/pins come from the binary's own record format, not from the reader under test; byte-budget expectations come from the ND_* cap constants and MCP_MAX_RESULT_BYTES, the same arithmetic the compile-time assert checks; ordering expectations are hand-derived FIFO over explicit timestamps.
• Category check: issue asks (1) next_design tool mirroring next_ready — typed result, refused limit, existing FIFO ordering, question from the trusted raising comment with truncation flagged, shared enumeration: covered; (2) nd.md on the nr/ncc model with the stated grant, LIMIT convention, three-findings posture, post-RULED: an answered design question routes straight to producer rework, same as a rejection #219 exit: covered; (3) plugin version bump: covered (0.14.0, lockstep with the marketplace listing). Rust tests mirror next_ready's four named categories (limit guard, row shape, empty queue, truncation): covered.

Refs: #219, #130

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@thedavidmeister, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 26 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4c70101e-888a-4b6d-9a9c-b79655f3235c

📥 Commits

Reviewing files that changed from the base of the PR and between de65b91 and e507174.

📒 Files selected for processing (7)

• .claude-plugin/marketplace.json
• CLAUDE.md
• README.md
• plugins/human-fsm/.claude-plugin/plugin.json
• plugins/human-fsm/README.md
• plugins/human-fsm/commands/nd.md
• pr-review-report-rs/src/main.rs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thedavidmeister]

Reviewed e507174: approve — read the diff and verified the merge independently. /nd is the design-question read, the fourth sibling of /nr, /ncc and /nm, and it matches their discipline: enumeration derived from the shared machinery (ORGS scope, archived-repo withholding, the same human-override predicate presentable_queue reads), limit refused rather than clamped at both boundaries, a compile-time byte budget with allowances measured by test, and every withheld row counted and named so the inbox cannot silently shrink. Ordering is oldest-question-first and argued on the label's own semantics — ai:design parks the PR outside every AI actor's queue, so the wait is the cost and FIFO bounds it. The question arrives typed: source says whether the vetter's verdict or the producer's flag raised it, a vetter-raised question carries the sha it pinned with atHead beside it, and a producer flag reports null rather than asserting a comparison nobody performed. The #206 archived-repo withholding is now pinned as tested behaviour via nd_population, closing a hole where deleting the filter left the whole suite green. nd.md is bounded to reads its grant can actually perform and describes the post-#219 exit, which main now implements.
Rulings-conformance: checked against CLAUDE.md and every ruling stated for this work. (1) 'file and agent an /nd command like /nr and /ncc for the next design human item' — delivered as that sibling, same register, same second-opinion posture. (2) 'can we get test coverage rather than manual verification' — the archived-repo check became a tested pure function rather than an asserted wiring, and the merge's hand-checks became the full-suite-on-merge-commit run. (3) 'the prs are open, trying to get them right' — every review finding was folded into this PR rather than filed. (4) issue-examples-arent-exhaustive — withheld classes are enumerated as a partition, not a sample. (5) The plugin version is distinct and monotonic at 0.14.0 above main's 0.13.0, and 224's version of the /design README row was preserved rather than reverted by this merge. The artifact obeys each.
Merge note: the suite on the merge commit caught two counts git could not — both branches bumped tools.len() to the same literal 21 and narrowing to 6, while the true merged values with both next_leak and next_design present are 22 and 7. Third instance of that class today; the derived-total rule now in the sibling PRs prevents it.