build(preflight): install CommonMark runtime

[vincentkoc]

Summary

• pin the CommonMark reference parser at 0.31.2 with an npm lockfile
• install project dependencies before every workflow command that will load the parser
• add a contract test for dependency pinning, workflow ordering, and rendered link-title boundaries

Why

Clownfish PR #311 needs authoritative CommonMark parsing in the external-merge
preflight. Repeated review found that a handwritten Markdown state machine was
reimplementing parser semantics and accumulating bypasses. This prerequisite PR
adds only the maintained parser runtime and its workflow installation boundary;
it does not change preflight authorization behavior.

Validation

• node --test test/commonmark-runtime.test.mjs passes
• npm run validate validates 6,707 jobs
• npm test passes all 557 tests
• npm audit --omit=dev reports zero vulnerabilities
• local ClawSweeper exact-range review reports no correctness, security, or rank-up findings
• signed exact-head commit: 31f2feffac0d58ca1beded6ab883957acb7d5ae0

Risk

The workflows gain an npm install step. The runtime version and transitive graph
are locked, lifecycle scripts are disabled, and audit/funding network calls are
disabled during CI installation. Exact-head hosted CI must still exercise the
clean-runner installation and cache ordering before merge.

Maintainer decision

Adopt commonmark@0.31.2 as the locked parser runtime for external-merge
preflight review text. The reference parser owns Markdown syntax; Clownfish owns
the authorization projection over its AST. The paired parser PR must load it
only in the review-text parsing path so apply-only execution remains independent.
Any incompatible parser or contract change requires a separately reviewed
dependency update.

Gate disposition

• exact-head hosted validate completed successfully, including clean-runner
  installation before all 557 tests
• exact-head CodeQL completed successfully
• local and hosted ClawSweeper reviews found no correctness or security defect
• the hosted Rank-up move to complete exact-head validate is satisfied

[clawsweeper]

Codex review: needs changes before merge. Reviewed August 29, 2026, 8:00 AM ET / 12:00 UTC.

ClawSweeper review

What this changes

The PR pins CommonMark, installs dependencies before three CI workflows, and adds a contract test for parser availability and Markdown text extraction.

Merge readiness

⛔ Blocked by patch quality or review findings - 4 items remain

Keep this member-authored prerequisite PR open, but its added boundary test has a definite P1 failure: it expects a reference-definition title that the test’s text-only AST walk discards.

Priority: P2
Reviewed head: 31f2feffac0d58ca1beded6ab883957acb7d5ae0

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	The dependency change is narrowly scoped, but its introduced contract test has a deterministic P1 failure.
Proof confidence	🌊 off-meta tidepool	Not applicable: This MEMBER-authored CI prerequisite is exempt from the external-contributor proof gate; the remaining blocker is a source-proven failing contract test, not absent runtime proof.
Patch quality	🧂 unranked krab (1/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This MEMBER-authored CI prerequisite is exempt from the external-contributor proof gate; the remaining blocker is a source-proven failing contract test, not absent runtime proof.
Evidence reviewed	4 items	Introduced test cannot satisfy its positive assertion: The helper appends literals only for text and code nodes, while the positive fixture places the sentinel in a link-reference-definition title; that title is not included in the collected rendered text. Current default branch still lacks this runtime setup: Current main invokes the external preflight command without the proposed dependency-install step, so the central dependency-installation change is not already implemented. Prior review blocker remains at the exact same head: The previous completed review identified the same positive-sentinel defect at this exact head; no new commit has changed the test.
Findings	1 actionable finding	[P1] Put the positive sentinel in visible Markdown
Security	None	None.

How this fits together

Clownfish’s validation and external-merge-preflight workflows run Node scripts that inspect pull-request review text. This PR supplies a locked Markdown parser dependency before those workflows run their commands.

flowchart LR
  A[Pull request review text] --> B[External merge preflight]
  B --> C[CI workflow]
  C --> D[Install locked dependencies]
  D --> E[CommonMark parser]
  E --> F[Review-text decision]

Loading

Before merge

• Put the positive sentinel in visible Markdown (P1) - renderedText appends only text and code node literals, but the positive fixture places Do not merge. in a reference-definition title. That metadata is not returned by this walk, so the positive assertion fails and cannot test the claimed parser boundary.
• Resolve merge risk (P1) - Merging adds locked npm installation to three CI paths; integrity hashes and disabled lifecycle scripts reduce the supply-chain exposure, but workflow behavior must be revalidated after the test repair.
• Complete next step (P2) - A one-file, source-proven contract-test repair is available; the paired consumer PR remains open and should not be treated as resolved.
• Improve patch quality - Correct the positive CommonMark fixture and rerun the focused test, the full test suite, and validation on the refreshed head.

Findings

• [P1] Put the positive sentinel in visible Markdown — test/commonmark-runtime.test.mjs:65-70

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production versus test delta	production +74, tests +82, removed 0	The parser lockfile and three workflow edits add the runtime surface, while the contract test is intended to guard it.
Workflow coverage	3 workflows changed	Each changed CI path must install the same locked dependency before invoking repository scripts.

Merge-risk options

Maintainer options:

1. Repair the parser-boundary fixture (recommended)
   Put the positive sentinel in a visible text node and retain a separate assertion that a reference-definition title is excluded, then rerun exact-head CI.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Update the CommonMark boundary fixture so the positive sentinel is visible text, retain a distinct link-definition-title exclusion assertion, and rerun the focused test plus validate.

Technical review

Best possible solution:

Keep one locked CommonMark runtime installed before each parser consumer, correct the boundary fixture so it tests visible text versus reference-definition metadata, and then land the paired consumer work in #311.

Do we have a high-confidence way to reproduce the issue?

Yes—source inspection gives a high-confidence reproduction: the helper only collects text/code literals, yet the asserted positive sentinel appears only in a reference-definition title.

Is this the best way to solve the issue?

No: the locked dependency and workflow ordering address the stated prerequisite, but the current fixture must be corrected before it can prove the advertised parsing boundary.

Full review comments:

• [P1] Put the positive sentinel in visible Markdown — test/commonmark-runtime.test.mjs:65-70
renderedText appends only text and code node literals, but the positive fixture places Do not merge. in a reference-definition title. That metadata is not returned by this walk, so the positive assertion fails and cannot test the claimed parser boundary.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 00c1adb10bbe.

Labels

Label changes:

• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🌊 off-meta tidepool and patch quality is 🧂 unranked krab.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🧂 unranked krab, so this older rating label is no longer current.

Label justifications:

• P2: The PR changes the CI dependency boundary used by validation and merge-preflight automation.
• merge-risk: 🚨 automation: It adds npm installation to three GitHub Actions workflows before automation commands run.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🌊 off-meta tidepool and patch quality is 🧂 unranked krab.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This MEMBER-authored CI prerequisite is exempt from the external-contributor proof gate; the remaining blocker is a source-proven failing contract test, not absent runtime proof.

Evidence

Acceptance criteria:

• [P1] node --test test/commonmark-runtime.test.mjs.
• [P1] npm test.
• [P1] npm run validate.

What I checked:

• Introduced test cannot satisfy its positive assertion: The helper appends literals only for text and code nodes, while the positive fixture places the sentinel in a link-reference-definition title; that title is not included in the collected rendered text. (test/commonmark-runtime.test.mjs:21, 31f2feffac0d)
• Current default branch still lacks this runtime setup: Current main invokes the external preflight command without the proposed dependency-install step, so the central dependency-installation change is not already implemented. (.github/workflows/external-merge-preflight.yml:71, 00c1adb10bbe)
• Prior review blocker remains at the exact same head: The previous completed review identified the same positive-sentinel defect at this exact head; no new commit has changed the test. (test/commonmark-runtime.test.mjs:65, 31f2feffac0d)
• Current workflow surface was recently updated: The current default branch uses newer setup and cache action versions around the insertion points, so the repair should refresh the branch before its next hosted validation. (.github/workflows/cluster-worker.yml:551, 10711e119181)

Likely related people:

• github-actions[bot]: Current-main blame attributes the Node setup and cache context surrounding all three affected workflow insertion points to the recent workflow update. (role: recent workflow updater; confidence: medium; commits: 10711e119181; files: .github/workflows/cluster-worker.yml, .github/workflows/external-merge-preflight.yml, .github/workflows/validate.yml)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (50 earlier review cycles; latest 8 shown)

• reviewed 2026-08-15T14:57:27.552Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-15T21:57:25.999Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-21T19:08:05.851Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-23T11:10:54.703Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-24T02:24:24.019Z sha 31f2fef :: found issues before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-25T07:16:51.423Z sha 31f2fef :: found issues before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-26T19:35:02.406Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-29T06:04:35.394Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown