{"id":"development/aidd-tdd","relativePath":"development/aidd-tdd.md","title":"AIDD + TDD Discipline","markdown":"# AIDD + TDD Discipline\n\nThis project uses **AIDD + TDD** as the default delivery model.\n\n- **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.\n- **TDD:** run red -> green -> refactor with failing-first tests.\n\n## Required loop\n\n1. **AIDD framing**\n   - Define expected behavior in plain language.\n   - Map standards to `docs/linked-art/LinkedArtModel1.0-Reference.md`.\n   - Identify fixture anchors and protocol assertions touched.\n2. **Red**\n   - Write failing tests first.\n   - Confirm failures are for the expected reason.\n3. **Green**\n   - Implement the smallest passing behavior.\n4. **Refactor**\n   - Improve structure only after tests pass.\n   - Keep adapter boundaries and contract leaf rules intact.\n\n## Non-negotiables\n\n- AI output is assistive, not authoritative.\n- Human review owns correctness for Linked Art semantics, provider behavior, and protocol conformance.\n- PRs must be completed using `.github/pull_request_template.md`.\n- Provider/validation PRs must include Standards Mapping (rounds, fixture anchors, failing-first tests).\n\n## User story coverage gate\n\n- `docs/linked-art/LinkedArtUserStories.json` is the canonical persona backlog for standards-critical features.\n- If implementation work exposes a standards/process gap, add or update a user story before merging code.\n- Every provider/validation/protocol PR should reference at least one story ID in the PR summary.\n- Do not delete governance-critical stories without replacement coverage and reviewer sign-off.\n\nGovernance-critical coverage areas that must remain represented:\n- authority-backed classification UX (no free-text default for controlled terms)\n- data discovery signposting (`describedby` canonical link behavior)\n- cite-or-refuse output guarantees for generated content\n- ARK resolver conformance (opaque IDs, suffix pass-through, `?info`)\n- Wikibase Cloud-to-self-host migration and security baseline\n\n## Quality gates\n\n- `pnpm test`\n- `pnpm lint`\n- `pnpm build`\n- Required protocol/conformance tests for affected routes and providers\n\n## Technical comment standard\n\n- Add technical comments to all changed production modules when logic is non-obvious.\n- Comments must explain intent and invariants (for example: provider API constraints, rights safety rules, URI opacity, array-cardinality guarantees), not restate obvious syntax.\n- When adding provider routes/adapters, include comments for pagination limits, required auth/secrets behavior, and data-shape assumptions at validation boundaries.\n","sections":[{"level":2,"heading":"Required loop","anchor":"required-loop"},{"level":2,"heading":"Non-negotiables","anchor":"non-negotiables"},{"level":2,"heading":"User story coverage gate","anchor":"user-story-coverage-gate"},{"level":2,"heading":"Quality gates","anchor":"quality-gates"},{"level":2,"heading":"Technical comment standard","anchor":"technical-comment-standard"}],"html":"<h1 id=\"aidd-tdd-discipline\">AIDD + TDD Discipline</h1>\n<p>This project uses <strong>AIDD + TDD</strong> as the default delivery model.</p>\n<ul><li><strong>AIDD (AI-informed development):</strong> define behavior in natural language, map applicable Linked Art rounds and fixture anchors, use AI to draft tests/refactors, then human-verify semantic correctness.</li><li><strong>TDD:</strong> run red -&gt; green -&gt; refactor with failing-first tests.</li></ul>\n<h2 id=\"required-loop\">Required loop</h2>\n<ol><li><strong>AIDD framing</strong></li></ol>\n<ol><li><strong>Red</strong></li></ol>\n<ol><li><strong>Green</strong></li></ol>\n<ol><li><strong>Refactor</strong></li></ol>\n<ul><li>Define expected behavior in plain language.</li><li>Map standards to `docs/linked-art/LinkedArtModel1.0-Reference.md`.</li><li>Identify fixture anchors and protocol assertions touched.</li><li>Write failing tests first.</li><li>Confirm failures are for the expected reason.</li><li>Implement the smallest passing behavior.</li><li>Improve structure only after tests pass.</li><li>Keep adapter boundaries and contract leaf rules intact.</li></ul>\n<h2 id=\"non-negotiables\">Non-negotiables</h2>\n<ul><li>AI output is assistive, not authoritative.</li><li>Human review owns correctness for Linked Art semantics, provider behavior, and protocol conformance.</li><li>PRs must be completed using `.github/pull_request_template.md`.</li><li>Provider/validation PRs must include Standards Mapping (rounds, fixture anchors, failing-first tests).</li></ul>\n<h2 id=\"user-story-coverage-gate\">User story coverage gate</h2>\n<ul><li>`docs/linked-art/LinkedArtUserStories.json` is the canonical persona backlog for standards-critical features.</li><li>If implementation work exposes a standards/process gap, add or update a user story before merging code.</li><li>Every provider/validation/protocol PR should reference at least one story ID in the PR summary.</li><li>Do not delete governance-critical stories without replacement coverage and reviewer sign-off.</li></ul>\n<p>Governance-critical coverage areas that must remain represented:</p>\n<ul><li>authority-backed classification UX (no free-text default for controlled terms)</li><li>data discovery signposting (`describedby` canonical link behavior)</li><li>cite-or-refuse output guarantees for generated content</li><li>ARK resolver conformance (opaque IDs, suffix pass-through, `?info`)</li><li>Wikibase Cloud-to-self-host migration and security baseline</li></ul>\n<h2 id=\"quality-gates\">Quality gates</h2>\n<ul><li>`pnpm test`</li><li>`pnpm lint`</li><li>`pnpm build`</li><li>Required protocol/conformance tests for affected routes and providers</li></ul>\n<h2 id=\"technical-comment-standard\">Technical comment standard</h2>\n<ul><li>Add technical comments to all changed production modules when logic is non-obvious.</li><li>Comments must explain intent and invariants (for example: provider API constraints, rights safety rules, URI opacity, array-cardinality guarantees), not restate obvious syntax.</li><li>When adding provider routes/adapters, include comments for pagination limits, required auth/secrets behavior, and data-shape assumptions at validation boundaries.</li></ul>","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"cd0a0524525a1eaa1218bbbed59b4ffa15835cd7936faa340dad06e72ae0063f","checksumPrefix":"cd0a0524525a","anchorCount":5,"lineCount":56,"rawUrl":"/api/docs/content?path=development%2Faidd-tdd.md","htmlUrl":"/docs?doc=development%2Faidd-tdd.md","apiUrl":"/api/docs/content?path=development%2Faidd-tdd.md"}