Skip to content

Make the first real workflow read-only - #160

Merged
abrichr merged 5 commits into
mainfrom
codex/docs-safe-first-workflow
Aug 26, 2026
Merged

Make the first real workflow read-only#160
abrichr merged 5 commits into
mainfrom
codex/docs-safe-first-workflow

Conversation

@abrichr

@abrichr abrichr commented Aug 26, 2026

Copy link
Copy Markdown
Member

What changed

The first-workflow guide now starts with a real read-only lookup on test data.
It keeps openadapt quickstart as an optional installation check, then walks
through 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.py
  • uv run mkdocs build --strict --site-dir /tmp/openadapt-ops-first-workflow-contract-site2
  • uv run python scripts/check_published_version_claims.py --offline
  • Public-writing check against the no-ai-slop evaluation and WRITING_GUIDE.md

@abrichr
abrichr marked this pull request as ready for review August 26, 2026 22:35
@abrichr
abrichr merged commit 04587f0 into main Aug 26, 2026
5 checks passed
@abrichr
abrichr deleted the codex/docs-safe-first-workflow branch August 26, 2026 22:50
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