Make the first real workflow read-only - #160
Merged
Merged
Conversation
abrichr
marked this pull request as ready for review
August 26, 2026 22:35
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
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.
What changed
The first-workflow guide now starts with a real read-only lookup on test data.
It keeps
openadapt quickstartas an optional installation check, then walksthrough record, compile, strict lint, supervised replay, and report inspection.
The bundled result doesn't qualify the reader's app.
The old page told readers to continue when lint found an unarmed irreversible
write. This change stops before replay when it finds a write, unknown risk, a
consequential action, or an irreversible action. An action also stops when it
needs an identity or effect contract and that contract is absent. A missing
required policy stops it too. The guide sends those workflows to qualification
and certification.
The guide now says the released lint command reports write-shaped or
irreversible actions, risks that may be under-classified, missing evidence, and
missing assertions. Manual review decides whether a write is unexpected.
The page frontmatter now declares a read-only first-workflow scope and requires
qualification before the first write. The docs validator requires both values
and rejects either failure-demo flag on this page. Focused tests mutate each
value and insert each flag.
I also updated the start-page links to describe the read-only supervised path.
The neutral Desktop navigation link remains. I removed the stronger Desktop
recommendation until its engine-enforced first-run gate is released.
Checks
uv run python -m pytest tests/test_validate_docs.py -q(14 passed)uv run python scripts/validate_docs.pyuv run mkdocs build --strict --site-dir /tmp/openadapt-ops-first-workflow-contract-site2uv run python scripts/check_published_version_claims.py --offlineWRITING_GUIDE.md