AC-036: golden-standard repository experience (Gate E) - #7
Merged
Merged
Conversation
Gate E (human repository usability). Documentation only - no runtime, test, fixture, or workflow change. The defect: Quick Start sat at line 418 of a 1084-line README, behind ~400 lines of conceptual material describing capability that is not implemented end to end. An unfamiliar developer met the target product before they could run the real one. Restructured into the required cognitive order, with everything runnable in the first ~250 lines: what it is and its truthful status -> the problem -> install -> a successful end-to-end run -> two deliberate refusals -> what the output fields mean -> how to integrate -> what is NOT implemented -> where to go next. Deep conceptual material is preserved verbatim below a "How it works - the full model" divider that states plainly those worked examples are target behavior. Every command and every output block in the new front matter was executed against committed fixtures at this commit and pasted from real stdout. No output was prettified; the CLI emits single-line JSON and the README says so where it reflows for readability. Refusals are presented as successful demonstrations, with reason_code, non-zero exit, and a plain-language reading: RUN_UNCLASSIFIED_ACTION for an undeclared action, RUN_FACT_STALE for an approval outside its freshness window. Also notes that no receipt is issued on refusal. Integration section documents only interfaces that exist and were exercised while writing it (CLI, Python library, GitHub merge gate, receipt verification), and states plainly what does not exist: no published package, no HTTP service, no persistence, no multi-contract registry, no replay protection. Metadata audit: no badges added - none of the maturity states a badge would assert (published package, coverage, audit, certification) is established. Confirmed requires-python >=3.10 matches the documented requirement. Adds a License section recording the truthful current state: no LICENSE file exists and pyproject declares no license, so default copyright applies. Not resolved here - declaring a license is an owner decision with legal effect, not an executor decision. Removes the now-superseded Quick start section rather than leaving two competing entry points.
…restructure The AC-021/AC-021A/AC-021B documentation guards caught three real regressions the restructure introduced. All three are restored; no assertion was weakened. 1. The accepted quickstart sentence 'Re-run the evidence - independently recompute the receipt bindings from the raw artifact, action, and fact inputs and compare:' was deleted with the old Quick start section. Restored verbatim, now attached to the receipt-verification step where it belongs. 2. The literal '**Implementation status:**' marker was replaced by a reworded callout. Restored, carrying its required clauses verbatim: the one-synthetic-banking-specimen scope and the statement that automated natural-language source-to-rule comparison is target behavior and is not yet implemented end to end. It still precedes the first worked example. 3. The '## Quick start' heading was removed. It anchors an accepted structural invariant - deep ontology vocabulary (OIC, ZTL, OAM, VEIP, AEP) must sit below it. Restored by naming the top install section 'Quick start', which satisfies the invariant more strongly than before: it now sits at line 23 rather than line 418. Also reworded the verify-receipt line in the CLI table to avoid the phrasing the guard bans, rather than relying on capitalisation to slip past it. 342 passed.
docs/REPOSITORY-USABILITY.md records the Gate E clean-room test performed from a genuinely fresh clone at 35e2bef, using only README instructions. Results: ~30-second comprehension PASS; install to first meaningful end-to-end success in ~24s against a five-minute budget; both deliberate refusals reproduced byte-for-byte (RUN_UNCLASSIFIED_ACTION, RUN_FACT_STALE, both exit 1, both correctly issuing no receipt); receipt verification reproduced; Python integration example executed verbatim from the README. Findings recorded rather than resolved: U1 no license is declared - stated truthfully in the README, but choosing a license is an owner decision, not an executor one U2 README remains long; the runnable surface is the first ~250 lines and the conceptual body is now explicitly fenced as target behavior U3 the AC-021 documentation guards constrain README structure, correctly - they caught three genuine regressions in the first draft U4 CLI emits single-line JSON; the README reflows it and says so U5 the benchmark DUT guard protects README.md, so documentation-only changes exit 2. Deliberately not worked around. No behavioral regression is possible: authcontract/, tests/, fixtures/, .github/, pyproject.toml and benchmarks/ are byte-identical to merged main 4c90aa7, where the benchmark last ran 7/7 and 38/38 green. Also links the usability record from the README's next-steps table. Does not self-certify Gate E.
…kflow Documentation truthfulness only. No workflow, runtime, test, fixture, or repository-configuration change. The defect was mine, introduced by the AC-036 restructure. The new integration section stated that authcontract-gate.yml runs git-gate "as a required status check". That asserts GitHub repository configuration, not repository content - and the two are independent. A workflow file can exist while branch protection requires nothing. Notably the README already carried the correct boundary further down: "Repository-level branch protection requiring that check is a separate GitHub configuration concern and should not be inferred merely because the workflow exists." The front matter contradicted an accepted statement in the same document. Corrected to say what is actually true of the repository: the workflow exists, it runs git-gate on pull requests, and it re-resolves the base ref so a stale or isolated-head result cannot pass the gate's own check - followed by an explicit statement that the workflow's presence does not establish that GitHub requires it, and that enforcement lives in branch protection or rulesets. This executor could not independently verify the branch-protection state: this session's GitHub toolset exposes no branch-protection read endpoint. That is itself the argument for the correction - an unverifiable claim should not be published as fact, and the corrected wording is accurate under either enforcement state. Section heading changed from "GitHub merge gate" to "GitHub merge-gate workflow" so the heading itself does not imply enforcement. All AC-021/AC-021A/AC-021B guards re-verified intact; 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-036 — Human Repository Usability (CURRENT-SDLC Gate E)
Executor state: SUBMITTED FOR REVIEW. Do not merge — Engineering Lead adjudicates. This PR does not self-certify Gate E.
Documentation only.
authcontract/,tests/,fixtures/,.github/,pyproject.toml, andbenchmarks/are byte-identical to merged main4c90aa79. The only changed file against that commit isREADME.md, plus one new doc.The defect
Quick Start sat at line 418 of a 1,084-line README, behind ~400 lines of worked examples describing the automated source-to-rule comparison that is not implemented end to end. An unfamiliar developer met the target product before they could run the real one.
The change
Restructured into the required cognitive order, with everything runnable in the first ~250 lines:
what it is + truthful status → the problem → Quick start → a successful end-to-end run → two deliberate refusals → what the output fields mean → how to integrate → what is not implemented → license → where to go next
Deep conceptual material is preserved verbatim below a
# How it works — the full modeldivider that states plainly those examples are target behavior.Every command and output block in the new front matter was executed against committed fixtures and pasted from real stdout. Nothing was prettified; the CLI emits single-line JSON and the README says so where it reflows for readability.
Clean-room verification (fresh clone, README instructions only)
ALLOW OK/PASS OKFull record:
docs/REPOSITORY-USABILITY.md.Documentation guards caught three real regressions
The AC-021/AC-021A/AC-021B guards fired on the first draft. All three were restored; no assertion was weakened:
**Implementation status:**marker was reworded away. Restored with its required clauses intact.## Quick startwas removed — it anchors an accepted invariant (ontology vocabulary must sit below it). Restored, and now satisfies that invariant more strongly: line 23 rather than line 418.Also reworded the
verify-receiptCLI table entry to avoid a banned phrasing rather than relying on capitalisation to slip past the guard.Metadata audit (Phase 6)
No badges added. None of the states a badge would assert — published package, coverage, audit, certification — is established. Confirmed
requires-python = ">=3.10"matches the documented requirement.Finding U1 — no license is declared. No
LICENSEfile exists andpyproject.tomldeclares no license field, so default copyright applies. Now stated truthfully in the README. Not resolved here — choosing a license is an owner decision with legal effect, not an executor decision.Finding U5 — the benchmark DUT guard trips on doc-only changes
benchmarks/run_benchmarks.pyexits2on this branch:DUT DRIFT: 1 file(s) differ— that file beingREADME.md, which AC-035A declared a protected DUT path. This is the guard working correctly and was deliberately not worked around. Weakening it, or trimmingREADME.mdfromDUT_PATHS, to make a docs PR go green would defeat the property it exists to provide.No behavioral regression is possible: all behavioral surfaces are byte-identical to
4c90aa79, where the benchmark last ran 7/7 end-to-end, 38/38 adversarial, exit 0.Regression
python3 -m pytest -q→ 342 passed.Scope
No architecture or runtime semantics were redesigned. Claim ceiling, benchmark evidence, and the public/private boundary are preserved — the README documents product behavior, supported commands, public evidence, and limitations, and exposes no derivation machinery.
Generated by Claude Code