@nusoft/nuos-build-catalogue 0.9.0 → 0.10.1

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,26 @@
+# Philosophy
+
+> The architectural commitments of {{PROJECT_NAME}}, in narrative form. Where decisions (D-NNN) are point-in-time choices, philosophy documents are *the story of why the project is shaped this way at all*. They are read by anyone integrating with the project, by investors, and by future operators trying to understand the spirit of the system.
+
+## When to write a philosophy document
+
+Not on day one. Philosophy emerges as decisions accumulate. By around D010 — perhaps D020 — patterns are visible across decisions: a recurring concern, a consistent prioritisation, an architectural commitment that was never written down because every decision implied it.
+
+That is when a philosophy doc becomes worth writing. One short narrative-form document per cross-cutting commitment. Examples from NuOS: *separation of personal data and AI inference*, *intent-typed boundaries*, *PII isolation*.
+
+## Index
+
+| Doc | Topic |
+| --- | --- |
+| _none yet — philosophy emerges as decisions accumulate_ | |
+
+## Pattern
+
+Each philosophy doc:
+- Names the commitment in present tense
+- Gives the historical context — what was wrong with the alternatives
+- States the architectural implications
+- Lists the decisions that implement it
+- Lists the contracts and surfaces it constrains
+
+Philosophy docs are the *upstream* of decisions. A new decision should be checkable against the philosophy: is this consistent with the project's commitments? If not, either the decision is wrong or the philosophy needs revisiting.

package/templates/starter-kit/methodfile.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://nusoft.dev/schemas/methodfile/v1.json",
+  "method": {
+    "version": "1.0",
+    "lastValidatedAt": "{{TODAY}}"
+  },
+  "project": {
+    "name": "{{PROJECT_NAME}}",
+    "tagline": "{{PROJECT_TAGLINE}}",
+    "domain": "{{PROJECT_DOMAIN}}"
+  },
+  "catalogue": {
+    "root": "docs/build/",
+    "registers": {
+      "decisions": "decisions/",
+      "workUnits": "work-units/",
+      "sessions": "sessions/",
+      "risks": "risks/",
+      "openQuestions": "open-questions/"
+    },
+    "snapshot": "STATE.md",
+    "protocols": {
+      "startOfSession": "START-OF-SESSION.md",
+      "endOfSession": "END-OF-SESSION.md"
+    },
+    "supportingLayers": {
+      "philosophy": "../philosophy/",
+      "contracts": "../contracts/",
+      "guides": "../guides/"
+    }
+  },
+  "harness": {
+    "wired": false,
+    "runtime": {
+      "nuvector": null,
+      "nuflow": null,
+      "nuwiki": null
+    },
+    "packs": {
+      "method": null
+    },
+    "documentTypes": []
+  },
+  "domain": {
+    "type": "standard",
+    "confidentialityRequired": false,
+    "auditRetentionMonths": 0
+  },
+  "ecology": {
+    "role": "{{PROJECT_ROLE}}",
+    "parentCatalogue": null,
+    "siblingCatalogues": []
+  }
+}