ApprovalFlow Instructions for Claude

Follow AGENTS.md first. This file is a short Claude-specific reminder.

Authority Order

1. Assignment-faithful wording in docs/REQUIREMENTS.md
2. Approved Human Developer decisions in docs/REQUIREMENTS.md
3. docs/SCOPE.md (V1 baseline only)
4. Accepted decisions in ADR.md
5. docs/ARCHITECTURE.md
6. docs/planning/BASELINE_PLAN.md (frozen main) · docs/planning/V4_PLAN.md (current dev work; V2/V3 plans historical)
7. AGENTS.md
8. CLAUDE.md

An ADR may clarify architecture. It may not weaken the assignment or approved requirements.

On dev, docs/planning/V4_PLAN.md is the plan-of-record (Human-approved 2026-07-13); the assignment, requirements, and lecture teachings stay the top authority. main is frozen per M2 and governed by docs/planning/BASELINE_PLAN.md/docs/SCOPE.md. V2_PLAN.md and V3_PLAN.md are historical.

Scope

Build the minimum assignment system, not a production platform.

Keep exactly three business services:

• Workflow
• Decision
• Payment

Keep assignment-mandatory F1-F10, M1-M18, and D1-D7. Keep the approved Human Developer gates named in docs/REQUIREMENTS.md: all-20 fixture conformance, INV-1009, INV-1014A/B, INV-1015, exact duplicate correction behavior, trusted server-side approver identity, trusted payment authority, non-overridable hard stops, and durable compensation visibility.

N1-N5 and B1-B3 are deferred unless explicitly assigned.

Safety Rules

• AI is advisory.
• Deterministic Python owns the final route.
• AI output and browser input cannot authorize payment.
• The real LLM-backed AI provider must use a bounded Tool Call Agent Loop only inside the AI advisory layer.
• Review that the loop remains advisory-only.
• Review that policy facts come through read-only policy tools backed by deterministic Python policy code, not by feeding the full policy document into the LLM prompt.
• Do not add write tools, payment tools, approval tools, rejection tools, workflow mutation tools, or irreversible side-effect tools to the LLM tool registry.
• Do not let the LLM approve, reject, pay, create authority, enforce policy, mutate Workflow state, or bypass human approval.
• Review that no write, payment, approval, rejection, or state-mutation tools are exposed to the LLM.
• Keep the router deterministic.
• Review that deterministic routing remains final authority.
• Keep human approval authority separate from AI advisory output.
• Review that explicit policy violations cannot be overridden by LLM output.
• Request-body approver_id cannot override server identity.
• Human approval cannot override deterministic hard stops.
• Human approval after AI_PROVIDER_ERROR is allowed only when deterministic checks succeeded and no hard stop applies.
• Decision creates trusted authority.
• Payment validates authority before reservation or payment.
• Exact duplicates stay terminal, including linked corrections with the same fingerprint.
• Failed release after reservation remains COMPENSATION_PENDING.

Work Rule

Work only on the assigned PLAN task.

Use the skills available to you: check for and invoke the relevant skill (planning, TDD, debugging, verification, code review) and announce it.

Before coding, present a short plan and surface every decision that needs making, with options and a recommendation. No silent decisions: if you are choosing, ask and wait for approval. Surface new decisions mid-task the same way.

Work efficiently: grep to locate, then read only the relevant ranges instead of reloading whole files or re-reading established docs; batch independent tool calls in one turn.

Use focused TDD for observable mandatory behavior:

1. Add a focused failing test.
2. Capture RED evidence.
3. Implement the smallest change.
4. Capture GREEN evidence.
5. Refactor only while green.

Use smoke checks for Docker, static UI shell, simple config, Dapr wiring, health, OpenAPI, and documentation formatting.

Stop when the assigned task is complete. Do not add optional features, extra abstractions, extra endpoints, production hardening, or unrelated refactors.

Documentation Completion Gate

After each task or meaningful feature group is completed, update the project documents before final handoff. The relevant PLAN file is a mandatory status target every time. Then check every other relevant architecture/demo/evidence file affected by the task, including README.md, docs/ARCHITECTURE.md, ADR.md, docs/RECORDING_SCRIPT.md, and docs/evidence/.

Mark what is complete, pending, deferred, planned, or future. Clearly distinguish implemented behavior from target architecture, and remove stale references to renamed files or old commands. Do not edit assignment sources or docs/PRODUCT_DILEMMA.md unless explicitly assigned.

Speed / Scope Review Rules

Review narrowly. Do not re-audit completed tasks.

Inspect only:

• files changed by Codex
• tests changed by Codex
• required docs for the assigned task
• generated run artifacts needed for this review

If another file is needed, explain why before reading it.

Do not re-read all docs unless scope is unclear or the task explicitly requires it.

Review whether Codex made the smallest change that satisfies the assigned task.

Review Command Style

Run review diagnostics as simple, separate commands.

Run verification commands one at a time.

Do not chain commands with &&, ;, pipes, command substitution, shell loops, or multiline scripts unless the Human Developer explicitly approves.

Do not create or run temporary scratchpad Python scripts from /private/tmp, Claude scratchpad folders, or other generated temp paths.

Do not ask for one large chained Bash command that combines echo, grep, git, ls, variable assignment, pipes, and multiline python3 -c.

The Human Developer's Claude permissions are intentionally scoped to simple commands. Chained commands may trigger unnecessary permission prompts.

Prefer:

git status --short
grep -n "Speed / Scope" AGENTS.md CLAUDE.md
python3 -m py_compile services/decision/router.py

Avoid:

echo "status" && git status --short && DIR=$(ls -d services/* | head -1) && python3 -c "..."

If a complex diagnostic is truly needed, ask first and explain why simple commands are not enough. If approved, split it into separate commands and briefly explain why each command is needed.

Code Quality Review Rules

Review whether the code is simple enough for a human beginner/intermediate Python developer to read and explain.

Prefer clear, direct code over clever abstractions.

Check for:

• clear names
• small functions
• straightforward control flow
• useful validation
• appropriate error handling
• useful logging when behavior needs traceability
• configuration only when the task needs it
• short comments for non-obvious decisions
• tests that explain the expected behavior

Do not require production-scale infrastructure, generalized frameworks, extra abstraction layers, or speculative scalability work unless the assigned task explicitly needs it.

Best-practice feedback should improve clarity, safety, and maintainability without expanding scope.

Refactoring Review Rules

Accept refactoring when it is behavior-preserving and directly improves clarity, safety, or maintainability for the assigned task.

Flag refactoring when it:

• changes behavior without saying so
• expands the assigned task
• introduces unnecessary abstractions
• weakens deterministic authority boundaries
• hides behavior changes inside cleanup
• makes tests pass through fixture-specific hacks
• mixes product changes with broad cleanup

For large refactors, verify that public API behavior, response shapes, route/status/state transitions, deterministic authority boundaries, and existing tests are preserved.

Keep business authority explicit during review:

• AI may advise or extract evidence only.
• Deterministic code owns routing and policy enforcement.
• Payment authority must be trusted and server-created.
• Human approval cannot override deterministic hard stops.

Verification Budget Review

Use tools/test.sh as the canonical repo-local pytest command. It runs pytest through .venv/bin/python when available and falls back to python3; do not rely on globally installed pytest.

For all tests, run:

tools/test.sh

For focused tests, run:

tools/test.sh path/to/test_file.py
tools/test.sh path/to/test_file.py -q

The whole-suite run must go through tools/test.sh, which runs each service in its own process. A bare .venv/bin/python -m pytest -q across all services fails at collection because the services share top-level package names (accessors, engines, managers, ledger, contracts) that collide on one sys.path. For a single service or file the direct venv call is fine:

.venv/bin/python -m pytest services/decision/tests -q

1. Prefer focused tests for the changed area first.
2. Run related service tests only if shared behavior changed.
3. Run the full relevant pytest suite only if needed for final confidence.
4. Do not run Docker/Compose unless infrastructure, gateway, Dapr, or browser UI behavior changed.

Do not stage. Do not commit. Do not push.

Reviews

Human Developer review is required after each task or meaningful feature group.

Independent review is required after any task that touches a safety-critical boundary — the deterministic routing/ceiling boundary, cross-service contracts, payment authority validation or reservation, the AI advisory layer, or the final integrated system. In V2 that maps to T3 (contracts boundary), T4 (Decision ledger/state machine), T5 (MAF advisory), Optional Task B (Payment/ETag reserve), and T7 (final integrated gate). Do not require independent review after every small task.

Documentation and Git

Claude may edit README.md during implementation.

Agents may edit ADR wording only when assigned and must preserve the Human Developer's decision. Do not silently change ADR meaning.

Do not edit docs/PRODUCT_DILEMMA.md unless explicitly assigned.

Do not edit assignment sources.

Do not commit, push, merge, or create pull requests without Human Developer authorization.