AC-037: agent usability and adoption readiness (Gates F and G) - #8
Merged
Merged
Conversation
No agent instruction surface existed (no AGENTS.md, CONTRIBUTING.md, skills, or machine-readable usage guidance), so this is additive rather than duplicative. Documents only verified behavior: the six real CLI commands, the three valid --execution-result values, the canonical success and both canonical refusal paths, receipt verification including the wrapper-vs-receipt extraction step that returns VEIP_RECEIPT_MALFORMED if skipped, exit-code semantics, the library entry points, and the full stable reason-code set extracted from source rather than recalled. States plainly what does not exist - no PyPI package, no HTTP/gRPC service, no persistence, no multi-contract registry, no replay protection, no telemetry - and carries the claim ceiling, the undeclared-license position, and the distinction between the gate workflow existing and GitHub enforcing it. Includes an explicit prohibition on inventing commands, interfaces, or maturity, and instructs agents not to treat a refusal as a failure to work around. Documentation only; no runtime, test, fixture, or workflow change.
Documentation only. authcontract/, tests/, fixtures/, .github/, pyproject.toml and benchmarks/ are byte-identical to main 8077785 (git diff --stat empty). docs/AGENT-USABILITY.md records a fresh-clone agent clean-room test against criteria A-J: 10 PASS, 0 FAIL, 0 NOT EVALUATED. Every AGENTS.md claim was executed rather than asserted, including the negative ones - the five unsupported module names raise ModuleNotFoundError, --help lists exactly the six documented subcommands, both refusal paths omit the receipt, and passing the run-specimen wrapper to verify-receipt returns VEIP_RECEIPT_MALFORMED as documented. The record states plainly that it was produced by the same executor that wrote AGENTS.md, so it evidences that the instructions are accurate and executable, not that an independent agent would follow them. Independent agent reproduction remains absent. Records the decision NOT to add a separate skill file: AGENTS.md already carries the full sequence, and a second surface would either duplicate it and drift - the exact defect AC-036S corrected in README.md - or invent automation scaffolding that does not exist here. README adoption surface added only where the provider state is real, verified against the GitHub API: Issues are enabled, so the issue path is linked; Discussions are disabled, so none is mentioned; the commercial path points to the owner-set homepage veraxis.io. No Discord/Slack, no SLA, no support commitment, no adoption statistics, no certification, no package registry. Contribution status is stated truthfully rather than invented: no contribution process, contributor licence, or review policy exists, so issues are named as the reliable path. Scope-of-support is stated as having no commitment. The star prompt is a single optional human-facing line, conditional on the run having been useful, and appears only in README - never in CLI JSON, receipts, reason codes, CI output, or benchmark JSON. Benchmark DUT guard refuses with exit 2 (DUT DRIFT: 1 file - README.md, a protected DUT path). Deliberately not worked around; weakening it to green a docs PR would defeat the property it exists to provide. 342 passed.
AGENTS.md and README.md both described reason_code as a 'stable' machine-facing identifier. That is stronger than the evidence: this repository establishes no versioned public-interface commitment that reason codes survive future releases, and no versioning or pinning mechanism exists. Corrected in both files to the semantics the repository actually supports: reason codes are machine-facing identifiers in the current implementation and are the intended programmatic signal within the documented and tested interface; they are accurate for this commit; cross-version stability is not guaranteed and consumers should re-check on upgrade; message remains non-contractual at any version. No reason code renamed. No runtime behavior changed. No test changed. README and AGENTS.md are the only modified files; authcontract/, tests/, fixtures/, .github/, pyproject.toml and benchmarks/ are byte-identical to main 8077785. 342 passed.
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.
AC-037 — Agent Usability (Gate F) and Adoption Readiness (Gate G)
Executor state: SUBMITTED FOR REVIEW. Do not merge — Engineering Lead adjudicates. This PR does not self-certify Gate F or Gate G.
Documentation only.
authcontract/,tests/,fixtures/,.github/,pyproject.toml, andbenchmarks/are byte-identical to main80777850—git diff --statagainst those paths is empty.What was added
AGENTS.mddocs/AGENT-USABILITY.mdREADME.mdAGENTS.mdpointerGate F — every claim executed, not asserted
Clean-room test from a fresh clone at
7e7f28d6, using onlyREADME.mdandAGENTS.md:10 PASS · 0 FAIL · 0 NOT EVALUATED across criteria A–J.
The negative claims were tested too, which is where agent instructions usually rot:
authcontract.server/.api/.http/.registry/.db→ allModuleNotFoundErrorauthcontract --help→ exactly the six documented subcommands, no othersreceiptkey confirmed absentverify-receipt→VEIP_RECEIPT_MALFORMED, exactly as documented (this is the AC-028 clean-room defect, now documented before an agent can hit it)REFUSED/RUN_FACT_STALEwith no exception raised, confirming the documented "refusals are return values, not exceptions"The reason-code list in
AGENTS.md§10 was extracted from source, not recalled.AGENTS.mdcarries the claim ceiling, the undeclared-license position, the workflow-exists-≠-enforced distinction, and an explicit prohibition on inventing commands or treating a refusal as something to work around.Gate G — adoption surface, verified against provider state
Checked the GitHub API before writing anything:
https://veraxis.io(owner-set)No Discord/Slack, no SLA, no support commitment, no adoption statistics, no certification, no package registry, no telemetry. Contribution status is stated as it actually is — no process, no contributor licence, no review policy exists — rather than a welcoming fiction.
The star prompt is one optional human-facing line, conditional on the run having been useful, in
README.mdonly.Phase 7 — no output contamination
CLI JSON keys unchanged (7 top-level, 10 receipt fields). No promotional or telemetry strings anywhere in
authcontract/. Nothing was added to receipts, reason codes, CI output, or benchmark JSON.Deliberate omission: no separate skill file
Recorded as a decision, not an oversight.
AGENTS.mdalready carries the full sequence; a second surface would either duplicate and drift — the exact defect AC-036S corrected inREADME.md— or invent automation scaffolding that does not exist here.Honest limitation
docs/AGENT-USABILITY.mdstates plainly that it was produced by the same executor that wroteAGENTS.md. It evidences that the instructions are accurate and executable, not that an independent agent would follow them. Independent agent reproduction remains absent, consistent with TRL 4.Finding U5 — benchmark DUT guard (unchanged, deliberate)
benchmarks/run_benchmarks.pyexits2:DUT DRIFT: 1 file(s) differ—README.md, a protected DUT path per AC-035A. Working correctly; not worked around. Weakening it to green a docs PR would defeat the property it exists to provide. No behavioral regression is possible — all behavioral surfaces are byte-identical to80777850.Regression
python3 -m pytest -q→ 342 passed.No runtime or architecture semantics were redesigned.
Generated by Claude Code