@nusoft/nuos-build-catalogue 0.9.0 → 0.10.1

package/dist/search/format.js

@@ -0,0 +1,23 @@
+/**
+ * Output formatter — human-readable table or JSON.
+ */
+export function formatHumanReadable(hits) {
+    if (hits.length === 0)
+        return '(no results)';
+    return hits
+        .map((h, i) => {
+        const idTag = h.idInKind ? ` ${h.idInKind}` : '';
+        const status = h.status ? ` [${h.status}]` : '';
+        const heading = h.headings ? ` › ${h.headings}` : '';
+        const lines = h.startLine ? `:${h.startLine}-${h.endLine}` : '';
+        return [
+            `${(i + 1).toString().padStart(2)}. ${h.path}${lines}`,
+            `    ${h.fileKind}${idTag}${status}${heading}  (score ${h.score.toFixed(4)})`,
+            `    ${h.snippet}`,
+        ].join('\n');
+    })
+        .join('\n\n');
+}
+export function formatJson(hits) {
+    return JSON.stringify({ hits }, null, 2);
+}

package/dist/search/query.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Search — embed the query, call NuVector.searchKnowledge, format results.
+ */
+import type { NuVector } from '@nusoft/nuvector';
+import type { Embedder } from '../embedder/types.js';
+export interface SearchOptions {
+    query: string;
+    limit?: number;
+    kind?: string;
+    status?: string;
+}
+export interface SearchHit {
+    chunkId: string;
+    path: string;
+    fileKind: string;
+    idInKind: string;
+    status: string;
+    date: string;
+    headings: string;
+    startLine: number;
+    endLine: number;
+    score: number;
+    snippet: string;
+}
+export declare function runSearch(store: NuVector, embedder: Embedder, options: SearchOptions): Promise<{
+    hits: SearchHit[];
+    embedMs: number;
+    searchMs: number;
+}>;

package/dist/search/query.js

@@ -0,0 +1,71 @@
+/**
+ * Search — embed the query, call NuVector.searchKnowledge, format results.
+ */
+import { TENANT } from '../store/open.js';
+export async function runSearch(store, embedder, options) {
+    const limit = options.limit ?? 10;
+    const t1 = Date.now();
+    const [queryEmbedding] = await embedder.embed([options.query]);
+    const embedMs = Date.now() - t1;
+    const t2 = Date.now();
+    // Use retrieveContext (not searchKnowledge — that's the NuWiki four-layer
+    // entry point and only returns Layer 1 article summaries). For arbitrary
+    // document chunks like the catalogue indexer's, retrieveContext + kind
+    // filter is the correct method.
+    const result = await store.retrieveContext({
+        embedding: queryEmbedding,
+        tenant: TENANT,
+        topK: Math.max(limit * 3, 30),
+        filters: { kind: 'document_chunk' },
+    });
+    const searchMs = Date.now() - t2;
+    const items = (result?.items ?? []);
+    let hits = items.map((it) => {
+        const meta = it.metadata ?? {};
+        return {
+            chunkId: String(it.ref ?? ''),
+            path: String(meta.path ?? ''),
+            fileKind: String(meta.file_kind ?? ''),
+            idInKind: String(meta.id_in_kind ?? ''),
+            status: String(meta.status ?? ''),
+            date: String(meta.date ?? ''),
+            headings: String(meta.headings ?? ''),
+            startLine: Number(meta.start_line ?? 0),
+            endLine: Number(meta.end_line ?? 0),
+            score: Number(it.score ?? 0),
+            snippet: makeSnippet(String(it.text ?? it.summary ?? ''), options.query),
+        };
+    });
+    if (options.kind) {
+        hits = hits.filter((h) => h.fileKind === options.kind);
+    }
+    if (options.status) {
+        hits = hits.filter((h) => h.status.toLowerCase().includes(options.status.toLowerCase()));
+    }
+    return { hits: hits.slice(0, limit), embedMs, searchMs };
+}
+function makeSnippet(text, query) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    if (flat.length <= 200)
+        return flat;
+    const tokens = query
+        .toLowerCase()
+        .split(/\s+/u)
+        .filter((t) => t.length > 2);
+    let bestIdx = -1;
+    for (const tok of tokens) {
+        const idx = flat.toLowerCase().indexOf(tok);
+        if (idx >= 0) {
+            bestIdx = idx;
+            break;
+        }
+    }
+    if (bestIdx === -1) {
+        return flat.slice(0, 200) + '…';
+    }
+    const start = Math.max(0, bestIdx - 60);
+    const end = Math.min(flat.length, bestIdx + 140);
+    const prefix = start > 0 ? '…' : '';
+    const suffix = end < flat.length ? '…' : '';
+    return prefix + flat.slice(start, end) + suffix;
+}

package/dist/store/open.d.ts

@@ -0,0 +1,14 @@
+/**
+ * NuVector store factory — opens the file-backed store at the configured
+ * location, creating it if missing. The verification gate (scripts/
+ * verify-persistence.ts) confirmed file-backed persistence works in
+ * @nusoft/nuvector@0.1.0; see WU 110 notes for the verdict and known
+ * API quirks.
+ */
+import { NuVector } from '@nusoft/nuvector';
+export declare const TENANT = "nuos_build_catalogue";
+export interface StoreConfig {
+    storagePath: string;
+    dimensions: number;
+}
+export declare function openStore(config: StoreConfig): Promise<NuVector>;

package/dist/store/open.js

@@ -0,0 +1,16 @@
+/**
+ * NuVector store factory — opens the file-backed store at the configured
+ * location, creating it if missing. The verification gate (scripts/
+ * verify-persistence.ts) confirmed file-backed persistence works in
+ * @nusoft/nuvector@0.1.0; see WU 110 notes for the verdict and known
+ * API quirks.
+ */
+import { NuVector } from '@nusoft/nuvector';
+export const TENANT = 'nuos_build_catalogue';
+export async function openStore(config) {
+    return NuVector.open({
+        storage: config.storagePath,
+        dimensions: config.dimensions,
+        tenant: TENANT,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "NuOS build-catalogue tooling: semantic search (WU 110) + migration runner that lifts markdown artefacts into JSON-backed workflow records (WU 111, Phase G).",
   "type": "module",
   "bin": {
@@ -9,15 +9,17 @@
   "files": [
     "dist",
     "scripts",
+    "templates",
     "README.md"
   ],
   "publishConfig": {
     "access": "restricted"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
+    "prepublishOnly": "npm run build",
     "verify-storage": "tsx scripts/verify-persistence.ts",
-    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts",
+    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts tests/init.test.ts",
     "typecheck": "tsc --noEmit",
     "index": "tsx src/cli.ts index",
     "search": "tsx src/cli.ts search"

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

@@ -0,0 +1,19 @@
+# end-of-session
+
+Run the end-of-session protocol for this NuOS Build Method project.
+
+Follow `docs/build/END-OF-SESSION.md` exactly. Nine steps:
+
+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.
+
+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.

package/templates/protocols/persona-new.md

@@ -0,0 +1,43 @@
+# persona-new
+
+Create a new persona (P-NNN) for this NuOS Build Method project.
+
+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.
+
+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:
+
+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:**
+
+   - **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.
+
+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:**
+
+   - **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.
+
+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
+
+**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.
+
+**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.
+
+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.

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

@@ -0,0 +1,19 @@
+# start-of-session
+
+Run the start-of-session protocol for this NuOS Build Method project.
+
+Follow `docs/build/START-OF-SESSION.md` exactly. Five steps:
+
+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.
+
+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.

package/templates/protocols/wu-new.md

@@ -0,0 +1,52 @@
+# wu-new
+
+Create a new work unit (WU) for this NuOS Build Method project.
+
+If arguments are provided (`$ARGUMENTS` for OpenCode/Claude Code, prompt-supplied for Codex), use them as the WU title; otherwise prompt the operator for the title.
+
+The WU template carries the **six-field outcome shape** (per D046): persona link, trigger, walkthrough with failure paths, verification (= acceptance criteria), contracts produced, contracts consumed. For infrastructure WUs (build, publish, hardening, refactors) the persona/trigger/walkthrough fields are marked `N/A — infrastructure WU` and the rest is unchanged.
+
+Steps:
+
+1. **Determine the next available WU number.** Scan `docs/build/work-units/` and `docs/build/work-units/done/` for the maximum 3-digit prefix. The new number is max + 1.
+2. **Slugify the title** — lowercase, dashes for spaces, no special characters, max 60 chars.
+3. **Ask the operator: is this an outcome WU (a user-facing capability) or an infrastructure WU (build, publish, hardening, refactor)?** If outcome, walk the full six-field flow. If infrastructure, skip persona/trigger/walkthrough and ask for the technical artefacts directly.
+4. **Generate the file** at `docs/build/work-units/<NNN>-<slug>.md` from the template at `starter-kit/docs/build/work-units/001-template.md`. Replace placeholders with operator-supplied values.
+5. **Prompt the operator (outcome WU) for:**
+   - **Persona** — which P-NNN persona does this outcome serve? If none exists yet, prompt to run `persona-new` first. For paired outcomes (a customer-side outcome paired with an organiser-side one), capture both persona links.
+   - **Trigger** — the real-world event that makes this outcome necessary. Not a UI click; the event in the persona's life that created the need.
+   - **Outcome** — one paragraph. Apply 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. For each step, surface the **five failure-path injection points**: (1) what if the persona cannot complete this step in one sitting? (2) what if the information 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? Failure handling lives inline at each step, not as a separate section.
+   - **Acceptance criteria (= verification)** — 5 to 10 criteria, each phrased as an inspection that passes or fails. Apply the auditor's-question test: *"Can a third-party reader confirm 'yes, this is shipped' by inspection alone?"* Each criterion must be evaluable by a person looking at the running system, not inferred from technical state.
+   - **Contracts produced** — what this WU makes available to other WUs once it lands, in domain language. Not "a row in the bookings table"; "a confirmed booking record, linked to a specific customer and a specific event".
+   - **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, surface that gap immediately — file it as an open question or a new WU before this one starts.
+   - **Dependencies** — existing WU numbers this depends on (drawn from the contracts-consumed mapping; blank if none).
+   - **Decision implemented** — D-NNN if any (blank for none).
+   - **Forward-compatibility commitments** — if this WU's shape decisions affect later WUs, name them (per Pattern C).
+6. **Prompt the operator (infrastructure WU) for:**
+   - **Outcome** — single-sentence test as above.
+   - **Acceptance criteria** — same discipline.
+   - **Dependencies, decision implemented, forward-compatibility commitments** — same as outcome WU.
+   - **Persona / Trigger / Walkthrough** — auto-filled with `N/A — infrastructure WU.`
+   - **Contracts produced** — list the technical artefacts (e.g., "`@nusoft/nuwiki@0.1.4` published privately on npm").
+   - **Contracts consumed** — list the WUs whose output this WU builds on.
+7. **Apply the four quality traps** to the outcome before saving (operator review, not enforced by tooling today):
+   - **Vagueness:** could this outcome be implemented in more than one way that satisfies its wording but produces different user experiences?
+   - **Technical language:** does any part describe implementation rather than behaviour?
+   - **Happy path only:** does the walkthrough describe only what happens when everything goes right?
+   - **Kitchen sink:** does this WU try to do more than one thing? Could it be split into two outcomes with separate triggers and separate verification?
+
+   Surface any traps that fired and offer to rewrite the affected section before saving.
+8. **Add a row to `docs/build/work-units/_index.md`** in the appropriate phase section, with status `🟢 ready` (or `🔵 proposed` if dependencies aren't met).
+9. **If the WU cites a P-NNN, update that persona's `Used by WUs` list** to include the new WU.
+10. **Surface to the operator:**
+    - The new WU file path (clickable)
+    - The row added to `_index.md`
+    - Any inferred dependencies that should be confirmed
+    - Any quality traps that fired and were addressed (or deferred to a later refinement)
+
+**Discipline:** every acceptance criterion must be checkable by inspection, not described as a feature. *"The login page works"* is not an acceptance criterion. *"When a user submits a valid form, a row appears in `users` and an audit entry in `audit_events`"* is.
+
+**On the six-field shape (per D046):** the planning depth is what makes the catalogue durable. Skipping persona/trigger/walkthrough for an outcome WU produces a feature wearing an outcome-shaped name. Skipping contracts produced/consumed produces an outcome that integrates with nothing. The fields are not bureaucracy; each one closes a category of silent assumption the LLM teammate would otherwise fill in invisibly.
+
+If the operator pushes back on the auto-numbered slug or wants to adjust acceptance criteria, accommodate. The catalogue's strength is that the operator is in charge of the substance; the protocol just makes sure the substance is recorded properly.

package/templates/starter-kit/CLAUDE.md

@@ -0,0 +1,73 @@
+# {{PROJECT_NAME}} — Project Bootstrap for an LLM Teammate
+
+> This file is read at the start of every session. It is the entry point to the project memory.
+
+## What this project is
+
+{{PROJECT_NAME}} is {{PROJECT_TAGLINE}}.
+
+This project runs **the NuOS Build Method** — see [the canonical strategic note](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md) for the discipline, and [the harness contract](https://github.com/DarrenJCoxon/nuos/blob/main/docs/contracts/method-harness.md) for how the catalogue plugs into NuOS when wired.
+
+## At the start of every session — always
+
+Run the start-of-session protocol. The single command is:
+
+> "Run start-of-session"
+
+When asked to do this, follow [docs/build/START-OF-SESSION.md](docs/build/START-OF-SESSION.md) exactly. It will:
+
+1. Read [docs/build/STATE.md](docs/build/STATE.md) — the always-current project snapshot
+2. Read the most recent entry in [docs/build/sessions/](docs/build/sessions/)
+3. Identify the active work unit and read it in full
+4. Surface any blocking open questions or risks
+5. Confirm the state and propose the next concrete action
+
+## At the end of every session — always
+
+Run the end-of-session protocol. The single command is:
+
+> "Run end-of-session"
+
+When asked to do this, follow [docs/build/END-OF-SESSION.md](docs/build/END-OF-SESSION.md) exactly. It will:
+
+1. Update the active work unit's notes with what was done
+2. Update [docs/build/STATE.md](docs/build/STATE.md) to reflect current state
+3. Write a new session log entry in [docs/build/sessions/](docs/build/sessions/)
+4. Update any decisions, open questions, or risks that emerged
+5. Update the relevant `_index.md` files
+6. Verify nothing is lost
+
+If a session ends without the end-of-session protocol being run, work may be lost. Always run it.
+
+## The canonical operational plan lives in maps
+
+The `docs/build/maps/` directory holds the canonical operational plan for this project. **Story-level detail lives in maps**, not in fragmented planning docs. Each phase step in a map has an acceptance criterion and a verification gate (a specific file/grep/test in the target repo that proves the step is done).
+
+When a session starts, after reading STATE.md, identify the active map and read the active phase step. The verification gate names exactly what to run to know whether the step is complete. **Run the gate before doing more work.**
+
+If you find yourself writing *"likely"*, *"presumably"*, *"should be"* in code or planning text, **stop**. The hedge word indicates a verification step was skipped. Run the gate, replace the hedge with the result, then continue.
+
+**Before generating non-trivial implementation, produce at least two fundamentally different designs, evaluate each, then pick.** This is Ousterhout's "design it twice" applied to agent-led work. Agents satisfice on the first plausible idea; the structured comparison is what catches blind spots before they reach code. Record the alternatives in the WU's notes (or a D-NNN decision file).
+
+These are two of the five agentic-age patterns 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. The discipline isn't borrowed from agile; it's shaped for the specific failure modes of LLM-driven building.
+
+## The single rule
+
+> Every non-trivial action taken in the build must leave a durable trace in the catalogue.
+
+This is enforced by mechanism, not memory. The end-of-session protocol is the mechanism. Run it.
+
+## What never to do
+
+- Never make architectural decisions without recording them in [docs/build/decisions/](docs/build/decisions/)
+- Never start work outside the active work unit without recording why
+- Never proceed past a `🔴 blocked` work unit without first resolving its blocker
+- Never assume something is decided because it "must have been"; if the catalogue does not record it, surface it as a new open question
+
+## Where implementation work happens
+
+[Edit this section to describe where this project's code lives. If implementation is in-repo, say so. If it lives in sibling repos, list them and explain the relationship to this catalogue.]
+
+## The current state, at a glance
+
+The project state changes as work proceeds. The always-current snapshot is at [docs/build/STATE.md](docs/build/STATE.md). Read it.

package/templates/starter-kit/README.md

@@ -0,0 +1,116 @@
+# NuOS Catalogue Starter
+
+> A copy-this-and-go template for any project adopting **the NuOS Build Method**. Unzip into a fresh project, replace the `{{PROJECT_NAME}}` placeholders, commit, and the project is harness-ready. The starter kit gets you to a healthy catalogue in under thirty minutes; from there, the build pack `build-pack-nuos-method` (when it ships per WU 049) can wire up the NuOS runtime harness.
+
+## What this is
+
+The NuOS Build Method is described in [`nuos/docs/THE-NUOS-BUILD-METHOD.md`](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md). The method requires a structured catalogue: decisions, work units, sessions, risks, open questions, plus protocols for starting and ending every session.
+
+This starter kit is the **catalogue scaffold** — the directory tree, the template files, the `methodfile.json` manifest, and the protocols pre-populated with sensible defaults. It is the static, copy-and-edit form of a NuOS-method catalogue.
+
+The starter kit is *not* the harness. The harness is when NuVector indexes the catalogue, NuFlow runs the protocols, and NuWiki compiles the snapshots. Until you wire the harness, the catalogue runs on operator discipline and an LLM teammate. That is sufficient for a small team running the method on its own; harnessing comes when scale demands it.
+
+## What's in here
+
+```
+.
+├── README.md                          # this file
+├── methodfile.json                    # the manifest the harness reads
+├── CLAUDE.md                          # session-start instruction for an LLM teammate
+└── docs/
+    ├── philosophy/                    # the project's architectural commitments — narrative
+    │   └── _index.md
+    ├── contracts/                     # type-stable surfaces — what each part of the project promises
+    │   └── _index.md
+    ├── guides/                        # the persuasion layer — investor, customer, partner-readable
+    │   └── _index.md
+    └── build/
+        ├── STATE.md                   # always-current snapshot — read this first every session
+        ├── START-OF-SESSION.md        # the protocol — every session starts by following this
+        ├── END-OF-SESSION.md          # the protocol — every session ends by following this
+        ├── maps/                      # the canonical operational plan(s) — story-level detail with verification gates
+        │   ├── _index.md
+        │   └── 01-template.md
+        ├── decisions/
+        │   ├── _index.md
+        │   └── D001-template.md
+        ├── work-units/
+        │   ├── _index.md
+        │   └── 001-template.md
+        ├── sessions/
+        │   ├── _index.md
+        │   └── 0000-00-00-template.md
+        ├── risks/
+        │   └── _index.md
+        └── open-questions/
+            └── _index.md
+```
+
+## Epistemic discipline — the central commitment for agent-led building
+
+Method note (post-Phase-3 evolution; see [`THE-NUOS-BUILD-METHOD.md`](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md)). The catalogue's discipline isn't borrowed from agile — it's shaped for the specific failure modes of LLM-driven building. The five load-bearing patterns:
+
+1. **Verification gates anchored in target-repo files** (in maps; per phase step) — exact targets so the agent can't generate plausible-looking work that misses reality
+2. **Maps as single canonical plan** — single entry point so the agent (or fresh session) can't act on partial context
+3. **Contracts as immutable truth** — fixed reference points that turn agent reasoning into citation rather than improvisation
+4. **Hedge words as stop signal** — "likely", "presumably", "should be" indicate a verification step was skipped; replace with the grep/test/file-read result before the work ships
+5. **Design alternatives before implementation** — Ousterhout's "design it twice"; for any non-trivial architectural choice, produce at least two fundamentally different designs, evaluate, then pick (or hybrid) before generating implementation. Agents satisfice on the first plausible idea; structured comparison catches blind spots before they reach code
+
+These appear throughout the catalogue. The maps directory is where (1), (2), and (5) are concretely enforced. Pattern (3) is enforced by `docs/contracts/`. Pattern (4) is enforced by the operator's discipline + memory rules.
+
+## How to adopt — the thirty-minute path
+
+1. **Copy the tree** into your project's repo. Either paste these files directly into a fresh project root, or use this directory as a git template.
+
+2. **Replace the placeholders.** Search-and-replace across the tree:
+   - `{{PROJECT_NAME}}` — your project's name (e.g., "Acme")
+   - `{{PROJECT_TAGLINE}}` — one-sentence description
+   - `{{PROJECT_DOMAIN}}` — the domain you're working in (e.g., "education", "healthcare")
+   - `{{PROJECT_ROLE}}` — `consumer` if you're building on top of NuOS; `standalone` if you're using the method without the trifecta
+   - `{{TODAY}}` — today's date in `YYYY-MM-DD` format
+
+3. **Commit the catalogue.** Single first commit. Use the message:
+   ```
+   Adopt the NuOS Build Method — catalogue scaffold in place
+   ```
+
+4. **Write your first decision.** Open `docs/build/decisions/D001-template.md`, rename it to match your first real architectural commitment (e.g., `D001-we-are-building-on-postgres.md`), fill it in. Update `docs/build/decisions/_index.md`.
+
+5. **Write your first work unit.** Open `docs/build/work-units/001-template.md`, rename it (e.g., `001-postgres-schema-bootstrap.md`), fill it in. Update `docs/build/work-units/_index.md`.
+
+6. **Update STATE.md.** Replace the placeholder content with your project's actual current state (Phase 0, no work units shipped, first decision in flight).
+
+7. **Run the start-of-session protocol.** Tell your LLM teammate: *"Run start-of-session"*. It should read STATE.md, the most recent session log, and the active work unit. (At first start, there is no session log — the protocol notes that and prompts for the first one.)
+
+8. **Do work, then run end-of-session.** When you stop, tell your LLM teammate: *"Run end-of-session"*. It will write a session log entry, update STATE.md, update the work-unit notes, and update the relevant `_index.md` files.
+
+That is the loop. Every session opens with start-of-session. Every session closes with end-of-session. The catalogue accumulates. Nothing is lost.
+
+## What you do not need to do
+
+- **Do not write a `philosophy/` document on day one.** The philosophy emerges as you commit decisions. By decision 10, patterns are clear; that is when the philosophy doc becomes worth writing.
+- **Do not write `contracts/` documents on day one.** Contracts are how stable surfaces communicate. Until you have stable surfaces, you have no contracts to write.
+- **Do not write guides on day one.** Guides are the persuasion layer; you write them when you need to persuade somebody (an investor, a customer, a regulator). Until then, they're empty `_index.md` files.
+
+The catalogue's strength is that it grows as you need it. Day one is just the scaffold and the first decision and the first work unit. That is enough.
+
+## When to wire the harness
+
+When the catalogue gets big enough that grep starts being slow, when manual maintenance of STATE.md drifts, when the project starts producing confidential material that needs role-aware redaction — that is the moment to wire the NuOS runtime harness. The thresholds are roughly:
+
+- **NuVector** when the catalogue has more than 50 entries (decisions + WUs + session logs combined)
+- **NuFlow** when the protocols are being run more than once a day (multiple operators or multiple sessions per day)
+- **NuWiki** when STATE.md is being hand-edited and is drifting from reality
+- **The deidentifier subsystem** from day one if your domain is regulated (clinical, legal, statutory)
+
+The build pack `build-pack-nuos-method` (per WU 049 in the NuOS catalogue) automates the wiring when it ships. Until then, the markdown-only catalogue is fully functional — the method works without the harness; the harness just makes it scale.
+
+## License
+
+[choose a license — MIT or Apache-2.0 are typical]
+
+## Pointers
+
+- [The NuOS Build Method — durable strategic note](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md) — what this kit operationalises
+- [The Method Harness contract](https://github.com/DarrenJCoxon/nuos/blob/main/docs/contracts/method-harness.md) — how the catalogue plugs into NuOS
+- [NuOS itself](https://github.com/DarrenJCoxon/nuos) — the worked example; every claim the method makes is demonstrated by NuOS's own catalogue

package/templates/starter-kit/docs/build/END-OF-SESSION.md

@@ -0,0 +1,62 @@
+# End-of-Session Protocol
+
+> Run this every time a session ends. The point is to commit the session's results into the catalogue before context is lost. **If a session ends without this protocol, work is lost.** This is the single load-bearing ritual that prevents the project from drifting.
+
+## Steps
+
+1. **Update the active work unit's notes section.** Append a dated entry describing:
+   - What was attempted
+   - What worked
+   - What did not work and why
+   - What was learned (if any pattern is starting to emerge)
+   - What the next concrete action should be
+
+   The auditor's-question test: *"Could a third-party auditor read this entry and answer 'why was this done and what evidence justifies the next step?' without contacting the team?"* If yes, the entry is sufficient.
+
+2. **Update [`STATE.md`](STATE.md)** to reflect the session's outcome:
+   - Refresh "What is currently in flight"
+   - Refresh "What just shipped" if anything completed
+   - Refresh "What is next"
+   - Update the work-units-in-flight table
+   - Update the decisions-made-recently table if any decisions landed
+   - Update the "Last updated" date
+
+3. **Write a new session log entry** in [`sessions/`](sessions/) named `YYYY-MM-DD-short-description.md`. The entry should include:
+   - **What this session was about** — one paragraph framing
+   - **What was done** — chronological narrative; reference any commits
+   - **Decisions that surfaced** — link to D-NNN files
+   - **Open questions raised** — link to Q-NNN files
+   - **Risks identified** — link to R-NNN files
+   - **What's next** — the concrete next action (mirrors STATE.md "What is next")
+
+4. **Update the relevant `_index.md` files**:
+   - If a new D-NNN landed, add it to `decisions/_index.md`
+   - If a new WU landed or a WU's status changed, update `work-units/_index.md`
+   - Always add the new session log entry to `sessions/_index.md`
+   - If a new Q-NNN or R-NNN landed, update those indexes
+
+5. **Verify nothing is lost.** Read the session log entry back and check:
+   - Did anything happen that is not captured somewhere?
+   - Are there cross-references that should exist? (a WU should link to the decision that justifies it; a session should link to the WU it advanced)
+   - Are the dates right?
+
+6. **Commit.** Single commit, message format:
+   ```
+   end-of-session: {{TODAY}} — [one-line summary of session outcome]
+   ```
+
+## What this protocol guarantees
+
+- No work happens that is not recorded in the catalogue
+- Every session has a replay-grade trace; a fresh session (or a fresh operator) can pick up exactly where this one left off
+- The catalogue compounds rather than drifts
+
+## What to do if a session was unusually short or unusually long
+
+- **Short session (<30 min, no work landed):** Still write a session entry. It can be brief: "explored X, decided not to start; reason: Y." This counts as a non-trivial action because it consumed a decision-making slot.
+- **Long session (multiple WUs touched, multiple decisions):** Write one session entry covering all of it. If the session is genuinely two sessions worth of work that happened in one sitting, write two entries with appropriate timestamps.
+
+## What to do if you cannot run the full protocol
+
+- **You're rushing to stop:** at minimum, write one paragraph into the active WU's notes section saying *"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.
+- **You're handing off mid-task to another operator:** do run the full protocol, even if the work is incomplete. The next operator needs the current truth.

package/templates/starter-kit/docs/build/START-OF-SESSION.md

@@ -0,0 +1,33 @@
+# Start-of-Session Protocol
+
+> Run this every time a session begins. The point is to absorb the project state in under sixty seconds and propose a concrete next action. If this takes more than two minutes to follow, the catalogue is unhealthy — fix that first.
+
+## Steps
+
+1. **Read [`STATE.md`](STATE.md)** in full. It is the single source of "where are we right now?"
+
+2. **Read the most recent session log entry** in [`sessions/`](sessions/). The directory is sorted newest-last; the most recent entry is the last one chronologically. If there is no session log yet, this is the first session — note that and proceed.
+
+3. **Read the active work unit** named in STATE.md. Read it in full, including the notes / log section at the bottom. The notes capture what the previous session learned that has not yet been generalised into a decision.
+
+4. **Skim `open-questions/_index.md` and `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)
+   - What the active work unit is and what its current status is (one sentence)
+   - Any blockers (one bullet each)
+   - The next concrete action (one bullet)
+
+6. **Confirm the next action with the operator before starting 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.
+
+## What this protocol guarantees
+
+- No session begins without a clear understanding of where the project stands
+- No work happens outside an acknowledged work unit (or with an explicit acknowledgement of why it is outside)
+- Blockers are surfaced before work starts, not after work has been wasted on something that cannot ship
+
+## What to do if something is missing
+
+- **STATE.md is out of date.** Note this to the operator immediately. Likely the previous end-of-session was skipped or incomplete. Check the latest session log and the latest WU notes for what the truth actually is.
+- **No active work unit named.** Note this. Likely a phase boundary just closed and the next WU has not been picked yet. Surface the candidate WUs and ask the operator to pick.
+- **Blocking open questions.** Stop. Surface them. Do not start work that depends on an unresolved question.