@nusoft/nuos-build-catalogue 0.12.0 → 0.14.1

package/templates/hooks/pre-commit

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+#
+# NuOS catalogue pre-commit hook (WU 111 enforcement phase).
+#
+# Catches drift before commit. After WU 111's Phase J ship, the
+# accepted-decision rule has flipped from warning → block (per the
+# pack's narrower-than-originally-planned enforcement scope, recorded
+# in WU 111's "Forward-compatibility commitments" section). Other
+# rules described in WU 128's original aggressive list are NOT shipping
+# — distinguishing tool-written from human-written content was deemed
+# overengineering for a planning-artefact catalogue.
+#
+# Active rules:
+#   1. index-drift detection — every WU/decision/open-question/risk file
+#      must have a matching row in its _index.md (and vice versa)
+#   2. active-decision modification block — modifying a committed
+#      `accepted` decision file is BLOCKED (not just warned). The
+#      discipline is to write a superseding D-NNN+1 and link forward.
+#      To deliberately fix a typo or link in an accepted decision,
+#      use `git commit --no-verify` (CLAUDE.md prohibits this for
+#      substantive changes; reserve it for typo-only fixes).
+#
+# Sentinel-protected sections (e.g. STATE.md's `nuos:sentinel`) remain
+# protected via the existing `.claude/hooks/check-catalogue-write.sh`
+# Claude Code hook. That rule continues unchanged at WU 111 ship.
+#
+# Bypass: this hook respects --no-verify like any other. The CLAUDE.md
+# policy explicitly prohibits --no-verify use for substantive changes;
+# the technical block fires at the CI server-side check (a future WU).
+
+set -uo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+ENFORCEMENT_LOG="$REPO_ROOT/.nuos-enforcement.log"
+EXIT_CODE=0
+
+red()    { printf '\033[31m%s\033[0m\n' "$*"; }
+yellow() { printf '\033[33m%s\033[0m\n' "$*"; }
+green()  { printf '\033[32m%s\033[0m\n' "$*"; }
+dim()    { printf '\033[2m%s\033[0m\n' "$*"; }
+
+log_event() {
+  printf '%s | %s | %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$1" "$2" >> "$ENFORCEMENT_LOG"
+}
+
+# ---------- Generic index-drift checker ---------------------------------
+#
+# Args:
+#   $1 — kind label (for messages)
+#   $2 — directory (relative to repo root)
+#   $3 — _index.md path (relative to repo root)
+#   $4 — filename regex (matches IDs the directory contains)
+#   $5 — index-row ID regex (a Perl-compatible regex that anchors on the
+#        leftmost column of an index table row)
+#
+# The two regexes must extract the SAME set of IDs (e.g. "001", "030g",
+# "D042") so set comparison works.
+
+check_index_drift() {
+  local kind="$1" dir="$2" index="$3" file_regex="$4" row_regex="$5"
+
+  if [[ ! -d "$REPO_ROOT/$dir" ]]; then return 0; fi
+  if [[ ! -f "$REPO_ROOT/$index" ]]; then return 0; fi
+
+  # IDs extracted from filenames in the directory (top-level + one subdir
+  # like done/, resolved/, superseded/)
+  local ids_in_tree
+  ids_in_tree=$(cd "$REPO_ROOT/$dir" && {
+    find . -maxdepth 2 -type f -name "*.md" \
+      -not -name "_index.md" \
+      -not -name "*-template.md" 2>/dev/null \
+      | sed -nE "$file_regex" \
+      | sort -u
+  })
+
+  # IDs extracted from leftmost column of table rows in the index
+  local ids_in_index
+  ids_in_index=$(sed -nE "$row_regex" "$REPO_ROOT/$index" | sort -u)
+
+  local missing_from_index
+  missing_from_index=$(comm -23 <(printf '%s\n' "$ids_in_tree") <(printf '%s\n' "$ids_in_index"))
+
+  if [[ -n "$missing_from_index" ]]; then
+    red "✖ index-drift ($kind): on disk but missing from $index:"
+    while IFS= read -r id; do echo "    — $id"; done <<< "$missing_from_index"
+    log_event "index-drift" "$kind missing from index: $(echo "$missing_from_index" | tr '\n' ',')"
+    EXIT_CODE=1
+  fi
+}
+
+dim "[nuos:pre-commit] index-drift check"
+
+# Note: BSD sed (macOS default) is fussy about `|` as both delimiter and
+# regex content. Using `#` as the s/// delimiter sidesteps the collision.
+
+# Work units: filenames are NNN-slug.md or NNNa-slug.md (with optional letter).
+# Index rows are `| NNN |` or `| NNNa |` in the leftmost column.
+check_index_drift \
+  "work-units" \
+  "docs/build/work-units" \
+  "docs/build/work-units/_index.md" \
+  's#^\./(done/)?([0-9]{3}[a-z]?)-[^/]*\.md$#\2#p' \
+  's#^\| ([0-9]{3}[a-z]?) \|.*$#\1#p'
+
+# Decisions: filenames are DNNN-slug.md.
+# Index rows: `| DNNN |` or `| [DNNN](...) |`.
+check_index_drift \
+  "decisions" \
+  "docs/build/decisions" \
+  "docs/build/decisions/_index.md" \
+  's#^\./(done/|superseded/)?(D[0-9]{3})-[^/]*\.md$#\2#p' \
+  's#^\| \[?(D[0-9]{3}).*$#\1#p'
+
+# Open questions: filenames are QNNN-slug.md.
+check_index_drift \
+  "open-questions" \
+  "docs/build/open-questions" \
+  "docs/build/open-questions/_index.md" \
+  's#^\./(resolved/)?(Q[0-9]{3})-[^/]*\.md$#\2#p' \
+  's#^\| \[?(Q[0-9]{3}).*$#\1#p'
+
+# Risks: per current convention, individual risk files are inline in
+# risks/_index.md (no per-risk .md files yet). Skip the check entirely
+# until that pattern changes.
+if compgen -G "$REPO_ROOT/docs/build/risks/R[0-9][0-9][0-9]-*.md" > /dev/null; then
+  check_index_drift \
+    "risks" \
+    "docs/build/risks" \
+    "docs/build/risks/_index.md" \
+    's#^\./(R[0-9]{3})-[^/]*\.md$#\1#p' \
+    's#^\| \[?(R[0-9]{3}).*$#\1#p'
+fi
+
+# ---------- Rule 2: active-decision modification block (WU 111 ship) ---
+
+dim "[nuos:pre-commit] active-decision modification check"
+modified_decisions=$(git diff --cached --name-only --diff-filter=M \
+  | grep -E '^docs/build/decisions/D[0-9]+.*\.md$' \
+  | grep -v '/superseded/' \
+  || true)
+
+if [[ -n "$modified_decisions" ]]; then
+  red "✖ active-decision modification — BLOCKED (WU 111 enforcement):"
+  while IFS= read -r f; do echo "    — $f"; done <<< "$modified_decisions"
+  red "  Decisions are immutable once accepted. The discipline is to write a"
+  red "  superseding D-NNN+1 and link forward. Use:"
+  red "    nuos-catalogue decision supersede <target> --by=<new-D> --reason=\"...\""
+  red ""
+  red "  If this edit is a non-substantive typo fix or link cleanup that does"
+  red "  not change the decision's meaning, you may bypass this block with"
+  red "  --no-verify. CLAUDE.md prohibits --no-verify for substantive changes."
+  log_event "active-decision-block" "$(echo "$modified_decisions" | tr '\n' ',')"
+  EXIT_CODE=1
+fi
+
+# ---------- Result ------------------------------------------------------
+
+if [[ $EXIT_CODE -eq 0 ]]; then
+  green "[nuos:pre-commit] all rules pass (WU 111 enforcement)"
+  log_event "pre-commit-pass" "$(git diff --cached --name-only | wc -l | tr -d ' ') files"
+fi
+exit $EXIT_CODE

package/templates/protocols/end-of-session.md

@@ -1,19 +1,107 @@
 # end-of-session
 
-Run the end-of-session protocol for this NuOS Build Method project.
+You are ending a session on a project that uses the **NuOS Build Method catalogue**. Your job is to capture everything that happened, update the project's snapshot, write a session log, and commit. **Without this, work is lost. The whole catalogue is built on the assumption that every period of work gets captured before it closes.**
 
-Follow `docs/build/END-OF-SESSION.md` exactly. Nine steps:
+**The operator is most likely a domain expert, not a software engineer.** Plain English throughout. Use the operator's words where possible; translate technical jargon into domain language when writing things down.
 
-1. **Update the active work unit's notes section** with what was attempted, what worked, what did not work and why, what was learned, and what the next concrete action should be. Apply the auditor's-question test: could a third-party reader read this entry and answer "why was this done and what justifies the next step?" without contacting the team?
-2. **Capture any new decisions** as `docs/build/decisions/D<NNN>-<slug>.md` files plus an entry in `decisions/_index.md`.
-3. **Capture any new open questions** as `docs/build/open-questions/Q<NNN>-<slug>.md` files plus an entry in `open-questions/_index.md`. If a question was both raised AND resolved this session, capture it as a decision instead.
-4. **Capture any new risks** as entries in `docs/build/risks/_index.md`.
-5. **Update the work-units index.** Confirm status icons reflect reality. **When a WU promotes to ✅, move its file from `work-units/<NNN>-<slug>.md` to `work-units/done/<NNN>-<slug>.md` and update the row link in `_index.md` to point at `done/<file>`.** Fix internal relative paths in the moved file (one level deeper after the move).
-6. **Update `STATE.md`.** Refresh: last-updated date, last-session reference, active work unit, "What was just done", "What is next" if priorities shifted, decisions/questions/risks tables.
-7. **Write a session log entry** in `docs/build/sessions/<YYYY-MM-DD>-<slug>.md`. Add a row to `sessions/_index.md`.
-8. **Verify nothing is lost.** Every decision has a file + index entry. Every question has a file + index entry. Every risk has an index entry. STATE.md reflects current state. Cross-references resolve. Dates are right.
-9. **Commit.** A single commit with the message `end-of-session: <YYYY-MM-DD> — <one-line summary>`. The pre-commit hook (per WU 128) will validate index integrity on the way through; if it blocks, fix the underlying drift, do not bypass with `--no-verify`.
+---
 
-**End-of-session is non-negotiable.** Without it, work is lost — that is the single rule the catalogue is built on.
+## Steps
 
-If you cannot run the full protocol (rushing to stop, handing off mid-task), at minimum write one paragraph into the active WU's notes section: *"session ended without full end-of-session protocol; the state is approximately X; outstanding actions Y."* Then run the full protocol at the start of the next session before any new work.
+### 1. Update the active work unit's notes section (or the active planning phase's notes if mid-planning)
+
+Append a dated entry to the active work unit's `## Notes / log` section. Capture:
+
+- **What was attempted** — in their words, in plain language
+- **What worked** — concrete and specific
+- **What didn't work and why** — be honest; vague entries are worthless
+- **What was learned** — anything generalisable; patterns starting to emerge
+- **What the next concrete action should be** — specific enough that the next session can pick up without thinking
+
+**The test:** could a future-you (or anyone joining the project) read this entry and answer *"why was this done, and what justifies the next step?"* without asking? If yes, the entry is sufficient. If you'd need to explain, write more.
+
+### 2. File any new decisions made this session
+
+If anything was decided in conversation — even if it felt obvious at the time — file it as a decision in `docs/build/decisions/`. Use the next available D-NNN number. Add a row to `decisions/_index.md`. Link from the active work unit if it shaped the work.
+
+**This is non-negotiable.** Decisions made and not filed are drift. The catalogue's value is that what was decided is recorded.
+
+### 3. File any new open questions raised
+
+If something came up that needs deciding later, file it in `docs/build/open-questions/` as Q-NNN. Add a row to `open-questions/_index.md`. If a question was both raised AND resolved this session, skip the question file and just file the decision in step 2.
+
+### 4. Note any new risks
+
+If something to watch was identified, add a row to `docs/build/risks/_index.md`.
+
+### 5. Update the work-units index
+
+Confirm status icons reflect reality. When a work unit promotes to ✅ shipped:
+
+- Move its file from `work-units/NNN-slug.md` to `work-units/done/NNN-slug.md`
+- Update the row link in `_index.md` to point at `done/`
+- Fix any internal relative paths in the moved file (they go one level deeper)
+
+### 6. Update STATE.md
+
+Refresh:
+
+- **Last updated** — today's date
+- **What is currently in flight** — the current state of work in one paragraph
+- **What just shipped** — the most recent completion
+- **What is next** — the immediate next action
+- **Planning progress** — if a planning phase advanced, update its status here
+- The decisions, questions, and active work units tables — pull the most recent rows from each register
+
+### 7. Write a session log entry
+
+Create `docs/build/sessions/YYYY-MM-DD-short-slug.md`. The entry includes:
+
+- **What this session was about** — one paragraph
+- **What was done** — chronological, in plain language; the story of the session
+- **Decisions made** — linked to the D-NNN files filed this session
+- **Open questions raised** — linked to Q-NNN files
+- **Risks identified** — linked to R-NNN rows
+- **What's next** — the concrete next action; what the next session should start with
+- **Resume hint** — *critical if the session ended mid-task*. A one-paragraph note of exactly where you were and what was about to happen next, so the next session can pick up cleanly. Example: *"We were in Phase B of planning, working on the contract for the Overnight Consolidation module. Next: walk through the Planning Module contract."*
+
+Add a row to `sessions/_index.md`.
+
+### 8. Verify nothing is lost
+
+Before committing, scan:
+
+- Every decision filed has a D-NNN file AND an index entry
+- Every open question filed has a Q-NNN file AND an index entry
+- Every risk filed has an index row
+- STATE.md reflects current state
+- Cross-references resolve (no dead links)
+- Dates are right
+
+### 9. Commit
+
+Single commit. Message format:
+
+```
+end-of-session: YYYY-MM-DD — one-line summary
+```
+
+The pre-commit hook validates index integrity on the way through. If it blocks, fix the underlying issue — don't bypass with `--no-verify`. The post-commit hook will refresh the search index in the background after the commit lands.
+
+---
+
+## What never to do
+
+- **Never close a session without end-of-session running.** If you have to stop in a rush, at minimum write one paragraph into the active work unit's notes saying *"session ended without full end-of-session protocol; state is approximately X; outstanding actions Y"*. Then run the full protocol at the start of the next session before any new work.
+
+- **Never bypass the pre-commit hook with `--no-verify` for substantive changes.** Typo fixes on accepted decisions are the only legitimate use. If the hook blocks you, something in the catalogue is inconsistent — fix it; don't paper over.
+
+- **Never leave a decision in conversation rather than in a file.** *"We agreed to use X"* in chat is not a decision. The file is the decision; chat is the conversation that produced it.
+
+---
+
+## Why this matters
+
+The catalogue's compounding value comes from the accumulated record. Every session writes a small layer of context. Six months in, a new contributor — or future-you — opens the project and can read the path from origin to now. Drift is what makes that path unreadable. End-of-session is the protocol that prevents drift.
+
+If end-of-session feels like ceremony, the project is fine; carry on. If end-of-session feels like the only thing standing between coherence and chaos, the catalogue is doing its job.

package/templates/protocols/persona-new.md

@@ -1,43 +1,77 @@
 # persona-new
 
-Create a new persona (P-NNN) for this NuOS Build Method project.
+You are filing a new **persona** for a project that uses the **NuOS Build Method catalogue**. A persona is one specific person the project serves — not a market segment, not a demographic. One person with a name, a situation, and a reason to need what's being built.
 
-A persona is a **specification of who will use an outcome and what situation they will be in when they use it** — not a demographic snapshot, but a design constraint. Personas live as first-class catalogue entries (per D046) so they can be cited by stable handle from multiple WUs.
+**The operator is most likely a domain expert, not a software engineer.** Plain English throughout. Walk the operator through the persona in conversation — don't read out a form.
 
-If arguments are provided (`$ARGUMENTS` for OpenCode/Claude Code, prompt-supplied for Codex), use them as the persona name; otherwise prompt the operator for the name.
+---
 
-Steps:
+## Step 1 — Open with the why
 
-1. **Determine the next available P number.** Scan `docs/build/personas/` and `docs/build/personas/done/` for the maximum P-NNN prefix. The new number is max + 1.
-2. **Slugify the persona name** — lowercase, dashes for spaces, no special characters, max 60 chars.
-3. **Generate the file** at `docs/build/personas/P<NNN>-<slug>.md` from the template at `starter-kit/docs/build/personas/001-template.md`. Replace placeholders with operator-supplied values.
-4. **Prompt the operator for the seven dimensions:**
+Briefly explain why we're doing this (one or two sentences):
 
-   - **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. What account do they have? What role do they play? What other systems have they used that shape their expectations?
-   - **2. Reality** — physical environment when they use the outcome. Device, connection quality, noise level, time pressure. 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?
-   - **4. Trigger** — what brings them to this outcome. A real-world event, not a UI click. The event in their life that created the need.
-   - **5. History** — what they have done before arriving at this outcome. Returning user vs first-time visitor. Saved details vs no context.
-   - **6. Success** — what "done" looks like from *their* perspective. Not what the system logs — what they *feel*. This drives the design.
-   - **7. Constraints** — what they cannot or will not do. Defines the outer boundary of acceptable design.
+> "I'll capture this person specifically so everything we build downstream can refer back to them. The point isn't to fill in a form — it's so that when we file a feature later, we can say 'this is for [name], in [their situation], when [their trigger happens]' and not have to re-explain who they are every time."
 
-5. **Prompt for the acid-test refinement.** The hardest legitimate user — this persona with the most demanding combination of real constraints. Not a hostile user; a legitimate one with the worst realistic conditions. Slow device, low technical confidence, time pressure, complex situation. Design for the acid-test and the standard cases hold.
-6. **Prompt for paired persona (if any).** If this persona's outcomes are paired with another's — a customer who books an event and an organiser who receives the booking — capture the paired P-NNN. If no pair exists yet, the operator may file the paired persona next via a second `persona-new` invocation.
-7. **Apply the persona discipline checks:**
+Then ask for their name. Even a made-up one is fine.
 
-   - **Does this persona change a design decision?** If you could substitute this persona with a different one and the WU specification would be identical, the persona is decorative. Surface the gap and prompt for refinement.
-   - **Does this persona have specific triggers, not just a demographic profile?** A persona without triggers is a character in search of a plot. Surface and prompt for refinement.
-   - **Is the acid-test the hardest legitimate combination, or only a slightly harder version of the easy case?** The acid-test must be uncomfortable to design for — that is its point.
+## Step 2 — Walk the seven dimensions as conversation
 
-8. **Add a row to `docs/build/personas/_index.md`.** Status `🟢 active`. The "Used by WUs" cell stays empty until WUs cite it (which the `wu-new` protocol will update).
-9. **Surface to the operator:**
-   - The new persona file path (clickable)
-   - The row added to `_index.md`
-   - Any discipline checks that surfaced gaps (paired-persona suggestion; "this persona doesn't yet constrain a decision" warning)
-   - The next concrete action — typically: file a WU that serves this persona (`wu-new`), or file the paired persona
+Don't list "the seven dimensions" to the operator. Weave them into questions. Below are the dimensions and a conversational prompt each. Adapt to the operator's flow — if they answer two dimensions in one breath, capture both and skip ahead.
 
-**Discipline:** the persona is a design constraint or it is decoration. The seven dimensions exist to make every design decision answerable. If the persona file does not constrain at least one decision a future WU will need to make, rewrite it until it does.
+1. **Identity** — *"Tell me about them in the context of this project. What's their role? What account do they have? What systems are they used to? Just enough that someone reading this knows who they are in relation to what we're building."*
 
-**On the multi-month context (per D046):** in serious systems, personas are referenced from many WUs over many months. The seven-dimension shape is what makes the persona reusable — generic personas ("the user") force every WU to invent the persona inline; specific personas with stable handles let outcomes inherit the constraint. The persona register is the catalogue's commitment to this reuse.
+2. **Reality** — *"Where are they when they need this? What device? Are they at their desk, on the school playground, on a train, at home? Time of day? Noise? Pressure?"*
 
-If the operator wants to skip a dimension because it feels obvious, accommodate but record what was skipped — a future WU may need exactly that dimension and find it missing. The catalogue's value is that what was decided is recorded; what was not yet decided is also recorded, as a known gap.
+3. **Psychology** — *"How tech-confident are they? Are they patient when things don't make sense, or do they abandon fast? How much energy do they have when they're using this?"*
+
+4. **Trigger** — *"What's happening in their day that makes them need this? Not 'they open the app' — what comes before that? What's the moment in their life that creates the need?"*
+
+5. **History** — *"What have they done already by the time they reach this? Are they a returning user with saved details, or is this fresh every time? What previous experiences shape what they expect?"*
+
+6. **Success** — *"What does 'this worked' feel like from their side? Not what the system logs — what they actually feel. Relief? Confidence? Done with it?"*
+
+7. **Constraints** — *"What can they not (or will they not) do? What's the hard edge of acceptable for this person?"*
+
+## Step 3 — The acid-test refinement
+
+Ask one more question:
+
+> *"Now imagine the hardest legitimate version of this person — same role, same job, but with every realistic constraint at its worst at the same time. Slow device. Low confidence. Time pressure. Bad day. Tired. Distracted. The combination that's still real but makes everything harder. Design for that person and the easier cases hold."*
+
+Capture the acid-test as the last dimension on the persona file.
+
+## Step 4 — Discipline check (gentle)
+
+Look at what you've captured. Two questions to surface (gently, in plain language):
+
+- **Would swapping this person for a different one force you to change anything?** If no, the persona isn't constraining yet — ask one more sharpening question.
+- **Are the triggers specific real-life moments, or just "uses the system"?** Vague triggers produce vague designs.
+
+If either is weak, ask one more probing question — but don't force perfection. Captured-but-imperfect is much better than not captured.
+
+## Step 5 — File the persona
+
+1. **Number it.** Scan `docs/build/personas/` and `docs/build/personas/done/` for the highest P-NNN prefix; new number is max + 1.
+2. **Slugify the name** — lowercase, dashes for spaces, no special characters, max 60 chars.
+3. **Write the file** at `docs/build/personas/PNNN-slug.md`. Use the template at `docs/build/personas/001-template.md`. Fill in each dimension from the conversation.
+4. **Add a row** to `docs/build/personas/_index.md`. Status `🟢 active`. "Used by" column stays empty until work units reference this persona.
+
+## Step 6 — Tell the operator what happened
+
+Plain English:
+
+- Where the file landed (clickable path)
+- Anything you noticed during the conversation (e.g. "you mentioned a colleague who reviews this work — is that a paired persona we should file separately?")
+- The next concrete action — usually: file the paired persona if there is one; otherwise carry on with the active phase
+
+---
+
+## Why personas are first-class in this catalogue
+
+Many projects describe their users in passing — a vague "teachers" or "users" mentioned inside a feature spec, different every time. That works for small projects. For projects with real complexity, it doesn't: every feature spec re-invents who it's for; downstream features can't be designed coherently against a moving target.
+
+Personas as first-class catalogue entries fix this. **One sharp persona, referenced by stable handle, used across many work units over many months.** Every feature filed says who it's for by P-NNN handle. When the persona evolves, every reference updates with it.
+
+The seven dimensions are what make a persona sharp enough to carry that weight. The acid-test is what makes the design robust. If the catalogue has decorative personas — ones that don't change any design decision — they're worse than no personas at all, because they create the illusion of constraint without supplying any.
+
+If the operator skips a dimension because it feels obvious, accommodate but note what was skipped. A later work unit may need exactly that dimension and find it missing. The catalogue records what's decided AND what's not yet decided — both are load-bearing.

package/templates/protocols/plan-orientation.md

@@ -0,0 +1,122 @@
+# plan-orientation
+
+You are running **Phase A of the planning arc** for a project that just adopted the NuOS Build Method catalogue. This is the operator's first real conversation with the harness. By the end of this session they should have:
+
+- A short, plain-English project description filed in `STATE.md`
+- 1-3 personas filed in `docs/build/personas/`
+- Map 1 — The Horizon — filed in `docs/build/maps/01-the-horizon.md`
+- Initial open questions captured for anything they couldn't yet answer
+- The Phase A row in STATE.md's Planning progress table flipped to `✅ complete`
+
+The whole session should take about 30 minutes. **The operator is most likely a domain expert, not a software engineer.** Plain English throughout. Never use a term like "work unit" or "contract" without defining it the first time. Read [`docs/build/GLOSSARY.md`](../../docs/build/GLOSSARY.md) once before you start so your vocabulary matches the catalogue's.
+
+---
+
+## How to lead this conversation
+
+- **Lead the operator. Don't quiz them.** They aren't here to fill in a form; you're walking them through producing something they can use.
+- **Translate the answers into catalogue artefacts as you go.** They don't need to know the artefact shape — you do.
+- **One question at a time.** If they answer two at once, capture both and move on.
+- **Use their words wherever possible.** Translate jargon out, not in.
+- **If they don't know something, file an open question and move on.** Don't stall.
+- **Save as you go.** Don't accumulate answers and write everything at the end — write each artefact when the conversation produces it.
+
+**Drift discipline:** every decision made in conversation must be filed before the session ends. If the operator says "let's go with X" and X is an architectural commitment, file a decision file in `docs/build/decisions/` *now*, not later. Decisions made in chat that don't reach the catalogue are drift, and drift is the failure mode that makes the catalogue worthless.
+
+---
+
+## Step 1 — Welcome (2 min)
+
+Open with something like:
+
+> "Welcome. I'm going to help you plan your project. We'll do this step by step over the next half-hour or so, with breaks if you want. By the end, your catalogue will have a real project description, the first person or two it's for, and a map of where this whole thing is heading. Anything we decide gets saved as we go — you don't have to remember any of it.
+>
+> Take your time. If a question doesn't have an obvious answer, we'll file it as an open question and keep moving. Ready?"
+
+Wait for confirmation.
+
+## Step 2 — Project description (5 min)
+
+Ask, in conversation:
+
+> "Tell me about what you're building. A paragraph or two is enough. What is it? Who's it for, roughly? What does it do? Why does it need to exist?"
+
+Listen. Don't interrupt. When they're done, summarise back in 2-3 sentences in your words, and ask if you've got it. Refine if needed.
+
+When the description is settled, **write it into `STATE.md`'s "What is currently in flight" section** — replacing the placeholder. Keep their voice; don't make it sound corporate. Show them the file path and confirm it's saved.
+
+## Step 3 — One persona, then one or two more (15-20 min)
+
+Tell the operator what's coming:
+
+> "Now I'm going to ask about the specific people this project serves. Not 'teachers' or 'users' — one specific person with a name. Their situation, what makes them need this, what success feels like for them. We'll do one in detail, then maybe one or two more. This becomes the anchor for everything we file later."
+
+Then **switch to the `persona-new` protocol** (invoke `/persona-new` if available, otherwise read `.claude/commands/persona-new.md` and follow it) to walk the operator through the persona conversationally. File the persona as P001.
+
+When P001 is filed, surface it and ask:
+
+> "We have [name] filed. Are there other specific people this project serves? Most projects have 2 or 3. The most common shape is: the primary user, and someone else who's affected — a colleague, a parent, an administrator, the person whose work this enables. Want to file another?"
+
+If yes, run `/persona-new` again. Aim for **1-3 total** — more than 3 in Phase A usually means the project is overscoped; file the rest as open questions and revisit later.
+
+## Step 4 — Map 1: The Horizon (8-10 min)
+
+When the personas are filed, transition:
+
+> "Now let's draw the whole picture. Not the details yet — the destination. What does the world look like when this project is finished? What's true that isn't true today?"
+
+Use the template at `docs/build/maps/01-template.md`. Walk through its sections **as conversation, not as a form**:
+
+- **What this project is** — one paragraph, plain language. (You may already have most of this from Step 2 — refine it for the map.)
+- **Who it's for** — list the personas just filed, one line each with their P-NNN handle.
+- **What "done" looks like** — describe the destination in 3-6 sentences. Not how to get there; the place itself.
+- **The shape of the journey** — two or three paragraphs in plain language describing the major stages, in narrative form. *"First we'll build X so Y is possible. Once Y is in place, we can do Z, which is what really matters for [persona]. The last stretch is making it reliable enough for real classrooms."* That kind of writing. A story, not a Gantt chart.
+- **What's not in scope** — 3-5 things adjacent to the project that someone might assume are included but aren't. Naming the negative space prevents drift.
+
+Write the map to `docs/build/maps/01-the-horizon.md`. Show them the file path and confirm.
+
+## Step 5 — Open questions (2 min)
+
+Pass over the conversation looking for anything the operator wasn't sure about. For each:
+
+- File it as Q-NNN in `docs/build/open-questions/`
+- Add a row to `open-questions/_index.md`
+
+> "I noticed a few things you weren't sure about yet — [list]. I've filed them as open questions so we'll come back to them. Two of them affect Phase B (Architecture), so we'll definitely hit them next session."
+
+## Step 6 — Close (2 min)
+
+Update STATE.md:
+
+- Set the **Planning progress** Phase A row to `✅ complete (YYYY-MM-DD)`
+- Set the Phase B row to `🟡 next` (so the next `/start-of-session` knows where to route)
+- Refresh the "Last updated" date
+
+Then tell the operator what they now have:
+
+> "You've got your first catalogue substrate:
+>
+> - **[N] personas** in `docs/build/personas/` — these anchor every later decision
+> - **Map 1** at `docs/build/maps/01-the-horizon.md` — the whole-project picture
+> - **[N] open questions** in `docs/build/open-questions/` — these are what we'll resolve as planning continues
+> - **STATE.md** updated to reflect Phase A is done
+>
+> Next session, we move to **Phase B — Architecture & Contracts** (about 60-90 minutes). We'll name the major pieces of your project and what each one provides to the others.
+>
+> For now, run `/end-of-session` to commit everything. The catalogue's search index will refresh in the background, and next session can pick up from here."
+
+Then run `/end-of-session` to close out.
+
+---
+
+## What to do if it goes off-track
+
+- **Operator wants to skip personas:** strongly advise against it. Personas are the anchor for everything downstream. File at least one — even a rough one — and note it's a draft.
+- **Operator says "I don't know" too often:** that's fine for Phase A. File each as an open question; the architecture phase will tighten them up. The point of Phase A is to establish *enough* shape that B can begin, not to be complete.
+- **Operator wants to design implementation:** redirect. *"We'll get to how it's built in Phase B. Right now we're just figuring out what we're building and for whom."*
+- **Operator gets fatigued mid-phase:** offer to pause. Run `/end-of-session` capturing where you are with a "Resume hint" in the session log; pick up at the next session.
+- **Operator wants to file work units already:** suggest waiting. *"Phase E (Initial Work Units) is where we list them — by then we'll know the architecture, surfaces, and design system, so each work unit can be filed coherently."* If they insist, file as `🔵 proposed` with a note that the WU may need refinement after Phase B.
+
+## Recovery if the session was interrupted
+
+If the session log's "Resume hint" indicates Phase A was mid-way, read it carefully and pick up at exactly the step indicated. Re-read what's been filed so far (the personas already in `docs/build/personas/`, anything in STATE.md). Confirm with the operator before continuing — *"Last time we got as far as filing P001 — are we ready to add a second persona, or shall we go straight to Map 1?"*

package/templates/protocols/start-of-session.md

@@ -1,19 +1,58 @@
 # start-of-session
 
-Run the start-of-session protocol for this NuOS Build Method project.
+You are starting a session on a project that uses the **NuOS Build Method catalogue**. Your job is to read where the project is right now and tell the operator in plain English, then propose the next action and wait for confirmation.
 
-Follow `docs/build/START-OF-SESSION.md` exactly. Five steps:
+**The operator is most likely a domain expert, not a software engineer.** Plain English throughout. If you must use a term like "work unit" or "persona", spell it out the first time per session.
 
-1. **Read `docs/build/STATE.md` in full.** It is the single source of "where are we right now?"
-2. **Read the most recent session log entry** in `docs/build/sessions/` (the file with the most recent date in its filename). Read it in full.
-3. **Read the active work unit** named in STATE.md, in full — including the notes / log section at the bottom.
-4. **Skim `docs/build/open-questions/_index.md` and `docs/build/risks/_index.md`** for any items that block the active work unit. If any are blocking, surface them now before any work starts.
-5. **Surface to the operator:**
-   - Where the project is right now (one sentence)
-   - The active work unit and its current status (one sentence)
-   - Any blockers (one bullet each)
-   - The next concrete action (one bullet)
+---
 
-**Wait for confirmation before proceeding to substantive work.** If the operator wants to do something other than the proposed next action, that is fine — but record the divergence either as a new work unit or as a note on the active work unit.
+## Step 1 — First-run detection
 
-If STATE.md looks out of date — or if there is no active work unit named — note that to the operator immediately. Likely the previous end-of-session was skipped.
+Read `docs/build/STATE.md`. Look at the **Planning progress** section:
+
+- If **all five phases (A-E) are still `🔵 not yet started`** AND there are no real work units in `docs/build/work-units/` (only templates), this is a fresh project. Tell the operator:
+
+  > "This is a brand-new catalogue. Before we file any work units, we walk through 5 short planning phases that produce the substrate every later session draws on. Phase A — Orientation — takes about 30 minutes. Want to begin now? (yes / no, look around first)"
+
+  If yes, **switch to the `plan-orientation` protocol** (invoke `/plan-orientation` if available; otherwise read `.claude/commands/plan-orientation.md` and follow it). If no, point them at `docs/build/WELCOME.md` and `docs/build/GLOSSARY.md` so they can read about the catalogue first, then wait.
+
+- If **Phase A is in flight or any phase is mid-progress** (marked `🟡 in flight` in STATE.md's Planning progress section), route the operator back to the relevant `plan-*` protocol to continue planning. Read the most recent session log's "Resume hint" section to know exactly where to pick up.
+
+- If **all five planning phases are complete**, proceed with the normal session-start steps below.
+
+## Step 2 — Read where the project is
+
+Read these files in order:
+
+1. `docs/build/STATE.md` in full — the always-current snapshot
+2. The most recent file in `docs/build/sessions/` — what happened last session
+3. The active work unit named in STATE.md, including its notes section at the bottom
+4. Skim `docs/build/open-questions/_index.md` and `docs/build/risks/_index.md` for anything blocking the active work unit
+
+## Step 3 — Tell the operator where they are
+
+Use plain English. One short paragraph or 4-5 bullets:
+
+- **Where the project is right now** — one sentence describing the current state
+- **What was just done** — the last session's outcome in a sentence
+- **The active work unit** — what's open and its status
+- **Any blockers** — one bullet per blocking question or risk
+- **The next concrete action** — one bullet
+
+## Step 4 — Wait for the operator's confirmation
+
+The operator may want to do the proposed next action, or something different. Either is fine. Just don't start substantive work until they've confirmed direction.
+
+If they want to do something different from the proposed next action, record the divergence — either as a note on the active work unit, or by filing a new work unit if the divergence is significant.
+
+---
+
+## If anything is wrong with STATE.md
+
+If STATE.md still has placeholder text, references a work unit that doesn't exist, or is missing the planning progress section, tell the operator immediately. Likely the previous session ended without `/end-of-session` running. The recovery is to file a session log for what's known to have happened, update STATE, then proceed.
+
+## What never to do at session start
+
+- **Don't make decisions in conversation without filing them.** If the operator says "let's do X" and X is a real architectural choice, file it as a decision in `docs/build/decisions/` before moving on. Decisions made in conversation that aren't filed produce drift — and drift is the failure mode that makes the catalogue worthless.
+- **Don't start work that needs an open question resolved.** Surface the blocker; ask the operator how they want to proceed.
+- **Don't read past your tasks.** STATE, last session log, active work unit, blockers — then stop. Surface those, wait for direction.