Skip to content

docs: correct project status and documentation drift - #98

Merged
uberware merged 1 commit into
mainfrom
phase-3-documentation-audit
Jul 21, 2026
Merged

docs: correct project status and documentation drift#98
uberware merged 1 commit into
mainfrom
phase-3-documentation-audit

Conversation

@uberware

Copy link
Copy Markdown
Owner

A documentation accuracy pass over the whole repo, plus the record of the two deferred Wave D
components. No behaviour changes — Go edits here are comments only.

Stale project status

README.md, docs/index.md, ROADMAP.md, and docs/roadmap.md all still said Phase 3 was
"next" despite every planned component being merged. They now say the planned components are
merged and unreleased, with further work expected before v0.3 — deliberately not "complete",
since more is planned before release.

docs/roadmap.md had drifted from ROADMAP.md

It was missing four Phase 2 bullets (chunk bounds, auto-retry/failure limits, cross-job
dependencies, testing presets) and the retry-policy four-tier clause. It is a pure copy modulo
link paths, so it was regenerated and byte-verified against ROADMAP.md under path substitution.

README had no path to enabling auth

The feature was advertised but auth.enabled and docs/auth.md appeared nowhere in README,
docs/index.md, or the quickstart. Added a pointer in the feature bullet and in the deployment
section, where "there is no authentication in this mode" is the load-bearing fact.

docs/configuration.md — one materially wrong statement

It described the LDAP and OIDC blocks as "inert" without auth.enabled. They are not: that
combination fails validation and the server refuses to start. The doc now shows the actual
error text, so nobody stages an LDAP block behind a closed auth gate and wonders why the server
is down. Also documented two previously unstated rules: auth.session.cookie_name must be
non-empty when auth is on (an empty name silently disables CSRF), and discovery.instance_name
must be non-empty regardless of discovery.enabled.

Every other key, default, env var, and CLI flag was audited against internal/config and matched.

docs/architecture.md — the auth subsystem was absent

No internal/auth row, no boot step, no users/sessions/api_keys tables. All added. Two
pre-existing errors fixed while there: the chi router was attributed to internal/server when it
lives in internal/api (contradicting docs/development.md), and the schema table was also
missing job_dependencies, task_logs, and products from Phase 2.

Wave D deferrals recorded

D1 (per-user concurrent task caps) is deferred with no driver behind it; D2 (custom limit
dimensions) is dropped as already delivered by Phase 1 count-based usage pools. Both ROADMAP
bullets are struck.

This required re-justifying merged code: auth.validate_job_owner and the canonical-casing
storage in bindSubmitIdentity were documented as existing for per-user caps. They now cite
owner-scoped visibility — a typo'd or miscased owner yields a job invisible to its real owner
under the user role's owner-filtered listings — which is true today and does not lean on an
unbuilt feature. Behaviour unchanged; only the stated reason moved.

Also

docs/development.md was missing test-ldap, test-oidc, and smoke from its Makefile target
table.

@uberware
uberware merged commit 9026e68 into main Jul 21, 2026
27 checks passed
@uberware
uberware deleted the phase-3-documentation-audit branch July 21, 2026 06:15
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