8.4 KiB
Development protocol
Status: proposed v0.2, revised 13 October 2026. Applies to implementation of the architecture. Product requirements remain in the PRD. Owner-required modular development is specified in the module design and replacement protocol.
Work from a bounded contract
Before editing, inspect applicable project instructions, current files and Git status. Preserve unrelated edits. Identify the user-visible result, affected requirement IDs, authority/data boundary, failure behavior and evidence needed to call the slice complete. Use a short task note for ordinary work; reserve an ADR for a durable architectural change. Do not require a new approval cycle for each reversible implementation step already authorized by the user.
Implement one vertical behavior at a time. For example: a source with a wrong-page quote is rejected with a locator finding; an exact retry returns the same outcome; a reader sees the accepted note only after valid submission. Avoid scaffolding the entire roadmap before the first complete flow exists.
Every implementation task names its owning module, public boundary and affected consumers. Design replacement paths as part of the module, including its state/schema compatibility. A folder split alone does not satisfy modularity. Consumers must depend on public contracts and remain independent of a module's storage layout, provider SDK or private helper functions.
Code ownership rules
| Area | Required behavior |
|---|---|
| Domain | Own invariants and typed contracts; pure validation where practical. No transport, filesystem or model calls. |
| Application | Own use-case order, explicit scope, authorization checks, transaction/publication decisions and recovery. |
| Adapters | Own Git/files/SQLite/parsers/auth mechanics behind bounded interfaces. Never quietly decide policy. |
| HTTP/MCP | Validate inputs and map outputs/errors; expose only operations in the allowlisted catalog. No duplicate business rules. |
| Frontend | Read API data, route state and render evidence. No canonical mutation route or hidden browser proposal client. |
| Local skills | Reason and propose using public contracts. No direct canonical edits, SQL tools or assumed human authority. |
| Local agent runtime | Own bounded pipeline execution, model/tool dispatch and resumable client checkpoints. Use the service through public MCP contracts; never import its persistence or owner-credential internals. |
The operation catalog declares name/version, request/response schemas, handler, capabilities, permitted transports, idempotency semantics and limits. Test the generated route/tool surfaces, including forbidden exposure. An MCP readOnlyHint is documentation, not enforcement.
Use strict typing at new boundaries. Narrow exceptions to actionable domain errors; unexpected failures retain correlation IDs and private traces. Do not return success after a failed required write or check. Use parameterized SQL and subprocess argument arrays. Never interpolate source text, filenames or PR prose into shell commands.
Offload blocking work at one clear boundary. Bound queues and parser/model processes. Do not hold SQLite transactions or the Git writer while waiting for external calls. The durable publication sequence in the acceptance contract takes precedence over a convenient framework background-task helper.
Frontend engineering
Keep scope, search query, filters and selected node/revision in the URL. Browser back/forward and shared links must restore the intended reading view. Query keys include resolved/requested scope, filters, node/revision and API version as appropriate. Clear private caches on logout or identity changes.
Cancel obsolete requests or ignore their results, including obsolete loading and error states. Query polling exists only for a visible need and cannot overlap indefinitely. Avoid a global real-time event system before the product requires it.
Fetch through the typed API layer. Components receive enough data to render complete states: loading, empty, unavailable, forbidden, stale, index-lagged and successful. A valid empty search is different from a failed request. Profile before adding broad memoization or custom comparison functions. Sanitize Markdown rendering and scope reading typography so source headings cannot restyle navigation.
Verification proportional to the change
| Change | Minimum evidence |
|---|---|
| Documentation | Relative-link and consistency checks; no claim of runtime acceptance. |
| Pure domain rule | Focused tests with valid, invalid and boundary cases. |
| Scope/auth/catalog | Negative capability tests through actual HTTP and MCP adapters. |
| Files/Git/proposals | Isolated temporary repositories; replay, conflict and crash/restart tests. |
| Parsing | Labeled sources with exact location maps and failure states; successful conversion alone is insufficient. |
| Index/retrieval | Rebuild integrity, explicit scope, ranking/latency fixtures and model-change behavior. |
| UI | Type/lint/component checks plus browser reading flow, keyboard, narrow layout and screenshot inspection. |
| Connector/configuration | Preserve unrelated entries, rollback owned changes, and perform the native client workflow. |
| Module addition/replacement | Public contract tests, dependency/import-boundary checks, consumer integration and an explicit state migration/rollback where applicable. |
| Agent skill/pipeline | Typed stage fixtures, version pinning, budget/cancellation behavior and resume after an uncertain MCP result; semantic quality uses labeled source examples. |
| Deployment | Authenticated source-to-reading path on that deployment and a separate restore exercise. |
Use isolated fixtures, fixed clocks and explicit data roots. No unit test reaches live providers or production state. Never overlap tests sharing a mutable SQLite database. Regression tests should demonstrate the failure mechanism, not repeat implementation branches. Cosmetic documentation/UI edits do not justify an invented test suite.
Scaffolding must supply scripts for Ruff check/format, mypy, pytest, TypeScript, ESLint, unit tests and browser tests. Until those scripts exist, do not publish fictional command transcripts. Run focused checks during development, then the affected integration/release gates. Repeat only for changed code, failures or unresolved uncertainty.
Acceptance receipts record revision and dirty-tree baseline, runtime/OS versions, configuration without secrets, exact commands and outputs, fixtures, observed behavior and remaining limitations. Results are PASS, FAIL, BLOCKED, NOT RUN or UNSUPPORTED. User-reported and directly observed results are labeled separately.
Documentation and change management
Use docs/decisions/ADR-NNN-short-title.md for choices that change a public contract, trust boundary, persistence model, deployment topology or dependency family. Include status/date, context, decision, strongest alternative, consequences, migration/rollback and acceptance evidence. Routine implementation details stay with their module or task.
Keep one owner document per rule. Link from the handbook and later from a concise root AGENTS.md; thin harness pointers can refer to that file. Do not duplicate rules across CLAUDE/GEMINI/OpenCode copies. Reference project protocols inform decisions but never silently become GEWU instructions.
Write the result and reason first. Distinguish proposed, implemented, tested locally and verified in deployment. Use relative repository links, stable requirement IDs and specific dates. State failures and uncertainty directly. Do not borrow a reference project's metaphors as architecture terminology or present an agent's confidence as measured quality.
Before committing, inspect the exact diff and selectively stage the coherent slice. Commit only when authorized; never stage unrelated work or reset the user's tree. Report local commit, push, deployment and runtime evidence as separate outcomes. Git commits made by the knowledge service follow the stricter acceptance contract and cannot use blanket staging.
Completion gate
A slice is complete when its behavior and failure cases are implemented, required checks pass, changed contracts/docs are current, and required deployment/client evidence exists. Its module boundary and replacement obligations must also pass the modularity protocol. A blocked client or unrun recovery gate remains visible. Passing unit tests cannot close an untested end-to-end requirement.