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: blocked before merge. Reviewed September 4, 2026, 11:00 AM ET / 15:00 UTC.

ClawSweeper review

What this changes

The PR pins CommonMark, installs it in three GitHub workflows, and adds a contract test for parser availability and Markdown text extraction.

Merge readiness

⛔ Blocked before merge - 8 items remain

Keep open: this member-authored prerequisite remains distinct from current main, but its newly added test has the same unresolved P1 failure identified in the previous review cycle.

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 introduced contract test conflicts with its own parser walk and leaves the patch not quality-ready.
Proof confidence	🌊 off-meta tidepool	Not applicable: Not applicable: this is a member-authored CI/dependency PR without a contributor real-behavior-proof gate; its supplied validation claims are supplemental, and the introduced test remains source-invalid.
Patch quality	🧂 unranked krab (1/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: Not applicable: this is a member-authored CI/dependency PR without a contributor real-behavior-proof gate; its supplied validation claims are supplemental, and the introduced test remains source-invalid.
Evidence reviewed	5 items	Introduced test cannot observe its positive sentinel: The introduced helper appends only entered text and code node literals, while the positive fixture places “Do not merge.” solely in a link-reference definition title. That metadata is not rendered document text, so the assertion cannot pass. Previous blocker remains at the identical head: The prior completed ClawSweeper review raised “Put the positive sentinel in visible Markdown” against this exact head; no new commit has changed the file. Current main does not contain this prerequisite: Current main has no CommonMark dependency or lockfile and its workflow diff removes this branch’s dependency-install steps, so the requested runtime has not been implemented there.
Findings	1 actionable finding	[P1] Use visible Markdown for the positive sentinel
Security	None	None.

How this fits together

Clownfish workflows validate and preflight repository automation before guarded external merges. This change provides a locked Markdown parser runtime intended for review-text interpretation and installs it before those workflow commands run.

flowchart LR
  A[Workflow checkout] --> B[Install locked dependencies]
  B --> C[Validation and preflight commands]
  C --> D[CommonMark parser runtime]
  D --> E[Review-text interpretation]
  E --> F[Guarded external merge decision]

Loading

Decision needed

Question	Recommendation
Should Clownfish adopt CommonMark as a permanent locked runtime for external-merge review text, and should that dependency land separately from its consumer?	Approve the paired parser direction: Repair the test, rebase the workflow changes, and land the runtime in coordinated sequence with its review-text consumer.

Why: This introduces a lasting third-party runtime and CI installation boundary, while the intended parser consumer remains a separate open PR.

Before merge

• Use visible Markdown for the positive sentinel (P1) - renderedText appends only entered text and code node literals, but lines 65–67 place the sentinel solely in a link-reference definition title. CommonMark does not expose that metadata as rendered document text, so this assertion cannot pass; put the positive sentinel in visible Markdown and retain the title-only negative case.
• Resolve merge risk (P1) - The broken positive assertion makes the added test suite fail and leaves the claimed Markdown-boundary contract unproven.
• Resolve merge risk (P1) - The dependency-install edits must be rebased and revalidated against the current workflow layout so clean-runner automation remains reliable.
• Complete next step (P2) - Repair the visible-sentinel fixture, rebase onto current main, and obtain maintainer approval for the CommonMark runtime landing strategy before merge.
• Improve patch quality - Put the positive sentinel in visible parsed text while preserving a separate reference-title exclusion assertion.
• Improve patch quality - Rebase onto current main and rerun the exact-head workflow validation after the fixture is corrected.
• Improve patch quality - Obtain maintainer direction on whether the runtime should land separately from its paired consumer.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

• [P1] Use visible Markdown for the positive sentinel — test/commonmark-runtime.test.mjs:65-69

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Introduced surface	6 files affected: production +74, tests +82	Most production growth is a lockfile and three workflow install steps; the added test must reliably validate that boundary.

Merge-risk options

Maintainer options:

1. Repair and refresh the CI boundary (recommended)
   Move the positive sentinel into visible Markdown, retain the title-exclusion case, then rebase and rerun exact-head workflow validation.
2. Fold the prerequisite into its consumer
   Avoid a standalone parser dependency by incorporating the corrected runtime setup into the paired preflight parser change.

Technical review

Best possible solution:

Land the parser runtime only with a corrected visible-text regression fixture and a current-main rebase, ideally coordinated with the paired consumer at #311 so the permanent dependency has a real production use.

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

Yes, from source: the introduced AST walk cannot emit the reference-definition title used by the positive assertion, so the added test has a high-confidence failing path. No target code was executed during this read-only review.

Is this the best way to solve the issue?

No: the intended parser setup is reasonable, but the positive fixture does not test rendered text and the standalone dependency needs an explicit decision about landing it separately from its consumer.

Full review comments:

• [P1] Use visible Markdown for the positive sentinel — test/commonmark-runtime.test.mjs:65-69
renderedText appends only entered text and code node literals, but lines 65–67 place the sentinel solely in a link-reference definition title. CommonMark does not expose that metadata as rendered document text, so this assertion cannot pass; put the positive sentinel in visible Markdown and retain the title-only negative case.
  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 d3cb84d34b7e.

Labels

Label justifications:

• P2: The PR has a definite but bounded pre-merge test defect in CI/preflight infrastructure.
• merge-risk: 🚨 automation: It adds dependency installation to three GitHub workflows, where clean-runner and cache behavior affect automation execution.
• 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 is a member-authored CI/dependency PR without a contributor real-behavior-proof gate; its supplied validation claims are supplemental, and the introduced test remains source-invalid.

Evidence

What I checked:

• Introduced test cannot observe its positive sentinel: The introduced helper appends only entered text and code node literals, while the positive fixture places “Do not merge.” solely in a link-reference definition title. That metadata is not rendered document text, so the assertion cannot pass. (test/commonmark-runtime.test.mjs:65, 31f2feffac0d)
• Previous blocker remains at the identical head: The prior completed ClawSweeper review raised “Put the positive sentinel in visible Markdown” against this exact head; no new commit has changed the file. (test/commonmark-runtime.test.mjs:69, 31f2feffac0d)
• Current main does not contain this prerequisite: Current main has no CommonMark dependency or lockfile and its workflow diff removes this branch’s dependency-install steps, so the requested runtime has not been implemented there. (package.json, d3cb84d34b7e)
• Locked dependency and lifecycle control: The added lockfile pins CommonMark and its transitive packages with integrity hashes, while each introduced install command uses npm ci with lifecycle scripts disabled. (package-lock.json:17, 31f2feffac0d)
• Workflow-area history: Vincent Koc previously maintained the cluster-worker workflow through the merged workflow serialization change; Peter Steinberger most recently updated the workflow actions on main. (.github/workflows/cluster-worker.yml, 2daa0340388a)

Likely related people:

• vincentkoc: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Peter Steinberger: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

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

• 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
• reviewed 2026-08-29T12:00:10.966Z sha 31f2fef :: needs changes before merge. :: [P1] Put the positive sentinel in visible Markdown