Notaire

Act II · How a change flows

AI Factory · Lifecycle

From Issue to closed Issue, step by step

The Constitution defines one mandatory, sequential workflow of 24 steps for every change: feature, bug fix, refactor, docs, CI or schema. No step may be skipped. Five hard gates stop the work until their conditions hold, whether a human or an agent is doing it.
CONSTITUTION.md §5 Official SDLC Workflow. The yellow hexagons are the hard gates of §6.Swipe sideways to see the whole diagram.

PlanUnderstand and specify

  1. step 1

    Issue

    One GitHub Issue per change, labeled and linked to a Use Case (CU-XX), RF-XX or RNF-XX, with acceptance criteria.

    Checked by .github/ISSUE_TEMPLATE/issue.md

  2. step 2

    Refine the requirement

    Confirm the Use Case is accurate; create or update it first if not.

  3. step 3Gate 1

    Specification

    An OpenSpec change on the notaire-sdlc schema describes only this change: proposal, traceability, delta specs, design, tasks.

    Checked by openspec validate <change> --strict · validate-sdlc-plan.sh

  4. step 4

    Impact analysis

    Affected modules from workspace/modules.yaml, entities, endpoints, schema, tests and docs.

    Checked by python3 workspace/modules.py affected <path>

  5. step 5

    Architecture review

    Follow the existing architecture (hexagonal, ADR-030); write an ADR when the change is architectural.

  6. step 6

    Branch

    From an updated main: <type>/<issue>_<description>. Push it at once (continuous publication).

    Checked by Branch Naming Convention Check

  7. step 7

    Acceptance criteria

    Given-When-Then scenarios in the delta spec are the acceptance criteria.

ProveTests first, then code

  1. step 8Gate 2

    Design test cases

    Happy path, edge cases and error paths at unit, integration and E2E level.

  2. step 9–10

    Write failing tests

    Unit and integration tests first, and watch them fail. A test you never saw fail proves nothing (P1).

    Checked by check-tdd-evidence.sh: production code needs test changes

  3. step 11

    Implement

    The minimum code that makes the tests pass, following the conventions.

  4. step 12

    Update existing tests

    Never weaken an assertion to force green.

  5. step 13–14

    Run tests and full regression

    Unit, integration, coverage ratchet, Bruno API tests. No @Disabled without approval.

    Checked by mvn verify -pl backend-api

  6. step 15

    Playwright E2E

    Every UI change: golden path and edge cases at mobile, tablet and desktop widths.

    Checked by testing/e2e — TS-nnnn suites

PublishDocument, commit, open the PR

  1. step 16Gate 3

    Permanent documentation

    Update the docs the change affects, in the same diff. Never duplicate; point at the permanent document.

    Checked by check-doc-traceability.py

  2. step 17

    Atomic commits

    Conventional Commits; Refs #N on intermediate commits, Closes #N on the closing one.

    Checked by check-commit-messages.sh

  3. step 17.5

    Full local pipeline

    One dashboarded pre-PR gate: plan check, security cases, preflight --full, markdown lint.

    Checked by bash workspace/sdlc/run_pipeline.sh

  4. step 18–19

    Pull request and green CI

    PR titled [#N] type(scope): description, with the PR template; wait for every required workflow.

ShipReview, merge, deploy, verify

  1. step 20Gate 4

    Code review

    Code owner, or the Foreman's Gate 4 review with no open finding. Heavy CI must be terminal success.

    Checked by check-heavy-ci.sh <pr>

  2. step 21

    Merge

    Via the PR only. The OpenSpec change is archived in that same PR (#1623).

  3. step 22

    Deploy

    CI → CD builds, signs (cosign) and publishes images to GHCR; SBOMs on version tags.

  4. step 23Gate 5

    Smoke test

    Health endpoint and the key flow of the change on the target environment.

  5. step 24

    Close the issue

    Only after deploy and smoke. Board Status Done, WIP labels removed.

The five hard gates

G1
Do not start implementation without
  • Issue linked to a Use Case
  • Specification written
  • Acceptance criteria defined

validate-sdlc-plan.sh resolves the Issue live with gh: an invented or closed number fails

G2
Do not implement without
  • Test cases designed
  • Unit tests written and observed failing
  • Integration tests where applicable

check-tdd-evidence.sh; the local harness requires TEST_CMD to fail

G3
Do not create a PR if
  • Docs not updated
  • Any test failing
  • Coverage below the JaCoCo ratchet
  • Lint/format failing
  • run_pipeline.sh not run or red

preflight.sh pre-push hook + run_pipeline.sh dashboard

G4
Do not merge if
  • CI red or pending
  • Review unresolved
  • Merge conflicts
  • Docs pending

protect-main ruleset (5 required checks) + check-heavy-ci.sh

G5
Not finished until
  • Deploy succeeded
  • Smoke test passed
  • Issue closed
  • Board Status and labels coherent

check-board-status-label-coherence.py; archive hygiene on main (Main Health)

Definition of Done

A change is Done only when the Issue is linked to a Use Case with acceptance criteria, the specification passed Gate 1, tests were written first and seen failing, the full suite and coverage ratchet are green, Playwright is green for UI changes, permanent docs are updated without duplication, commits are atomic and conventional, the PR is green and reviewed, and the change is merged, deployed, smoke-tested and its Issue closed.

↗ CONSTITUTION.md §3 Definition of Done↗ tasks.md template (12 groups)