feat(pm): close-cards packs one card into ONE fleet-write dispatch (comment, labels_remove, issue_patch) from a per-card --plan

[objectstack-fleet]

Part of #19824
Clause-②: no

#19824 remains open until the seat's live one-card run of this tool closes it (the card's last acceptance step, owned by the skills seat at MERGED). This PR carries the code half: the pack, the per-card plan, the pre-flight and the read-back.

What changes

scripts/pm/close-cards.mjs is the only file changed.

• One card = one write under the relay. On the dispatch transport each actionable card becomes ONE repository_dispatch carrying exactly [comment, labels_remove, issue_patch], in that order (PACK_ORDER). write-pace counts the dispatch as the card's one write, so the hourly cap is untouched (DEFAULT_HOURLY_MAX and the gap are not edited) and a card costs a third of what it did. ⛔ One card per dispatch, never two.
• --plan FILE replaces --list / --comment / --reason. One row per card: N|REASON|COMMENT-FILE. The retired flags are refused by name, with the new spelling. The plan is refused before any request when a card is named twice, when two rows share one comment file, or when two comment files carry the same text once whitespace is collapsed and every digit run is masked. So posting the same comment text on many cards is structurally impossible in the tool.
• The pre-flight is kept and reused, not re-written. Every row's comment goes through post-stamped's exported renderBody + claimKeyedLineRefusals (via the existing preflightComment) before card one. It runs again on the act's own clock when the card is packed. A refusal is ZERO writes on that card and on every card after it (exit 2).
• The pack is judged by the relay's own validator before anything is sent. On dispatch, every row is packed once on placeholder labels before card one is read. So a payload over the platform's 64KB client_payload ceiling, or a body over the relay's body cap, is refused with zero writes on every card, never discovered on card 40.
• Step ④ reads the BOARD back after every run, and must MATCH. The card (state, state_reason, labels) and the comments since the dispatch are read. The comment must be found by post-stamped's pickRelayComment (the platform footer tolerated) with its stamp verdict from post-stamped's readBackVerdict. The labels are judged by label-write's readBackVerdict + verdictIsClean against the ② target from computeLabelTarget. The close must read closed under the row's reason. A run that FAILED is read back the same way to say which steps landed: exit 5 when none did, exit 4 naming them otherwise.
• The label strip is the card's pm-state plus every label PM_RESIDUE_LABELS names that it carries (e.g. pm:blocking). Identity stickers (pm:seat, pm:epic) stay. The vocabulary is imported, not restated.
• The direct transport keeps its three writes, each by the tool that owns it (post-stamped child, runLabelWrite, PATCH). Three requests are three throttle writes on that path whatever the packing. The comment child is now handed OS_FLEET_TRANSPORT=direct, so it cannot resolve a route of its own that differs from the run's.
• Exit 6 (UNCONFIRMED) is new for this tool. It covers a dispatch that was accepted but whose run did not appear or did not complete. ⛔ Not retried and ⛔ not fallen back to direct, even under auto. The pack's first action is a comment, so replaying a dispatch that may still run is a second closing comment, written as the seat's own user. The previous close-only relay path fell back to a direct PATCH on no-run under auto. That fall-back is gone because the dispatch now carries the comment.

The mechanism assumptions, measured (base 48c91e9, those files untouched here)

1. fleet-write/ops.mjs:128 CLIENT_PAYLOAD_MAX_BYTES = 64 * 1024 (the platform ceiling, quoted with its source in that header); :113 MAX_ACTIONS = 20; :116 MAX_BODY_BYTES = 60_000. validate.mjs:203 refuses a serialised payload at or over the ceiling. The ceiling is reachable under the body cap, because JSON escaping inflates a body. The self-test fixture is 40,000 double quotes: under 60,000 body bytes, over 64KB serialised.
2. fleet-write/execute.mjs:41: the first failure stops the run. So the pack's order keeps the old invariant: no strip and no close without the comment.
3. fleet-write/dispatch.mjs:112: the dispatch POST is the paced write. Measured below: a dry run adds 0 records.
4. runLabelWrite binds ③ and ④ into one call: its ③ sends its own dispatch (label-write.mjs:637). So the pack reuses the exported halves (computeLabelTarget, relayActions, readBackVerdict, verdictIsClean) instead of calling it on the relay path. No change to label-write.mjs. One piece of its ④ is deliberately NOT borrowed: re-adding a label stripped underneath (label-write.mjs:733). That is a write, and on the relay path it is a direct write (see Acceptance notes). A strip is reported as a READ-BACK MISMATCH (exit 4) instead.
5. The live skip matrix (not open, assignee, pm:retriage, pm-state not exactly --expect-state, open-PR cross-reference) is unchanged and runs per card before its pack. A skipped card gets no payload, and its line names the reason.
6. The self-test already had the pinned-battery shape (SELF_TEST_BATTERIES + SELF_TEST_BATTERY_FLOOR + selfTestReachedVerdict). New behaviour gets new named batteries. The list-file battery became the plan-file battery, and the close-only relay battery became four pack batteries. The roster floor moved 12 to 18. There is no total pin.

Why --plan over --list + --comment-dir

A plan row carries the card, its OWN reason and its OWN comment file in one reviewable line. The maintainer's closing replies are per card and differ in reason as well as text. --comment-dir pairs a comment to a card by file-name convention and keeps a batch-wide --reason. Both need the same content-identity check to make "one text on many cards" impossible. That check is judgePlanComments here, and the plan is the shape that also removes the shared reason.

Tests (at c474dc5)

• node scripts/pm/close-cards.mjs --self-test: OK close-cards self-test: 173 cases pass across 18 batteries — offline, no network, no token. (111 across 12 before). The three acceptance cases each have a named battery:
  • the pre-flight refusal battery: a comment refused before the pack is ZERO writes on its card (relay and direct, plus the plan-level refusal before any request);
  • the size ceiling battery: a payload over 64KB is refused before it is packed, with no dispatch and no card read;
  • the skip log battery: the assignee, pm:retriage, wrong-state and open-PR cards are skipped with their reasons named, and ONE payload goes for the one actionable card.
• Mutation legs through scripts/ablation-replace.mjs (anchor hit 1 to 0, blob changed, restored to the HEAD blob 60a97257, git diff HEAD empty), each turning its target red:
  • M1, drop the pre-card pack preview: size-ceiling battery 2 of 173 fail;
  • M2, burst rule off: burst battery 5 fail;
  • M3, ④ ignores the label verdict: read-back battery 2 fail;
  • M5, strip only the pm-state: residue case 1 fail.
• Live, read-only: node scripts/pm/close-cards.mjs --repo objectstack-ai/objectstack --plan PLAN --dry-run on close-cards: one card = one write — pack comment → pm:* strip → close into ONE fleet-write write set (write-pace cap unchanged, closing throughput ×3) #19824, PM corpus audit (maintainer-directed): classify every instruction line — keep / duplicate / demote / delete — then rewrite and re-lock every ratchet #13597 and Pace every seat write — one shared throttle in front of the five PM write scripts (maintainer 「截流应该要加」) #19572. Exit 0: re-exec through the proxy, transport dispatch, the pack preview accepted all three rows, and three SKIP lines naming assignee, assignee and not open (state closed/completed). write-pace.jsonl held 6 records before and after, with 0 stamped inside the run window. None of those cards is actionable, so the live payload print is covered offline by the relay-pack battery (#65 payload equals the packed JSON, 3 actions, 0 sent).
• Live refusals: --list gives exit 2 with the retirement line naming --plan. A two-card plan whose texts differ only in the card number gives exit 2 with the burst refusal and NOTHING was read and NOTHING was written.

Gates (derived by node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at c474dc5: 31 commands, plus six named by the dispatch)

All exit 0: the 30 derived commands other than check:pm-dispatch-gates, plus check:pm-post-stamped (610/21), check:pm-label-write (91/10), check:pm-fleet-write-validate (74/7), check:pm-fleet-write-execute (48/9), check:pm-fleet-write-dispatch (101/11) and check:pm-settings-deny-roster. Also check:pm-close-cards (173/18), check:pm-write-pace (113/12) and check:nul-bytes (9315 files, no raw control bytes).

check:pm-dispatch-gates: its self-test does not finish inside the container's ten-minute foreground cap (two attempts killed by the cap with 0 failures printed). It is being run to completion detached, and the report comment on #19824 carries its verdict. Until then: NOT MEASURED, reason: runtime over the foreground cap.

NOT MEASURED: live one-card run. Reason: the seat runs it on #19824 after MERGED.

Acceptance notes

• class a, a cubic-time regex on the claim marker. CLAIM_COMMENT_MARKER (check-half-states.mjs:1188) is a multiline ^, then optional whitespace, an optional quote marker, optional whitespace, then Claim or Claimed and a colon. Its two optional-whitespace runs both match newlines, so a body with a long run of blank lines backtracks cubically. Measured at c474dc5 on the bare regex: 500 newlines take 53 ms, 1000 take 456 ms, 2000 take 3410 ms. Through claimKeyedLineRefusals (post-stamped :1916), 2000 take 6.5 s and 10,000 did not finish in 100 s. Every comment markerMatches reads with it is exposed, the patrol's included. Probe: markerMatches(CLAIM_COMMENT_MARKER, 'x' + '\n'.repeat(2000) + 'end.'). Reported for the seat to file; not fixed here (another file, another defect class).
• class b, label-write's step ④ re-add leaves the relay. Under the dispatch route, runLabelWrite's ④ re-add of a label stripped underneath is doCall('label-add', …), the direct rest with the seat's token (label-write.mjs:733). In a cloud container that is a write as the seat's own user. The relay contract is that OS_FLEET_TRANSPORT=direct is the only way to do that (fleet-write/dispatch.mjs header, the fail-closed paragraph). Offline probe: runLabelWrite with a dispatch route and a relay that strips tooling inside the run records POST /repos/objectstack-ai/objectstack/issues/5/labels on the direct call. The pack here does not borrow that re-add. Reported for the seat to file.
• Doc lines this PR makes stale, both in .claude/** (outside this PR's surface). Carrier: the skills seat, at landing.
  • .claude/skills/pm-dispatch/references/platform-readings.md:107 says close-cards spends one dispatch per step. Under the relay it is now one per card.
  • .claude/skills/pm-dispatch/references/rest-channel.md:19 lists close-cards' failed-run exit as 4. It is now 4 when the board shows a step landed and 5 when it shows none, with 6 for UNCONFIRMED.
• Not done: the card's optional item 6 (a grading mode: comment plus label add/remove, no close). It is left out to keep this diff to the closure the card rules on.
• The Card-closure helper self-test comment block in .github/workflows/lint.yml still describes the three-step shape. Its assertions all still hold on the direct path, and the step command is unchanged.

---

Generated by Claude Code