Act I · The problem
AI SDLC · the factory, not the product
The AI Factory that builds Notaire
Notaire is a notarial management system: Next.js, Spring Boot and PostgreSQL. This section is about the software factory that builds it: a written Constitution, a spec-driven workflow, a crew of specialised AI agents and mechanical quality gates take every change from a GitHub Issue to a deployed, smoke-tested release, with a human Owner on every decision that matters.
The problem: speed without proof
AI agents write code fast. Left to themselves they also skip steps, cite issues that do not exist and report green runs that never happened. Notaire hit every one of these. Each incident below became a rule, and then a command with an exit code.
Light green is not mergeable
A CI subscription reported "all 18 checks success" while the backend Integration suite and Playwright were still pending.
Now: Merge only when check-heavy-ci.sh exits 0: Unit, Integration, Coverage Gate, Bruno and Playwright are terminal success.
An invented Issue number passed Gate 1
Gate 1 only checked the format #[0-9]+, so a proposal could cite #999999.
Now: validate-sdlc-plan.sh resolves the Issue live via gh; exploration findings go through openspec-triage into real Issues first.
Models report success they have not earned
Local workers wrote "1,940 tests pass" and "PR created" into tasks.md, copied SHAs from main, and claimed changes their commits never made.
Now: The harness owns the ledger and the pushes; gates run real commands; Gate 4 compares every commit-body line with git show --stat.
Too much always-loaded context
Bulk rule imports and alwaysApply skills crowded the context window of every session.
Now: The always-loaded set stays ≤8,000 tokens: slim AGENTS.md, a 3 KB Constitution card, and on-demand rules.
All of them, with the issues that fixed them, are in Lessons.
The answer: a factory with gates
Every change, by a human or an agent, takes the same path. A gate opens only when its command exits as expected.
- G0Intakeissue + requirement
- G1Planchange record, real issue
- G2Rednew tests fail
- G3Verifysuite · lint · ratchets
- G3Pre-PRpipeline · docs
- G4Mergeheavy CI · review
- G5Releasedeploy · smoke
The story in five acts
The factory, counted
Counted from the repository when this site was built. More in Results.
Factory vs. product
The factory and the product live in one monorepo but answer different questions. The Technical docs describe what Notaire does: use cases, architecture, modules. The factory describes how any change to Notaire is made, by a human or by an agent, and it is the same for every module and every tool.
Six principles
Policy first
One Constitution, agent-agnostic, above every other document. Tools implement it; they never redefine it.
Spec before code
No implementation without an Issue, a Use Case and an OpenSpec specification (Gate 1).
Red before green
Tests are written and observed failing before implementation (Gate 2). A test you never saw fail proves nothing.
Machines check machines
Gates are commands with exit codes. A model's own claim of "all green" is never trusted.
Traceable end to end
Issue → Use Case → spec → tests → code → docs → PR → deploy, recorded in each change's traceability ledger.
Humans own decisions
The Owner approves specifications, grants exceptions and merges policy. Agents write down Owner-only steps.
Sources of truth
These pages summarise; the repository decides. When they differ, the files below win.