diff --git a/CHANGELOG.md b/CHANGELOG.md index 6d803ff..9e38bac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ This project has a published GitHub Release line, but no stable support or API g ### Added +- Added a post-v0.3.0 functional contract evidence record covering the current CLI command matrix, init write behavior, and release-boundary limits. - Added a read-only `dedupe` baseline command for deterministic duplicate instruction-line detection across supported instruction files. - Added a read-only `conflicts` baseline command for deterministic contradictory-guidance detection across supported instruction files. - Added an OpenSSF Scorecard evaluation record with current official workflow constraints and a deferred workflow decision. diff --git a/docs/POST-V0.3.0-FUNCTIONAL-CONTRACT-EVIDENCE.md b/docs/POST-V0.3.0-FUNCTIONAL-CONTRACT-EVIDENCE.md new file mode 100644 index 0000000..044ad21 --- /dev/null +++ b/docs/POST-V0.3.0-FUNCTIONAL-CONTRACT-EVIDENCE.md @@ -0,0 +1,178 @@ +# Post-v0.3.0 Functional Contract Evidence + +Status: functional evidence record. +Scope: current post-v0.3.0 main state. +Branch: test/full-cli-functional-contract. +Main baseline SHA before this evidence phase: 6c32d5d4e94cf960b5bfc06d0aa4525bdeab7bf5. + +This document records local functional evidence for the current command contract after the published v0.3.0 release and before any later README finalization, external audit, tag, GitHub Release, or PyPI publication. + +It is not a release note, version bump, tag decision, GitHub Release approval, PyPI publication, stability guarantee, security guarantee, or public API guarantee. + +## Release boundary + +No release action is authorized by this document. + +Before any future release or PyPI publication, the maintainer must still complete, in separate phases: + +- internal audit; +- full functional verification; +- README finalization from verified behavior; +- external audit; +- correction phases for any audit findings; +- packaging dry-run from clean wheel and sdist artifacts; +- release metadata cut; +- GitHub Release; +- PyPI publication through the configured trusted publishing workflow; +- clean install smoke from the published PyPI package; +- post-release verification. + +## Verified command surface + +The local CLI help exposed the following command surface: + +- check; +- init; +- doctor; +- budget; +- dedupe; +- conflicts; +- explain. + +The local version command reported: + +- agent-rules-kit 0.3.0. + +This version string reflects the current package metadata at the time of the evidence run. It does not mean the post-v0.3.0 command additions are already published on PyPI. + +## Functional matrix result + +The functional matrix passed after correcting the test command to match the real CLI contract. + +Verified areas: + +- top-level help; +- per-command help for check, init, doctor, budget, dedupe, conflicts, and explain; +- check console output; +- check JSON output parsed by python -m json.tool; +- check Markdown output; +- doctor against tests/fixtures/repositories/multi-agent-overlap; +- budget against tests/fixtures/repositories/multi-agent-overlap; +- dedupe against tests/fixtures/repositories/multi-agent-overlap; +- conflicts against tests/fixtures/repositories/multi-agent-overlap; +- explain AIRK-GOV003; +- explain --list; +- init --dry-run in a temporary sandbox; +- init --write in a temporary sandbox; +- init --write backup-and-replace behavior in a temporary sandbox; +- editable installed console-script smoke; +- scripts/check.sh; +- scripts/post-release-audit.sh. + +## Observed functional outputs + +Against tests/fixtures/repositories/multi-agent-overlap: + +- doctor returned status review with 6 supported instruction files and 8 governance findings; +- budget returned status ok with 6 supported instruction files and deterministic local size metrics; +- dedupe returned status review with 5 duplicate groups and 16 duplicate lines; +- conflicts returned status ok with 0 conflict groups and 0 conflict lines; +- explain AIRK-GOV003 returned the expected review-or-CI-bypass rule explanation. + +These outputs are fixture-based functional evidence. They are not a guarantee that the tool detects every possible duplicate, contradiction, governance issue, or unsafe instruction pattern. + +## Init contract finding + +The functional matrix initially attempted to call: + +- init --write --force. + +That was incorrect. + +The real current init contract is: + +- init --dry-run; +- init --write. + +The CLI help does not expose --force. + +The source and tests show that init --write backs up an existing root AGENTS.md before replacing it. Therefore, --force must not be documented as part of the current contract unless a future explicit product phase adds it intentionally. + +Decision: + +- do not add --force in this phase; +- do not document --force in README; +- keep init documentation aligned with --dry-run and --write only; +- treat any future --force flag as a separate product and safety decision. + +## Sandbox write behavior + +The write behavior was verified only inside a temporary directory. + +Observed sequence: + +- init --dry-run planned AGENTS.md creation and did not create the file; +- init --write created AGENTS.md; +- a second init --write with an existing AGENTS.md performed backup-and-replace; +- AGENTS.md.agent-rules-kit.bak existed after replacement. + +No repository files were modified by the init sandbox check. + +## Installed editable smoke + +A temporary virtual environment installed the project in editable mode with development dependencies. + +The installed console script verified: + +- --version; +- check JSON output; +- doctor; +- budget; +- dedupe; +- conflicts; +- explain AIRK-GOV003; +- explain --list. + +This is not a substitute for final wheel and sdist verification. Future release preparation must still build distributions, install from clean artifacts, and smoke-test the built package. + +## Local gates + +The final isolated local gates passed: + +- python syntax; +- 152 unit tests; +- Ruff; +- text hygiene; +- Git whitespace checks; +- post-release audit. + +The post-release audit remained local and did not mutate GitHub, PyPI, tags, releases, or branch protection. + +## Known limits + +This evidence does not verify: + +- final wheel artifact installation; +- final sdist artifact installation; +- PyPI package installation for a future version; +- GitHub Release assets for a future version; +- external audit findings; +- branch protection through a fresh API capture; +- private vulnerability reporting through a fresh UI capture; +- universal semantic duplicate detection; +- universal contradiction detection; +- production readiness; +- repository security. + +## Impact on next phases + +This evidence supports moving toward README finalization, but only after it is committed, reviewed, merged, and verified on main. + +The README final should reflect: + +- dedupe and conflicts exist on current main after v0.3.0; +- dedupe and conflicts are not part of the published v0.3.0 package until a later verified release publishes them; +- init supports --dry-run and --write, not --force; +- init --write backs up existing root AGENTS.md before replacement; +- clean reports are not proof of safety; +- all release and PyPI claims require fresh verification during the release phase.