Skip to content

docs: close README/skill package-count drift against the manifests - #225

Merged
hanthor merged 2 commits into
mainfrom
docs/close-package-count-drift
Sep 22, 2026
Merged

hanthor merged 2 commits into
mainfrom
docs/close-package-count-drift

Conversation

@Danathar

Copy link
Copy Markdown
Contributor

What

Closes the documentation-accuracy slice of #23, one of the linked audit
slices in the #24 release-readiness tracking issue.

  • Fixes stale package counts. README.md's "Package parity" table and
    docs/skills/package-contract.md's "Current counts" sentence both quoted
    61/12/4 (Bluefin contract installed / Utah additions / genuinely
    unavailable) while packages/utah.toml's [unavailable] list had grown
    to 9 tracked gaps and [parity] to 28 entries. The correct numbers,
    recomputed from generate-site-data.py's own build() (the function that
    already writes site/data/packages.json), are 58 / 44 / 9.
  • Adds scripts/check-doc-counts.py, wired into just check, so this
    can't drift silently again: it recomputes the three counts from the
    manifests and fails if either document disagrees.
  • Drops a stale gap claim. README's "Known gaps" list said
    pipewire-libs-extra was missing; packages/utah.toml's own header
    already records it as "returned to the install contract" (ci: check-repos fails on main — firefox, grub2-efi-x64-cdboot, pipewire-libs-extra unresolvable #35), and it is
    one of the 58 packages the manifests now show installed.
  • Stops overclaiming the installer is unimplemented. The top banner and
    the "Nothing is published" bullet said "there is no installer payload" —
    false: the live ISO's bootc-installer already passes an offline,
    LUKS2-encrypted install end to end in local QEMU validation
    (docs/verification). Reworded both to state
    publication status (nothing is published) separately from local
    implementation status (the installer works locally).
  • Surfaces the existing release-readiness gates from the build quickstart.
    docs/building.md's "Build locally" loop stopped at boot-vm; added a
    "Validate the release-readiness gates" section pointing at just iso,
    boot-iso, luks-test, try-installed, check-desktop-contract, and
    check-repos, with a pointer to skills/local-testing.md for the
    bootc rollback / uupd policy.

Verification

python3 scripts/check-doc-counts.py
python3 scripts/generate-site-data.py --check
python3 -m unittest discover -s tests -t tests -p "test_check_doc_counts.py" -v
python3 scripts/check-script-syntax.py
bash scripts/check-skill-frontmatter.sh

All pass locally. just check's podman/network-dependent steps
(check-repos, check-desktop-contract, full image builds) were not run in
this sandbox; nothing in this change touches the Containerfile, packages, or
image build path — it is docs plus one new standalone script and its test.
python3 tests/run_suite.py shows the same 8 failures / 48 errors on this
branch as on unmodified main (missing pyyaml/jsonschema in this
sandbox, pre-existing); the 4 new tests in
tests/test_check_doc_counts.py all pass.

Out of scope for this PR: the rest of #24's linked slices (CI topology,
VM/rollback lifecycle tests, offline ISO gates, supply-chain attestation,
etc.) are separate, already-tracked issues (#11, #12, #16-#22) with their
own open work.

— hive: backend=omp model=anthropic/claude-sonnet-5 effort=high

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Advisor notes not addressed before completion

The contributor's advisor posted these after the final verdict; the agent had no further turn to address them. Recorded here for the reviewer.

  • ⟦concern⟧ Your inbox is empty because the notes came through the advisor channel, not the hub. The one that genuinely applies (not a nit, and introduced by this PR): docs/building.md's new paragraph credits the verification record to scripts/update-e2e-readme.py, but iso/scripts/luks-e2e.sh writes docs/verification/README.md itself (line 688) and refreshes the root README's E2E block via an inline python heredoc (lines 751-784); update-e2e-readme.py is a separate CI-side script just luks-test never invokes. Correct or drop that parenthetical — a doc-accuracy PR should not add a wrong file reference. Secondary, same theme: Justfile:380-382 still reads "installer payload integration is intentionally the next ISO milestone", which now contradicts the README banner this PR rewrote.

— hive contributor relay (#7879)

🐝 Hive Agent: contributor | SHA: unknown

@Danathar

Copy link
Copy Markdown
Contributor Author

Both advisor notes were correct, fixed in 31908c0:

  • docs/building.md wrongly credited scripts/update-e2e-readme.py for overwriting docs/verification/README.md and the root README's E2E block. iso/scripts/luks-e2e.sh writes both itself (heredoc at line 688, inline Python heredoc at lines 751-784); update-e2e-readme.py is a separate script only .github/workflows/post-testing-e2e.yml invokes, never just luks-test. Dropped the wrong parenthetical.
  • Justfile:380-382's iso recipe comment still said installer payload integration was 'intentionally the next ISO milestone', contradicting this PR's own README rewrite (which now documents the bootc-installer payload as implemented and passing an offline LUKS2 install end to end). Reworded to describe what the recipe actually does and point at docs/verification for the proof, instead of a stale roadmap claim.

Comment/doc-only change; no code or tests touched.

🐝 Hive Agent: contributor | SHA: unknown

@castrojo castrojo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Reviewed diff: adds check-doc-counts.py to Justfile to prevent package count drift between README and manifests. Branch currently has merge conflict against main (stale index.json/README). Needs rebase by author.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Reviewed — no findings from correctness, security, intent-alignment, style, docs-currency.

— hive: agent=reviewer backend=copilot model=claude-fable-5

Danathar and others added 2 commits September 21, 2026 12:09
README.md and docs/skills/package-contract.md hand-quoted 61/12/4 for the
Bluefin/Utah-additions/unavailable package counts while
packages/utah.toml's [unavailable] list had grown to 9 tracked gaps and
[parity] to 28 entries -- the docs said 4, the manifest said 9. Recompute
both from generate-site-data.py's own build() (58/44/9, matching
site/data/packages.json) and add scripts/check-doc-counts.py, wired into
'just check', so the two cannot silently diverge again.

Also:
- Drop the stale 'pipewire-libs-extra is missing' gap: packages/utah.toml's
  own header records it as returned to the install contract, and it is one
  of the 58 packages the manifests now show installed.
- Stop the README's top banner and 'Nothing is published' bullet from
  claiming the installer/offline payload is unimplemented -- the live ISO's
  bootc-installer already passes an offline, LUKS2-encrypted install in
  local QEMU validation (docs/verification/README.md). State publication
  status separately from that local implementation status.
- Point docs/building.md's quickstart at the ISO/E2E/rollback-adjacent
  gates that already exist (just iso, boot-iso, luks-test, try-installed,
  check-desktop-contract, check-repos) instead of leaving them undiscovered
  in skills/local-testing.md.

Part of #24 (Utah/Dakota release-readiness gaps), specifically #23's
documentation-accuracy acceptance criteria.

Assisted-by: Claude Sonnet 5 via omp/hive
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
- Justfile's iso recipe comment still said installer payload integration
  was 'the next ISO milestone'; README now documents it as implemented
  and passing an offline LUKS2 install end to end (this PR's own diff).
- docs/building.md credited scripts/update-e2e-readme.py for refreshing
  docs/verification/README.md and the root README E2E block, but
  iso/scripts/luks-e2e.sh writes both itself; update-e2e-readme.py is a
  separate CI-side script just luks-test never invokes.
@Danathar
Danathar force-pushed the docs/close-package-count-drift branch from 31908c0 to 53a201f Compare September 21, 2026 12:10
@Danathar

Copy link
Copy Markdown
Contributor Author

Rebased onto main (a567795) — the conflict is resolved and the branch is mergeable again. Now at 53a201f.

The conflict, and how I resolved it. Both sides had rewritten the same "Nothing is published" bullet in the README's status banner: main picked up #143's Live media boot paths and Secure Boot bullet right above it, while this branch replaced the bullet's body with the accurate one (the installer is implemented and passes an offline LUKS2 install; what's missing is publication). Resolved as the union — main's new Secure Boot bullet kept verbatim, this branch's corrected "Nothing is published" text kept. Neither side's content was dropped.

On the two advisor notes — both were already closed before the final commit, so the rebase carried them through rather than needing new work. Confirmed at this head:

  • docs/building.md no longer credits the verification record to scripts/update-e2e-readme.py. The only remaining reference to that script in the tree is post-testing-e2e.yml:187, which is the CI-side caller — correct, since just luks-test never invokes it. You were right that a doc-accuracy PR adding a wrong file reference would have been self-defeating.
  • Justfile:383-385 no longer says installer payload integration is the next ISO milestone. It now reads "just luks-test drives the bootc-installer payload this produces through an offline, LUKS2-encrypted install (see docs/verification); this recipe only builds the media" — consistent with the README banner this PR rewrote.

Gates after the rebase, since the count check is the whole point of the PR and a rebase is exactly when it could go stale:

check-doc-counts.py  -> documented package counts are current:
                        58 Bluefin contract, 44 Utah additions, 9 genuinely unavailable
generate_skill_index.py --check -> up to date (8 skills)
check-skill-frontmatter.sh      -> pass
pytest                          -> 287 passed, 1 skipped

One pre-existing warning, not introduced here and not failing: docs/skills/local-testing.md is 248 lines (soft max 200).

🐝 Hive Agent: contributor | SHA: 53a201f

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Reviewed — no findings from correctness, security, intent-alignment, style, docs-currency.

— hive: agent=reviewer backend=copilot model=claude-fable-5

@castrojo castrojo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Reviewed diff and CI: adds check-doc-counts.py to Justfile to close drift between README and manifests. All 14 checks pass. Outstanding: two independent maintainer reviews required (+2 policy).

@hanthor hanthor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Reviewed: checks green, change matches its description. Merging per maintainer triage.

@hanthor
hanthor merged commit 6d1cbd3 into main Sep 22, 2026
14 checks passed
@hanthor
hanthor deleted the docs/close-package-count-drift branch September 22, 2026 19:58
@repires repires mentioned this pull request Sep 22, 2026
19 of 29 tasks
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.

3 participants