THE AI-NATIVE SOFTWARE DEVELOPMENT PLAYBOOK
Chapter 10
ServiceFlow: from principle to passing tests
A companion implementation readers can run, inspect and adapt.
A released companion implementation: inspect the code, decisions, automated verification and human approval trail. AI-assisted reviews are identified as such, not presented as independent human review.
What is implemented
ServiceFlow v1.0.0 is a small Python/FastAPI application with SQLite persistence. It demonstrates authenticated request submission, manager approval, object-level authorisation, transaction-safe state changes, restricted audit viewing and 20 automated tests. It also uses a locked dependency set and CI validation on Python 3.11, 3.12 and 3.13. The demo account/password configuration is only for localhost teaching. Real deployments require identity-provider integration, transport security, secret management, recovery and operational controls.
The public companion repository includes AGENTS.md, requirements, SF-ADR-003 and SF-ADR-004, a threat model, work packets SF-WP-004 and SF-WP-005, FastAPI source, tests, release documentation and the GitHub Actions workflow. The stable evidence baseline is ServiceFlow Companion — First Edition (v1.0.0): https://github.com/justinunderhill/serviceflow-ai-native-playbook/releases/tag/v1.0.0. The book explains the choices; the repository makes them inspectable.
Start the application and inspect the API
Clone the repository on a machine with Python 3.11+ and the uv package manager. Run the example only on localhost; its bundled credentials are deliberately disposable.
uv sync --locked --extra dev
uv run uvicorn serviceflow.demo:app --host 127.0.0.1 --reload
uv run --locked --extra dev python -X dev -m pytest -q
uv run --locked --extra dev ruff check .Open http://127.0.0.1:8000/docs to explore the local API. When alice submits a request assigned to manager bob, an authenticated but unrelated user, charlie, receives HTTP 404 on retrieval, audit or approval. The same status and response body are returned for an unknown request ID, preventing simple existence disclosure. Alice, as the requester, receives HTTP 403 if she attempts to approve her own request. Bob may approve the pending request (HTTP 200); a repeat approval returns HTTP 409. Self-assignment at creation is rejected with HTTP 422. Response timing is not guaranteed to be indistinguishable.
The negative test that matters
A positive “manager can approve” test alone does not prove object-level access control. This negative test confirms that an authenticated non-participant cannot approve the request and that the state remains pending:
def test_different_authenticated_user_cannot_approve(client):
request_id = submit(client)
denied = client.post(f"/requests/{request_id}/approve", auth=auth("charlie"))
assert denied.status_code == 404
assert client.get(f"/requests/{request_id}", auth=auth("alice")).json()["status"] == "pending"The server-side decision
The actor is derived from verified credentials. The shared load_for_participant() helper obtains the request from the database and returns HTTP 404 both for a missing request and for an authenticated non-participant. The approval endpoint then distinguishes participant roles: a requester may not approve their own request (403), and only the assigned manager may approve a pending request. The transaction records the approval and audit event together; a second approval returns 409. The user interface is not relied upon for security.
row = load_for_participant(db, request_id, who)
if who != row["assigned_manager"] or who == row["requester"]:
db.rollback()
raise HTTPException(403, "Not permitted to approve request")What AGENTS.md can and cannot do
The repository’s AGENTS.md tells coding agents to read requirements, stay within a bounded work packet, add negative tests and report actual validation evidence. Instructions and agent hooks can improve execution discipline but do not replace application-level authorisation. In ServiceFlow, the API enforces request permissions, tests exercise those boundaries, the CI job checks each change, and GitHub branch rules enforce a passing check before merging.
Why the CI file is not enough
GitHub Actions executes locked installs, Ruff lint and development-mode tests across Python 3.11, 3.12 and 3.13, using a single required job called validate. The active Main Branch Protection ruleset requires a pull request, passing up-to-date validate results and resolved review conversations; it also blocks force pushes and branch deletion, without bypass actors. The ruleset requires zero approving reviews because this is currently a solo-maintainer repository. Human approval is therefore documented in the pull-request decision record rather than technically enforced as a separate reviewer requirement. A green workflow alone would not supply that merge gate.
Evidence and integrity
The first 10 tests passed despite three defects. In SF-WP-004, Claude Code committed failing tests before the fix, escalated the 404-versus-403 policy decision, and corrected connection cleanup, existence disclosure and self-assignment. PR #3 then passed 19 tests, with AI-assisted technical reviews by ChatGPT and Codex. Justin authorised the merge through ChatGPT, but no contemporaneous approving GitHub review recorded that decision; the learning report acknowledges this gap. SF-WP-005, merged in PR #4, added locked dependencies, resource-warning detection, multi-version CI, explicit human-decision records and version 1.0.0. The final merge commit defa482c passed lint and 20 tests across Python 3.11, 3.12 and 3.13 (CI run 43719852327). Release v1.0.0 points to that commit. Its lightweight tag, created through GitHub’s release interface, deviated from the annotated-tag checklist requirement and is reported openly. Evidence: PRs #3 and #4 and the verified release at https://github.com/justinunderhill/serviceflow-ai-native-playbook/releases/tag/v1.0.0.
Boundaries and next extensions
This teaching implementation uses local HTTP Basic authentication and SQLite, with no production deployment, no real organisation directory and no hosted service. It lacks enterprise SSO/OIDC, migration strategy, rate limiting, resilient audit storage, observability and operational security controls. The identical status and response bodies for unrelated and missing requests are tested, but response timing is not equalised. Start by reproducing the negative tests, then change one bounded requirement and document the evidence in a pull request.
Practical takeaway: inspect the v1.0.0 source and its 20 tests, review SF-ADR-003 and SF-ADR-004, trace the tests-first commit through PR #3, and evaluate which guarantees come from agent guidance, application code, verification workflows and host-enforced repository rules.