@nusoft/nuos-build-catalogue 0.12.0 → 0.14.1

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

@@ -1,28 +1,35 @@
 # 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.
+A **risk** is something that could go wrong and would matter if it did. Filed here so it's visible — both to you and to anyone else looking at the project. Zero risks on a real project usually means underthinking, not zero risk. See [the glossary](../GLOSSARY.md#risk) for the full definition.
 
 ## Index
 
 | ID | Risk | Severity | Status | Date opened |
 | --- | --- | --- | --- | --- |
-| _none yet_ | | | | |
+| _none yet — add a row when you spot something to watch_ | | | | |
 
-## Severity scale
+## Severity
 
-- **High** — blocks active work or threatens an architectural commitment
-- **Medium** — would slow work materially if it materialises
-- **Low** — worth tracking; not blocking
+- **High** — would block work or invalidate a major decision if it happens
+- **Medium** — would slow things down materially
+- **Low** — worth knowing about; not blocking
 
 ## Status
 
 - **open** — being watched
-- **mitigated** — action taken; risk reduced
-- **materialised** — happened; see linked WU or session for response
-- **closed** — no longer applicable
+- **mitigated** — something's been done to reduce it
+- **materialised** — it happened; see the linked work unit or session for what we did
+- **closed** — no longer relevant
 
-## How to add a risk
+## When to file 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
+- You can imagine something going wrong and want it surfaced rather than forgotten
+- You're about to commit to a path and there's a known downside
+- An open question has implications if it resolves the wrong way — file the risk separately so the project tracks it even before the question resolves
+- A dependency (a person, a service, a piece of hardware) might not be available when you need it
+
+> Example: "R002 — School wifi is unreliable on Mondays after maintenance; the morning briefing must degrade gracefully when offline."
+
+## How to file one
+
+Add a row to the table above with the next R-NNN number. If the risk is large enough to warrant detail (options for mitigation, escalation plan), write a `RNNN-short-title.md` file beside this index too. Reference the risk from any work unit it affects.

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

@@ -1,27 +1,29 @@
 # 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.
+A **session** is a period of focused work — could be an hour, could be an afternoon. Each session starts with `/start-of-session` (which tells you where the project is) and ends with `/end-of-session` (which writes down what just happened). One file per session lives here in date order, named `YYYY-MM-DD-short-description.md`. See [the glossary](../GLOSSARY.md#session) for the full definition.
+
+The session log is the project's **replay history**. Anyone joining mid-project — or future-you opening this folder six months later — should be able to read the most recent entries and pick up exactly where work stopped, without needing to ask.
 
 ## Index
 
-| Date | Session | Active WU | Notes |
+| Date | Session | Active work unit | Notes |
 | --- | --- | --- | --- |
-| {{TODAY}} | [Adopt the catalogue scaffold](0000-00-00-template.md) | WU 001 | First session; catalogue bootstrapped |
+| _filled in automatically when you run `/end-of-session`_ | | | |
+
+## What a session entry captures
 
-## How to add a session entry
+- **What this session was about** — one paragraph
+- **What was done** — chronological, in plain language
+- **Decisions made** — linked to the D-NNN files filed in this session
+- **Open questions raised** — linked to the Q-NNN files
+- **Risks identified** — linked
+- **What's next** — the next concrete action; what the next session should start with
+- **Resume hint** — if mid-phase (planning or work) when this session ended, a one-paragraph note of where you were so the next session picks up cleanly
 
-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
+The honest test for a good session entry: **could a future-you (or anyone joining the project) read it and answer "what happened, why, and what's next?" without contacting you?** If yes, the entry is sufficient.
 
-## What a session entry must include
+## How session entries are filed
 
-- 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)
+Run `/end-of-session`. It writes the entry, updates this index, refreshes STATE.md, commits everything in one atomic step, and the post-commit hook refreshes the search index in the background.
 
-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.
+**Never close a session without `/end-of-session`.** Work that isn't written down is work that's lost. The whole catalogue is built on the assumption that every period of work gets captured before it closes.

package/templates/starter-kit/docs/build/ui-ux/_index.md

@@ -0,0 +1,48 @@
+# UI/UX
+
+A **surface** is a piece of the user-facing experience — a page, a screen, a modal, a command, an email, a notification. Each surface lives here as its own file. The register captures *what people see, what they do, and what happens next.* Implementation lives in code; **the visual + interaction language each surface uses lives in [the design system register](../design-system/_index.md).**
+
+See [the glossary](../GLOSSARY.md#surface) for the full definition of a surface.
+
+## Index
+
+| Surface | Persona | Status |
+| --- | --- | --- |
+| _none yet — populated during the UI/UX + Design System phase of planning (phase C)_ | | |
+
+## What goes in a surface file
+
+For each user-facing surface:
+
+- **Who uses it** — link to the persona(s) in `personas/`
+- **When they reach it** — the trigger; what's happening in their day that brings them here
+- **What they see** — the content, the layout, the components from the design system that appear
+- **What they do** — the actions available
+- **What happens next** — where they go, what the system does
+- **What contracts it touches** — link to the contracts in `contracts/` this surface reads from or writes to
+- **What design-system pieces it uses** — the components, patterns, tokens, voice samples
+
+A surface file is *what's true about the experience*. It's not a mockup or wireframe; it's a description detailed enough that a designer or developer reading it knows what to build.
+
+## When the UI/UX register gets populated
+
+During the **UI/UX + Design System** phase of planning (phase C), after architecture is in place. Phase C produces TWO things in parallel:
+
+1. **The design system** — the shared vocabulary every surface uses
+2. **The surface files** — one per page/screen/modal/command/email — each consuming the design system
+
+This phase is end-to-end: it produces a complete design system AND the per-surface application of it.
+
+## How UI/UX connects to everything else
+
+- Every surface names ≥1 persona
+- Every surface names ≥1 contract it touches
+- Every surface references the design-system pieces it uses
+- Work units that build surfaces name which surface(s) they build
+- Surface changes that affect a persona's experience get filed as decisions
+
+## How to add a surface
+
+During planning: the AI does this for you via `nuos-catalogue ui-ux create`.
+
+Outside planning: copy `surface-template.md` to `<short-surface-name>.md`, fill it in, and add a row to the table above.

package/templates/starter-kit/docs/build/ui-ux/surface-template.md

@@ -0,0 +1,72 @@
+# [Surface name]
+
+> *Replace bracketed placeholders. Delete this hint block once filled in.*
+
+**Type:** [page / screen / modal / command / email / notification / printable]
+**Status:** 🔵 proposed / 🟡 in flight / 🟢 live / ⚫ retired
+**Last updated:** {{TODAY}}
+
+## Who uses this surface
+
+[Link to the persona(s). One per row.]
+
+- [P001 — name](../personas/P001-name.md): [one-line note on how they use this surface]
+
+## When they reach it
+
+[The trigger — what's happening in the persona's day that brings them here. Not "they click a link"; describe the moment.]
+
+> Example: "It's 4pm on a Tuesday. The teacher is winding down for the day. They want a quick look at tomorrow's high-need students before they go home."
+
+## What they see
+
+[Describe the content and layout. Reference design-system components by name.]
+
+- [Component or pattern from design-system] — [what it shows]
+- [Component] — [...]
+- ...
+
+> Example: "Heading using `Display.large` token (see design-system/typography.md). Below it, a vertical list of `Card.priority` components — see design-system/components/card.md — one per student, ranked by priority."
+
+## What they do
+
+[Actions available on this surface. One per row.]
+
+- [Action] → [what happens]
+- [Action] → [...]
+
+## What happens next
+
+[Where the user goes after this surface, or what the system does in the background.]
+
+## Contracts this surface touches
+
+[Which contracts does this surface read from or write to? Link to the contract files.]
+
+- **Reads:** [contract link]
+- **Writes:** [contract link]
+
+## Design system pieces this surface uses
+
+[What components, patterns, tokens, voice samples are consumed here. Link to the design system files.]
+
+- **Components:** [list, linked]
+- **Patterns:** [list, linked]
+- **Tokens:** [list, linked]
+- **Voice samples:** [microcopy keys or examples, linked to design-system/voice.md]
+
+## Accessibility
+
+[What this surface promises for accessibility. Should match or extend the design-system accessibility commitments.]
+
+- [Commitment: e.g. fully keyboard-navigable]
+- [Commitment: e.g. AA contrast minimum]
+- [...]
+
+## Open questions about this surface
+
+[Link to Q-NNN entries that affect this surface specifically.]
+
+## Notes
+
+[Date-stamped notes about how this surface has evolved.]

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

@@ -0,0 +1,43 @@
+# Work Unit [NNN] — [short title]
+
+> *This is the simple work-unit template. Use this one for everyday work units. Use `001-template-full.md` for infrastructure work (build, publish, refactor) or when you need to track contracts produced and consumed.*
+
+**Status:** 🔵 proposed / 🟡 in flight / 🟣 awaiting review / ✅ shipped / 🔴 blocked
+**For:** [persona handle and name — e.g. [P001 — name](../personas/P001-name.md)]
+**Last updated:** {{TODAY}}
+
+## What's done when this ships
+
+[One paragraph. What's true about the world after this work unit ships that wasn't true before? Plain language.]
+
+> Example: "When teachers open the morning briefing, they see their three highest-need students at the top of the screen, with the actions they took yesterday and the actions recommended for today."
+
+## Walkthrough
+
+[A short story of someone using this. Numbered steps from the persona's perspective. Include what happens if things go wrong.]
+
+1. [What happens first; what the persona does or sees]
+2. ...
+3. ...
+
+**What if something goes wrong:**
+
+- [If the data they need isn't ready: ...]
+- [If they make a mistake: ...]
+- [If the system fails: ...]
+
+## How we'll know it's done
+
+[3-6 things you can check. Each one should be yes/no, not "better" or "worse".]
+
+1. [Checkable statement]
+2. [Checkable statement]
+3. ...
+
+## Notes / log
+
+> *Updated at the end of every session this work unit is touched. Append dated entries with what was attempted, what worked, what didn't, what was learned, and what comes next.*
+
+### {{TODAY}} — initial filing
+
+[Why this work unit was filed; the moment it became clear it was worth a separate WU.]

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

@@ -1,34 +1,32 @@
-# Work Units
+# 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.
+A **work unit** is one concrete thing the project will build. Each one has a title, an outcome (what's true after it ships that wasn't true before), a story of someone using it, and a short list of how you'll know it's done. The catalogue's value compounds as work units accumulate notes — every session adds to the record of what was attempted, what worked, what didn't, and what was learned. See [the glossary](../GLOSSARY.md#work-unit) for the full definition.
 
 ## Index
 
-| WU | Title | Status | Depends on | Notes |
-| --- | --- | --- | --- | --- |
-| 001 | [first WU title] | 🟡 in flight | — | First work unit |
+| WU | Title | Status | Notes |
+| --- | --- | --- | --- |
+| _none yet — file your first one with `/wu-new`_ | | | |
 
-## Status legend
+## What status means
 
 - 🔵 **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
+- 🟣 **awaiting review** — implementation done, review pending
+- ✅ **shipped** — complete; lives in `done/`
+- 🔴 **blocked** — cannot proceed; the WU's notes say why
 
-## Deferred / proposed-with-trigger work units
+## When to file a work unit
 
-A work unit can be `🔵 proposed` in three flavours:
+When you're about to start (or have just started) work that you'll want to track. Anything bigger than "edit a paragraph" deserves one. Smaller work can land inside an existing work unit's notes.
 
-- **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
+If a work unit is **proposed** but can't start yet, say why right in its title or notes:
+- _waiting on Q003_ — an open question must resolve first
+- _waiting on WU 007_ — another work unit must ship first
+- _deferred — start when [specific condition]_ — set a checkable trigger
 
-The quarterly catalogue review walks each deferred WU and re-evaluates its trigger.
+## How to file one
 
-## How to add a work unit
+Easiest way: run `/wu-new`. The AI will walk you through the four fields (title, outcome, walkthrough, how-we-know-it's-done) and save the file in the right place, then add a row to this index.
 
-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
+If you'd rather file manually: copy `001-template-simple.md` to `NNN-short-title.md` and fill it in. Use `001-template-full.md` instead if your work unit is infrastructure (build, publish, refactor) and you want the fuller shape (contracts produced/consumed, forward-compatibility notes).

package/templates/starter-kit/methodfile.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://nusoft.dev/schemas/methodfile/v1.json",
   "method": {
-    "version": "1.0",
+    "version": "1.1",
     "lastValidatedAt": "{{TODAY}}"
   },
   "project": {
@@ -12,23 +12,34 @@
   "catalogue": {
     "root": "docs/build/",
     "registers": {
+      "personas": "personas/",
+      "maps": "maps/",
+      "architecture": "architecture/",
+      "contracts": "contracts/",
+      "uiUx": "ui-ux/",
+      "designSystem": "design-system/",
       "decisions": "decisions/",
+      "openQuestions": "open-questions/",
       "workUnits": "work-units/",
-      "sessions": "sessions/",
       "risks": "risks/",
-      "openQuestions": "open-questions/"
+      "sessions": "sessions/"
     },
     "snapshot": "STATE.md",
+    "welcome": "WELCOME.md",
+    "glossary": "GLOSSARY.md",
     "protocols": {
       "startOfSession": "START-OF-SESSION.md",
       "endOfSession": "END-OF-SESSION.md"
-    },
-    "supportingLayers": {
-      "philosophy": "../philosophy/",
-      "contracts": "../contracts/",
-      "guides": "../guides/"
     }
   },
+  "planning": {
+    "phaseA_orientation": "not_started",
+    "phaseB_architecture": "not_started",
+    "phaseC_uiUxDesignSystem": "not_started",
+    "phaseD_maps": "not_started",
+    "phaseE_initialWorkUnits": "not_started",
+    "completedAt": null
+  },
   "harness": {
     "wired": false,
     "runtime": {