DEVELOPMENT.md

Development workflow

Start a bounded change

1. Read current context, then git status --short. Preserve existing work.
2. Run npm run doctor. It reads environment, dependency versions, disk, Git, compiled-build age and aggregate HTTP health. It does not start/stop services, open a database, read secrets, call a model or delete files. Offline runtime and missing builds are warnings; --strict turns warnings into failure.
3. Use npm run map -- commons (or ui, lab, identity, scenario, services, tooling) to find entry points, existing helpers, owning stores and tests.
4. Express the task as an observable behavior and acceptance example. Reproduce a bug before editing. Reuse the indexed implementation before creating another.
5. Implement one coherent change. Use focused checks during iteration; finish implementation with npm run check and relevant browser verification.

Feedback commands

Command	Scope
npm run check:fast	Cached lint, map/document checks, pure scenario/grammar/tooling tests; no databases or build
npm run check:commons	Collaboration API, revision history, cancellation and merge contracts
npm run check:lab	Interpreter, grammar exclusion, strategy/rule execution and learning gates with mocked inference
npm run check:identity	Accounts, agent configurations, OAuth and related service integration
npm run check:scenario	Deterministic transitions, API, persistence and timeline/protocol
npm run check:services	Accounts, ranking, gateway failures and actual isolated service processes
npm run check:ui	Lint, repository checks, build, compiled DOM/axe integration and static serving
npm run check:tooling	Verification planner, diagnostics input validation and lint guardrails
npm run check	Full local gate, including every tests/*.test.mjs; unchanged required acceptance scope plus repository checks

Append -- --plan to any suite to inspect its exact commands without running them. Area maps also list Playwright .spec.mjs files for navigation; area checks run only Node .test.mjs files. Run npm run test:ui for real browser coverage. npm run browser:doctor checks the configured Chromium executable, opens a fresh blank page, verifies its temporary profile is inside .cache/tmp, closes it and checks profile removal. It reports no application or sandbox qualification. No browser is downloaded automatically. The mutable report is .cache/verification/latest-browser.json; preserve an immutable copy when needed. The complete test:ui command also writes .cache/verification/latest-browser-suite.json: source hashes before/after, the exact selected groups/specs, process exits and JSON reporter counts. A partial, skipped, flaky, failed or source-changing run cannot produce passed. Focused test:browser runs and browser:doctor never create that full receipt.

For the maintainer's separate source/publication workflow, run npm run evidence:status after verification, commit and publication. It compares current source with both full receipts, checks clean Git state and compares trees across the independent histories. It performs no fetch or write to Git. -- --github adds fresh public-main and exact-commit Verify reads through gh; without it, hosted CI is explicitly not queried. -- --json prints the full report. The report is saved to .cache/verification/latest-evidence-status.json. Freeze documentation and assets as well as code before the full check and full browser suite; editing either afterwards makes their source stamps stale. After verification and commit, maintainers with the independent publication checkout can use npm run publication:prepare -- --base-local <full-sha> --expected-public <full-sha> for a dry run, then explicitly --stage. Follow the publication contract for fresh fetches, matching bases, patch review, ordinary commits/push and exact CI. The preparer never fetches, commits, pushes or creates a release/tag. npm run skills:verify checks the existing vendored design references and their original notices against pinned byte identities. It performs no download or execution. Sources, terms and update procedure apply when using or changing those references; the full gate includes its drift checks. Source hashes identify actual working bytes. A Git archive can have different text line endings from a Windows working tree while retaining the same committed content. Record the Git revision/tree and each environment's hash separately. Doctor requires metadata belonging to its own root; an archive inside another checkout reports unavailable Git metadata instead of inheriting the parent branch. npm run benchmark:ui -- --history 1000 --samples 5 measures a labelled read-only chat fixture in cold browser contexts after npm run build. Use the same browser, viewport and parameters for comparison; it never opens a retained user store. npm run capture:launch performs disposable model-free journeys and captures ready-size launch images with provenance under runtime/verification/launch-assets. Review the actual images before copying them into source; see distribution. npm run agents:fixtures checks authored host envelopes for all disabled roles; -- --profile <stable-id> selects one. It performs no inference and reports no model-quality score. Fixture and holdout scope. The ecosystem decisions connect adopted/deferred tools and provider choices to primary sources, tests and exact activation blockers. npm run model:inspect checks declared local artifact metadata; -- --hash streams its bytes without starting a provider or reading a token. Metadata-only, digest identity and runtime readiness remain distinct. Local setup. Focused suites are explicitly labeled feedback, not full acceptance. Select an area deliberately: changed-file inference is unreliable in this dirty checkout and can miss integration dependencies. The full gate remains serial to bound PGlite memory.

The runner stops at the first failing stage, prints its command and elapsed time, and overwrites .cache/verification/latest-<suite>.json. It writes running before execution; interruption cannot leave a previous green report looking current. Reports include before/after hashes of indexed source, assets, docs and configs; edits during a run make it fail. Do not edit or run another suite concurrently with the final gate. These local summaries are disposable and not signed release receipts. There is one summary per known suite, one lint cache and project-local temporary output under .cache/tmp. Child processes receive TEMP/TMP/TMPDIR explicitly.

Source identity and inspection

npm run source:inspect [-- --samples 5] reports source-index version, file/byte counts, hashes and measured fingerprint durations. Its inspected state is a read-only input probe; full/browser gates remain separate. The local report is .cache/verification/latest-source-inspection.json, replaced with running/blocked when appropriate, inside the same validated workspace directory as other receipts.

Source index v2 includes every regular tracked input in an ordinary Git checkout, plus registered working source/assets/docs. It includes root policy/configuration, legacy prototype files and vendored skill references. Git modes participate in the hash. Source-only archives use the maintained registered inputs without requiring Git metadata; update scripts/project-files.mjs and the project map when adding an archive input outside the existing roots. No vendored skill engine is executed.

Root private configuration, runtime, dependencies, build output and cache material stay outside this index. Forced tracked private/runtime entries, links, unresolved stages and sparse/assume-unchanged index flags block source evidence. Inspect the reported input and git ls-files -v before correcting the intended Git state. The probe does not alter index flags, Git configuration or retained data. Raw working-byte hashes can differ between Windows and Linux line endings; public Git trees and each environment's frozen receipts provide their own association. Earlier v1 receipts retain their dated narrower scope; rerun both full gates after the v2 change before accepting the expanded source. Full and grouped-browser receipts carry sourceIndexVersion; the evidence preflight requires the current version as well as matching hashes, so an older-version stamp cannot qualify.

Find and diagnose problems

• npm run doctor -- --json: structured health; use --url http://127.0.0.1:PORT for a configured gateway. Only loopback origins are accepted, redirects refused, HTTP reads have a three-second timeout. A running model is optional for checks.
• npm run check:repo: broken local Markdown file links, missing map entries and an oversized current handoff. It does not validate URL availability or headings.
• npm run lint: browser and Node globals are separated. UI cannot statically import server internals/Node builtins; shared/domain code avoids transport/UI imports. JSX disclosure elements fail against the explicit open-content design. These are coding checks, not a security sandbox or complete dependency analysis.
• npm run diagnostics: storage measurements and existing limited diagnostic retention. Run before/after heavy batches; inspect growth before repeating work.
• npm run db:status: raw dependency health. Terminal output from the supervisor identifies the failing service. Never reset a store or kill another project's port to make a check green.
• A UI change needs a real browser at desktop and narrow widths. DOM tests have no layout engine and their axe check disables color contrast. The separate browser suite runs in CI; npm run test:ui requires matching installed Chromium. On Windows, a local Chrome installation can be used without downloading a Playwright browser by setting CZ_BROWSER_EXECUTABLE to its absolute executable path. CZ_CAPTURE_BROWSER=1 saves catalog desktop/narrow captures under runtime/verification. npm run test:ui runs the configured serial groups with fresh disposable in-memory services to preserve scenario independence and keep the normal 180-request/minute API limiter active. scripts/test-ui.mjs checks that each browser spec is listed exactly once. Playwright global setup awaits child-service shutdown after each group; the production limit is not changed. Run a focused spec with npm run test:browser -- tests/browser/<name>.spec.mjs (and optional --grep). The runner applies workspace TEMP, TMP and TMPDIR before importing Playwright or starting children. Capture and benchmark helpers use the same setup. These process-local paths are ordinary same-user storage, not isolation. Existing files, symlinks or junctions at .cache/.cache/tmp are rejected. Recovery fixtures wait for the actual failed request to settle before retrying. The initial Commons retry test pauses polling with Playwright's clock and holds the retry response until busy/disabled assertions pass. Resume its clock before axe analysis, which needs browser timers; do not add sleeps or automatic retries. Account recovery uses held real GET responses to check bookmark writes and session changes. Navigate by hash inside those fixtures so a page reload does not cancel the stale response being tested. CZ_CAPTURE_ACCOUNT_RECOVERY=1 captures its actual desktop and full-page narrow failure states.

Use npm run dev for React Fast Refresh while developing. npm start serves compiled dist and requires a rebuild after UI changes. They share port 4173: switch modes only after gracefully stopping this project's supervisor. Use npm run preview:qa for writable browser experiments against disposable in-memory services and automatic ports; its localhost origin separates normal preview cookies.

Keep orientation current

project-map.mjs owns the module index and focused test lists. Update it when moving modules or adding a subsystem. Keep CONTEXT.md under 120 lines: current direction, latest verification, preserved data and real limits. Move dated narrative to linked history, never delete evidence to shorten a handoff. Canonical contracts belong in ARCHITECTURE/API/domain docs, not repeated logs.

Bug reports should include a reproducible action, expected/actual behavior, route, run/revision when relevant, and failing check. Supply sanitized output; never attach credentials or databases. PRs should identify the behavior, validation and remaining limits. Repository templates provide these fields without adding approval steps.

Research used for this workflow

For backend/database changes, backend performance owns the storage contract, migration safety and npm run benchmark:backend procedure. The benchmark uses a disposable database and one bounded output report. Current workflow and history-size measurements record observed command costs and the limits of those comparisons.

• Anthropic: effective harnesses for long-running agents motivates incremental tasks, persistent handoffs and browser verification. Here, the existing workspace and required checks provide that structure; no additional model, agent framework or autonomous commit policy is introduced.
• GitHub: best practices for coding tasks supports explicit acceptance examples, relevant file pointers and reproducible build/test instructions. The project implements these in its map and commands.
• Birgitta Boeckeler: an autonomous coding-agent case study illustrates agents missing reusable code and variation in solution quality. The map emphasizes existing entry points; tests remain behavioral acceptance evidence.

These are engineering practices adapted to this repository, not evidence that AI-written code is universally correct or that development has a guaranteed speedup.