fullstack-agentic-flow 2.0.0

package/payload/ai-agents/architecture-context.template.md

@@ -0,0 +1,554 @@
+# Architecture Context — {PROJECT NAME}
+
+> **This file is generated per repository by `/bootstrap` (agent 00), then
+> corrected by a human. It is the single source of truth every other agent
+> reads before doing anything.**
+>
+> There is no global version of this file and there never will be. Two repos
+> that both "use React and Postgres" still disagree about where files go, what
+> a service is allowed to do, and what a button looks like — and those
+> disagreements are exactly what makes generated code feel foreign. This file
+> is where a repo states its own answers.
+>
+> **Agents must not modify this file.** Only `/bootstrap` writes it, and only
+> when you re-run it deliberately. If an agent discovers a pattern that
+> contradicts this file, it raises that as a finding — it does not silently
+> adapt.
+>
+> Delete every `{PLACEHOLDER}` and every instruction block like this one before
+> committing. A section that does not apply should say **"N/A — {why}"**, not be
+> left as template text. Agents treat leftover template text as an unfilled gap
+> and will stop to ask.
+
+**Generated**: {ISO timestamp}
+**Last verified against codebase**: {ISO timestamp}
+**Bootstrap confidence**: {high | medium | low — set by agent 00}
+
+---
+
+## 1. What this system is
+
+{Two or three sentences, plain language. What the software does and who uses
+it. Agents use this to judge whether a proposed feature belongs here at all.}
+
+**Primary users**: {roles}
+**Deployment shape**: {monolith | modular monolith | service in a mesh | ...}
+**Scale posture**: {rows/requests/users the design should assume today, and the
+horizon it should not over-engineer for}
+**Large table threshold**: {row count above which a table counts as "large" —
+agent 01b scores data and performance risk against it}
+**Hot paths**: {the endpoints/screens/jobs that carry most traffic — 01b D6}
+
+### 1.1 Topology
+
+**Topology**: {mvc | unified-api | split-backend | split-frontend}
+**Secondary surface**: {none | e.g. "JSON API under /api/v1 for the mobile app"}
+**API style**: {N/A — mvc | REST | GraphQL | RPC/tRPC | gRPC | mixed: which where}
+**Schema source of truth**: {N/A | generated from code annotations by {tool} | SDL file at {path} | router types | hand-written spec at {path}}
+**Counterpart repositories**: {N/A | repo — role — how contracts travel (path/URL)}
+**Seam mode(s)** (agent 02d): {page-contract | http-api | graphql | export | import}
+
+---
+
+## 2. Stack inventory
+
+| Concern | Choice | Version | Notes |
+|---------|--------|---------|-------|
+| Language | {} | {} | |
+| Backend framework | {} | {} | |
+| Datastore(s) | {} | {} | |
+| Cache / queue | {} | {} | |
+| UI framework | {} | {} | |
+| Styling | {} | {} | |
+| Build tooling | {} | {} | |
+| Test runner(s) | {} | {} | |
+| Package manager(s) | {} | {} | |
+
+**Deliberate exclusions** — libraries the team has decided NOT to use, and why.
+This prevents agents from helpfully introducing them:
+
+- {library} — {why not}
+
+---
+
+## 3. Commands
+
+Agents run these verbatim. If a command does not exist, write `N/A` rather than
+inventing a plausible one.
+
+| Purpose | Command |
+|---------|---------|
+| Install dependencies | `{}` |
+| Run dev server | `{}` |
+| Run full test suite | `{}` |
+| Run one test file | `{}` |
+| Lint | `{}` |
+| Lint with autofix | `{}` |
+| Type check | `{}` |
+| Static analysis | `{}` |
+| Apply schema migrations | `{}` |
+| Generate a migration | `{}` |
+| Build for production | `{}` |
+| Secret scan | `{}` |
+
+---
+
+## 4. Repository map
+
+Where things live. Agents use this to place new files and to know where to look
+before claiming something does not exist.
+
+```
+{paste the actual annotated tree — two or three levels deep, with a comment on
+each significant directory. Not the output of `tree`; a curated map.}
+```
+
+**Where a new feature's files go**: {describe the rule — by module, by layer, by
+domain. Give one concrete worked path.}
+
+---
+
+# BACKEND
+
+## 5. Backend architecture
+
+### 5.0 Canon mapping
+
+How this repository maps the pipeline's backend canon
+(`.ai-agents/canon/backend-canon.md`). Agent 00b generates new modules from this
+table; 00 bootstrap re-verifies it on every run.
+
+**Canon mapping**: {laravel | nestjs | express | django | fastapi | spring | go | custom}
+**Strictness**: {strict | pragmatic}
+**Modules root**: `{path}`
+**Use-case entry method**: {execute | handle}   **Output suffix**: {Result | View}
+**Data-class mechanism**: {Spatie Data | readonly classes | class + mapper | dataclasses | pydantic | records}
+**Conformance**: {conforms | different vocabulary | partial — see §11 | does not conform — see §11}
+
+| Canon layer | Path in this repo | Contains here |
+|-------------|-------------------|---------------|
+| Module registration | `{}` | {} |
+| Domain | `{}` | {} |
+| Application | `{}` | {} |
+| Infrastructure | `{}` | {} |
+| Interface | `{}` | {} |
+| Tests — unit / integration / feature | `{}` | {} |
+| Fakes | `{}` | {} |
+
+**Newest conforming module** (00b reads it for texture): `{path}`
+
+### 5.1 Layers and boundaries
+
+{Name the layers in dependency order and state, for each, what it may and may
+not do. Be specific about the illegal moves — those are what agents get wrong.}
+
+| Layer | Responsibility | May call | Must never |
+|-------|----------------|----------|------------|
+| {} | {} | {} | {} |
+
+**The rule that matters most here**: {e.g. "handlers never touch the ORM
+directly", "domain services never construct HTTP responses"}
+
+### 5.2 Request lifecycle
+
+{Trace one request end to end, naming the actual classes/functions it passes
+through. This single trace teaches an agent more than a paragraph of
+description.}
+
+```
+{HTTP entry} → {routing} → {middleware} → {handler} → {input contract}
+  → {domain service} → {data access} → {datastore}
+  → {response shape} → {serialization}
+```
+
+### 5.3 Data access
+
+- **Pattern**: {repository | active record | query builder | DAO | ...}
+- **Where queries live**: {}
+- **Naming conventions for read methods**: {list the exact required names — this
+  is high-value, agents invent synonyms otherwise}
+- **Pagination**: {approach, default page size, response shape}
+- **Filtering / search**: {how filters arrive and how they are applied}
+- **Eager loading / N+1 policy**: {}
+- **Raw query policy**: {when raw SQL is permitted, and how parameters bind}
+
+### 5.4 Input contracts and validation
+
+- **Mechanism**: {DTO class | schema object | decorator | framework request}
+- **Where validation lives**: {}
+- **Create vs update differences**: {especially uniqueness handling}
+- **Error message conventions**: {tone, casing, whether defaults are overridden}
+- **What is validated where**: {client, edge, domain — and what is duplicated on
+  purpose}
+
+### 5.5 Business logic
+
+- **Where it lives**: {}
+- **Transaction boundaries**: {who opens them, what must be inside one}
+- **Domain errors**: {exception types, how they map to responses}
+- **Side effects** (email, events, webhooks): {dispatched where, sync or async}
+
+### 5.6 Authentication and authorization
+
+- **Auth mechanism**: {session | token | JWT | mTLS}
+- **Where authorization is enforced**: {middleware | policy | guard | handler}
+- **Role/permission model**: {}
+- **Default posture**: {deny-by-default or allow-by-default — state it plainly}
+- **Multi-tenancy**: {N/A, or how tenant scoping is applied and enforced}
+
+### 5.7 Background work
+
+- **Queue/worker system**: {N/A or name}
+- **What must be async**: {the threshold rule}
+- **Job conventions**: {base classes, naming, retry/timeout defaults, idempotency}
+- **Scheduling**: {}
+
+### 5.8 Backend exemplar — copy this shape
+
+{Paste a real, complete, currently-committed file that exemplifies a handler and
+its dependencies. Verbatim, not idealized. This is the highest-signal part of
+the entire document — the implementer agent matches it structurally. Pick your
+cleanest recent example, not your oldest.}
+
+```{language}
+{paste}
+```
+
+**Non-negotiable in the above**: {call out the 3–5 specific things that must be
+reproduced — return types, constructor injection style, naming, ordering}
+
+---
+
+## 6. Persistence conventions
+
+- **Naming**: {tables, columns, keys, indexes, constraints}
+- **Primary keys**: {type and generation strategy}
+- **Foreign keys**: {constrained? on-delete behaviour?}
+- **Timestamps**: {which, what type, timezone policy}
+- **Soft deletes**: {used? on which tables? how queries account for them}
+- **Audit columns**: {which, populated where}
+- **Money and precision**: {exact types — this is where projects lose real data}
+- **Enums / status columns**: {native enum, string with constraint, lookup table}
+- **JSON columns**: {permitted? which type? indexed how?}
+- **Migration rules**: {idempotency, reversibility, whether they may contain data
+  changes, how destructive changes are staged}
+
+### 6.1 Migration exemplar
+
+```{language}
+{paste a real migration}
+```
+
+### 6.2 Indexing policy
+
+{When an index is required rather than optional. Which columns always get one.
+How composite index column order is chosen. Any partial-index conventions.}
+
+---
+
+## 7. Interface surface conventions
+
+The frontend is built against this. Agent 02d freezes the per-feature seam, but
+these are the standing rules it must conform to. Fill the subsections the
+topology in §1.1 uses; mark the others `N/A — topology is {x}`.
+
+### 7A. HTTP API
+
+- **Style**: {REST | RPC | mixed — and where each is used}
+- **Route naming**: {pattern, with two examples}
+- **Versioning**: {}
+- **Success response envelope**:
+
+```json
+{}
+```
+
+- **Error response envelope**:
+
+```json
+{}
+```
+
+- **Validation error shape** (the frontend renders this field-by-field):
+
+```json
+{}
+```
+
+- **Status codes**: {which codes are used for what — especially for validation
+  failure, authorization failure, and async acceptance}
+- **Pagination shape**: {}
+- **Empty collection**: {`[]` vs `null` — state it, agents guess otherwise}
+- **Dates over the wire**: {format and timezone}
+- **Money over the wire**: {string or number, and precision}
+- **Async operations**: {how a queued job reports acceptance and completion}
+
+### 7B. GraphQL
+
+- **Schema approach**: {SDL-first | code-first — with which library}
+- **Naming**: {types, inputs, enums, mutations — e.g. `createBrand(input: CreateBrandInput!): CreateBrandPayload!`}
+- **Nullability policy**: {}
+- **Error model**: {typed union results | errors with extension codes — which for what}
+- **Pagination**: {connections | offset}
+- **Batching / N+1**: {dataloader or equivalent, where it lives}
+- **Authorization**: {per resolver | per field | directive}
+
+### 7C. Page contracts (MVC)
+
+- **Rendering call**: {e.g. `Inertia::render('Masters/Brands/Index', BrandIndexViewModel::from(...))`}
+- **View model convention**: {one Data class per screen, in `{path}`, named `{Screen}ViewModel`}
+- **Shared props**: {what every page receives, and where it is defined}
+- **Validation error bag**: {shape, and how the UI reads it}
+- **Flash messages**: {keys, tone, where rendered}
+- **Redirect after write**: {convention}
+- **Lazy / partial props**: {N/A or the mechanism}
+
+### 7D. Cross-repository contracts (split topologies)
+
+- **Contracts directory**: `contracts/{slug}/` — `seam.md`, schema fragment, `VERSION`
+- **Transport between repos**: {git submodule | copied by `/seam import` from a path | fetched from a URL | package}
+- **Versioning**: semver per `agents/02d-interface-seam.md`; consumers pin the version they built against
+
+---
+
+# FRONTEND
+
+## 8. UI architecture
+
+### 8.0 Frontend canon mapping
+
+How this repo maps `.ai-agents/canon/frontend-canon.md`.
+
+| Canon area | Path here |
+|------------|-----------|
+| Routes / pages | `{}` |
+| Feature folders | `{}` |
+| Shared UI (the inventory) | `{}` |
+| API client | `{}` |
+| Tokens | `{}` — or `DESIGN.md` |
+
+**Product and design context**: {`PRODUCT.md` + `DESIGN.md` (impeccable) | N/A}
+
+### 8.1 Composition model
+
+- **Rendering approach**: {SPA | SSR | islands | server-rendered templates}
+- **Routing**: {file-based | config | server-driven}
+- **How a page receives data**: {props from server | fetch on mount | loader |
+  server component — be specific, this drives every page the agent writes}
+- **State management**: {local | store library | server-state cache}
+- **What may hold state**: {which layer owns what — page vs component vs store}
+
+### 8.2 Screen anatomy
+
+{Describe the standard skeleton every screen conforms to. Layout wrapper,
+header, content container, action placement.}
+
+```
+{Layout}
+  └── {Page header: title, breadcrumb, primary action}
+       └── {Content container}
+            └── {feature content}
+```
+
+**Standard screen types and their required shape**:
+
+| Screen type | Required elements | Notes |
+|-------------|-------------------|-------|
+| List / index | {} | |
+| Create / edit form | {} | |
+| Detail / show | {} | |
+| Dashboard | {} | |
+
+### 8.3 Component inventory — the approved list
+
+Agents compose UI **only** from these. Inventing a component is a contract-level
+decision that must be raised at Gate 1, never made silently during
+implementation, because every ad-hoc component permanently widens the surface
+the team maintains.
+
+| Component | Import path | Use for | Do not use for |
+|-----------|-------------|---------|----------------|
+| {} | {} | {} | {} |
+
+**If a feature appears to need something not on this list**, the UI contract
+agent records it under "Architectural decisions needed" with a proposed API and
+a justification. A human approves it before it exists.
+
+### 8.4 Design tokens
+
+Agents must reference tokens, never literal values. A hex code in a diff is a
+review failure.
+
+**If `DESIGN.md` exists, it is the visual source of truth.** This section then
+records only where the tokens live in code and anything `DESIGN.md` omits. When
+the two disagree, bootstrap raises it; agents do not pick.
+
+| Token group | Values / source of truth |
+|-------------|--------------------------|
+| Color — semantic (primary, danger, success, warning, muted) | {} |
+| Color — surface / background / border | {} |
+| Typography scale | {} |
+| Font families | {} |
+| Spacing scale | {} |
+| Border radius | {} |
+| Elevation / shadow | {} |
+| Breakpoints | {} |
+| Z-index layers | {} |
+| Motion — duration and easing | {} |
+
+**Dark mode**: {supported? how it is implemented? what agents must do to keep a
+component correct in both themes}
+
+### 8.5 Required states
+
+Every data-bound surface must handle all of these. A UI task is not done if any
+is missing, and the QA agent tests each one explicitly.
+
+| State | Required treatment |
+|-------|--------------------|
+| Loading — initial | {skeleton? spinner? which component?} |
+| Loading — refetch / background | {} |
+| Empty — no data yet | {illustration? copy tone? call to action?} |
+| Empty — no results for filter | {must differ from "no data yet"} |
+| Error — recoverable | {inline? retry affordance?} |
+| Error — fatal | {} |
+| Partial / degraded | {} |
+| Success feedback | {toast? inline? duration?} |
+| Destructive confirmation | {dialog pattern, wording convention} |
+
+### 8.6 Forms
+
+- **Form state library / pattern**: {}
+- **Where validation errors come from**: {server shape from §7, client rules, or
+  both — and which wins}
+- **Error display**: {position, styling, timing — on blur, on submit, live}
+- **Submit behaviour**: {disabled while pending? optimistic? redirect after?}
+- **Unsaved-changes handling**: {}
+- **Field-level conventions**: {labels, required markers, help text, placeholders}
+- **Multi-step forms**: {N/A or the pattern}
+
+### 8.7 Interaction and feedback
+
+- **Primary action placement**: {}
+- **Keyboard support expected**: {which interactions must work without a mouse}
+- **Focus management**: {after navigation, after modal open/close, after submit}
+- **Optimistic updates**: {where permitted}
+- **Debounce/throttle conventions**: {search input, autosave}
+
+### 8.8 Responsive behaviour
+
+- **Breakpoints**: {from tokens}
+- **Approach**: {mobile-first or desktop-first — state it}
+- **How tables degrade on narrow viewports**: {}
+- **Navigation on narrow viewports**: {}
+- **Touch target minimum**: {}
+
+### 8.9 Accessibility baseline
+
+Non-negotiable minimums. The QA agent tests these.
+
+- **Target standard**: {e.g. WCAG 2.2 AA}
+- **Contrast**: {minimum ratio, and which token pairs are pre-verified}
+- **Semantic markup**: {landmark and heading requirements}
+- **Labels**: {every input labelled how}
+- **Focus visibility**: {}
+- **Announcements**: {live regions for async results}
+- **Motion**: {reduced-motion handling}
+
+### 8.10 UI exemplar — copy this shape
+
+{Paste one real, complete, currently-committed component or page that
+exemplifies the conventions above. Same reasoning as §5.8: structural imitation
+beats description.}
+
+```{language}
+{paste}
+```
+
+**Non-negotiable in the above**: {the 3–5 things that must be reproduced}
+
+---
+
+# CROSS-CUTTING
+
+## 9. Testing conventions
+
+| Level | Framework | Location | What must be covered |
+|-------|-----------|----------|----------------------|
+| Unit | {} | {} | {} |
+| Integration | {} | {} | {} |
+| End-to-end | {} | {} | {} |
+| Visual / component | {} | {} | {} |
+
+- **TDD mechanics** (rule TDD-1):
+  - Run one test: `{}`
+  - Pending/skip marker for acceptance specs: `{e.g. ->todo() | test.todo | xfail(strict=True)}`
+  - Mirrored or co-located tests: {}
+  - In-memory fakes location: `{}`
+- **Test data strategy**: {factories, fixtures, builders — returning named types, not arrays}
+- **Database in tests**: {}
+- **What is NOT tested by policy**: {so agents stop writing tests nobody wants}
+- **Coverage expectation**: {number, or "no gate — judgment"}
+
+---
+
+## 10. Non-negotiable rules
+
+The specific mistakes that are always wrong in this repository. Each becomes a
+CI check where mechanically checkable, and a review item where not.
+
+### 10.0 Pipeline-wide rules
+
+Installed with the pipeline. Copied verbatim by bootstrap; never deleted or
+softened. A scoped exception is written directly beneath the rule it relaxes,
+naming the exact path and the reason, and must have been approved at a gate.
+
+| # | Rule | Applies to | Checked by |
+|---|------|-----------|------------|
+| T1 | No untyped array, map, `mixed`, or `any` in a signature that crosses a layer, module, process, or network boundary. Named Data classes instead. | both | `scripts/check-typed-boundaries.mjs` + static analysis |
+| T2 | Collections are typed collections of named types. A bare array is never a return type. | both | static analysis |
+| T3 | Fixed value sets are enums, not strings. | both | review |
+| T4 | Optional is explicit (nullable or a variant), never "key may be missing". | both | type checker |
+| T5 | Untyped data only at the parse edge, converted to a named type on the next line. No casts on response bodies. | both | review |
+| T6 | Money, quantities, identifiers, and dates with rules are value objects or branded types. | both | review |
+| TDD-1 | Tests are written first. A commit that changes source without a test change needs `[no-test: reason]` in its message. | both | `scripts/check-test-with-change.mjs` + `tdd-log.md` at Gate 2 |
+| TDD-2 | Acceptance tests from the frozen seam are un-skipped, never edited, by implementers. | both | review |
+| CANON-1 | Dependencies point Interface → Application → Domain; Infrastructure implements ports. Domain imports no framework code in `strict` mode. | backend | review; graph check where installed |
+| CANON-2 | A controller/resolver action calls exactly one use case and never a repository or the ORM. | backend | review |
+| CANON-3 | Canonical names only — use cases `VerbNoun`, repository methods per canon §4, no synonyms. | backend | review |
+
+### 10.1 Repository rules
+
+Write these as your team would say them out loud. Vague rules produce vague
+enforcement.
+
+| # | Rule | Applies to | Mechanically checkable? |
+|---|------|-----------|-------------------------|
+| 1 | {} | {backend/frontend/both} | {yes — regex / no — review} |
+
+**Rationale for the non-obvious ones**: {a sentence each. Agents apply a rule
+correctly to novel situations only when they understand what it protects
+against.}
+
+---
+
+## 11. Known debt and no-go zones
+
+Places the codebase is knowingly wrong, or where change is disproportionately
+risky. Agents must not "fix" these opportunistically and must flag when a
+feature forces them into one.
+
+| Area | What is wrong | Why it is still there | Rule for agents |
+|------|---------------|----------------------|-----------------|
+| {} | {} | {} | {} |
+
+---
+
+## 12. Glossary
+
+Domain terms that mean something specific here. Include the ones with an
+everyday meaning that differs from the local one — those cause the worst bugs.
+
+| Term | Means | Does NOT mean |
+|------|-------|---------------|
+| {} | {} | {} |

package/payload/ai-agents/archive/README.md

@@ -0,0 +1,22 @@
+# Archive
+
+Finished features land here, one directory per slug, written by agent 09a when
+`/finalize` runs — on the branch, before the merge, so the record arrives with
+the code rather than after it.
+
+```
+{slug}/
+├── feature.md            what was asked for
+├── contract-backend.md   how the backend was designed
+├── contract-ui.md        how the interface was designed
+├── contract-seam.md       the frozen seam both tracks built against
+├── plan.md               dependency map and the task sequences
+├── impact.md             predicted and actual impact, with the risk class
+├── decisions.md          judgment calls made during implementation
+├── tdd-log.md            the red → green record
+└── stage.md              final state, including any accepted findings
+```
+
+Keep these. When someone asks in a year why a field behaves the way it does,
+`decisions.md` and the contracts are the only record — the diff shows what
+changed, never why.