forked from retoor/devplacepy
11 KiB
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)
- 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.
- 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.
- A specification exists somewhere. Literally everything has a declared spec: a
spec.pysingle source of truth, a registry (REPORTABLE_TARGETS,DOCS_PAGES,NOTIFICATION_TYPES,GATEWAY_APPS,CUSTOMIZATION_PREF_COLUMNS), a table in aCLAUDE.md, or an explicit decision section. The new behaviour is declared in it, not just implemented. - 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.
- The four faces. Every feature is one data source fanning out into HTML, JSON (
respond(..., model=XOut), and a context key not on the*Outschema is silently dropped from JSON), a Devii agent action, and documentation. State each face explicitly, including "no change" where that is the decision. - Import gate and static checks.
python -c "from devplacepy.main import app"imports clean;pyflakes/ruffon 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). - 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, thenmake test-faileduntil empty. A failing existing test is a contract to satisfy, never to skip, narrow (-k,--deselect), or rewrite to fit the change. - 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).
- 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.
- Production database untouched without explicit confirmation.
data/devplace.dband everything underdata/is never read or written by an agent-initiated command without the user's own written confirmation plus theI-HAVE-CONFIRMED-PRODUCTION-DB-ACCESStoken. Disposable verification scripts useDEVPLACE_DATABASE_URL/DEVPLACE_DATA_DIRon scratch files. - No comments, no docstrings. Code is self-documenting. No em dashes anywhere.
- Forbidden patterns respected. No
_new/_old/_temp/_v2/better_/my_/the_names;RedirectResponse(url=..., status_code=302)with an integer literal; nois_admin-style context key colliding with a Jinja global (useviewer_is_admin-style names); dates shown DD/MM/YYYY vialocal_dt/dt_ago.
2. Tests (committed, reusable, in the mirrored tree)
- HTTP tests under
tests/api/<url path>/, browser tests undertests/e2e/<url path>/, pure-function tests undertests/unit/<module path>/. Reusealice/bob,app_server,seeded_db,local_db. - Browser rules: every
page.goto/wait_for_urlpasseswait_until="domcontentloaded"; preferlocator().wait_for(state="visible"); scope ambiguous selectors; restore globalsite_settingsflips intry/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
/tmpprobe 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):
- Property checks on every pure function over the full input domain (monotonicity, bounds, non-negativity, idempotency), iterating the real range, not spot checks.
- Stateful fuzzing: many entities, long randomized action sequences, invariants re-checked after every action (balances never negative, monotonic counters never decrease, bounds never exceeded).
- 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 driverrowcount), never a client-side lock. - Static analysis beyond
py_compile:pyflakes/ruffon 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 filtersdeleted_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 inREPORTABLE_TARGETSwithresolve_object_urland_report_button.html, or inUNREPORTABLE_TABLESwith a reason (the suite enforces this). init_dbensures 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
COALESCEin every precondition. - Migrations:
init_dbis idempotent, guarded by locks, skipped seeds stay skipped (consumers pass defaults toget_setting, never assume the seed ran). Consent backfills are forbidden (never fabricate consent);terms_versionstays NULL for legacy accounts. - Runtime paths come only from
config.DATA_DIRconstants, 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 withinclude_router); route guards mirror auth needs (require_user,require_admin,require_user_api); public pages useget_current_user. Mutations are POST withdata-confirm; deletes additionally allow any admin; seniority gates (is_senior_admin) bind Devii too. - One shared
templatesinstance;nav_activefor nav state;static_url/assetUrlfor 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 reusesHttp/Poller/JobPoller/OptimisticAction/FloatingWindow/ScrollMemory. - Server pipeline renders content for SEO (
render_content/render_title, withlocal_dt/dt_agofor timestamps); the client pipeline is only for live content (DOMPurifyfail-closed). Notifications userender_title. Emoji shortcodes come from the one map; YouTube embeds followembeds.pyonly; emails are masked; em dashes become hyphens. - CSS: tokens from
variables.cssonly (file-scoped--x-*palette block per new file, then--color-*/--space-*);--z-*bands; closed breakpoints;prefers-reduced-motiondisables animation; no literals, novar()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*Outmodel,admin-*classes,local_dt, capped lists,Poller, theADMIN_SECTIONSregistry;tests/unit/admin_spec.pypasses.
6. Services and jobs
- Background services run only in the lock owner, supervised with health checks and lock files; a new
JobServiceneeds 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_systemwith cataloguedevents.mdkeys (never raising into the caller), and telegram/push delivery never invents new channels. New websockets get their own nginx upgradelocationabovelocation /. - New dependencies are unpinned only by deliberate exception; outbound HTTP goes through stealth with
net_guardwhere untrusted; feature code never blocks the event loop (gateway-adjacent sync calls run into_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
confirmboolean (additionalProperties: falsemakes 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/ruffclean; 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 testfully 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 (
/docsprose +DOCS_PAGES,docs_apigroups,events.md, nestedCLAUDE.mdnotes). - Committed, deployed, verified live, same session.