@nusoft/nuos-build-catalogue 0.9.0 → 0.10.1

package/templates/starter-kit/docs/build/STATE.md

@@ -0,0 +1,47 @@
+# {{PROJECT_NAME}} — Always-Current State
+
+> The single snapshot read at the start of every session. If anything important is not here, it is not real. Update this file at the end of every session via the end-of-session protocol.
+
+**Last updated:** {{TODAY}}
+**Active phase:** Phase 0 — bootstrap
+**Active work unit:** WU 001 — [first work unit name]
+
+## What is currently in flight
+
+[One paragraph describing what work is happening right now. Edit when work changes shape.]
+
+## What just shipped
+
+Nothing yet — this catalogue was just adopted on {{TODAY}}.
+
+## What is next
+
+[The next concrete action. Should be specific enough that an LLM teammate can pick it up and start without further context.]
+
+## Open questions blocking progress
+
+None currently filed. Filed questions live in [`open-questions/_index.md`](open-questions/_index.md).
+
+## Active risks
+
+None currently filed. Filed risks live in [`risks/_index.md`](risks/_index.md).
+
+## Decisions made recently
+
+| Decision | Status | Date |
+| --- | --- | --- |
+| _none yet_ | | |
+
+## Work units in flight
+
+| WU | Status | Owner | Notes |
+| --- | --- | --- | --- |
+| WU 001 | 🟡 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

package/templates/starter-kit/docs/build/decisions/D001-template.md

@@ -0,0 +1,38 @@
+# D001 — [Decision title in present tense, e.g., "We commit to PostgreSQL as the primary store"]
+
+| Field | Value |
+| --- | --- |
+| Status | accepted |
+| Date | {{TODAY}} |
+| Affects | [which work units, modules, or surfaces this commits] |
+| Supersedes | none |
+| Superseded by | — |
+
+## Context
+
+[What is the situation in which this decision is being made? What are the constraints, what is forcing a choice now, what does *not* doing this look like? One or two paragraphs.]
+
+## Decision
+
+[The commitment in plain language. One short paragraph. The reader should be able to read just this section and understand what was committed.]
+
+## Rationale
+
+[Why this and not the alternatives? What does this commit us to, and what does it rule out? Be specific about trade-offs accepted.]
+
+## Consequences
+
+- [What this means for downstream work]
+- [What this means for future flexibility]
+- [What this means for any current open questions or risks]
+
+## Alternatives considered
+
+- **[Alternative 1]** — rejected because [...]
+- **[Alternative 2]** — rejected because [...]
+
+## Pointers
+
+- [Link to relevant work units]
+- [Link to any open question this resolves]
+- [Link to any prior decision this builds on]

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

@@ -0,0 +1,30 @@
+# Decisions
+
+> Architectural commitments made by this project. Each decision lives in its own D-NNN file. Decisions are dated, justified, and have a status (`accepted`, `superseded`, `withdrawn`).
+
+## Index
+
+| ID | Title | Status | Date |
+| --- | --- | --- | --- |
+| _none yet — see the template_ | | | |
+
+## How to add a decision
+
+1. Copy `D001-template.md` to `DNNN-short-title-with-dashes.md` (next available number)
+2. Fill in the template
+3. Add a row to the table above
+4. If the decision affects a work unit's acceptance criteria, link it from the WU
+5. If the decision supersedes a prior one, mark the prior one's status as `superseded` and link forward
+
+## When to write a decision
+
+- An architectural commitment is being made
+- Two reasonable approaches are being chosen between
+- A constraint is being adopted that future work will need to honour
+- A prior decision is being overridden (write the supersede; don't silently shift)
+
+## When NOT to write a decision
+
+- The choice is implementation-detail and easy to reverse
+- The work unit's notes are sufficient to capture the rationale
+- The matter is open and unresolved — file it as an open question (Q-NNN), not a decision

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.