Skip to content

chore: keep the book current, the website rule, the same-PR book guard and the docs guards - #53

Merged
rubentalstra merged 2 commits into
mainfrom
chore/docs-upkeep
Oct 21, 2026
Merged

rubentalstra merged 2 commits into
mainfrom
chore/docs-upkeep

Conversation

@rubentalstra

Copy link
Copy Markdown
Collaborator

What changed and why

The working discipline and the guards that keep the book at https://ferropix.eu/ in step with the code, ported from the siblings (FerroEHR's docs-website rule and docs-claims guard, the family book's writing-style guard, the changelog guard's shape for the same-PR rule).

  • .claude/rules/docs-website.md, path-scoped to the site: layout and URLs, the family-book split, the same-PR rule, authoring rules (built versus planned with a tracker link, sibling wiring said as planned, no typed versions), what a gate checks and what only review can, the toolchain and the 1440/390 light/dark look before a website PR merges.
  • CLAUDE.md: the "Keep the book current" hard rule, the guards in the repo map, the rule and the new hook in the discipline list. /phase-done gains the book check; the pull request template asks for it; a memory note records the owner's order.
  • scripts/checks/book-guard.sh (CI book-guard, pull requests): a change to crates/*/src/**, a crate's [features], app/**, docker/**, deploy/** or a compose file must touch website/book/src, or carry the new no-book label (added to scripts/gh/labels.sh and created). A version bump, a dependency move or a test alone is no surface: the book renders versions.
  • scripts/checks/docs-claims.sh (CI docs-claims): every published crate has its page and its row on the crates page; its Features table names exactly the features of its Cargo.toml, both ways; no page types its current version; every section that says "planned" links a FerroHEALTH tracker issue or milestone.
  • scripts/checks/writing-style.sh (CI docs-claims, and the new docs_style.sh PostToolUse hook on every edit): em dashes, the buzzword list and AI attribution over the published prose (website, root and crate markdown).
  • All three have a --self-test, run by the self-tests job, and both new jobs are in the required conclusion.
  • The book: the owner's decision that lookups by a patient identifier use POST, in the security page, the ihe-iti PIXm and PDQm sections, the configuration table and the getting-started example (now .invoked_by(Invocation::Post)): the planned PIX Manager accepts $ihe-pix by GET (ITI-83) and by POST with a Parameters body (FHIR R4 Operations §3.2.0.1) and logs no URL query (The PIX Manager answers $ihe-pix by POST as well as GET, and no request log records a URL query #52); FerroHEALTH clients call by POST so a BSN never appears in a URL; proxies must not log query strings. The "keeping the book current" page lists the four guards, and two "test harness" phrasings are reworded for the writing-style guard.

Closes #48

Licensing of contributions

  • I accept the terms in CONTRIBUTING.md § Licensing of contributions: I have the right to submit this work, I license it under the project licence of the version it lands in, and I grant the Licensor the relicensing right stated there.

Checklist

  • Every conformance decision cites the specification (the IHE ITI Technical Framework, PIXm, PDQm, HL7 FHIR R4, HL7 v2), never memory and never another implementation.
  • Rust gates pass, once the workspace has a member: no Rust changes.
  • Every refusal the change adds has an asserted negative test, and no test was weakened to pass.
  • Shell and workflow files are clean: shellcheck --severity=style, actionlint, zizmor --min-severity=low .github/, and the self-test of every script the change touches.
  • CHANGELOG.md has an [Unreleased] entry.
  • The book under website/book/src is updated for every user-visible change.
  • No patient data, real identifier, key, token or password in a fixture, test or example.
  • Every commit is signed.
  • No AI or assistant attribution anywhere in the commits or this PR.

…d and the docs guards

.claude/rules/docs-website.md, path-scoped to the site, holds the layout,
the family-book split, the authoring rules and what a gate checks against
what only review can. CLAUDE.md gains the same-PR book rule as a hard rule,
phase-done checks it at close and the pull request template asks for it.
Three guards with self-tests join CI's required conclusion: book-guard.sh
refuses a change to a crate's source or features, the server or a
deployment file that leaves the book alone, with the new no-book label as
the escape; docs-claims.sh holds each crate's Features table to its
Cargo.toml both ways, refuses a typed crate version and a planned item
without its tracker link; writing-style.sh refuses an em dash, a banned word
or AI attribution in the published prose, which the new docs_style.sh hook
also runs on every edit.
The owner's decision, in the security page, the ihe-iti page's PIXm and
PDQm sections, the configuration table and the getting-started example:
FerroPIX's planned PIX Manager is to accept $ihe-pix by GET (ITI-83) and by
POST with a Parameters body (FHIR R4 Operations 3.2.0.1) and keep no URL
query in a request log (#52); FerroHEALTH clients call it by POST
(ihe_iti::pixm::Invocation::Post), so a BSN never appears in a URL; and a
proxy in front of a Manager must not log query strings.
@rubentalstra rubentalstra added this to the v0.0.3 milestone Oct 21, 2026
@rubentalstra rubentalstra added the chore Maintenance with no product change. chore/ and chore:. label Oct 21, 2026
@rubentalstra
rubentalstra added this pull request to the merge queue Oct 21, 2026
Merged via the queue into main with commit 0870f08 Oct 21, 2026
33 of 60 checks passed
@rubentalstra
rubentalstra deleted the chore/docs-upkeep branch October 21, 2026 10:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

chore Maintenance with no product change. chore/ and chore:.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Keep the book current: the website rule, the same-PR book rule and the docs guards

1 participant