Files
devplacepy/DEFINITION_OF_DONE.md
T

11 KiB

Definition of Done

This is the completion contract for every change in this repository. A change is done only when every applicable gate below passes. It is linked from the root CLAUDE.md and draws on all nested CLAUDE.md files; where a nested file states a stricter rule for its subsystem, the stricter rule wins.

1. Universal gates (every change)

  1. Exact, minimal diffs. Edit existing files; create a new file only when the change genuinely needs a home. No unrelated edits, no drive-by refactors.
  2. DRY, one choke point. If the behaviour already exists somewhere, reuse it through the existing choke point; never add a second implementation, second focus system, second removal path, second suspension check, second consent gate, second terms check, second proxy, second bulk mechanism, or second query on a different basis. A per-type copy of shared logic is a defect.
  3. A specification exists somewhere. Literally everything has a declared spec: a spec.py single source of truth, a registry (REPORTABLE_TARGETS, DOCS_PAGES, NOTIFICATION_TYPES, GATEWAY_APPS, CUSTOMIZATION_PREF_COLUMNS), a table in a CLAUDE.md, or an explicit decision section. The new behaviour is declared in it, not just implemented.
  4. Zero tolerance for inconsistency. New code matches existing implementation structurally and visually. Before modifying, find the relatable example; if none exists, explain and let the user decide how to continue.
  5. The four faces. Every feature is one data source fanning out into HTML, JSON (respond(..., model=XOut), and a context key not on the *Out schema is silently dropped from JSON), a Devii agent action, and documentation. State each face explicitly, including "no change" where that is the decision.
  6. Import gate and static checks. python -c "from devplacepy.main import app" imports clean; pyflakes/ruff on every touched file is clean (module-level load order and missing function-level imports are invisible to the other checks). Check each touched language manually (Python compiles/imports, JS parses, CSS braces and HTML tags balance).
  7. Full suite green. make test (unit + api + e2e, serial, one pass) passes with no tier skipped and no subset substituted. Triage cheapest-first: make test-fast, then make test-failed until empty. A failing existing test is a contract to satisfy, never to skip, narrow (-k, --deselect), or rewrite to fit the change.
  8. Verification through the real path. Real filesystem, real concurrency, real failure injection: bursts, races, and full disks are test cases, not weather. Re-running your own probe is not verification; the oracle must be independent (the repo's own tests, a golden file, a second method).
  9. Commit, deploy, verify, in that order, same session. A change that is not running is not done. After deploy, verify live; green locally means nothing until prod confirms it.
  10. Production database untouched without explicit confirmation. data/devplace.db and everything under data/ is never read or written by an agent-initiated command without the user's own written confirmation plus the I-HAVE-CONFIRMED-PRODUCTION-DB-ACCESS token. Disposable verification scripts use DEVPLACE_DATABASE_URL/DEVPLACE_DATA_DIR on scratch files.
  11. No comments, no docstrings. Code is self-documenting. No em dashes anywhere.
  12. Forbidden patterns respected. No _new/_old/_temp/_v2/better_/my_/the_ names; RedirectResponse(url=..., status_code=302) with an integer literal; no is_admin-style context key colliding with a Jinja global (use viewer_is_admin-style names); dates shown DD/MM/YYYY via local_dt/dt_ago.

2. Tests (committed, reusable, in the mirrored tree)

  • HTTP tests under tests/api/<url path>/, browser tests under tests/e2e/<url path>/, pure-function tests under tests/unit/<module path>/. Reuse alice/bob, app_server, seeded_db, local_db.
  • Browser rules: every page.goto/wait_for_url passes wait_until="domcontentloaded"; prefer locator().wait_for(state="visible"); scope ambiguous selectors; restore global site_settings flips in try/finally.
  • A behavior change keeps one focused failing-first test with the change, in the existing layout, using the existing fixtures. No new test framework. Throwaway probes stay out of the repo (and a /tmp probe never substitutes for the committed test).
  • Never weaken a failing test to obtain green; fix the product or justify the expectation change. Observe the authentic failure before the fix when safe and runnable; run the focused test after the final edit; run the broad suite once, at the end.

3. Concurrency and state-machine rigor (the four layers)

For any spendable resource (coins, credits, quotas), bounded state machine (levels, tiers, counters with a floor/ceiling), or read-then-write mutation reachable from more than one worker, the persisted suite is not enough. Run, in order, as disposable scripts against a temp DB (never pytest files unless also requested):

  1. Property checks on every pure function over the full input domain (monotonicity, bounds, non-negativity, idempotency), iterating the real range, not spot checks.
  2. Stateful fuzzing: many entities, long randomized action sequences, invariants re-checked after every action (balances never negative, monotonic counters never decrease, bounds never exceeded).
  3. Real multi-process races: separate OS processes, never threads; production-representative state, never pre-seeded columns (NULL is not 0 in SQL, use COALESCE). Prove exact right-wins counts and hand-computed final totals. Fix with one atomic conditional SQL statement (UPDATE ... WHERE <precondition>, real driver rowcount), never a client-side lock.
  4. Static analysis beyond py_compile: pyflakes/ruff on every touched file.

Single-process races do not count. Threads do not count. Luck does not count.

4. Data layer

  • Every insert into a soft-deletable table writes deleted_at: None, deleted_by: None; every read filters deleted_at IS NULL. Toggles revive, never duplicate; cascades share one stamp; delete authz is owner-or-admin on the endpoint; GC stays hard. New user-generated tables are classified in REPORTABLE_TARGETS with resolve_object_url and _report_button.html, or in UNREPORTABLE_TABLES with a reason (the suite enforces this).
  • init_db ensures the full column set of any table code filters on before creating indexes; new columns go through the ensure idiom plus the born-live pair, never bare DDL that misses pre-existing tables.
  • Bounded, indexed reads: window functions over full-table loads, batch helpers over N+1, live-partial indexes built to plan without table scans. Nullable legacy columns need COALESCE in every precondition.
  • Migrations: init_db is idempotent, guarded by locks, skipped seeds stay skipped (consumers pass defaults to get_setting, never assume the seed ran). Consent backfills are forbidden (never fabricate consent); terms_version stays NULL for legacy accounts.
  • Runtime paths come only from config.DATA_DIR constants, never computed from scratch; blobs shard on uuid tail or hash, never the head.

5. Routing, templates, frontend

  • Routers mirror the URL path (routers/<path>.py, packages aggregate with include_router); route guards mirror auth needs (require_user, require_admin, require_user_api); public pages use get_current_user. Mutations are POST with data-confirm; deletes additionally allow any admin; seniority gates (is_senior_admin) bind Devii too.
  • One shared templates instance; nav_active for nav state; static_url/assetUrl for every asset, never a bare /static/ href; dp-* web components (no duplicates, real-button triggers inside popovers so no-JS stays correct, Escape closes); new JS reuses Http/Poller/JobPoller/OptimisticAction/FloatingWindow/ScrollMemory.
  • Server pipeline renders content for SEO (render_content/render_title, with local_dt/dt_ago for timestamps); the client pipeline is only for live content (DOMPurify fail-closed). Notifications use render_title. Emoji shortcodes come from the one map; YouTube embeds follow embeds.py only; emails are masked; em dashes become hyphens.
  • CSS: tokens from variables.css only (file-scoped --x-* palette block per new file, then --color-*/--space-*); --z-* bands; closed breakpoints; prefers-reduced-motion disables animation; no literals, no var() fallbacks, one radius per element, matching dark theme on first paint.
  • Admin pages conform to devplacepy/routers/admin/CLAUDE.md (A1-A11): server-rendered first paint, one builder for HTML and /data, respond() with an *Out model, admin-* classes, local_dt, capped lists, Poller, the ADMIN_SECTIONS registry; tests/unit/admin_spec.py passes.

6. Services and jobs

  • Background services run only in the lock owner, supervised with health checks and lock files; a new JobService needs a server restart and registers its kind. The DB row is the queue; retention is built in; cleanup decisions are per-kind and deliberate (disposable archive vs permanent artifact).
  • Services report state through the one live-view relay row, audit through record/record_system with catalogued events.md keys (never raising into the caller), and telegram/push delivery never invents new channels. New websockets get their own nginx upgrade location above location /.
  • New dependencies are unpinned only by deliberate exception; outbound HTTP goes through stealth with net_guard where untrusted; feature code never blocks the event loop (gateway-adjacent sync calls run in to_thread).

7. AI, Devii, and money

  • The gateway is the single point of truth for AI: every consumer points at it, keys fall back to the internal key, spend is attributed and metered, financial figures are admin-only everywhere. Consent (ai_third_party) gates user-content calls at exactly one place; structured internal callers may bypass the operator preamble, conversational ones never do.
  • Devii: every gated tool declares a confirm boolean (additionalProperties: false makes a gateless confirm fatal); classifier recall beats precision; budget-bounded tools with fail-closed redaction; lessons carry provenance and are never auto-applied from third-party content; channels stay isolated; self-dial uses the real origin URL.
  • Economy and scoring invariants hold exactly: one pure function per number, atomic transitions only, recomputation beats counters, races proven with real processes (see section 3).

8. Done means

  • Minimal diff, no unrelated edits; new files only with a home.
  • One choke point reused; spec/registry updated; four faces stated.
  • Import gate + pyflakes/ruff clean; per-language manual checks done.
  • Committed reusable tests added/updated in the mirrored tree; focused failure observed before, passing after.
  • Section 3 layers run where applicable (spendable resource, bounded state machine, multi-worker mutation).
  • make test fully green; no tier skipped, no test narrowed or rewritten to fit.
  • No production data touched; scratch DBs only.
  • Docs touched where the behaviour is user-visible (/docs prose + DOCS_PAGES, docs_api groups, events.md, nested CLAUDE.md notes).
  • Committed, deployed, verified live, same session.