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: found issues before merge. Reviewed August 23, 2026, 10:24 PM ET / August 24, 2026, 02:24 UTC.

ClawSweeper review

What this changes

This PR pins CommonMark, installs dependencies in three GitHub workflows, and adds a runtime/workflow contract test for future external-merge preflight parsing.

Merge readiness

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

Keep this member-authored draft open: current main does not contain the CommonMark runtime prerequisite, but the unchanged contract test has a P1 assertion that cannot pass. Landing also needs a maintainer decision to adopt the parser dependency for the paired preflight work.

Priority: P2
Reviewed head: 31f2feffac0d58ca1beded6ab883957acb7d5ae0
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	The scope is focused, but the submitted contract test contains a definite P1 failure.
Proof confidence	🌊 off-meta tidepool	Not applicable: Not applicable: this MEMBER-authored PR is not subject to the external-contributor real-behavior-proof gate; listed validation remains supplemental.
Patch quality	🧂 unranked krab (1/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: Not applicable: this MEMBER-authored PR is not subject to the external-contributor real-behavior-proof gate; listed validation remains supplemental.
Evidence reviewed	5 items	Failing parser contract assertion: The walker appends only text and code literals, but the positive sentinel is solely a reference-definition title; that metadata produces neither node type, so the assertion cannot match it. Current main lacks the prerequisite: Current main has no CommonMark dependency, lockfile, or runtime test; its manifest ends after the Node engine declaration and the test path does not exist there. Branch provenance: Blame attributes the unchanged broken assertion to the PR-head commit, matching the previous review’s blocker.
Findings	1 actionable finding	[P1] Put the positive sentinel in visible Markdown
Security	None	None.

How this fits together

Clownfish’s external-merge preflight runs in GitHub Actions before automated adoption and turns pull-request review evidence into a merge decision. This change supplies a locked Markdown parser runtime for the paired review-text parsing work and makes project workflows install it first.

flowchart LR
  A[Locked CommonMark package] --> B[Dependency installation]
  B --> C[Validation workflow]
  B --> D[External merge preflight]
  B --> E[Cluster worker]
  D --> F[Review-text parsing]
  F --> G[Merge decision]

Loading

Decision needed

Question	Recommendation
Should Clownfish adopt CommonMark as the locked parser runtime for the paired external-merge preflight work?	Approve the paired parser prerequisite: Adopt CommonMark for the linked parser direction after the P1 test repair and normal exact-head checks.

Why: The mechanical test repair is clear, but adding a new core runtime dependency and CI installation boundary is an architectural choice that cannot be inferred from this prerequisite alone.

Before merge

• Put the positive sentinel in visible Markdown (P1) - The positive fixture puts Do not merge. only in a reference-definition title, while renderedText collects only text/code literals. The title is not emitted as either node type, so this assertion fails and cannot prove the claimed boundary. This is the unchanged blocker from the prior review.
• Resolve merge risk (P1) - Merging adds a locked registry dependency and mandatory npm installation to validation, external-preflight, and cluster-worker automation.
• Resolve merge risk (P1) - The runtime has no consumer on current main, so it should land only with maintainer-backed paired parser work.
• Improve patch quality - Put the positive sentinel in visible Markdown and rerun the focused test.
• Improve patch quality - Obtain maintainer approval for CommonMark as the paired preflight parser runtime.

Findings

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

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Workflow installation surface	3 workflows changed	Validation, external preflight, and the cluster worker each gain a mandatory dependency-install step.
Production vs test growth	production +74, tests +82	The dependency lockfile and workflow changes are accompanied by a focused contract test of comparable size.

Merge-risk options

Maintainer options:

1. Repair the parser contract before merge (recommended)
   Move the positive sentinel into rendered Markdown while retaining the hidden reference-title case, then rerun the focused test and clean-runner validation.
2. Pause pending parser direction
   Keep this prerequisite draft until maintainers explicitly approve the CommonMark dependency for the paired preflight parser.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Move the positive sentinel into visible paragraph text while retaining the hidden reference-title negative case, then rerun the focused test and exact-head validation.

Technical review

Best possible solution:

Repair the visible-Markdown test fixture, then adopt the locked no-lifecycle-install parser runtime only if maintainers approve the paired preflight parser direction.

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

Yes—source inspection shows the positive assertion cannot observe a reference-definition title through this walker; no test was executed under the read-only review policy.

Is this the best way to solve the issue?

No—the intended contract needs visible Markdown for its positive sentinel, and the dependency adoption still needs explicit maintainer direction.

Full review comments:

• [P1] Put the positive sentinel in visible Markdown — test/commonmark-runtime.test.mjs:67-70
  The positive fixture puts Do not merge. only in a reference-definition title, while renderedText collects only text/code literals. The title is not emitted as either node type, so this assertion fails and cannot prove the claimed boundary. This is the unchanged blocker from the prior review.
  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 90d7db5c754e.

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: 🦐 gold shrimp: Current PR rating is rating: 🧂 unranked krab, so this older rating label is no longer current.

Label justifications:

• P2: This is a bounded build and automation prerequisite with a definite test failure, not an active user-facing outage.
• merge-risk: 🚨 automation: The PR makes npm installation a required step in three critical GitHub Actions 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: Not applicable: this MEMBER-authored PR is not subject to the external-contributor real-behavior-proof gate; listed validation remains supplemental.

Evidence

What I checked:

• Failing parser contract assertion: The walker appends only text and code literals, but the positive sentinel is solely a reference-definition title; that metadata produces neither node type, so the assertion cannot match it. (test/commonmark-runtime.test.mjs:67, 31f2feffac0d)
• Current main lacks the prerequisite: Current main has no CommonMark dependency, lockfile, or runtime test; its manifest ends after the Node engine declaration and the test path does not exist there. (package.json:46, 90d7db5c754e)
• Branch provenance: Blame attributes the unchanged broken assertion to the PR-head commit, matching the previous review’s blocker. (test/commonmark-runtime.test.mjs:61, 31f2feffac0d)
• Workflow change is dependency-specific: The PR installs the locked dependency with lifecycle scripts disabled before validation; the test directly imports CommonMark, so parser-runtime and supply-chain review applies. (.github/workflows/validate.yml:24, 31f2feffac0d)
• Paired work remains open: The PR body identifies fix(preflight): consume exact bot comment states #311 as the intended consumer; that related parser PR remains open, so this prerequisite is not superseded. (d9e138fd1d45)

Likely related people:

• vincentkoc: Authored the current-main external-merge preflight update and the proposed CommonMark runtime branch. (role: recent preflight contributor; confidence: high; commits: bcecd27124da, 31f2feffac0d; files: scripts/preflight-external-pr-merge.mjs, test/preflight-external-pr-merge.test.mjs, test/commonmark-runtime.test.mjs)

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 (46 earlier review cycles; latest 8 shown)

• 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
• 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