Skip to content

docs: generate the Mintlify changelog, sync the site with the review fixes, clear CodeQL - #165

Merged
CodeWithJuber merged 5 commits into
masterfrom
claude/forgekit-deep-review-issues-ww6y0h
Sep 26, 2026
Merged

CodeWithJuber merged 5 commits into
masterfrom
claude/forgekit-deep-review-issues-ww6y0h

Conversation

@CodeWithJuber

Copy link
Copy Markdown
Owner

What & why

This is a follow-up to #164, which merged with one red check: CodeQL flagged one new high-severity alert. The Mintlify changelog page had also fallen behind: it had one hand-written entry from July while about thirty releases shipped. Several doc surfaces still described behavior from before the review fixes.

1. Security: CodeQL goes from 3 results to 0. I verified this with a local run of the same CodeQL version (2.27.0, javascript-code-scanning suite).

2. The Mintlify changelog page is generated from CHANGELOG.md.

  • src/changelog_page.js renders every release, plus [Unreleased], as a Mintlify <Update> entry: 62 entries and 428 headlines. Each entry has filter tags and a link to that release's full notes on GitHub.
  • forge docs render writes the page between JSX-comment markers, because MDX rejects HTML comments. It is a strict target, so forge docs check fails when the page is stale.
  • scripts/bump.mjs regenerates the page in the release commit, so a release can't leave it behind.
  • All 19 Mintlify pages compile under MDX 3.
  • The generated page surfaced two corrections to the CHANGELOG:
    • 1.1.2 called the project's own second-machine re-run an "independent replication". It now carries a dated correction.
    • 1.0.0 had lost the \r\n escapes inside two code spans.

3. Docs synced with the merged fixes.

  • Mintlify reference pages:

    • forge verify: per-package coverage, pre/post binding, verifier events, .forge/forge.config.json.
    • forge stack: available runners.
    • forge context: what COMPLETE means, --block.
    • forge reuse and forge ledger: lossless keys, serve-time revalidation, one vote per event, archive reasons, conflicts, --fix --dry-run.
    • forge dash: Host check on every route, session token.
    • The universal router, which the site did not document at all.
  • Landing page: now lists all ten native targets; OpenClaw was missing. The grid was checked in headless Chromium at 8 widths: rows are always full and nothing overflows.

  • Claim registry: I re-ran the review's probes on the merged commit 7eef611, as regression tests: 46 pass, and 1 skip needs a non-root user. The claims found refuted at d2abfa6 are re-assessed:

    Status now Claims
    implemented verify binding, context completeness, exact reuse (scope in the notes)
    partial evidence independence, outcome provenance
    still refuted the imagine "sandbox" claim, the router target guarantee

    The impact fixture's F1 is updated to 0.28.

  • Config and contributor docs: biome.json is migrated to the installed Biome 2.5.13, with lint results unchanged. CLAUDE.md now states the right Biome version and says to run docs render after editing the CHANGELOG.

Checklist

  • npm test passes: 1,692 tests, 1,688 pass, 0 fail, 4 platform-gated skips (Node 22 locally)
  • npm run check passes (Biome lint + format)
  • New public functions have a test
  • Conventional commit message (feat:/fix:/docs: …)
  • CHANGELOG.md updated under ## [Unreleased]
  • No new runtime dependency (dev deps ok). The MDX compile and Chromium checks ran from a scratch directory, not the repo.
  • Substrate/docs updated if this changes forge substrate, forge impact, router/gate, or MCP substrate tools

Risk & rollback

  • Risk level: low. The regex replacements are behavior-identical, and each is tested against its old regex. The rest is docs, plus one new strict docs-check target.
  • One new contributor step: after editing CHANGELOG.md, run node src/cli.js docs render. The docs check names this fix when it fails, and CLAUDE.md states it.
  • Rollback plan: revert the merge commit.

Extra checks (tick if applicable)

  • npm run typecheck passes
  • Input validated at boundaries; errors handled (no swallowing)
  • Authorization/ownership checked (if it touches access): n/a
  • Logs contain no secrets/PII
  • If AI-assisted: I understand it, verified the package APIs, and it has tests

🤖 Generated with Claude Code

https://claude.ai/code/session_01GVVG2VDETWsDxMu6MBWPz2


Generated by Claude Code

CodeQL flagged one new high-severity alert in #164 and two older ones.
A local run of the same CodeQL version (2.27.0, javascript-code-scanning
suite) goes from 3 results to 0 with this change.

- scripts/claims-status.mjs (js/incomplete-sanitization, new in #164):
  table cells escaped `|` but not `\`, so a trailing backslash could
  undo the escape. Backslashes are escaped first.
- src/model_catalog.js (js/polynomial-redos, pre-existing): the
  tokenizer's `/(?:\.0)+$/` and trimUrl's `/\/+$/` backtracked
  quadratically on library input. Trailing ".0" parts are popped
  instead, and URLs use a new linear stripTrailingSlashes (src/util.js).
- The same patterns in code added by #164 are hardened too: the
  workspace-glob trim (src/stack.js) and the semantic guard's edge
  punctuation trim, now a code-point scan (trimEdges).

Each replacement is checked against the regex it replaced (tokenize on
known ids; trimEdges on 2,000 seeded random tokens) and gets a
linear-time test on a hostile input.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GVVG2VDETWsDxMu6MBWPz2
The docs site's changelog page was hand-written and stopped at one July
entry while thirty releases shipped. It is now generated:

- src/changelog_page.js parses CHANGELOG.md and renders every release,
  plus [Unreleased], as a Mintlify <Update> entry: each change's
  headline (the bold lead, else the first sentence), filter tags per
  section, and a link to the release's full notes on GitHub. Text is
  made MDX-safe outside code spans, and relative links point at GitHub.
- forge docs render splices it between JSX-comment markers (MDX rejects
  HTML comments). It is a strict target, so forge docs check fails when
  the page is stale.
- scripts/bump.mjs regenerates the page in the release commit, so a
  release never leaves it behind (the bump workflow commits with
  git add -A).

All 19 Mintlify pages compile under MDX 3. CHANGELOG corrections that
the page surfaced: 1.1.2 called the project's own second-machine re-run
an independent replication (now a dated correction), and 1.0.0 had lost
the \r\n / \n escapes inside two code spans. GUIDE, ARCHITECTURE, the
Mintlify README/CLI page and CLAUDE.md describe the new surface.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GVVG2VDETWsDxMu6MBWPz2
After the 2026-09-26 review fixes merged (#164), several surfaces still
described the old behavior:

- Mintlify reference: forge verify (per-package coverage, pre/post
  binding, verifier events, .forge/forge.config.json), forge stack
  (available runners), forge context (what COMPLETE means, --budget,
  --block), forge reuse and forge ledger (lossless keys, serve-time
  revalidation, one vote per event, archive reasons, conflicts,
  --fix --dry-run), forge dash (Host check on every route, session
  token), and the universal router, which the site did not cover at all
  (objectives, INFEASIBLE, advice-only models, outcome provenance, and
  the limits of its evidence).
- Landing page: all ten native targets (OpenClaw was missing, "Nine
  native targets"). The grid is now two rows of five on wide screens and
  two columns below 1180px, checked in headless Chromium at eight widths
  with no overflow or horizontal scroll.
- Claim registry: the claims the review found refuted at d2abfa6 are
  re-assessed on 7eef611 (the merge), after re-running the review's
  probes as regression tests (46 pass; 1 skip needs a non-root user):
  verify binding, context completeness and exact reuse are implemented
  (with their scope in the notes); evidence independence and outcome
  provenance are partial; the imagine sandbox and router target claims
  stay refuted. The impact fixture's F1 is 0.28 after the CLI move.
- biome.json migrated to the installed Biome 2.5.13 (schema URL;
  `recommended` → `preset`); lint results unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GVVG2VDETWsDxMu6MBWPz2
@CodeWithJuber
CodeWithJuber marked this pull request as ready for review September 26, 2026 21:32
The v1.5.0 release commit (fd71bf8) moved the [Unreleased] notes of #164 under
[1.5.0] and bumped the version strings; this branch had added its own notes to
the same [Unreleased] section, so the PR could not merge and CI never ran.

Resolution:
- CHANGELOG.md: this PR's four new entries (the CodeQL fixes, the generated
  changelog page, the Mintlify reference sync and the two historical
  corrections) move back to [Unreleased]; [1.5.0] keeps exactly what shipped,
  apart from this PR's bold headline leads. Fixes a doubled "separately" in the
  Qur'anic-lens entry.
- landing/index.html: this branch's page with the release's version strings
  (softwareVersion and both "forgekit v1.5.0" labels), as scripts/bump.mjs
  writes them.
- mintlify/changelog/overview.mdx: re-rendered with `forge docs render`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GVVG2VDETWsDxMu6MBWPz2
…t stale

The Windows CI job (Git Bash, core.autocrlf) failed "the repository's
changelog page is current": the page checks out with CRLF while
`forge docs render` emits LF, so the byte comparison could never match.
`forge docs check` had the same fault for every strict block on a
Windows checkout, and `forge docs render` wrote LF block lines into
CRLF files.

src/docs_render.js now reads each managed doc in LF (renderDocs and
renderFile), compares in LF, and writes a changed file back in its own
line endings. The page test normalizes the file it reads. New tests
reproduce a CRLF checkout for both render paths; both fail against the
old renderer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GVVG2VDETWsDxMu6MBWPz2
@CodeWithJuber
CodeWithJuber merged commit 6747978 into master Sep 26, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants