@novare-technologies/nvaid 0.0.0-stage → 0.2.0

package/templates/rules/ISSUE-TRACKER-TEMPLATE.md

@@ -0,0 +1,221 @@
+---
+document: Issue Tracker Integration (Jira / GitHub Projects)
+project: "{{PROJECT_NAME}}"
+version: 0.3.0
+owner: "[Process Facilitator name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Issue Tracker Integration
+
+**What this file is:** the field shape and creation rules for how Fig. 2's Intent-to-Release
+artifacts show up in Jira or GitHub Projects — one Epic per Intent, one Story or Bug per
+Unit of Work, bundled for shipping by Release Checkpoint rather than by sprint — so the
+tracker and the `aidlc-docs/` artifacts never disagree about what was decided.
+
+**What this file is not:** not a replacement for `intent.md`, `unit-breakdown.md`, or any
+contract file. The tracker is the *tracking* layer — status, ownership, checkpoint
+placement, at-a-glance search. The artifacts are the *content* layer — what was actually
+agreed, in full, versioned in git. A ticket field never carries content that only exists in
+the ticket; if it's worth writing down, it's worth writing into the file the AI agent
+actually reads, and the ticket links to it.
+
+**Companion files:** [PROJECT-RULES.md](./PROJECT-RULES.md) §7 rule 11 is the operating
+rule this file implements. [unit-breakdown-rules.md](./unit-breakdown-rules.md) governs
+*how* a Unit of Work is decided and classified before it ever becomes the ticket
+described here. The worked example in `docs/templates/samples/` is what every link below
+would actually point at for `INTENT-004`.
+
+**Why no sprints:** Scrum's sprint boundary is a batching mechanism for coordinating fixed
+human capacity in fixed time boxes. Once a Unit of Work is small, AI-implemented, and gated
+independently rather than committed to as part of a sprint's bundle, the fixed box adds
+waiting without adding structure. This file uses continuous, pull-based flow instead — see
+§3 for the checkpoint that replaces the sprint as the unit of release planning.
+
+---
+
+## 0. The Rule This File Exists to Enforce
+
+A ticket holds three kinds of information, and only two of them belong in ticket fields:
+
+1. **Tracking metadata** (status, gate state, checkpoint, owner) — belongs in ticket
+   fields. This is what Jira/GitHub boards are good at, and it's fine for it to live only
+   there.
+2. **Links to content** (the Intent, the contracts, the design docs) — belongs in ticket
+   fields, as links, never as pasted text.
+3. **The content itself** (what the API contract actually says, what the acceptance
+   criteria actually are) — belongs *only* in the `aidlc-docs/` artifact. Pasting it into
+   a ticket description creates a second copy that drifts the first time either one is
+   edited without the other, and the AI agent isn't the one reading the ticket anyway — it
+   reads the file.
+
+## 1. Epic — one per Intent
+
+Created by the AI agent immediately after the Decomposition Approved gate (Fig. 2, Stage
+3) — not before, since the Epic's content depends on Joint Elaboration having actually
+happened.
+
+| Field | Value | Set By |
+|---|---|---|
+| Issue type | Epic | — |
+| Title | `[<INTENT-ID>] <business objective, short>` | AI |
+| Intent ID | e.g. `INTENT-004` | AI |
+| Link — Intent | permalink to `intent.md` | AI |
+| Link — Unit Breakdown | permalink to `unit-breakdown.md` | AI |
+| Gate: Decomposition Approved | status / approver / date | AI transcribes an approval already recorded in `unit-breakdown.md` — never grants it |
+| Contracts produced | links only, e.g. Solutions / Backend / Frontend / Quality / CX &mdash; each to its own file | AI, from the Contracts Produced table in `unit-breakdown.md` |
+| Role explicitly not pulled in | e.g. `devops: not pulled in — see devops-architecture-contract.md` | AI |
+| Epic owner (accountable human) | Customer Experience Architect (BA/PM) | AI sets, human is the actual owner |
+| Status | see §4 | AI, mechanically |
+| Release Checkpoint | *(blank at creation)* | **Process Facilitator**, following the CX Architect's prioritized backlog — see §3 |
+
+**Contracts live here, not on the Story.** Architecture Contracts are produced once per
+Intent, at Joint Elaboration — they are never re-created per Unit of Work. A Story (§2)
+links to whichever of *this* Epic's contracts are relevant to it, via that contract's own
+`covers_units` field; it does not carry its own copy or its own contract.
+
+**Worked example (`INTENT-004`):** Title `[INTENT-004] Developer Provisions a mycv
+Environment with a Branch Override`; contracts linked for Solutions, Backend, Frontend,
+Quality, and CX; DevOps flagged not pulled in, linking `devops-architecture-contract.md`.
+
+## 2. Story or Bug — one per Unit of Work, child of its Intent's Epic
+
+Created as a stub alongside the Epic (Stage 3), status `Backlog`; filled in as the owning
+role's Per-Role Authoring (Stage 4) and its gate (Stage 5) complete. **One Unit of Work is
+always exactly one Story or one Bug** — never a separate ticket type, never both. Which
+one is decided by `unit-breakdown-rules.md` §3's classification rule (new/changed
+capability &rarr; Story; existing shipped behavior violating its own spec &rarr; Bug), not
+by the tracker.
+
+| Field | Value | Set By |
+|---|---|---|
+| Issue type | `Story` or `Bug` (Jira native types; GitHub: Issue labeled `type:story` / `type:bug`, sub-issue of the Epic) — per `unit-breakdown-rules.md` §3 | AI |
+| Title | `[<UNIT-ID>] <short description>` | AI |
+| Unit ID | e.g. `UNIT-004-02` | AI |
+| Owning role | e.g. Backend Solutions Architect | AI, from `unit-breakdown.md` |
+| Link — Unit design | permalink to `unit-XXX-design.md` | AI, added at Stage 4 |
+| Link — Gate approval | permalink to `gate-approval-unit-XXX.md` | AI, added at Stage 5 |
+| Relevant contracts | a **list** of links, one per Epic contract whose `covers_units` names this Unit &mdash; a Story routinely carries more than one | AI |
+| Gate: Per-Unit Design Approved | status / approver / date | AI transcribes; owning Architect grants |
+| Merge Approval | status / approver / date / PR link | AI transcribes; owning Architect grants |
+| Status | see §4 | AI, mechanically |
+| Release Checkpoint | *inherited from the parent Epic — not set independently* | — |
+
+**A Story never carries its own Release Checkpoint.** All Units of Work under one Intent
+ship in the same checkpoint as that Intent — splitting them across two checkpoints would
+mean the Intent's own success criteria could be satisfied on one deploy and not the other,
+which breaks the reason the Intent was decomposed as a whole in the first place.
+
+**Sub-tasks are not a default part of this shape.** A Unit of Work is already sized to be
+one AI-implementable increment (Fig. 2, Stage 6) — splitting it into sub-tasks by default
+would just be re-inventing what the Unit boundary already does. Add a sub-task only if the
+Unit's own design doc identifies a genuinely separable implementation chunk, and let that
+doc, not the ticket, be the reason why.
+
+## 3. Release Checkpoint — a bundle of Intents, not a date
+
+Replaces the sprint as the unit of release planning. A Release Checkpoint is a **named,
+content-defined set of Intents** assigned to ship together — mapped directly onto a native
+tracker construct rather than a bespoke one:
+
+| Tracker | Native construct |
+|---|---|
+| Jira | Fix Version / Release |
+| GitHub Projects | Milestone |
+
+Both already carry the right semantics out of the box: a bundle of issues, a completion
+percentage, and a "Release" / close action — no custom issue type needed.
+
+**Completion rule:** a Release Checkpoint is **Released** — deployment happens — only once
+*every* Epic assigned to it has reached **Intent Complete**: every one of its child
+Stories has reached `Merged`, and each Story's own Definition of Done (`PROJECT-RULES.md`
+§5.1, which already includes the Design-Code Dictionary update) was satisfied on the way
+there. This is deliberately all-or-nothing: one straggler Intent holds the whole checkpoint
+back. That's a real tradeoff, not a hidden one — it buys a release that always contains a
+coherent, fully-tested set of capabilities, at the cost of a fast Intent sometimes waiting
+on a slow sibling. If that tradeoff stops being worth it for a given checkpoint, split it
+into two smaller checkpoints — don't quietly ship a partial one.
+
+**Who assigns what:**
+
+- The **CX Architect (BA/PM)** decides which Intents belong together and in what order —
+  this is the prioritized backlog they already own (see the Roles table).
+- The **Process Facilitator** turns that priority into the actual checkpoint assignment
+  (moving the Epic into the Fix Version / Milestone) and watches flow — if a checkpoint's
+  scope stops looking realistic given current throughput, that's flagged, not silently
+  absorbed by working longer hours.
+- **Release Approval** (Fig. 2, Stage 10) is granted at the checkpoint level by the
+  Solutions Architect + CX Architect, once every contained Epic shows Intent Complete —
+  read Stage 10 in Fig. 2 as operating on the checkpoint, not on a single Intent in
+  isolation.
+
+## 4. Status — Story and Epic tracked separately
+
+Kanban-shaped: continuous flow through named columns, not a sprint burndown. Suggested WIP
+limits apply only at genuinely constrained (human-gated) columns — AI-only stages aren't a
+shared human resource in the same way, so capping them is a pipeline-capacity question, not
+a flow-discipline one.
+
+### Story
+
+| Status | Fig. 2 stage | Set by | Suggested WIP limit |
+|---|---|---|---|
+| Backlog | 3 &middot; Decomposition Approved | AI creates | none — it's the queue |
+| Design In Progress | 4 &middot; Per-Role Authoring | AI | &asymp;1&ndash;2 per owning role in parallel |
+| Design Approved | 5 &middot; Gate passed | AI transcribes; owning Architect grants | transient, no cap needed |
+| In Progress | 6 &middot; Implementation | AI | pipeline-capacity bound, not human-bound |
+| Gates Running | 7 &middot; Automated Gates (incl. self-correct loop) | AI / pipeline | pipeline-capacity bound |
+| Merge Pending | 7 passed, awaiting 8 | AI | &asymp;1&ndash;2 per owning Architect &mdash; keeps approvals from queuing into a rubber-stamped batch |
+| Merged | 8 &middot; Merge Approved | AI transcribes; owning Architect grants | &mdash; |
+
+### Epic
+
+| Status | Meaning | Set by |
+|---|---|---|
+| Backlog | Decomposition Approved, not yet assigned a Release Checkpoint | AI creates |
+| In a Checkpoint | Assigned; child Stories in flight | Process Facilitator assigns; status itself rolls up automatically |
+| Intent Complete | Every child Story is `Merged`, DoD satisfied on each | AI, mechanically, once true |
+| Released | Its Release Checkpoint has been approved and deployed | AI transcribes; Solutions Architect + CX Architect grant, at the checkpoint (§3) |
+
+## 5. Who Creates, Who Schedules
+
+- **The AI agent creates and maintains every issue** — Epic and Story, every field in §1
+  and §2 except Release Checkpoint — as a direct, mechanical byproduct of the artifacts it
+  already produces. This is reversible (edit or close an issue, nothing breaks) and
+  evidence-based (every field is a transcription of something already decided in a file),
+  so it fits the same "propose, don't dispose" rule that governs the agent's other
+  unsupervised actions — see `PROJECT-RULES.md` §7.
+- **A human is the only one who assigns a Release Checkpoint** — see §3's split between the
+  CX Architect (priority) and the Process Facilitator (the actual assignment and flow
+  health). That's a scope and capacity call the agent has no real visibility into.
+- **Gate and approval fields are transcriptions, not grants.** The AI agent writes
+  "Design Approved: yes, [Architect], [date]" into the ticket only after that approval
+  already exists in the corresponding `gate-approval-unit-XXX.md` file — it never sets an
+  approval field as an independent action.
+
+**Known limitation, stated plainly:** neither Jira nor GitHub Projects has a built-in
+permission that technically restricts *which fields* an integration can write — unlike a
+git branch-protection rule, "AI never assigns a Release Checkpoint" is a process convention
+enforced by this document and spot-checked at the Process Facilitator's regular review, not
+a hard technical lock. If the harness's tracker integration ever supports scoped field
+permissions, tighten this from convention to enforcement and update this section.
+
+## 6. Jira vs. GitHub Projects — mechanics
+
+| Concept | Jira | GitHub Projects |
+|---|---|---|
+| Epic | Native `Epic` issue type | Tracking issue with native sub-issues, or a Project grouping field |
+| Story / Bug | Native `Story` / `Bug` issue type, linked via Epic Link | Issue, labeled `type:story` / `type:bug`, added as a sub-issue of the Epic |
+| Custom fields (Intent ID, Gate status, etc.) | Custom fields, single-select for status-like values | Project (beta) custom fields — same types available |
+| Release Checkpoint | Fix Version / Release | Milestone |
+| Sprint / Iteration | Native field — **deliberately unused** under this flow model | Native field — **deliberately unused** under this flow model |
+| Link to repo artifact | Web Link / Remote Link to the file's permalink | Native — link or reference the file path directly |
+
+## 7. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Question raised while reviewing the Mob Elaboration Ceremony: how do Jira/GitHub tickets relate to these artifacts |
+| 0.2.0 | [date] | Replaced Sprint/Iteration with Release Checkpoint (Fix Version / Milestone, bundling Intents, all-or-nothing completion); split the Story and Epic status enums; added WIP-limit guidance; clarified contracts are Intent-level, referenced per-Unit via `covers_units`, never duplicated per Story | Kanban-vs-Scrum discussion; clarifying question on Intent/Unit-of-Work/contract relationships |
+| 0.3.0 | [date] | A Unit of Work is now explicitly Story *or* Bug, classified by `unit-breakdown-rules.md` §3; clarified a Story/Bug carries a list of contract links, not a single one | New companion file: `unit-breakdown-rules.md` |

package/templates/rules/backend-architecture-contract-generation-rules.md

@@ -0,0 +1,56 @@
+---
+document: Backend Architecture Contract — Generation Rules
+project: "{{PROJECT_NAME}}"
+version: 0.1.0
+owner: "[Backend Solutions Architect name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Backend Architecture Contract: Generation Rules
+
+**What this file is:** the rules the AI agent follows to draft a Backend Architecture
+Contract for an Intent, during Mob Elaboration Phases 2–5 — what triggers producing one,
+and what it must contain when it does.
+
+**What this file is not:** not the worked example —
+`docs/templates/samples/contracts/backend-architecture-contract.md` is the canonical
+shape and sign-off format, filled in for `INTENT-004`. Not the draft/human-edit
+relationship either — every generated contract is a starting framework, never a verdict;
+see the AI-Native Engineering Model's §Mob Elaboration for how the Backend Solutions
+Architect accepts, extends, or simplifies it before Sign-Off.
+
+**Companion files:** [unit-breakdown-rules.md](./unit-breakdown-rules.md) (same
+Elaboration session). The other five `*-architecture-contract-generation-rules.md` files
+are siblings, one per role.
+
+---
+
+## 1. When This Contract Is Required
+
+Any Intent with at least one Unit of Work touching the backend — an API/service layer, an
+async worker or job runner, or a data-store schema. If none of an
+Intent's Units touch these, this contract is not produced — logged the same way
+`devops-architecture-contract-generation-rules.md` §1 logs a skip: the file states "not
+pulled in" and why, rather than simply not existing.
+
+## 2. Required Content
+
+- **API Contract Exposed.** Full request/response shape for any new or changed endpoint,
+  including error cases (4xx/5xx) — not just the happy path.
+- **Shared Derivation Rules.** Anything another role (most often Frontend) needs to
+  independently reproduce — a naming rule, an ID derivation — is defined once, here, and
+  referenced elsewhere. It is never re-derived independently by the consuming role.
+- **Data Model Touches.** Which tables/columns are written, and whether a migration is
+  needed.
+- **Components Touched (Design-Code Dictionary impact).** Named components this
+  Intent's Backend work will add, move, or touch.
+- **What This Contract Deliberately Excludes.** Anything the room discussed and
+  explicitly deferred — stated, not silently dropped.
+- **Sign-Off.**
+
+## 3. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Companion to the five sibling `*-contract-generation-rules.md` files |

package/templates/rules/customer-experience-contract-generation-rules.md

@@ -0,0 +1,51 @@
+---
+document: Customer Experience Contract — Generation Rules
+project: "{{PROJECT_NAME}}"
+version: 0.1.0
+owner: "[Customer Experience Architect name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Customer Experience Contract: Generation Rules
+
+**What this file is:** the rules the AI agent follows to draft a Customer Experience
+Contract for an Intent, during Mob Elaboration Phases 2–5 — what triggers producing one,
+and what it must contain when it does.
+
+**What this file is not:** not the worked example —
+`docs/templates/samples/contracts/customer-experience-contract.md` is the canonical
+shape and sign-off format, filled in for `INTENT-004`. Not the draft/human-edit
+relationship either — every generated contract is a starting framework, never a verdict;
+see the AI-Native Engineering Model's §Mob Elaboration for how the Customer Experience
+Architect accepts, extends, or simplifies it before Sign-Off.
+
+**Companion files:** [unit-breakdown-rules.md](./unit-breakdown-rules.md) (same
+Elaboration session). The other five `*-architecture-contract-generation-rules.md` files
+are siblings, one per role.
+
+---
+
+## 1. When This Contract Is Required
+
+**Always.** Every Intent originates from, or must be validated against, a real business
+need — the Customer Experience Architect is the one who closes that loop after the
+technical contracts land, confirming the room's final shape still serves it.
+
+## 2. Required Content
+
+- **Reconciliation Against the Original Intent.** Where the final, technically-grounded
+  shape narrowed, resolved, or held unchanged against what `intent.md` originally said —
+  named explicitly, not silently absorbed into the acceptance criteria without comment.
+- **Final Acceptance Criteria.** The technically-grounded version of the Intent's own
+  Success Criteria, incorporating what the other contracts actually committed to — not a
+  restatement of the Intent verbatim.
+- **What "Done" Looks Like to the Business.** Tied to a concrete validation scenario, not
+  "the code merged."
+- **Sign-Off.**
+
+## 3. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Companion to the five sibling `*-contract-generation-rules.md` files |

package/templates/rules/frontend-architecture-contract-generation-rules.md

@@ -0,0 +1,56 @@
+---
+document: Frontend Architecture Contract — Generation Rules
+project: "{{PROJECT_NAME}}"
+version: 0.1.0
+owner: "[Identity Access and Frontend Architect name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Frontend Architecture Contract: Generation Rules
+
+**What this file is:** the rules the AI agent follows to draft a Frontend (Identity
+Access and Frontend) Architecture Contract for an Intent, during Mob Elaboration Phases
+2–5 — what triggers producing one, and what it must contain when it does.
+
+**What this file is not:** not the worked example —
+`docs/templates/samples/contracts/frontend-architecture-contract.md` is the canonical
+shape and sign-off format, filled in for `INTENT-004`. Not the draft/human-edit
+relationship either — every generated contract is a starting framework, never a verdict;
+see the AI-Native Engineering Model's §Mob Elaboration for how the Identity Access and
+Frontend Architect accepts, extends, or simplifies it before Sign-Off.
+
+**Companion files:** [unit-breakdown-rules.md](./unit-breakdown-rules.md) (same
+Elaboration session). The other five `*-architecture-contract-generation-rules.md` files
+are siblings, one per role.
+
+---
+
+## 1. When This Contract Is Required
+
+Any Intent with at least one Unit touching the frontend (web or mobile), a design
+system component, or an identity/access/RBAC/SSO surface. Skipped only for Intents with
+zero user-facing or access-model impact — rare, since most Intents eventually surface
+somewhere in the UI.
+
+## 2. Required Content
+
+- **Consumes.** Which Backend contract (if any) this one consumes verbatim, with
+  confirmation that no field is locally reinterpreted or renamed.
+- **UI Flow.** The concrete step-by-step, tied to specific screens or components — not a
+  general description of the feature.
+- **Shared Derivations, Sourced Not Re-Derived.** Point to the Backend contract's version
+  of anything both roles need (an ID derivation, a naming rule); never re-derive it
+  independently.
+- **Identity / Access Implications.** Stated explicitly even when the answer is "none for
+  this Intent" — never left implicit. This is the one open risk area (SRS §9, no
+  RBAC/SSO in POC scope) most likely to get silently assumed away if it isn't required in
+  writing every time.
+- **Components Touched (Design-Code Dictionary impact).**
+- **Sign-Off.**
+
+## 3. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Companion to the five sibling `*-contract-generation-rules.md` files |

package/templates/rules/quality-architecture-contract-generation-rules.md

@@ -0,0 +1,86 @@
+---
+document: Quality Architecture Contract — Generation Rules
+project: "{{PROJECT_NAME}}"
+version: 0.5.0
+owner: "[Quality Architect name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Quality Architecture Contract: Generation Rules
+
+**What this file is:** the rules the AI agent follows to draft a Quality Architecture
+Contract for an Intent, during Mob Elaboration Phases 2–5 — what triggers producing one,
+and what it must contain when it does. This file owns the **Intent-Specific Gates** only
+(`PROJECT-RULES.md` §5.2) — content that's regenerated fresh per Intent. It does not
+define, and a generated contract must never redefine, the **Solution-Specific Gates**
+(Build, Code Coverage, Code Quality, Reusability/Duplication, Regression Test, SAST) —
+those are fixed codebase-wide thresholds set once in §5.2, not something any single
+Intent opts into or out of.
+
+**What this file is not:** not the worked example —
+`docs/templates/samples/contracts/quality-architecture-contract.md` is the canonical
+shape and sign-off format, filled in for `INTENT-004`. Not the draft/human-edit
+relationship either — every generated contract is a starting framework, never a verdict;
+see the AI-Native Engineering Model's §Mob Elaboration for how the Quality Architect
+accepts, extends, or simplifies it before Sign-Off.
+
+**Companion files:** [unit-breakdown-rules.md](./unit-breakdown-rules.md) (same
+Elaboration session). The other five `*-architecture-contract-generation-rules.md` files
+are siblings, one per role.
+
+---
+
+## 1. When This Contract Is Required
+
+**Almost always.** Any Intent that reaches Implementation (Fig. 2 Stage 6) at all gets a
+Quality Architecture Contract. The rare exception is an Intent whose Units are pure
+documentation or process changes with no code path to test.
+
+## 2. Required Content
+
+- **Required Test Coverage table.** One row per meaningful scenario, and — this is the
+  load-bearing rule, not a formatting preference — **every row traces to one of the
+  owning Unit's own stated Acceptance Criteria** (`unit-XXX-design.md`, per
+  `unit-breakdown-rules.md` §2), not surfaced independently from Elaboration discussion
+  and hoped to line up. Each row is also classified by type — never left as an unlabeled
+  list:
+  - **Happy Path** — the primary success scenario(s).
+  - **Negative Path** — deliberate invalid input, with a specific expected failure
+    response (not just "it errors").
+  - **Edge Case** — a boundary condition or ambiguous scenario that's neither a clean
+    success nor a clean rejection. This is where a Known Gap most often originates — see
+    below.
+
+  **Both directions of the trace are checked, not just one:** every Acceptance
+  Criterion gets at least one covering row, and every row names the criterion it
+  verifies — or is marked explicitly supplementary rather than left looking like
+  undocumented coverage. A criterion with no covering row is a Known Gap, logged below,
+  not silently assumed to be "probably fine." The worked example demonstrates exactly
+  this: one row in `quality-architecture-contract.md` traces to nothing, which is how
+  its Known Gap got caught rather than missed.
+
+  Collectively, this table is what `PROJECT-RULES.md` §5.2's Unit Test Gate (and, where
+  more than one component is touched, the Integration Test Gate) run against — both
+  Intent-Specific. See §5.2 for the full nine-gate taxonomy and where the line sits
+  against the six fixed Solution-Specific gates this file never touches.
+- **NFRs in Scope (Intent NFR gate).** Which of the SRS's existing non-functional
+  requirements this Intent's Units are held to, *beyond* the solution-wide baseline
+  §5.2 already sets; state "none beyond the standing baseline" explicitly when true,
+  rather than leaving the section blank.
+- **Known Gaps.** Anything the room identified as untested and consciously accepted —
+  flagged, not silently dropped. Matches the worked example's `{user}`-derivation
+  collision gap.
+- **Definition of Done addition**, specific to this Intent, beyond `PROJECT-RULES.md`
+  §5.1's standing checklist — only if this Intent actually needs one.
+- **Sign-Off.**
+
+## 3. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Companion to the five sibling `*-contract-generation-rules.md` files |
+| 0.2.0 | [date] | Required Test Coverage rows must now be classified Happy Path / Negative Path / Edge Case, and explicitly tied to `PROJECT-RULES.md` §5.2's Unit/Integration Test Gates | Quality gate types were unspecified; §5.2 was a placeholder |
+| 0.3.0 | [date] | Scoped this file to Intent-Specific Gates only; Solution-Specific Gates (Code Coverage, Code Quality, Reusability, SAST, Build) are fixed in §5.2 and out of scope for any generated contract | Gate taxonomy split into Intent-Specific vs. Solution-Specific categories |
+| 0.4.0 | [date] | Required Test Coverage rows must now trace to the owning Unit's stated Acceptance Criteria in both directions — every criterion covered, every row justified | Should a Unit's acceptance criteria be the same thing its unit tests are based on? |
+| 0.5.0 | [date] | Solution-Specific gate list now includes Regression Test (added in `PROJECT-RULES.md` §5.2) — six fixed gates, nine total | Should Quality Gates include a card for regression testing? |

package/templates/rules/solutions-architecture-contract-generation-rules.md

@@ -0,0 +1,59 @@
+---
+document: Solutions Architecture Contract — Generation Rules
+project: "{{PROJECT_NAME}}"
+version: 0.1.0
+owner: "[Solutions Architect name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Solutions Architecture Contract: Generation Rules
+
+**What this file is:** the rules the AI agent follows to draft a Solutions Architecture
+Contract for an Intent, during Mob Elaboration Phases 2–5 — what triggers producing one,
+and what it must contain when it does.
+
+**What this file is not:** not the worked example —
+`docs/templates/samples/contracts/solutions-architecture-contract.md` is the canonical
+shape and sign-off format, filled in for `INTENT-004`. Not the draft/human-edit
+relationship either — every generated contract is a starting framework, never a verdict;
+see the AI-Native Engineering Model's §Mob Elaboration for how the Solutions Architect
+accepts, extends, or simplifies it before Sign-Off.
+
+**Companion files:** [unit-breakdown-rules.md](./unit-breakdown-rules.md) (same
+Elaboration session). The other five `*-architecture-contract-generation-rules.md` files
+are siblings, one per role.
+
+---
+
+## 1. When This Contract Is Required
+
+**Always.** Every Intent gets a Solutions Architecture Contract, even when the honest
+assessment is "no cross-cutting impact, no new ADR needed." This is the one contract
+never marked "not pulled in" — someone has to always confirm nothing systemic was
+missed, and that confirmation *is* the contract. An empty-looking assessment is a
+completed one, not a skipped one.
+
+## 2. Required Content
+
+- **System-Level Assessment.** Does this Intent introduce a new system container, cross
+  a boundary named in the SRS's System Containers (Fig. 2), or need a new ADR? State the
+  answer plainly, including when it's "no" on every count — don't omit the section
+  because the answer is negative.
+- **What This Intent Is Allowed to Touch.** An explicit boundary statement: which
+  containers/components are in scope for this Intent's Units of Work, and which are
+  explicitly out.
+- **AI-Agent Guardrail Implications.** Does this Intent introduce any unsupervised-action
+  surface `PROJECT-RULES.md` §7 doesn't already cover — a new destructive operation, a
+  new external API call, a new credential path? Flag it explicitly; don't assume the
+  existing rules cover a case they were never written against.
+- **Cross-Role Consistency Check.** Confirms the other contracts produced this session
+  don't contradict each other — this is the Solutions Architect's half of Phase 6's
+  Consistency Gate, recorded in writing rather than only spoken in the room.
+- **Sign-Off.**
+
+## 3. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Companion to the five sibling `*-contract-generation-rules.md` files |

package/templates/rules/unit-breakdown-rules.md

@@ -0,0 +1,121 @@
+---
+document: Unit of Work Decomposition Rules
+project: "{{PROJECT_NAME}}"
+version: 0.2.0
+owner: "[Process Facilitator name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Unit of Work Decomposition Rules
+
+**What this file is:** the rules the AI agent follows when proposing a Unit of Work
+breakdown at Mob Elaboration Phase 2 (Strawman Review) — how to cut one Intent into
+Units, how to classify each Unit as a Story or a Bug, and the sizing signals that say a
+strawman is cut wrong before the room spends time negotiating around a bad boundary.
+
+**What this file is not:** not the ticket field shape (`ISSUE-TRACKER-TEMPLATE.md`
+governs that), not the ceremony's choreography (the AI-Native Engineering Model's
+§ Mob Elaboration governs that), not the Intent template itself. This file governs
+one specific judgment call: given an approved Intent, what its Units of Work are.
+
+**Companion files:** [ISSUE-TRACKER-TEMPLATE.md](./ISSUE-TRACKER-TEMPLATE.md) is where a
+Unit of Work, once decided here, becomes a ticket. [PROJECT-RULES.md](./PROJECT-RULES.md)
+§7 rule 12 is the operating rule this file implements.
+
+---
+
+## 1. What a Unit of Work Is
+
+The smallest slice of an Intent that can be:
+
+- **designed** by one owning role, without needing another role's design to already
+  exist first (though it may *reference* another role's contract),
+- **gated** independently at Fig. 2's Stage 5 (Per-Unit Design Approved) and Stage 8
+  (Merge Approval), without waiting on a sibling Unit's gate, and
+- **implemented** by the AI agent in one sitting, without losing the earlier reasoning
+  in its own context (`PROJECT-RULES.md` §7 rule 8, scope discipline).
+
+A Unit of Work is never split further inside the ticket tracker by default
+(`ISSUE-TRACKER-TEMPLATE.md` §2) — the Unit boundary *is* the atomic boundary. If a
+"Unit" doesn't fit in one sitting, it was cut wrong; fix the cut, don't add sub-tasks
+around it.
+
+## 2. Acceptance Criteria — every Unit states its own
+
+A Unit of Work carries its own Acceptance Criteria, stated once in its design doc
+(`unit-XXX-design.md`, Fig. 2 Stage 4) — narrowed from the Intent's own Success Criteria
+(`intent.md`) down to just this Unit's slice. Not a restatement of the whole Intent's
+criteria on every Unit; each Unit states only the part of "done" that's actually its own
+to satisfy.
+
+**The traceability rule this exists to enforce:** the Quality Architecture Contract's
+Required Test Coverage table (`quality-architecture-contract-generation-rules.md` §2) is
+generated *from* this list, not surfaced independently and hoped to line up. Every
+stated Acceptance Criterion gets at least one Happy Path, Negative Path, or Edge Case
+test row that verifies it; every test row traces back to a criterion it verifies, or is
+marked explicitly supplementary rather than left looking like undocumented coverage. A
+criterion with no covering test row is a Known Gap (`PROJECT-RULES.md` §6) the same way
+an untested edge case already is — not silently assumed to be "probably fine."
+
+Without a named source, a Unit's tests and its actual "done" bar are two independently
+populated lists that happen to usually agree — right up until they don't. This is the
+rule that closes that gap. See the worked example: `unit-004-02-backend-design.md`'s
+four Acceptance Criteria are what `quality-architecture-contract.md`'s test table
+traces to, row by row — including the one row that traces to nothing, which is exactly
+how that Unit's Known Gap got caught instead of missed.
+
+## 3. Story or Bug — the classification rule
+
+Every Unit of Work is exactly one of these two ticket types. Classify per Unit, not per
+Intent — one Intent can produce a mix of both.
+
+| Classify as | When | Example |
+|---|---|---|
+| **Story** | The Unit adds or changes a capability — net-new or intentionally different behavior | The branch-override selector itself (`UNIT-004-01`) |
+| **Bug** | The Unit brings existing, already-shipped behavior back in line with a spec, contract, or FR it currently violates | A previously merged Unit's `{user}` derivation collides on two usernames in production |
+
+**Boundary case:** a defect found *during* Construction of a Story, before that Story's
+own Merge Approval, is fixed inside that same Unit — it does not spin out as a separate
+Bug. Only a defect discovered *after* a Unit has already merged becomes its own Bug-type
+Unit — under a fast, often single-Unit Intent of its own, or folded into a Known Gap per
+`PROJECT-RULES.md` §6 if it isn't urgent enough to justify a full Mob Elaboration pass by
+itself.
+
+## 4. Decomposition Heuristics
+
+Applied by the AI agent when proposing the Phase 2 strawman, and by the room when
+critiquing it:
+
+- **One primary owning role per Unit.** If a Unit's design would need two Architects to
+  co-author it, it's two Units connected by a contract, not one Unit that spans both.
+  This is what turns Fig. 2 Stage 4 into "×N roles in parallel" instead of one
+  tangled design.
+- **A shared dependency is a contract, not a split.** When two Units both need the same
+  answer to something (the worked example's `{user}` derivation rule), that answer is
+  negotiated once, in a contract, and referenced by both — never independently
+  re-derived, and never used as a reason to merge the two Units into one.
+- **Size to one sitting.** If a Unit's own design doc is trending toward the size of
+  several of the worked examples combined, that's a smell the Unit is actually two.
+- **Don't split to satisfy an org chart.** A Unit boundary is justified by an
+  independent design-and-gate need, never by "everyone should have something to own."
+  Splitting a naturally single-role, single-behavior change into two Units just to give
+  a second role a ticket produces busywork, not independence.
+- **Watch the Unit count as a signal, not a rule.** One Unit for an Intent that went
+  through full Joint Elaboration is a sign the Intent probably didn't need the
+  cross-role machinery at all. More than roughly six to eight Units is a sign the
+  "Intent" was actually several Intents bundled together and should have been split
+  before Elaboration, not after.
+
+## 5. Numbering
+
+`UNIT-<INTENT-NUMBER>-<sequence>`, zero-padded two digits — `UNIT-004-01`,
+`UNIT-004-02`, matching the worked example in `docs/templates/samples/`. Sequence order
+follows the order Units are listed in `unit-breakdown.md`, not build or gate order.
+
+## 6. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Clarifying how Units of Work get decomposed, classified (Story/Bug), and sized, separate from how they're ticketed |
+| 0.2.0 | [date] | Added §2: every Unit states its own Acceptance Criteria, and the Quality Architecture Contract's test coverage table must trace to them, not be surfaced independently | Should a Unit's acceptance criteria be the same thing its unit tests are based on? |