Skip to content

README and documentation site: the two docs issues, verified against the source they describe - #46

Merged
RobeyBeswick merged 2 commits into
mainfrom
loop/docs-41-42
Aug 16, 2026
Merged

RobeyBeswick merged 2 commits into
mainfrom
loop/docs-41-42

Conversation

@RobeyBeswick

Copy link
Copy Markdown
Collaborator

The two documentation issues, built by the loop on the tree that finally has every module in it.

What's in it

Issue What landed
#41 README: install, a first rule, the fluent-API grammar, one example per module, and what is not implemented yet — 10 lines to 519
#42 Docs site: 11 pages under docs/, a layout, CSS, and .github/workflows/pages.yml to deploy it

Both were deliberately held back until the two parallel hosts were merged. A README is the most
cross-cutting thing in the backlog — it has to see slices/ and metrics/ at the same time — so they
ran on one host against main at 305ef70, never split.

The part worth reading

Neither issue is only prose. #41 added readme_test.go and #42 added docs_test.go, together 1.7k lines
that hold both documents to the source they describe:

  • every ```go block is parsed, so a snippet that would not compile fails the build rather than the
    reader's afternoon;
  • every archunit.X and every method of a chain rooted there is resolved against this module's own
    syntax tree, read with go/parser rather than reflection — reflection cannot see an uncalled method
    or a field's name, and those are most of what a document names;
  • the sentences claiming a feature is absent are checked against the absence.

That is #41's own stated failure mode made unfailable: "a sibling port's README documents a slice API
that does not exist." It cannot happen here now without a red build.

Verification

Every job in .github/workflows/ci.yml, run by hand on this exact tree, because GitHub Actions still
reports nothing on this repository
— zero workflow runs, ever.

Job Result
build — go build, go vet, go mod tidy -diff clean
test — go test -race -shuffle=on -count=1 ./... 31 packages, 0 failures
dogfood — the architecture suite green
lint — config verify, fmt --diff, run ./... 0 issues
cross-build — windows/amd64, linux/386 clean

gofmt -l . clean.

Two things need the repository owner

  1. Pages is not enabled. docs/ and the deploy workflow are here, but GET /repos/.../pages is a
    404 and Actions has never run, so nothing publishes until both are switched on. That is an admin
    setting.
  2. The loop's token needs the workflow scope. Documentation site on GitHub Pages #42 was gated green and then refused at the push:
    refusing to allow a Personal Access Token to create or update workflow .github/workflows/pages.yml without workflow scope. The commit was intact and is what this branch carries, pushed under a
    credential that has the scope. Until the loop's own token has it, any issue that touches
    .github/workflows/ will pass every check and then fail to land.

🤖 Generated with Claude Code

ArchUnitDev loop added 2 commits August 16, 2026 11:08
Closes #41

Implemented by the ArchUnitDev loop.
Closes #42

Implemented by the ArchUnitDev loop.
@RobeyBeswick
RobeyBeswick merged commit 71c3ea2 into main Aug 16, 2026
12 checks passed
@RobeyBeswick
RobeyBeswick deleted the loop/docs-41-42 branch August 18, 2026 20:47
RobeyBeswick added a commit that referenced this pull request Aug 18, 2026
README and documentation site: the two docs issues, verified against the source they describe
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