This project uses AIDD + TDD as the default delivery model.
- AIDD (AI-informed development): define behavior in natural language, map applicable Linked Art rounds and fixture anchors, use AI to draft tests/refactors, then human-verify semantic correctness.
- TDD: run red -> green -> refactor with failing-first tests.
Required loop
- AIDD framing
- Red
- Green
- Refactor
- Define expected behavior in plain language.
- Map standards to `docs/linked-art/LinkedArtModel1.0-Reference.md`.
- Identify fixture anchors and protocol assertions touched.
- Write failing tests first.
- Confirm failures are for the expected reason.
- Implement the smallest passing behavior.
- Improve structure only after tests pass.
- Keep adapter boundaries and contract leaf rules intact.
Non-negotiables
- AI output is assistive, not authoritative.
- Human review owns correctness for Linked Art semantics, provider behavior, and protocol conformance.
- PRs must be completed using `.github/pull_request_template.md`.
- Provider/validation PRs must include Standards Mapping (rounds, fixture anchors, failing-first tests).
User story coverage gate
- `docs/linked-art/LinkedArtUserStories.json` is the canonical persona backlog for standards-critical features.
- If implementation work exposes a standards/process gap, add or update a user story before merging code.
- Every provider/validation/protocol PR should reference at least one story ID in the PR summary.
- Do not delete governance-critical stories without replacement coverage and reviewer sign-off.
Governance-critical coverage areas that must remain represented:
- authority-backed classification UX (no free-text default for controlled terms)
- data discovery signposting (`describedby` canonical link behavior)
- cite-or-refuse output guarantees for generated content
- ARK resolver conformance (opaque IDs, suffix pass-through, `?info`)
- Wikibase Cloud-to-self-host migration and security baseline
Quality gates
- `pnpm test`
- `pnpm lint`
- `pnpm build`
- Required protocol/conformance tests for affected routes and providers
Technical comment standard
- Add technical comments to all changed production modules when logic is non-obvious.
- Comments must explain intent and invariants (for example: provider API constraints, rights safety rules, URI opacity, array-cardinality guarantees), not restate obvious syntax.
- When adding provider routes/adapters, include comments for pagination limits, required auth/secrets behavior, and data-shape assumptions at validation boundaries.