Skip to content

docs: state the mechanism directly in the entry-point READMEs - #91

Merged
kmadan merged 2 commits into
mainfrom
docs/entry-point-readme-register
Aug 30, 2026
Merged

docs: state the mechanism directly in the entry-point READMEs#91
kmadan merged 2 commits into
mainfrom
docs/entry-point-readme-register

Conversation

@kmadan

@kmadan kmadan commented Aug 30, 2026

Copy link
Copy Markdown
Contributor

What this changes

Rewrites the introductory sections of the three entry-point READMEs so they read
as reference documentation rather than narration, and corrects several imprecise
descriptions. Documentation only; no .rego file is touched.

Type

  • New policy (specify framework path)
  • New framework directory
  • Policy update (semver MINOR — backward compatible)
  • Policy update (semver MAJOR — breaking; new v2/ directory)
  • Bug fix
  • Tooling / CI / docs

Detail

README.md, examples/model-switch/README.md and docs/coverage/README.md
mixed two registers. Their reference sections read as documentation; their
introductory sections staged behaviour as a sequence of events, used fragments
for emphasis, and put unnamed people in place of the component doing the work.
Those sections now state the condition, the mechanism and the result, with the
policy, the score or the threshold as the grammatical subject.

Four descriptions were also imprecise and are corrected:

  • The model-switch caption described a live model swap. The example compares
    checked-in baseline and candidate toxicity metrics with the prompts, the
    scoring method and the policy held fixed.
  • "Why GOPAL" characterised the alternatives by naming vendor categories. It now
    states what generic policy-as-code and proprietary governance platforms each
    supply, and where an open AI-regulatory policy library differs. A Portable
    point is added, covering opa eval, Conftest, an existing OPA server and
    AICertify.
  • The declared/measured distinction now states why a supplied number remains a
    declaration unless the evaluator evidence behind it is supplied as well.
  • The EU AI Act figure is stated as 185 input-field reads rather than 185
    fields, which is what the count measures; unique declared fields are fewer.

An earlier correction rides along in 1685c11: 4321e7a moved the EU split to
170 declarations and 15 measurements but left the following sentence reading 14.

Every claim, figure, link and heading target is preserved. Verified against the
tree: 29 EU AI Act policy files, and the 170/15/185 split unchanged from main.

Checklist

  • Every new .rego has a sibling *_test.rego — n/a, no .rego changed
  • Metadata block present on every new policy — n/a, no new policy
  • Framework-level README.md lists the new policy — n/a, no new policy
  • opa check --ignore custom/ . passes locally
  • regal lint --ignore-files custom/ . passes locally
  • Not breaking; no v2/ directory required

Also run locally, all passing: check-anchors.sh, check-version-refs.sh,
check-test-coverage.sh, check-deprecations.sh, generate-coverage.sh --check,
model-card-coverage.sh --check.

Source(s)

No regulation is encoded or reinterpreted by this PR.

Notes for reviewers

These two commits were pushed to chore/zenodo-2-0-0-doi after #90 had already
merged, so they were stranded on a closed PR's head branch and never reached
main. This PR carries them across unchanged; nothing is rebased or squashed.

Four framework READMEs (examples/github-actions/, industry_specific/,
international/, international/uk/) carry one-line wording changes from
1685c11 and are included in the diff for that reason.

Reviewing 86a986e and 1685c11 separately is easier than reading the combined
diff, since the second commit rewrites paragraphs the first had already touched.

kmadan added 2 commits August 30, 2026 07:46
The root README, the model-switch example and the coverage index mixed two
kinds of prose. The reference sections read as documentation; the introductory
sections read as narration, with fragments used for emphasis, behaviour staged
as a sequence of events, and unnamed people standing in for the component doing
the work. A reader arriving at the repository meets the narrated sections
first, which are the hardest to skim and the slowest to answer "what does this
do and how".

Those passages now state the condition, the mechanism and the result directly,
with the policy, the score or the threshold as the grammatical subject. Every
claim, figure, link and heading target is unchanged, the "Jump to" anchors
still resolve, and opa check, regal lint, check-anchors.sh, check-version-refs
and model-card-coverage --check all pass.

Two substantive corrections ride along:

- 4321e7a moved the EU field split to 170 declarations and 15 measurements but
  left the next sentence reading 14. It now reads 15.
- "The problem" described an AI system as changing on the order of weeks. Model
  swaps, prompt edits and index rebuilds now land on the order of days.
The introductory sections of README.md, examples/model-switch/README.md and
docs/coverage/README.md narrated behaviour as a sequence of events, while the
reference sections already read as documentation. A reader arriving at the
repository meets the narrated sections first. Those sections now state the
conditions and the resulting policy outcome, with the score, the threshold and
the rule as the subject.

Several descriptions were also imprecise:

- The model-switch caption described a live model swap. The example compares
  checked-in baseline and candidate toxicity metrics with the prompts, the
  scoring method and the policy held fixed.
- "Why GOPAL" characterised the alternatives by naming vendors. It now
  describes what generic policy-as-code and proprietary governance platforms
  each supply, and where an open AI-regulatory policy library differs.
- The declared/measured distinction now says why a supplied number remains a
  declaration unless the evaluator evidence behind it is supplied as well.
- The EU AI Act figure is stated as 185 input-field reads rather than 185
  fields, which is what the count measures; unique declared fields are fewer.

Every claim, figure, link and heading target is preserved. opa check, regal
lint, check-anchors.sh, check-version-refs.sh, check-test-coverage.sh,
check-deprecations.sh, generate-coverage.sh --check and model-card-coverage.sh
--check all pass.
@kmadan
kmadan merged commit dc8bae2 into main Aug 30, 2026
3 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