docs: state the open-execution wedge on the acquisition surfaces - #88
Merged
Conversation
github-actions
Bot
added
📝 documentation
Prinevo
approved these changes
Aug 30, 2026
The README, the PyPI description and the CLI help are the first three surfaces a prospective user meets, and each described AICertify by its output formats rather than by what distinguishes it: the policy logic is open, versioned Rego that a third party can re-run against the same inputs. README.md now leads with open execution and evidence, carries a jump navigation for the four questions a first-time reader asks, and makes reproducibility the primary differentiation rather than framework breadth. The declared-facts and measured-evidence distinction is stated explicitly, since a supplied number is an assertion unless the evaluator evidence behind it is supplied too. The canonical example becomes `aicertify evaluate`, and the demo's fail-closed result is described as intended behaviour rather than left to look like a defect. main carried two "Why AICertify" sections; the second is replaced by "What makes an AICertify result reproducible". README-pypi.md is resynchronised with the README, and pyproject's description states the same wedge so PyPI search results carry it. Three accuracy corrections: - The policy count read 91 in README.md and 85 in README-pypi.md. The GOPAL tree pinned at aicertify/opa_policies reports 92 policies, all 92 with tests and empty-input tests, per docs/coverage/coverage.json totals. - cli.py documented "Two subcommands". The parser registers five: demo, evaluate, explain, init-contract and score-card. - The "10-second demo" claim in cli.py help and README-pypi.md is unmeasured and is removed. No behaviour changes; the only cli.py edits are the module docstring and the parser description string. Verified: cli.py compiles and `--help` renders the five subcommands, pyproject.toml parses, every added relative link and all five jump-navigation anchors resolve, and no heading is duplicated.
kmadan
force-pushed
the
docs/adoption-readme
branch
from
August 30, 2026 04:20
62a58da to
38eef59
Compare
This was referenced Aug 30, 2026
kmadan
added a commit
that referenced
this pull request
Aug 30, 2026
…-additive docs: carry the technical-voice pass into the surfaces #88 did not touch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🚀 Overview
Rewrites the three surfaces a prospective user meets first —
README.md, thePyPI description, and
aicertify --help— so they state what distinguishesAICertify (open, versioned Rego that a third party can re-run against the same
inputs) rather than listing output formats. Includes three accuracy corrections.
No behaviour changes. The only
aicertify/cli.pyedits are the module docstringand the parser
descriptionstring.📜 Changes Made
README.md— leads with open execution and evidence; adds jump navigation;makes reproducibility the primary differentiation instead of framework breadth;
states the declared-facts vs measured-evidence distinction explicitly; changes
the canonical example to
aicertify evaluate; describes the demo's fail-closedresult as intended behaviour rather than leaving it to read as a defect.
README-pypi.md— resynchronised with the README; stale claims removed.pyproject.toml— description states the same wedge, so PyPI search resultscarry it.
aicertify/cli.py— docstring and help text corrected (see below).maincarried two## Why AICertifysections, at L189 and L343. The second isreplaced by
## What makes an AICertify result reproducible. Heading count isunchanged at 26 and no heading is duplicated.
🔧 Accuracy corrections
README.md)docs/coverage/coverage.jsontotalsin the pinned GOPAL treeREADME-pypi.md)add_parsercount incli.pyThe GOPAL tree pinned at
aicertify/opa_policiesreportspolicies: 92, policies_with_tests: 92, policies_with_empty_input_test: 92.The five registered subcommands are
demo,evaluate,explain,init-contractandscore-card.🎯 How to Test
Verified locally:
cli.pycompiles,--helprenders the five subcommands,pyproject.tomlparses, the added relative link(
docs/integrations/github-actions.md) resolves, all five jump-navigationanchors resolve to real headings, and pre-commit (ruff, black, whitespace)
passes.
📚 Documentation
README.md,README-pypi.md,pyproject.tomldescription, CLI help📄 Notes for reviewers
The submodule pointer
aicertify/opa_policiesis deliberately not touched bythis PR. The 92 figure holds at the pin already on
main, so the correction doesnot depend on a bump.
Branch
docs/technical-voice(5ab4d11) is pushed with no open PR and overlapsthis one on
README.md,README-pypi.mdandcli.py. This PR is based onmain, not on that branch. That branch needs a separate decision — see thediscussion on the PR.