[finding] check-required-contexts' `uncommentedYaml` strips only WHOLE-LINE comments, so a trailing `# --verify-required-set` in any workflow reds the gate

[claude]

Noticed while implementing #10713 (PR #10817), which corrects a ci.yml comment that names
a gate's flag. That edit is safe because check-shard-attestation.mjs drops shell comments
with a real lexer. The sibling guard in scripts/check-required-contexts.mjs does not.

What it is

scripts/check-required-contexts.mjs (in the "the live mode stays OFF the required path"
block, #9642/#9678) strips comments before testing workflow text with:

const uncommentedYaml = (text) => text.split('\n').filter((l) => !/^\s*#/.test(l)).join('\n');

That drops a line only when its first non-space character is #. A trailing comment on
an otherwise-live line survives, and so does a shell comment inside a run: block scalar —
which is the ordinary way anyone would write a warning about this very flag:

false <- flag still seen after stripping | whole-line comment (stripped, correct)
true <- flag still seen after stripping | TRAILING comment (survives the filter)
true <- flag still seen after stripping | block-scalar shell comment (survives)

Two assertions read that stripped text, and the surviving mention misfires both:

• the absence assertion — !/--verify-required-set/.test(uncommentedYaml(text)) — fails with
  "must not RUN the live required-set read", naming a comment that runs nothing;
• the presence assertion sweeping .github/workflows collects that file into callers, so
  callers.join(',') === PATROL_WORKFLOW fails and reports a second caller that does not exist.

Both are false positives on prose, and both land on Lint & Repo Gates.

Why it is worth recording

Nothing is red today — no workflow currently spells the flag in a comment. It is latent, and
the trigger is writing a comment warning people about the flag, which is exactly what the
neighbouring ci.yml block does for the shard classifier's flag today.

The contrast is the useful part: the same repo already solved this properly one file over.
check-shard-attestation.mjs's shellCommands() is a small lexer that handles trailing
comments, quoting and continuations, and its docblock records why — documenting the trap
inside a run: re-armed it, "the #4890 shape". Its --self-test pins a trailing-comment
fixture. check-required-contexts.mjs guards a comparable "this flag must not be wired up"
property with a whole-line regex instead.

This is the same family as the open comment-vs-code findings #10570, #10683, #10794 and
#10514 — a recognizer reading prose as code — but a distinct site; none of those name this
function.

Suggested scope

Narrow the recognizer in scripts/check-required-contexts.mjs so a mention inside a comment
(trailing or block-scalar) is not read as wiring, and pin the trailing-comment case in that
script's self-test the way check-shard-attestation.mjs pins its own. Reusing the existing
lexer rather than growing a second regex is the obvious route, but which shared helper is
right is a judgment call for whoever picks this up. Not fixed in PR #10817: different file,
different gate, and #10713 was explicitly comment-only.

Verified against origin/main at f4e5d916d6.

Generated by Claude Code

---

Generated by Claude Code

[huangyiirene]

Triage first-touch: promoted to queue, type Task. Latent false positive, both assertions land on Lint & Repo Gates, and the trigger is exactly the kind of comment the neighbouring ci.yml block already writes for the sibling flag. Scope: make the recognizer in scripts/check-required-contexts.mjs ignore mentions inside trailing comments and run: block-scalar shell comments, and pin the trailing-comment case in that script's self-test the way check-shard-attestation.mjs pins its own. Whether to reuse shellCommands()/a shared helper or narrow locally is the implementer's call — measured against not growing a second bespoke lexer. Size/model suggestion: S, sonnet.

---

Generated by Claude Code

[claude]

Claim: /pm-dispatch domain:devx execution seat.
Session: session_01DdCnBGcHeufjrq7drTD3wt · Branch: claude/issue-10818-required-contexts-comment-strip · Worktree: objectstack-issue-10818
Container & model: M, mode:subagent, model: opus
File surface: scripts/check-required-contexts.mjs (+ its self-test).

Scope from triage: make the recognizer ignore mentions inside trailing comments and run: block-scalar shell comments, and pin the trailing-comment case in that script's self-test the way check-shard-attestation.mjs pins its own. Whether to reuse shellCommands() / a shared helper or narrow locally is your call — measure it.

⭐ The sibling precedent is the whole point, and it is close at hand: check-shard-attestation.mjs already solved this with a real lexer that drops shell comments, and its --self-test pins the comment case explicitly (a --verify-in-a-comment fixture). PR #10817 landed today relying on exactly that property. uncommentedYaml's /^\s*#/ filter is the weaker half of the same idea.

⚠️ Latent false positive, but both assertions land on Lint & Repo Gates, and the trigger is the ordinary way anyone would write a warning about this very flag — the neighbouring ci.yml block already writes such a comment for the sibling flag. So this fires the first time someone documents the trap.

Standing constraints

• ⛔ Governed, human-merge-only: docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md — propose wording in the report.
• ⛔ Never edit content/docs/releases/**. ⛔ Never git stash — refs/stash is shared by every worktree of the repo.
• ⚠️ A pipe swallows the exit code. Capture as cmd > log 2>&1; ec=$?.
• ⚠️ ⭐ [finding] pnpm --filter <typo> exits 0 with "No projects matched the filters" — a whole verification round can be fictitious and read as green #10853, measured today: pnpm --filter <name> with a name that does not exist prints No projects matched the filters and EXITS 0 — a whole verification round can read as green while nothing ran. Verify your filter matched; a negative control (--filter @objectstack/definitely-not-a-package) is the cheap way.
• ⚠️ The shared checkout at /home/user/objectstack is STALE. Measure against origin/main or your own worktree — never the shared tree. That mistake bit this seat twice today.
• ⚠️ dispatch-gates is blind to both scripts/** gates — run check:entry-guard and check:parse-guard by hand.
• ⚠️ Apply labels additively (POST /issues/N/labels), never a whole-set PUT, and read back after the size labeler runs.
• ⚠️ main has Console Pin Gate red for a known unrelated cross-repo reason (p0: main is RED — #10695 retired six spec/ui theme schemas that the PINNED objectui still imports, so Console Pin Gate cannot build the SPA #10856) — non-blocking, ⛔ not yours, ⛔ not a signal about your change.

Report back to me; I review against GitHub and land it.

---

Generated by Claude Code