@nusoft/nuos-build-catalogue 0.8.1 → 0.10.0

package/templates/starter-kit/docs/build/maps/01-template.md

@@ -0,0 +1,126 @@
+# Map [number] — [title]
+
+> **The canonical operational plan for [workstream name].** Sequenced work units from "today" to "[goal state]", each with phase-step decomposition, contracts realised, and verification gates anchored in target-repo files. If a step isn't here, it isn't planned. This map is the single source of truth for [workstream name] — read this before any other planning surface.
+
+> Replace the bracketed placeholders. Delete this hint block.
+
+## How to read this map
+
+The catalogue's decomposition (which this map operationalises):
+
+```
+Contracts                deep-module surfaces — what the system IS
+   │
+   │ realised by
+   ▼
+Maps                     strategic plan — when, in what order, why
+   │
+   │ ordering
+   ▼
+Work units (WUs)         executable units against contract surfaces — what ships
+   │
+   │ decomposed into
+   ▼
+Phases                   sub-units when a WU is too large for one shot
+   │
+   │ decomposed into
+   ▼
+Phase steps              the actual moves; each has acceptance + verification gate
+```
+
+Maps own **sequencing and outline**. WU files own **acceptance design and execution log**. Contracts own **the surface specs**. Sessions own **the temporal history**. No other planning artefact.
+
+## The five agentic-age patterns this map enforces
+
+These are the load-bearing discipline for agent-led building (codified in [`THE-NUOS-BUILD-METHOD.md`](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md) §post-Phase-3 epistemic discipline):
+
+1. **Verification gates anchored in target-repo files** — every phase step names a specific file/grep/test as acceptance proof. Closes the spec-vs-reality drift loop.
+2. **Maps as single canonical plan** — story-level detail lives here, not in side docs. Closes the proliferation loop.
+3. **Contracts as immutable truth** — phase steps cite the contract surface they realise. Closes the "agent makes things up" loop.
+4. **Hedge words as stop signal** — "likely", "presumably", "should be" indicate a missing verification step.
+5. **Design alternatives before implementation** — Ousterhout's "design it twice"; produce at least two fundamentally different designs, evaluate, then pick or hybrid before generating non-trivial implementation. Phase steps that generate implementation carry an implicit prerequisite: design alternatives recorded in WU notes.
+
+## Where we are now ([date])
+
+| WU | Title | Status | Repo / branch |
+|---|---|---|---|
+| [WU number] | [title] | [🔵 ready / 🟡 in flight / 🟣 in_review / ✅ done / 🔴 blocked] | [repo + branch] |
+
+## What "[goal state]" means
+
+The workstream is **complete** when all of the following hold simultaneously:
+
+1. [Outcome 1]
+2. [Outcome 2]
+3. [Outcome 3]
+4. ...
+
+(List the verifiable end-state of the workstream. Each outcome should be an observable fact about the system, not a process step.)
+
+## Critical path
+
+```
+[diagram of WU sequencing with dependencies — use ASCII art or describe in prose]
+```
+
+---
+
+## WU [number] — [title]
+
+| Field | Value |
+|---|---|
+| Contracts realised | [which contract surface(s) this WU fulfils] |
+| Status | [🔵 / 🟡 / 🟣 / ✅ / 🔴] |
+| Repo | [repo + branch] |
+| Estimate | [working days] |
+| Depends on | [upstream WUs / npm publishes / external] |
+
+**Design alternatives considered (Pattern N — before any non-trivial implementation step):**
+
+> If this WU includes any non-trivial architectural choice (schema, migration, integration shape, adapter, RBAC, audit, retention, error-handling), record at least two fundamentally different design candidates here before phase steps that generate implementation. State the chosen one and why. Delete this block if the WU is purely incremental work against an already-decided design.
+
+- **Option A:** [first fundamentally different design]. Trade-offs: [...]. Errors created: [...].
+- **Option B:** [second fundamentally different design]. Trade-offs: [...]. Errors created: [...].
+- *(Option C if useful)*
+- **Chosen:** [A / B / C / hybrid] because [...]. Records as: [WU notes / D-NNN decision file].
+
+| # | Phase step | Acceptance | Verification gate |
+|---|---|---|---|
+| 1 | [what move is being made] | [what proves it produced the intended outcome] | [specific file/grep/test the operator runs to confirm] |
+| 2 | ... | ... | ... |
+
+**Done when:** [the overall WU acceptance — usually "all N steps complete + canonical green line + integration test"].
+
+**Risks:** [anything that could derail the WU; mitigations].
+
+---
+
+## WU [number] — [title]
+
+[Repeat the structure above for each WU on the critical path. Each WU with non-trivial design choices gets its own "Design alternatives considered" block; routine incremental WUs can omit it.]
+
+---
+
+## What runs in parallel
+
+[List independent workstreams that don't gate the critical path.]
+
+## Trigger conditions for deferred WUs
+
+[List WUs that are deferred and what unblocks them.]
+
+## What this map is not
+
+- It does NOT describe [out-of-scope topic 1] — see [other doc].
+- It does NOT cover [out-of-scope topic 2] — see [other doc].
+
+## How to use this map
+
+- **At session start** — read this map plus the active WU's spec file. The map tells you which phase step is next + the verification gate; the WU spec tells you the deeper acceptance design.
+- **Mid-step** — if you find yourself writing a hedge word ("likely", "presumably", "should be"), stop. Run the verification gate's grep/test/file-read first. Replace the hedge with the result.
+- **At session end** — flip phase-step status here; if scope changed, edit the step description here (not in a side doc).
+- **When a phase completes** — flip the WU's phase status; update STATE.md to reflect; confirm the dependency graph still holds.
+
+## Pointers
+
+- [List relevant WU files, contracts, decisions, prior maps]

package/templates/starter-kit/docs/build/maps/_index.md

@@ -0,0 +1,63 @@
+# Maps — index
+
+> Maps are the canonical operational plan for a project running the NuOS Build Method. **Story-level detail lives in maps**, not in fragmented planning docs. If a phase step isn't here, it isn't planned. The maps are the single source of truth for sequencing.
+
+## Why maps matter (the post-Phase-3 evolution)
+
+The NuOS catalogue has many surfaces — decisions, contracts, work units, sessions, risks, open questions. Maps are what stops planning from sprawling across all of them. Maps own:
+
+- **Sequencing** — which work unit comes when, with explicit dependencies
+- **Phase-step decomposition** — when a WU is too large for one shot, the phase steps live here, each with acceptance + verification gate
+- **Contracts realised** — every WU on the path cites the contract surface(s) it fulfils
+
+This is one of the four agentic-age patterns codified in the NuOS Build Method (see [`docs/THE-NUOS-BUILD-METHOD.md`](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md) §post-Phase-3). The pattern: **maps as single canonical plan** closes the proliferation loop. A fresh session — human or agent — should be able to read STATE.md + the active map and have full operational context.
+
+## Map conventions
+
+- **Map 1 — the horizon.** The whole project journey, narrative form. Layperson-readable. If you read only one map, this is it.
+- **Map 2 — phases-in-detail (optional).** When the project has clearly separated phases (e.g., NuOS's Phases 0–F), this map gives mid-level detail per phase.
+- **Map N — canonical operational plan(s).** One per major workstream. Story-level detail with verification gates. This is where the active work lives.
+
+A small project may only need Map 1 + Map 2 (canonical plan). A larger project may have several Map N variants for parallel workstreams. The convention: numbered sequentially; the latest is the most operational.
+
+## Story-step shape
+
+Every executable phase step in a map has the following shape (per [`01-template.md`](01-template.md)):
+
+```
+| # | Phase step | Acceptance | Verification gate |
+|---|---|---|---|
+| 1 | <what move is being made> | <what proves it produced the intended outcome> | <specific file/grep/test in the target repo that the operator runs to confirm the gate> |
+```
+
+The **verification gate** is the load-bearing column for agent-led work. *"This works"* is not a gate. *"`grep 'createSensightMisWriteAdapter' apps/web/lib/nuos/nuflow/runtime.ts` returns a hit"* is a gate. Vague gates leave room for plausible-looking work that doesn't match reality; precise gates close that loop.
+
+## Hedge words are a stop signal
+
+If you find yourself writing *"likely"*, *"presumably"*, *"should be"* in a map, stop. The hedge word indicates a verification step you skipped. Replace it with the grep/test/file-read result before the map ships.
+
+## Design alternatives before implementation
+
+For any non-trivial architectural choice — schema, migration, integration shape, adapter design, audit composition, RBAC pattern, error-handling strategy, retention policy — **produce at least two fundamentally different designs, evaluate them, then pick or hybrid before any implementation is generated.** This is Ousterhout's "design it twice" applied to agent-led work.
+
+Two syntactic variations of the same design (e.g., `USING` clause vs `WITH CHECK` clause for the same RLS pattern) do not count. Three fundamentally different designs (e.g., session-variable RLS / Supabase auth.uid() RLS / defense-in-depth + app-side enforcement) do count.
+
+Record the alternatives in the WU's Design notes (or as a D-NNN decision when the choice is durable enough). The audit trail of *"we considered A, B, C; chose B because X"* is catalogue value — future sessions can re-evaluate when context changes.
+
+In maps, any phase step whose work is *"generate non-trivial implementation"* carries an implicit prerequisite: design alternatives recorded in the WU notes. The gate fires before code is written, not after.
+
+## Naming
+
+- `01-the-horizon.md` — the high-level narrative (recommend keep verbatim if adopting unchanged)
+- `02-<name>.md` — phases-in-detail or first canonical operational plan
+- `03-<name>.md`, `04-<name>.md`, etc. — additional canonical plans per workstream
+
+When a map is superseded (e.g., the project's operational shape changes), preserve the old map with a `(HISTORICAL)` header pointing at its replacement. Don't delete — the evolution is part of the audit trail.
+
+## Maps in this catalogue
+
+| File | Title | Purpose |
+|---|---|---|
+| `01-template.md` | Map template | Shape for a canonical operational map (copy + rename) |
+
+Update this list as you add real maps.

package/templates/starter-kit/docs/build/open-questions/_index.md

@@ -0,0 +1,26 @@
+# Open Questions
+
+> Questions blocking work that have not yet been resolved into decisions. Each question is Q-NNN. Open questions exist in three states: `open` (under deliberation), `resolved` (resolved into a D-NNN — link forward), `withdrawn` (no longer relevant).
+
+## Index
+
+| ID | Question | Status | Blocks | Date opened |
+| --- | --- | --- | --- | --- |
+| _none yet_ | | | | |
+
+## How to file an open question
+
+1. Add a new row with Q-NNN (next available number)
+2. If the question warrants detail (multiple options, real trade-offs), write a `Q-NNN-short-title.md` file beside this index laying out the options
+3. Reference the question from any blocked work unit
+4. When the question resolves, file a D-NNN; mark this question `resolved` and link forward
+
+## When a question becomes a decision
+
+A question is "ready to resolve" when:
+
+- The trade-offs are clear enough to choose between
+- The information needed to choose is available (or its absence is itself a decision)
+- An active or imminent work unit needs the answer
+
+Resolving prematurely produces fragile decisions. Resolving late produces blocked work units. The catalogue review walks open questions and forces the choice when blocking begins.

package/templates/starter-kit/docs/build/personas/001-template.md

@@ -0,0 +1,68 @@
+# P001 — [Persona name, e.g., "Returning bookshop customer" or "Watling Street Primary SENCo"]
+
+| Field | Value |
+| --- | --- |
+| Status | 🟢 active |
+| Paired with | [P-NNN if this persona's outcomes are paired with another (e.g., customer ↔ organiser); `none` otherwise] |
+| Used by WUs | [List of WU numbers that cite this persona — keep updated] |
+| First filed | {{TODAY}} |
+| Last refined | {{TODAY}} |
+
+## What this persona is, in one sentence
+
+[One sentence describing who this person is in the context of *this system*. Not "Sarah, 32, marketing manager". A relationship to the system: "a returning customer who has attended at least one event before and has an existing account", "a SENCo at a primary school managing 22 pupils on the SEN register".]
+
+## The seven dimensions
+
+### 1. Identity
+
+[Who they are in the context of this system. Their relationship to it. Not their demographic profile — their position in the system's world. What account do they have? What role do they play? What other systems have they used before that shape their expectations?]
+
+### 2. Reality
+
+[The physical environment they are in when they use this system. Device, connection quality, noise level, time pressure. "At home on a laptop, stable connection, no time pressure." "On a phone in the staff room between lessons, intermittent wifi, four-minute window." Real conditions, not idealised ones.]
+
+### 3. Psychology
+
+[Technical confidence, stress level, tolerance for confusion. Will they read instructions or click around? Will they abandon if a page takes more than three seconds? Will they call a colleague for help, or give up silently? What is their emotional state when they arrive at this system?]
+
+### 4. Trigger
+
+[What brought them to this outcome. A real-world event, not a UI click. "They saw an event announcement on the bookshop's social media." "Their head teacher forwarded a safeguarding form that needs completing today." "A pupil disclosed something at lunch and they need to record it before the day ends."]
+
+### 5. History
+
+[What they have done before arriving at this outcome. Have they used the platform before? Do they have saved details? Do they understand how this kind of system works? What context do they bring with them that the system can rely on?]
+
+### 6. Success
+
+[What "done" looks like from *their* perspective. Not what the system logs — what they feel. "I know I have a place, I know when it is, and I will not forget." "The disclosure is recorded, the right people are notified, and I can go home knowing I did my duty." This drives the design — the system must produce that subjective state, not just write a database row.]
+
+### 7. Constraints
+
+[What they cannot or will not do. "Will not phone the shop to book." "Will not create a new account if their login fails — they will give up." "Will not wait more than five seconds for a page to load." "Cannot share the screen with a parent — confidentiality." These define the outer boundary of acceptable design.]
+
+## The acid-test refinement
+
+[The hardest legitimate user — this persona with the most demanding combination of real constraints. Not a hostile user; a legitimate user with the worst realistic conditions. Slow device, low technical confidence, time pressure, complex situation, possibly distracted or stressed.
+
+Design for the acid-test and the standard cases hold. If only one scenario gets verified end-to-end, verify this one.]
+
+## Paired persona
+
+[If this persona's outcomes are paired with another's — e.g., a customer who books an event and an organiser who receives the booking — link the paired P-NNN here. The contract between them (what one outcome produces and the other consumes) lives in the WU files, but the relationship is recorded here so a future reader can find both sides quickly.
+
+If this persona has no paired counterpart, write `none`.]
+
+## Used by WUs
+
+[Keep this list updated as WUs cite the persona. Format: `WU NNN — title` per line.]
+
+- [WU NNN — title]
+- ...
+
+## Notes / refinements
+
+### {{TODAY}} — first filed
+
+[Initial draft of the seven dimensions. What was clear; what was guessed; what needs verification with a real person.]

package/templates/starter-kit/docs/build/personas/_index.md

@@ -0,0 +1,77 @@
+# Personas Index
+
+> Master list of the personas this project's work units serve. Personas are P-NNN-numbered, written along the seven dimensions, and refined with the acid-test. Reusable across multiple WUs — a "paired outcome" (e.g., a customer-side outcome paired with an organiser-side one) cites two personas, both filed here.
+
+## What a persona is
+
+A persona is a **specification of who will use an outcome and what situation they will be in when they use it.** It is not a demographic snapshot; it is a design constraint. A persona that does not change a design decision is decoration — rewrite it until it does.
+
+The seven dimensions every persona addresses:
+
+1. **Identity** — who they are in the context of *this system*. Not their age or job title in the abstract — their relationship to this particular system.
+2. **Reality** — physical environment when they use the outcome. Device, connection quality, noise level, time pressure.
+3. **Psychology** — technical confidence, stress level, tolerance for confusion.
+4. **Trigger** — what brought them to this outcome. A real-world event, not a UI click.
+5. **History** — what they have done before arriving at this outcome.
+6. **Success** — what "done" looks like from their perspective. Not what the system logs — what they feel.
+7. **Constraints** — what they cannot or will not do. Defines the outer boundary of acceptable design.
+
+Every persona is then refined into an **acid-test persona** — the hardest legitimate user, with the most demanding combination of real constraints. Design for the acid-test and the standard cases hold.
+
+## How a persona is filed
+
+```
+personas/
+├── _index.md          (this file)
+├── 001-template.md    (the template; copy when filing a new persona)
+├── P001-<slug>.md     (your first persona)
+├── P002-<slug>.md     ...
+└── done/              (when a persona retires — e.g., the user role no longer exists)
+```
+
+Personas are P-NNN-numbered. Numbers are stable: a retired persona moves to `done/` but keeps its number. Cross-WU references use the stable handle (`{repo}:P-NNN` for cross-catalogue references; `[P-NNN](../personas/P-NNN-slug.md)` within the same catalogue).
+
+## Personas — active
+
+| ID | Name | Used by WUs | Status |
+| --- | --- | --- | --- |
+
+[Add a row when you file a new persona. Status: `🟢 active`, `🟡 evolving` (the persona shape is being refined), `🟣 paired-with-PNNN` (this persona's outcomes are paired with another), `⚫ retired`.]
+
+## Status legend
+
+- 🟢 `active` — in use; cited by one or more current WUs
+- 🟡 `evolving` — the seven dimensions are being refined as understanding deepens
+- 🟣 `paired-with-PNNN` — this persona pairs with another (e.g., customer + organiser)
+- ⚫ `retired` — no longer in use; moved to `done/`
+
+## How to write a persona
+
+Use the file format established in `001-template.md`. A persona document has:
+
+- Identity dimension
+- Reality dimension
+- Psychology dimension
+- Trigger dimension
+- History dimension
+- Success dimension
+- Constraints dimension
+- Acid-test refinement (the worst legitimate combination of constraints)
+- Paired persona (if any) — the persona on the other side of any outcome this persona triggers
+- WUs this persona is cited by
+
+A persona should be small enough to read in two minutes and specific enough that swapping it for a different persona would force at least one design decision to change. If you can substitute the persona without changing anything in the WU, the persona is decorative — rewrite it until it constrains.
+
+## How personas connect to WUs
+
+A WU's `Persona` field links the P-NNN that the outcome serves. A WU's `Trigger` field draws from the persona's Trigger dimension but specifies the *moment* (not just the class of event). A WU's `Walkthrough` is written from the persona's perspective, using their reality, psychology, and history to constrain what they need to be told and what they already know.
+
+If a WU has no clear persona, it is one of two things:
+1. An infrastructure WU (build, publish, hardening) — mark the persona field `N/A — infrastructure WU`.
+2. An unanchored feature — the WU describes a category of capability without a person doing a thing. Rewrite as an outcome with a real persona, or split into smaller outcomes.
+
+## How personas evolve
+
+Personas evolve as understanding deepens. The seven dimensions get sharper; the acid-test gets harder; new constraints surface. Update the persona file in place — but record the *date* of each refinement in the file itself, so a future reader can see how the understanding changed.
+
+If a persona's role in the system changes substantially (e.g., "customer" splits into "registered customer" + "guest customer"), file two new personas with new P-NNN numbers and mark the original `⚫ retired` rather than amending it.

package/templates/starter-kit/docs/build/risks/_index.md

@@ -0,0 +1,28 @@
+# Risks
+
+> Tracked risks to the project. Each risk is R-NNN. A risk is anything that could prevent a work unit from shipping, prevent a phase from completing, or invalidate an architectural commitment if it materialises.
+
+## Index
+
+| ID | Risk | Severity | Status | Date opened |
+| --- | --- | --- | --- | --- |
+| _none yet_ | | | | |
+
+## Severity scale
+
+- **High** — blocks active work or threatens an architectural commitment
+- **Medium** — would slow work materially if it materialises
+- **Low** — worth tracking; not blocking
+
+## Status
+
+- **open** — being watched
+- **mitigated** — action taken; risk reduced
+- **materialised** — happened; see linked WU or session for response
+- **closed** — no longer applicable
+
+## How to add a risk
+
+1. Add a new row to the table with R-NNN (next available number)
+2. If the risk is large enough to warrant detail, write a `R-NNN-short-title.md` file beside this index
+3. Reference the risk from any work unit it affects

package/templates/starter-kit/docs/build/sessions/0000-00-00-template.md

@@ -0,0 +1,47 @@
+# {{TODAY}} — Session: [short description]
+
+| Field | Value |
+| --- | --- |
+| Operator | [name] |
+| Active WU | WU NNN — [title] |
+| Duration | [approximate, e.g., "90 minutes"] |
+| Outcome | [one phrase: "WU NNN advanced", "D-NNN landed", "blocked on Q-NNN", etc.] |
+
+## What this session was about
+
+[One paragraph framing. Why was this session run? What was the entry-point question or task?]
+
+## What was done
+
+[Chronological narrative. Reference any commits by hash or branch. Link any artefacts created or modified.]
+
+- [bullet]
+- [bullet]
+- [bullet]
+
+## Decisions that surfaced
+
+| ID | Title | Status |
+| --- | --- | --- |
+| _none_ | | |
+
+## Open questions raised
+
+| ID | Question | Owner |
+| --- | --- | --- |
+| _none_ | | |
+
+## Risks identified
+
+| ID | Risk | Severity |
+| --- | --- | --- |
+| _none_ | | |
+
+## What's next
+
+[The concrete next action. Mirrors STATE.md "What is next". Should be specific enough that the next session's start-of-session protocol can pick it up without further context.]
+
+## Pointers
+
+- [Link to the active WU]
+- [Link to any decisions or open questions referenced]

package/templates/starter-kit/docs/build/sessions/_index.md

@@ -0,0 +1,27 @@
+# Sessions
+
+> Chronological audit trail of every session run on this project. One entry per session, named `YYYY-MM-DD-short-description.md`. The session log is the catalogue's replay history; a fresh operator (human or agent) should be able to read the most recent entries and pick up exactly where work stopped.
+
+## Index
+
+| Date | Session | Active WU | Notes |
+| --- | --- | --- | --- |
+| {{TODAY}} | [Adopt the catalogue scaffold](0000-00-00-template.md) | WU 001 | First session; catalogue bootstrapped |
+
+## How to add a session entry
+
+1. Copy `0000-00-00-template.md` to `YYYY-MM-DD-short-description.md` (today's date, dashes-not-spaces description)
+2. Fill in the template
+3. Add a row to the table above
+4. Link the entry from STATE.md if the session significantly shifted state
+
+## What a session entry must include
+
+- What this session was about (one paragraph)
+- What was done (chronological narrative)
+- Decisions that surfaced (linked)
+- Open questions raised (linked)
+- Risks identified (linked)
+- What's next (the concrete next action)
+
+The auditor's-question test: *could a third-party auditor read this entry and answer "what happened, why, and what's next?" without contacting the team?* If yes, sufficient.

package/templates/starter-kit/docs/build/work-units/001-template.md

@@ -0,0 +1,82 @@
+# Work Unit 001 — [Outcome-bounded title, e.g., "Bookshop event booking flow" or "Bootstrap the Postgres schema"]
+
+| Field | Value |
+| --- | --- |
+| Status | 🟡 in flight |
+| Depends on | none |
+| Blocks | [WUs that cannot start until this lands] |
+| Implements | [the decision or pattern this realises] |
+| Owner | [name or "—"] |
+| Estimated effort | [days or "small/medium/large"] |
+| Repo | [where the implementation lands] |
+
+## Persona
+
+[Link to the P-NNN persona this outcome serves — e.g., `[P001 — Returning bookshop customer](../personas/P001-returning-customer.md)`. For paired outcomes, link both personas. For infrastructure WUs (build, publish, hardening), write `N/A — infrastructure WU.`]
+
+## Trigger
+
+[The real-world event that makes this outcome necessary. Not "the user clicks the booking button" — that is a UI interaction. The trigger is what happened *before* they opened the platform: "the customer saw an event announcement on social media and wants to reserve a place", "the SENCo received an email that a child has been placed on the SEN register". For infrastructure WUs, write `N/A — infrastructure WU.`]
+
+## Outcome
+
+[One paragraph. The single sentence test: *what will be true when this is done that is not true now?* That sentence is the outcome.]
+
+## Walkthrough
+
+[Numbered steps from the persona's perspective — what they do and what they see. Include failure paths via the five injection points: (1) what if the persona cannot complete this step in one sitting? (2) what if the information they need is incorrect or missing? (3) what if the system itself fails? (4) what if the persona makes a mistake? (5) what if they realise immediately afterwards they used the wrong information?
+
+For infrastructure WUs, write `N/A — infrastructure WU.`]
+
+1. [Persona action; system response; including any failure handling that lives at this step]
+2. ...
+
+## Acceptance criteria
+
+When this WU is `✅ merged / shipped`:
+
+1. [Concrete, observable, checkable criterion — phrased as an inspection that passes or fails. Each criterion must be evaluable by a person looking at the running system, not inferred from technical state.]
+2. ...
+
+The auditor's-question test applies: *can a third-party reader read these and confirm "yes, this is shipped" by inspection alone?*
+
+The four quality traps apply when reviewing acceptance criteria: vagueness (could this be implemented in more than one way that satisfies the wording?); technical language (does this describe implementation rather than behaviour?); happy-path-only (have failure paths been covered?); kitchen-sink (does this WU try to do more than one thing?).
+
+## Contracts produced
+
+[What this WU makes available to other WUs once it lands, in domain language. Not database schemas, not API endpoints — facts about the world that the system now knows. Examples:
+
+- "A confirmed booking record, linked to a specific customer and a specific event"
+- "A verified customer account: name, email, login credentials, saved payment method"
+- "A published event with capacity, price, and date"
+
+For infrastructure WUs, list the technical artefacts: "A `@nusoft/nuwiki@0.1.4` published privately on npm with caret-range trifecta deps".]
+
+## Contracts consumed
+
+[What must already exist before this WU can run. Each entry should map to another WU's `Contracts produced` field. If something this WU consumes is not produced by any WU in the plan, that is a planning gap — file it as an open question or a new WU before this one starts.]
+
+## Approach
+
+[Two or three short paragraphs. Not a design doc; just enough that an LLM teammate or a fresh operator can see how the work breaks down. If "design twice" applies (any non-trivial architectural choice), produce two fundamentally different designs in the Notes section before generating implementation.]
+
+## What this WU does NOT do
+
+- [Things deliberately deferred to later WUs]
+- [Things that look in-scope but are not]
+
+## Forward-compatibility commitments
+
+[If this WU's shape decisions affect later WUs, name them here. Future WUs depend on these surviving.]
+
+## Notes / log
+
+### {{TODAY}} — session 1
+[What was attempted, what worked, what did not, what was learned, what is next.]
+
+## Pointers
+
+- [Link to the decision this implements, if any]
+- [Link to the persona(s) this serves]
+- [Links to dependent WUs (those this consumes from, those this blocks)]
+- [Links to relevant module-level contracts in `docs/contracts/`]

package/templates/starter-kit/docs/build/work-units/_index.md

@@ -0,0 +1,34 @@
+# Work Units
+
+> Concrete, buildable pieces of work. Each work unit has an outcome, acceptance criteria, dependencies, and a status. Work units are the unit of progress; the catalogue's compounding value comes from accumulated WU notes.
+
+## Index
+
+| WU | Title | Status | Depends on | Notes |
+| --- | --- | --- | --- | --- |
+| 001 | [first WU title] | 🟡 in flight | — | First work unit |
+
+## Status legend
+
+- 🔵 **proposed** — written down, not yet started
+- 🟡 **in flight** — actively being worked on
+- 🟣 **built / awaiting review** — implementation done, review pending
+- ✅ **merged / shipped** — complete and integrated
+- 🔴 **blocked** — cannot proceed; see notes for blocker
+
+## Deferred / proposed-with-trigger work units
+
+A work unit can be `🔵 proposed` in three flavours:
+
+- **proposed-ready** — eligible to activate at next priority review
+- **proposed-deferred-with-trigger** — committed, awaiting a checkable condition (state the condition in the WU itself)
+- **proposed-blocked-on-question** — cannot activate until an open question resolves; link to the Q-NNN
+
+The quarterly catalogue review walks each deferred WU and re-evaluates its trigger.
+
+## How to add a work unit
+
+1. Copy `001-template.md` to `NNN-short-title-with-dashes.md` (next available number)
+2. Fill in the template
+3. Add a row to the table above
+4. If the WU resolves an open question, link it; if the WU was created in response to a decision, link the decision

package/templates/starter-kit/docs/contracts/_index.md

@@ -0,0 +1,26 @@
+# Contracts
+
+> Type-stable surfaces — what each part of {{PROJECT_NAME}} promises to its consumers. Where decisions justify *why* and philosophy frames the spirit, contracts specify *what is true at the boundary*. A contract is what an integrator (human or LLM) reads to know how to interact with this part of the system.
+
+## When to write a contract
+
+Not on day one. Contracts come when stable surfaces emerge — when something has been built, tested, and is being depended on by other parts of the system or other projects.
+
+Premature contracts ossify the wrong shape. Late contracts allow drift. The signal a contract is needed: a downstream consumer is asking *"what does X actually guarantee?"* and the answer is not in any single place.
+
+## Index
+
+| Contract | Surface | Status |
+| --- | --- | --- |
+| _none yet_ | | |
+
+## Pattern
+
+Each contract document:
+- Names the surface
+- Lists the type-stable promises (what shape inputs come in, what shape outputs go out, what side effects fire)
+- Specifies the conformance gate (the test or check that proves a candidate implementation honours the contract)
+- Lists what is *not* covered (so consumers don't depend on incidentals)
+- Records the contract's version (semver if it's published)
+
+Contracts are change-controlled. Breaking a contract requires a decision (D-NNN) and a downstream-impact note.

package/templates/starter-kit/docs/guides/_index.md

@@ -0,0 +1,26 @@
+# Guides
+
+> The persuasion layer. Where decisions are committed-to, contracts are typed, and philosophy is committed-architectural-spirit, **guides are written to persuade**. They explain {{PROJECT_NAME}} to investors, customers, partners, regulators, and domain experts. They are the artefact you send when you need a non-technical reader to understand and care.
+
+## When to write a guide
+
+When you need to persuade somebody. Not before. A guide written without an audience and a goal is academic. A guide written *for an audience* against a known goal is the most leveraged writing you can do — it is the artefact that opens conversations, closes deals, and aligns stakeholders.
+
+The catalogue's other layers are the source material. A guide is the curated, audience-tuned read.
+
+## Index
+
+| Guide | Audience | Topic |
+| --- | --- | --- |
+| _none yet_ | | |
+
+## Pattern
+
+Each guide:
+- States the audience explicitly (one or two reader personas)
+- States the goal — what should the reader do or believe after reading?
+- Stays in the language of the audience (no jargon the audience doesn't already use)
+- Cites the catalogue (decisions, contracts, philosophy) as evidence
+- Is dated — guides go stale; the date tells the reader whether they're reading current
+
+A guide is not eternal. When the underlying truth shifts, the guide gets revised or retired. Catalogue decisions persist; guides are seasonal.