forked from retoor/devplacepy
Comment and post layouts stay full width on small screens. Secondary actions live in the More menu. Notifications can be grouped and throttled, and Enter can submit when that profile setting is on. Emulated-tool models accept large catalogs, with reserved names aliased on the wire and the catalog cached per owner. A dropped service-worker navigation is retried once. The test server waits 120s to finish importing before it is stopped.
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.
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.