Skip to content

facts: read-only engine README plan; Node 20 in facts-validate - #190

Merged
luisleo526 merged 2 commits into
mainfrom
facts/engine-readme-plan
Nov 16, 2026
Merged

luisleo526 merged 2 commits into
mainfrom
facts/engine-readme-plan

Conversation

@luisleo526

Copy link
Copy Markdown
Contributor

Adds a read-only plan step for the engine README facts, and installs Node 20 in the facts-validate job so the facts renderer runs on the version it needs.

  • scripts/facts_engine_plan.py, scripts/facts_engine_release.py, scripts/facts_engine_render.mjs, scripts/facts_markdown.mjs: the plan reads the engine README facts without writing.
  • .github/workflows/facts-validate.yml: installs Node 20 before the facts steps.

🤖 Generated with Claude Code

scripts/facts_engine_plan.py plans an update of the engine README's fact
markers without writing anything remote. It reads the hub's main commit,
facts/facts.json, facts/facts.schema.json and VERSION through GitHub's
public REST API (GET only, no redirects, no proxies), selects the release
named by VERSION (scripts/facts_engine_release.py), resolves the engine's
release tag to its commit, renders the engine README through the pure
fact-marker renderer (scripts/facts_markdown.mjs, run by the Node 20
bridge scripts/facts_engine_render.mjs), and checks any open proposal pull
request by its plan identity. The output is a local review directory:
plan.json and, when the README changes, the proposed README. The plan is
marked superseded when the hub's main commit, the engine's default branch
or its commit moved during the run.

tests/test_facts_engine_plan.py runs the planner against loopback HTTP
servers and the real Node 20 bridge: 33 tests covering the create, noop,
already-planned, update-needed and superseded outcomes and the refusals.
The facts-validate job's CLI acceptance step runs every
tests/test_facts_*.py module, including the engine README plan tests,
which call the Node 20 bridge scripts/facts_engine_render.mjs. That bridge
refuses any other Node major, so the job now installs Node 20 with the
same pinned actions/setup-node release that python-test.yml uses, under
the job's existing docs-only condition.

@graphify-labs graphify-labs Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Graphify reviewed this change.

Worth a look — the grounded gate found no coupling regressions or blocking issues, but 3 advisory finding(s) below merit a look before merge.

Not checked: tests were not run; no formal proof of the changed code.


Graphify review — findings

Adds a read-only planner that builds a proposal for the engine README from public GitHub state, binding the facts, renderer source and proposed UTF-8 bytes to a plan identity. Every GitHub read goes through a GET-only transport that refuses redirects, ignores proxies, and sends the token only to the pinned origin. It checks exact repository identity, branch and annotated-tag resolution, Contents blob digests and capped pull-request pagination, and refuses on any mismatch rather than selecting silently, so the Content-Length-optional read path and the write_plan rollback on failure are where the guarantees can slip. Renders the README through a Node bridge with its own Markdown renderer, and installs Node 20 in the validation workflow for non-docs-only runs, so the bridge cannot run without it.

Worth a look

  • CLI failures can exit with status 0 — scripts/facts_engine_plan.py · Escalate · medium
    • unverified hypothesis — survived the adversarial refute pass; needs human review
  • Rollback can delete a concurrent replacement file — scripts/facts_engine_plan.py · Escalate · medium
    • unverified hypothesis — survived the adversarial refute pass; needs human review
  • Responses without Content-Length can bypass the size limit — scripts/facts_engine_plan.py:123 · Escalate · medium
    • unverified hypothesis — survived the adversarial refute pass; needs human review

Review partial — this diff was larger than one review pass covers, so later files were not reviewed; some findings may be missing.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 110 functions depend on the 110 functions this change touches.

Health — this change adds coupling hotspots:

  • new: build_engine_plan() — 2 callers, 6 callees

Verification — 110 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

  • verification_scope: 110 function(s) in the blast radius were not formally verified this run

Test selection

Test selection

35 of 35 test file(s) selected (100%) via static blast radius.

Escalated to a full run for safety (noncode-change, uncovered-code) — the selection is not trustworthy on its own (see below). CI should run the whole suite.

  • tests/test_facts_cards.py — full-run-safety
  • tests/test_facts_descriptions.py — full-run-safety
  • tests/test_facts_engine_plan.py — impact, changed-test, full-run-safety
  • tests/test_facts_fanout.py — full-run-safety
  • tests/test_facts_validate.py — full-run-safety
  • tests/test_fingerprint_canonical.py — full-run-safety
  • tests/test_parity_bundle.py — full-run-safety
  • tests/test_parity_source_proof.py — full-run-safety
  • tests/test_release_action_pins.py — full-run-safety
  • tests/test_release_asset_fetch.py — full-run-safety
  • tests/test_release_binding.py — full-run-safety
  • tests/test_release_binding_workflows.py — full-run-safety
  • tests/test_release_coordinator_receipts.py — full-run-safety
  • tests/test_release_docs_runtime.py — full-run-safety
  • tests/test_release_fanout_check.py — full-run-safety
  • tests/test_release_guard_policy.py — full-run-safety
  • tests/test_release_hosted_postmerge_receipts.py — full-run-safety
  • tests/test_release_hpo_image.py — full-run-safety
  • tests/test_release_main_push_inventory.py — full-run-safety
  • tests/test_release_pair.py — full-run-safety
  • tests/test_release_parity.py — full-run-safety
  • tests/test_release_parity_image.py — full-run-safety
  • tests/test_release_parity_runtime.py — full-run-safety
  • tests/test_release_parity_wire.py — full-run-safety
  • tests/test_release_receipt_collect_sweep.py — full-run-safety
  • tests/test_release_receipt_legacy_previous.py — full-run-safety
  • tests/test_release_receipt_shards.py — full-run-safety
  • tests/test_release_receipts.py — full-run-safety
  • tests/test_release_redeliver.py — full-run-safety
  • tests/test_release_runtime_smoke.py — full-run-safety
  • tests/test_release_sink_image.py — full-run-safety
  • tests/test_release_sources.py — full-run-safety
  • tests/test_release_workflows.py — full-run-safety
  • tests/test_repo_descriptions.py — full-run-safety
  • tools/release-dry-run/test_wfrun.py — full-run-safety

non-code file(s) changed (.github/workflows/facts-validate.yml) → running the full suite for safety (a code graph can't see config/fixture/data deps)

changed code file(s) with no mapped test (.github/workflows/facts-validate.yml, scripts/facts_engine_render.mjs, scripts/facts_markdown.mjs) — a coverage gap or a missing link — running the full suite rather than only the selected tests

Selection is safe under the controlled-regression assumption; always-run tests + a periodic full run are the backstops. Advisory — it never changes the check verdict.

Docs that may be stale (advisory)

…and 10 more.

· 1 grounded finding(s) anchored inline below.

return current


def build_engine_plan(api, renderer):

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Health regression — build_engine_plan()

fans out to 6 callees (efferent coupling).

Grounded coupling-delta finding (deterministic), not an LLM guess.

@luisleo526
luisleo526 merged commit 0a1c2aa into main Nov 16, 2026
11 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.

1 participant