@novare-technologies/nvaid 0.0.0-stage → 0.1.0

package/templates/commands/breakdown.md

@@ -0,0 +1,27 @@
+---
+command: nvaid:breakdown
+summary: Cut an approved Intent into Units of Work — the Phase 5 final cut, each unit tagged with its Owning Repo.
+stage: "Mob Elaboration — Phase 5"
+precondition: Contracts drafted (/nvaid:contracts has run)
+---
+
+# /nvaid:breakdown
+
+Produce `unit-breakdown.md` — the **Phase 5 output**, the decomposition of record,
+informed by the contracts from `/nvaid:contracts`. This runs **after** contracts, not
+before (the `unit-breakdown` Skill is Phase 5; the contract Skills are Phases 2–5).
+
+## Steps
+
+1. Read `intent.md` and the drafted `contracts/`.
+2. Run the `unit-breakdown` Skill per `{{AIDLC_ROOT}}/unit-breakdown-rules.md`: cut into
+   Units each with its own Acceptance Criteria, classify Story or Bug, size per the rules.
+3. Tag each Unit with its **Owning Repo** (frontend | backend | platform) — this is what
+   assigns units across the family (proposal §7).
+4. Reconcile each contract's `covers_units` against the final cut.
+5. Write `nvaid/intents/<INTENT-ID>-<slug>/unit-breakdown.md`. Flag as a draft awaiting
+   room critique (Phases 3–4) and the Decomposition-Approved gate.
+
+## Next
+
+`/nvaid:apply` — generate the per-repo unit design docs and open construction branches.

package/templates/commands/contracts.md

@@ -0,0 +1,35 @@
+---
+command: nvaid:contracts
+summary: Draft the per-role Architecture Contracts for an approved Intent (Phases 2–5).
+stage: "Mob Elaboration — Phases 2–5"
+precondition: Intent approved (Decomposition-Approved gate green)
+---
+
+# /nvaid:contracts
+
+Draft the Architecture Contracts for an **already-approved** Intent, running each role's
+contract Skill. The contracts are negotiated across Elaboration Phases 2–5 and **precede**
+the unit-breakdown (which is the Phase 5 output) — run `/nvaid:breakdown` after this.
+
+## Precondition
+
+Only run once the Intent is approved. If `intent.md` is still a draft awaiting the
+stakeholder, stop and say so.
+
+## Steps
+
+1. Read the approved `intent.md`.
+2. Run each required role Skill per its `*-architecture-contract-generation-rules.md`
+   under `{{AIDLC_ROOT}}`: solutions, the relevant tier contract(s) (frontend / backend),
+   quality, customer-experience. Pull a role in only if the Intent touches its domain;
+   state "not pulled in" explicitly for the rest.
+3. Write each to `nvaid/intents/<INTENT-ID>-<slug>/contracts/`.
+4. Each contract is a **draft awaiting its Architect's sign-off** — never present as final.
+   Read the architect roster from `nvaid/config.yml` (`architects.<role>`) and flag each
+   contract as "awaiting sign-off from <that named architect>". Never fill in a sign-off
+   on an architect's behalf (propose, don't dispose). If a role has no named architect in
+   config, state that its contract is not pulled in rather than inventing an owner.
+
+## Next
+
+`/nvaid:breakdown` — cut the approved Intent into Units, informed by these contracts.

package/templates/commands/intent.md

@@ -0,0 +1,32 @@
+---
+command: nvaid:intent
+summary: Draft an Intent (intent.md) — the business need and success criteria only, then STOP.
+stage: "Fig. 2 Stage 1 — Intent captured, pre-Elaboration"
+---
+
+# /nvaid:intent
+
+Draft a new Intent from the user's description. Produce **only** `intent.md` — the
+business need, who it's for, success criteria, and scope boundaries — then **stop**.
+
+## Hard rule: generate the intent and nothing else
+
+Do NOT generate contracts, a unit-breakdown, or any downstream artifact. The Intent must
+be approved by the stakeholder (the Decomposition-Approved green light) before anything
+downstream is generated. Stopping here is the whole point of the gated workflow, not a
+limitation — propose, don't dispose.
+
+## Steps
+
+1. Read this repo's `nvaid/PROJECT-RULES.md` (if present) for the project's operating
+   guardrails and approved stack. If it is still the unfilled template, proceed but note
+   that the project rules are not yet defined.
+2. Write `nvaid/intents/<INTENT-ID>-<slug>/intent.md`: business need, who it's for,
+   Intent-level success criteria (observable outcomes, not implementation), scope
+   boundaries (name what's out of scope, don't silently drop it), and open questions for
+   the room. Do not decide the technical shape here.
+3. Flag the file as a draft awaiting stakeholder approval. Stop.
+
+## Next (do not run automatically)
+
+After the stakeholder approves: `/nvaid:contracts`, then `/nvaid:breakdown`.

package/templates/nvaid/DESIGN-CODE-DICTIONARY.md

@@ -0,0 +1,90 @@
+---
+document: Design-Code Dictionary
+project: "{{PROJECT_NAME}}"
+version: 0.1.0
+owner: "<owner name>"
+maintained_by: AI agent — updated as part of any unit of work that touches a mapped component
+last_updated: "<YYYY-MM-DD>"
+status: draft
+---
+
+# {{PROJECT_NAME}} — Design-Code Dictionary
+
+> **Template dropped by `nvaid init` — HAND-OWNED, fill this in.**
+> `nvaid update` never overwrites this file. Delete these template notes once you have
+> real content.
+
+**What this file is:** a *technical README for the code* — the specs and design patterns
+of this repository, and a live map from each named concept (a feature, a module, an
+architectural component) to where it actually lives in the codebase and what else touches
+it. It answers two questions without opening the source: **"where does this live?"** and
+**"what breaks if I change it?"**
+
+**What this file is not:**
+
+- Not a replacement for reading the code when making a change — it is a navigation aid for
+  deciding whether a change is safe and who should review it.
+- Not a product spec. `nvaid/PROJECT-RULES.md` says what to build and how; this file says
+  where that intent actually landed, after the fact.
+- Not a promise of completeness. §5 exists so this file can honestly state what it has not
+  mapped yet, rather than implying coverage it doesn't have.
+
+**Keep it current.** Updating this file for every component a change adds, moves, or
+removes is part of the Definition of Done — a stale map is worse than none, because it is
+trusted and wrong.
+
+---
+
+## 1. Tech stack & toolchain
+
+The authoritative, structured stack lives in **`nvaid/config.yml` → `tech_stack`** (that is
+what agents and the CLI read). Don't duplicate it here — instead, add the *narrative* this
+file is for: why each major choice was made, how the pieces fit together, and any
+non-obvious interactions or constraints a contributor should know before changing them.
+
+<e.g. "React + Vite for the SPA; Vitest chosen over Jest for ESM-native speed. The build
+emits a static bundle served by nginx — see §2 and the Dockerfile. No SSR.">
+
+
+## 2. Project structure
+
+<A short orientation to the top-level directories — what each is for. Example:>
+
+```
+src/
+  <area>/        <one line: what lives here>
+  <area>/
+test/
+```
+
+## 3. Design patterns & conventions
+
+<The patterns a contributor (human or agent) must follow to stay consistent with the
+codebase. Be specific — these are the rules an agent can't infer from a single file.
+Examples:>
+
+- **<Pattern name>** — <what it is, when to use it, where an example lives>.
+- **State / data flow** — <how state is managed and data moves>.
+- **Error handling** — <the project's convention>.
+- **Naming** — <files, modules, symbols>.
+
+## 4. Component map (design concept → code)
+
+| Concept / feature | Lives in | Depends on | Changing it affects |
+|---|---|---|---|
+| <e.g. Auth session> | `src/auth/session.ts` | <modules> | <what breaks> |
+| | | | |
+
+## 5. Not yet mapped
+
+<List components or areas that exist in the code but aren't documented above yet, so this
+file is honest about its coverage. Keep this section — an empty "not yet mapped" is a
+claim of full coverage, and should only be empty when that's actually true.>
+
+- <none yet — fill the map as the code grows>
+
+## 6. Change log
+
+| Version | Date | Change | Author |
+|---|---|---|---|
+| 0.1.0 | <YYYY-MM-DD> | Initial draft from the nvaid template | <name> |

package/templates/nvaid/PROJECT-RULES.md

@@ -0,0 +1,93 @@
+---
+document: Project Standards & Engineering Rules
+project: "<project name>"
+version: 0.1.0
+owner: "<owner name>"
+last_updated: "<YYYY-MM-DD>"
+status: draft
+---
+
+# <project> — Project Standards & Engineering Rules
+
+> **Template dropped by `nvaid init` — HAND-OWNED, fill this in.**
+> `nvaid update` never overwrites this file. It is intentionally project-specific:
+> nvaid ships the universal skills and contract/unit rules, but *this* file is where a
+> developer records what is unique to this repo — the approved stack, the guardrails, the
+> data rules. Delete these template notes once you have real content.
+
+## 1. What this project is
+
+<One short paragraph: the objective, this phase's scope, explicit non-goals. The "why"
+an agent needs in the same file as the "how".>
+
+## 2. Architecture principles & constraints
+
+### 2.1 Approved technology stack
+
+| Layer | Approved | Disallowed without an ADR |
+|---|---|---|
+| <e.g. Backend> | <language/framework> | <what's off-limits> |
+| <e.g. Frontend> | <framework> | <what's off-limits> |
+| <e.g. Data store> | <engine> | <what's off-limits> |
+
+### 2.2 Non-negotiable constraints
+
+- <e.g. deployment target, network posture, build output format — things an agent must
+  not quietly change.>
+
+### 2.3 Architecture Decision Records (ADRs)
+
+<Where ADRs live and the rule to check them before proposing a change in an area one
+already covers.>
+
+## 3. Data rules
+
+- <How tenant/user/domain data is handled; what the project's own data is vs. isn't;
+  secret-handling discipline.>
+
+## 4. Design & coding standards
+
+- Follow the existing file/module layout; flag any new structural pattern.
+- Documentation bar (docstrings, module responsibilities) applies to AI-generated code
+  the same as human-authored.
+- Linter/formatter config: <link once established>.
+
+## 5. Quality & testing rules
+
+### 5.1 Definition of Done (per Unit of Work)
+
+- [ ] The Unit's stated Acceptance Criteria are met and each traces to a covering test.
+- [ ] Static analysis / security scan passes with no unresolved High findings.
+- [ ] Merge approved by the owning reviewer on gate evidence.
+- [ ] `nvaid/DESIGN-CODE-DICTIONARY.md` updated for every component added/moved/removed.
+
+### 5.2 Quality gates (CI gates that must pass before merge)
+
+<List the gates CI enforces for this project — build, unit test, coverage floor,
+code quality, security scan, etc. Keep project-wide gates here; per-Intent gates come
+from each Quality Architecture Contract.>
+
+## 6. Known gaps (do not silently resolve)
+
+- <Open questions the agent must treat as questions, not assumptions to fill in.>
+
+## 7. AI operating rules (guardrails, not suggestions)
+
+1. **Propose, don't dispose.** A named human approves before anything is merged or
+   treated as final. Never approve your own gate.
+2. **Ask before assuming.** Ambiguity → a clarifying question, not a best-guess fill-in.
+3. **Respect existing decisions.** Conflict with an ADR or an approved design → flag it,
+   don't quietly resolve it.
+4. **No unreviewed new dependencies.**
+5. **No destructive/irreversible actions without explicit per-action confirmation.**
+6. **Artifact hygiene is part of the task** — code without the matching `nvaid/` artifact
+   update is an incomplete task.
+7. **Identify AI-assisted changes** in commits and PRs.
+
+<Extend with project-specific guardrails.>
+
+## 8. Change log
+
+| Version | Date | Change | Author |
+|---|---|---|---|
+| 0.1.0 | <YYYY-MM-DD> | Initial draft from the nvaid template | <name> |

package/templates/nvaid/config.yml

@@ -0,0 +1,74 @@
+# nvaid project config — HAND-OWNED. `nvaid update` never overwrites this file.
+#
+# This is the one place a repo declares who and what it is in the AI-DLC workflow:
+#   - which coding agents nvaid targets here,
+#   - what tier/role this repo plays,
+#   - the full tech stack of the project,
+#   - who the named architects are that sign off on each contract,
+#   - the always-on project context every agent should carry.
+#
+# Written by `nvaid init`, then yours to maintain. The skills and slash commands read
+# this file to know, for example, who a drafted contract is "awaiting sign-off" from.
+
+schema: nvaid/v1
+
+# A short name for this project/repo, used in generated artifact headers
+# (replaces the {{PROJECT_NAME}} placeholder in PROJECT-RULES.md and the dictionary).
+project_name: "<set-me>"
+
+# Which repo this is in the family — used to tag the units this repo owns when a
+# unit-breakdown is cut. One of: frontend | backend | platform | <other>.
+owning_repo: "<set-at-init>"
+
+# The full tech stack of this project. This is the STRUCTURED, machine-readable source of
+# truth that agents and the CLI key off — e.g. a skill checks `languages` before proposing
+# a dependency, or picks the right test command from `test`. Keep it factual and short;
+# the narrative "why we chose this / how it fits together" belongs in
+# nvaid/DESIGN-CODE-DICTIONARY.md, which references this block rather than repeating it.
+#
+# Leave a field blank or omit it if it doesn't apply. `additional` is an open map for
+# anything the fixed fields don't cover (message brokers, infra, cloud, auth providers…).
+tech_stack:
+  languages: []                 # e.g. ["TypeScript", "Python"]
+  runtime: ""                   # e.g. "Node >=18", "Python 3.12"
+  frameworks: []                # e.g. ["React", "FastAPI"]
+  package_manager: ""           # e.g. "npm", "pnpm", "uv", "poetry"
+  build: ""                     # e.g. "Vite", "tsup", "hatch"
+  test: ""                      # e.g. "Vitest", "pytest"
+  lint_format: ""               # e.g. "eslint + prettier", "ruff"
+  database: ""                  # e.g. "PostgreSQL 16", "none"
+  deploy: ""                    # e.g. "Docker + Kubernetes", "GitHub Pages"
+  additional: {}                # e.g. { cache: "Redis", broker: "RabbitMQ", auth: "OIDC" }
+
+# Named architects who sign off on each role's Architecture Contract.
+#
+# These are SIGN-OFF / OWNERSHIP identities: the person accountable for approving that
+# contract. The AI drafts contracts and flags them "awaiting <role> sign-off from <name>";
+# it never signs on their behalf (propose, don't dispose). Leave a role blank/null if this
+# repo doesn't have that architect — a contract for a missing role is simply not pulled in.
+architects:
+  solutions: "<name>"            # Solutions Architect
+  frontend: "<name>"             # Frontend / Identity-Access Architect (if this repo has a frontend)
+  backend: "<name>"              # Backend Solutions Architect (if this repo has a backend)
+  quality: "<name>"              # Quality Architect
+  customer_experience: "<name>"  # Customer Experience Architect (BA / PM)
+  # add any project-specific roles here, e.g.:
+  # devops: "<name>"
+
+# Coding agents nvaid injected skills into. `nvaid update` regenerates exactly these.
+# Managed by init/update; change via `nvaid init` rather than by hand.
+agents: []
+
+# Optional project context passed to every agent — constraints an agent can't infer
+# from the code. Keep discoverable codebase facts OUT (same discipline as openspec).
+# The project's full guardrails live in nvaid/PROJECT-RULES.md (fill in that template);
+# this field is just the short, always-on context.
+# Example:
+#   context: |
+#     On-premises only. No cloud targets.
+#     See nvaid/PROJECT-RULES.md for the approved stack and gates.
+context: ""
+
+# nvaid version this repo was last generated against. `nvaid validate` compares the
+# installed CLI version to this and flags drift.
+generated_with: "0.1.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 |