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 15, 2026, 5:57 PM ET / 21:57 UTC.

ClawSweeper review

What this changes

The PR pins CommonMark, installs it before validation and external-merge workflows, and adds a contract test for dependency setup and Markdown rendering boundaries.

Merge readiness

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

Keep this member-authored PR open, but block merge: its new CommonMark contract test asserts that a reference-definition title is rendered even though the helper collects only visible text and code literals.

Priority: P2
Reviewed head: 31f2feffac0d58ca1beded6ab883957acb7d5ae0

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	The dependency and workflow scope is focused, but the added contract test contains a deterministic failing assertion.
Proof confidence	🌊 off-meta tidepool	Not applicable: This member-authored internal automation prerequisite does not require the external-contributor real-behavior-proof gate; hosted checks remain supplemental to fixing the deterministic test failure.
Patch quality	🧂 unranked krab (1/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This member-authored internal automation prerequisite does not require the external-contributor real-behavior-proof gate; hosted checks remain supplemental to fixing the deterministic test failure.
Evidence reviewed	5 items	Unfixed contract-test failure: The walker appends only text/code literals and line breaks, but the positive fixture places the sentinel solely in a link-reference definition title and then expects it in rendered output. That title is not visible Markdown text for this helper. Prior blocker remains at the reviewed head: The current head is the same SHA as the previous completed review, and the targeted file has no intervening diff; the earlier P1 finding therefore remains unresolved. Work is not on current main: Current main has no dependencies section or CommonMark lockfile, and the PR commit is not an ancestor of current main.
Findings	1 actionable finding	[P1] Put the positive sentinel in visible Markdown
Security	None	None.

How this fits together

Clownfish’s GitHub Actions workflows validate cluster jobs and preflight external merges before any guarded apply. This PR provisions a Markdown parser runtime for the preflight text-analysis path and tests the parser boundary that a later preflight change would consume.

flowchart LR
  A[External pull request] --> B[External merge preflight]
  C[GitHub Actions workflow] --> D[Project dependency install]
  D --> E[CommonMark parser]
  E --> B
  F[Markdown boundary contract test] --> E
  B --> G[Guarded merge decision]

Loading

Before merge

• Put the positive sentinel in visible Markdown (P1) - The walker only emits text, code, and breaks, so the reference-definition title on this line cannot yield Do not merge.; the assertion below therefore fails. This is the unchanged blocker from the prior review cycle—place the positive sentinel in a visible paragraph or link label while keeping the title-only negative fixture.
• Resolve merge risk (P1) - Adding npm ci to three workflows makes clean-runner dependency installation a merge-critical automation path; hosted validation should be rerun after the broken fixture is corrected.
• Improve patch quality - Move the positive sentinel into visible Markdown and retain the title-only negative boundary.
• Improve patch quality - Run the focused test, full test suite, validation, and exact-head hosted workflow after the correction.

Findings

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

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production versus test lines	production +74, tests +82	Most production growth is the locked dependency graph and three workflow install steps; the new test is the merge blocker.
Automation surfaces	3 workflows changed	Each now performs a clean project dependency install before commands that may load the parser.

Merge-risk options

Maintainer options:

1. Repair the visible-text fixture (recommended)
   Move the positive sentinel into visible paragraph or link-label text, preserve the title-only negative assertion, and rerun the focused test plus hosted validation.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Move the positive sentinel into visible Markdown in test/commonmark-runtime.test.mjs while retaining the title-only negative fixture; run the focused test, npm test, and npm run validate.

Technical review

Best possible solution:

Keep the parser runtime change narrow, move the positive sentinel into visible Markdown while retaining the title-only negative case, then validate the exact head in the affected workflows.

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

Yes, from source: the walker excludes link-reference titles, while the positive assertion places its only sentinel in such a title.

Is this the best way to solve the issue?

Yes, the narrowest repair is to make the positive sentinel visible Markdown and keep the existing title-only fixture as the negative boundary check.

Full review comments:

• [P1] Put the positive sentinel in visible Markdown — test/commonmark-runtime.test.mjs:67
  The walker only emits text, code, and breaks, so the reference-definition title on this line cannot yield Do not merge.; the assertion below therefore fails. This is the unchanged blocker from the prior review cycle—place the positive sentinel in a visible paragraph or link label while keeping the title-only negative fixture.
  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 a2b287af3b2f.

Labels

Label justifications:

• P2: This is a bounded preflight-automation prerequisite with a deterministic test defect, not a live user-facing outage.
• merge-risk: 🚨 automation: The PR changes dependency installation behavior in validation, external preflight, and cluster-worker workflows.
• 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 internal automation prerequisite does not require the external-contributor real-behavior-proof gate; hosted checks remain supplemental to fixing the deterministic test failure.

Evidence

Acceptance criteria:

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

What I checked:

• Unfixed contract-test failure: The walker appends only text/code literals and line breaks, but the positive fixture places the sentinel solely in a link-reference definition title and then expects it in rendered output. That title is not visible Markdown text for this helper. (test/commonmark-runtime.test.mjs:67, 31f2feffac0d)
• Prior blocker remains at the reviewed head: The current head is the same SHA as the previous completed review, and the targeted file has no intervening diff; the earlier P1 finding therefore remains unresolved. (test/commonmark-runtime.test.mjs:67, 31f2feffac0d)
• Work is not on current main: Current main has no dependencies section or CommonMark lockfile, and the PR commit is not an ancestor of current main. (package.json:46, a2b287af3b2f)
• Workflow installation boundary: The PR adds a locked, lifecycle-script-disabled npm install before the external preflight’s Codex setup, making the dependency setup part of automation behavior. (.github/workflows/external-merge-preflight.yml:71, 31f2feffac0d)
• Current workflow provenance: Current workflow lines attribute to the recent automation-recording commit; available local history does not establish a stronger human area owner. (.github/workflows/external-merge-preflight.yml:44, 9420bb93657a)

Likely related people:

• github-actions[bot]: The current external-preflight workflow lines blame to its recent recording commit; no stronger human ownership trail is available in this checkout. (role: recent workflow recorder; confidence: low; commits: 9420bb93657a; files: .github/workflows/external-merge-preflight.yml, .github/workflows/cluster-worker.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 (43 earlier review cycles; latest 8 shown)

• reviewed 2026-08-14T12:04:40.552Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-14T15:10:28.856Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-14T20:57:20.150Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-14T22:01:59.541Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-15T02:13:38.575Z sha 31f2fef :: found issues before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-15T05:58:21.555Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-15T12:04:38.583Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown
• reviewed 2026-08-15T14:57:27.552Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown