@hippo-digital/hippocampus 1.0.0-rc.1 → 1.0.0-rc.2

package/CHANGELOG.md

@@ -47,9 +47,9 @@ journeys and screens they justify, rendered as a viewer inside your prototype.
 
 ### Docs and skills
 
-- The 16 guides are served at `{basePath}/docs`, version-matched to the
+- The 13 guides are served at `{basePath}/docs`, version-matched to the
   installed package rather than copied into your repo.
-- `skills install` copies the 19 agent skills into `.github/skills` with content
+- `skills install` copies the 20 agent skills into `.github/skills` with content
   hashes, so an upgrade can tell a stale copy from one your team has edited.
 - `init` reports research material in `hippocampus/source-artefacts/` rather
   than silently committing it; `--private-artefacts` gitignores it.

package/docs/agent-roadmap.md

@@ -206,8 +206,8 @@ The repo now has enough agent-facing documentation that overlap will become a ma
 - Do not make skills promote drafts automatically.
 - Do not treat generated artefacts as canonical source data.
 - Do not reintroduce active prompt-first workflows.
-- Do not port NCRS clinical content or FHIR-heavy workflows unless Hippocampus actually needs them.
-- Do not add a huge NHS component reference unless repeated component mistakes justify it.
+- Do not port a host project's domain content or integration-heavy workflows unless Hippocampus actually needs them.
+- Do not add a huge component reference unless repeated component mistakes justify it.
 
 ## Recommended Next Commits
 

package/docs/design-actions-and-decisions.md

@@ -29,14 +29,14 @@ along; it was only ever used for five notes about the prototype spike.
 ## Why the rejected options matter
 
 The accepted option ends up in production, where anyone can see it. The rejected
-ones are the ones that get asked about eighteen months later — "why didn't NCRS
+ones are the ones that get asked about eighteen months later — "why didn't we
 just do the obvious thing?" — and by then the answer lives in one person's memory
 or in a meeting no one recorded. A rejected decision record with a `consequence`
 answers it.
 
 ## The workbook
 
-`hippocampus/templates/ncrs-insight-design-action-tracker.xlsx`, one copy per round.
+`hippocampus/templates/insight-design-action-tracker.xlsx`, one copy per round.
 Three sheets that reference each other by ID:
 
 | Sheet | One row per | Key columns |

package/docs/research-source-file-conventions.md

@@ -7,8 +7,9 @@ is a change to how a file is *authored or named*, not a change to the research
 itself. Each convention exists because the ingestion pipeline currently loses
 something real without it.
 
-The reference corpus behind this guidance is the NCRS user research drive:
-599 files, 2.3 million extractable words, rounds 4 to 16.
+This guidance was derived from a real user research drive of 599 files and
+2.3 million extractable words spanning thirteen rounds, so the conventions are
+the ones that survived contact with a messy corpus rather than a tidy example.
 
 ## The one thing that matters most
 

package/lib/docs.js

@@ -15,8 +15,7 @@ const packagePaths = require('./package-paths')
 // a stale copy from an edited one.
 
 const TITLE_OVERRIDES = {
-  'hippocampus-for-designers-and-researchers': 'Hippocampus for designers and researchers',
-  'gp-connect-real-data-to-production': 'GP Connect: real data to production'
+  'hippocampus-for-designers-and-researchers': 'Hippocampus for designers and researchers'
 }
 
 function slugOf (filename) {

package/lib/schema.js

@@ -172,7 +172,7 @@ const ScreenSchema = z.object({
   purpose: nonEmptyString,
   needIds: z.array(id).min(1),
   components: stringList,
-  // A screen in the real NCRS prototype rather than in this viewer. The
+  // A screen in the host project rather than in this viewer. The
   // knowledge base models the service, not only the screens this repo happens
   // to render, so the route smoke test skips these instead of failing on them.
   external: z.boolean().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hippo-digital/hippocampus",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.2",
   "description": "A design-knowledge base for NHS Prototype Kit projects: research, insights, needs, journeys and screens, traceable end to end.",
   "license": "MIT",
   "main": "index.js",

package/scripts/import-design-actions.js

@@ -179,7 +179,7 @@ function main () {
 
 function rows (workbook, sheetName) {
   if (!workbook.sheetFiles.has(sheetName)) {
-    throw new Error(`The workbook has no "${sheetName}" sheet. It has: ${[...workbook.sheetFiles.keys()].join(', ')}. Start from hippocampus/templates/ncrs-insight-design-action-tracker.xlsx.`)
+    throw new Error(`The workbook has no "${sheetName}" sheet. It has: ${[...workbook.sheetFiles.keys()].join(', ')}. Start from the blank tracker that ships with the package: node_modules/@hippo-digital/hippocampus/templates/insight-design-action-tracker.xlsx`)
   }
   const grid = readSheetGrid(workbook, sheetName)
   const header = grid.find((r) => r && r.some(Boolean)) || []

package/scripts/init.js

@@ -87,7 +87,7 @@ function planKnowledgeBase (root) {
   const id = kebab(dirName) || 'prototype'
   const name = dirName
   plan('hippocampus/source/project.json and an empty knowledge base', () => {
-    for (const dir of ['source', 'inbox/project', 'inbox/research', 'imports/project', 'imports/research', 'manifests']) {
+    for (const dir of ['source', 'inbox/personas', 'inbox/project', 'inbox/research', 'imports/project', 'imports/research', 'manifests']) {
       fs.mkdirSync(path.join(root, 'hippocampus', dir), { recursive: true })
     }
     fs.writeFileSync(projectPath, JSON.stringify({

package/scripts/link-insights-to-needs.js

@@ -28,23 +28,47 @@ const { createContextOrExit } = require('../lib/context')
 const ctx = createContextOrExit()
 const { knowledgeSourceDir } = ctx.paths
 
-// The tracker names user groups; the knowledge base names users.
-const GROUP_TO_USERS = [
-  [/safeguarding/i, ['admin-safeguarding', 'clinical-safeguarding']],
-  [/urgent\s*(&|and)\s*emergency|u&e/i, ['clinical-advisor', 'clinical-paramedic', 'clinical-ed-consultant']],
-  [/child health/i, ['admin-child-health']],
-  [/data quality/i, ['admin-data-quality']],
-  [/policy admin|overseas|funding|chargeable/i, ['admin-overseas-visitor-manager']],
-  [/pharmac/i, ['clinical-ed-consultant']],
-  [/screen(ing)? admin/i, ['admin-screening']],
-  [/booking|reception/i, ['admin-booking-and-reception']],
-  [/midwife|maternity/i, ['clinical-midwife']],
-  [/nurs/i, ['clinical-nursing']],
-  [/gp|out.of.hours/i, ['clinical-out-of-hours-gp']]
-]
-
-const STOP = new Set(`a an and are as at be but by can for from has have i if in is it its me my need needs not of on or our so that the their them then there these they this to use used user users want we what when where which who will with would you your also more most only other same some such than very
-nhs ncrs patient patients record records search searching system systems data information staff people person`.split(/\s+/))
+// The tracker names user groups; the knowledge base names users. Which group
+// maps to which user is a fact about one project's records, not something this
+// package can know, so it is declared in hippocampus.config.json:
+//
+//   "linkInsights": {
+//     "affectsPattern": "Affects ([^.]+)\\.",
+//     "userGroups": [
+//       { "match": "safeguarding", "users": ["admin-safeguarding"] }
+//     ]
+//   }
+//
+// There is deliberately no default. A built-in table would match one project's
+// user IDs and silently match nothing for everyone else, which reads as "your
+// data is wrong" rather than "this is not configured".
+const LINK_CONFIG = ctx.config.linkInsights || {}
+
+const GROUP_TO_USERS = (LINK_CONFIG.userGroups || []).map((entry, i) => {
+  if (!entry || !entry.match || !Array.isArray(entry.users)) {
+    throw new Error(
+      `linkInsights.userGroups[${i}] in ${ctx.configPath} needs a "match" pattern ` +
+      'and a "users" array of user ids.'
+    )
+  }
+  return [new RegExp(entry.match, 'i'), entry.users]
+})
+
+// The affected groups are read out of the insight summary. The sentence shape
+// comes from whichever importer wrote it, so it is configurable too.
+const AFFECTS_PATTERN = new RegExp(LINK_CONFIG.affectsPattern || 'Affects ([^.]+)\\.')
+
+// Generic English stopwords only. Domain vocabulary is deliberately NOT
+// listed here: a term that is noise in one service is the whole point in
+// another ("records" is filler in a clinical record service and the subject
+// matter in a records-management one). Projects add their own via
+// `linkInsights.stopwords` in hippocampus.config.json, which is merged in
+// below rather than replacing this list.
+const STOP = new Set(`a an and are as at be but by can for from has have i if in is it its me my need needs not of on or our so that the their them then there these they this to use used user users want we what when where which who will with would you your also more most only other same some such than very`.split(/\s+/))
+
+for (const word of (ctx.config.linkInsights && ctx.config.linkInsights.stopwords) || []) {
+  STOP.add(String(word).toLowerCase())
+}
 
 function tokens (text) {
   return (String(text).toLowerCase().match(/[a-z][a-z-]{2,}/g) || [])
@@ -75,12 +99,25 @@ function main () {
   const links = []
   const report = []
 
+  // Say this once, loudly, rather than only in per-insight reasons. Without a
+  // mapping every insight is skipped, and a run that scores nothing should not
+  // look like a run that found nothing.
+  if (!GROUP_TO_USERS.length && insights.length) {
+    console.warn(
+      `No linkInsights.userGroups mapping in ${ctx.configPath}.\n` +
+      'Insights are matched only against needs belonging to the users a round ' +
+      'affected, so with no mapping nothing can match and every insight will be ' +
+      'skipped. Add one entry per user group, e.g.\n' +
+      '  "linkInsights": { "userGroups": [{ "match": "safeguarding", "users": ["admin-safeguarding"] }] }\n'
+    )
+  }
+
   for (const insight of insights) {
     // Round 16's tracker names the affected user groups on every row. Other
     // rounds have no such column, so the candidate users come from who actually
     // took part in that round - an insight cannot bear on the needs of a user
     // group that was not in the room.
-    const affects = (insight.summary.match(/Affects ([^.]+)\./) || [])[1] || ''
+    const affects = (insight.summary.match(AFFECTS_PATTERN) || [])[1] || ''
     const users = new Set(
       GROUP_TO_USERS.filter(([re]) => re.test(affects)).flatMap(([, ids]) => ids)
     )
@@ -91,7 +128,13 @@ function main () {
         .join(' | ')
       for (const [re, ids] of GROUP_TO_USERS) if (re.test(roles)) for (const id of ids) users.add(id)
     }
-    if (!users.size) { report.push({ insight, users: 0, matched: [], reason: 'no user groups recorded and no participants in this round' }); continue }
+    if (!users.size) {
+      const reason = GROUP_TO_USERS.length
+        ? 'no user groups recorded and no participants in this round'
+        : `no linkInsights.userGroups mapping in ${path.basename(ctx.configPath)} - nothing can be matched until user groups are mapped to user ids`
+      report.push({ insight, users: 0, matched: [], reason })
+      continue
+    }
 
     const query = new Set(tokens(`${insight.title} ${insight.summary}`))
     const candidates = needs.filter((n) => users.has(n.userId))

package/scripts/smoke-routes.js

@@ -76,7 +76,7 @@ function buildRoutes (basePath, knowledge) {
   }
 
   for (const screen of knowledge.screens) {
-    // Screens marked external live in the real NCRS prototype, not here, so
+    // Screens marked external live in another repo, not here, so
     // this app has nothing to serve at their route.
     if (screen.external) continue
     routes.add(screen.route)

package/scripts/triage-research-corpus.js

@@ -10,7 +10,7 @@
  * Hippocampus schema, and writes a ranked review pack. It never writes to
  * hippocampus/source and never promotes anything.
  *
- *   node scripts/triage-research-corpus.js --source "/path/to/folder" --topic ncrs-ur
+ *   node scripts/triage-research-corpus.js --source "/path/to/folder" --topic user-research
  */
 
 const fs = require('fs')

package/skills/ingest-user-personas.skill.md

@@ -0,0 +1,77 @@
+---
+id: ingest-user-personas
+title: Ingest user personas
+purpose: Turn persona documents into user records, the needs they state, and the evidence that backs both.
+owners:
+  - ingestion-curator
+  - knowledge-builder
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - node_modules/@hippo-digital/hippocampus/docs/research-source-file-conventions.md
+  - hippocampus/inbox/personas/
+  - hippocampus/source/users.json
+  - hippocampus/source/needs.json
+  - hippocampus/source/evidence.json
+  - hippocampus/source/assumptions.json
+edits:
+  - hippocampus/source/users.json
+  - hippocampus/source/needs.json
+  - hippocampus/source/evidence.json
+  - hippocampus/source/assumptions.json
+  - hippocampus/source/relationships.json
+runs:
+  - npx hippocampus validate
+outputs:
+  - One user record per persona document
+  - One evidence record per source document, with a resolvable sourcePath
+  - Needs the document actually states, each linked to that evidence
+  - Assumptions naming every field the schema required but the document did not state
+guardrails:
+  - Every user, need and responsibility must come from the document. If it is not in the text, it does not go in the record.
+  - Do not fill accessNeeds or priority from judgement without recording an assumption - the schema requires both, so a guess is indistinguishable from a finding.
+  - Do not create needs the persona document does not state. A thin persona yields a user with few needs, which is the honest result.
+  - One user per persona. Do not merge two documents into a composite user, and do not split one into several.
+  - Record the document's own filename in evidence.sourcePath. If the working copy will be deleted, the name is the only way back to the original.
+acceptance:
+  - Every new user has a description and at least one responsibility taken from the document.
+  - Every new need has a userId, a statement from the document, and at least one evidenceId.
+  - Every persona document has exactly one evidence record with a sourcePath.
+  - Every schema-required field the document did not state has an assumption naming it.
+  - npx hippocampus validate passes.
+---
+
+# Ingest user personas
+
+## Use when
+- A project has persona documents and no user records yet. This is the first ingestion step: needs, scenarios, journeys and screens all reference users, so nothing else can be added until users exist.
+- New personas join an existing set after a later round of research.
+
+## Workflow
+
+1. Put the documents in `hippocampus/inbox/personas/` and read each one in full before writing anything.
+2. For each document, add one **evidence** record: `sourceType: user persona`, a summary of what the document is, `confidence`, and `sourcePath` set to the document's own filename.
+3. Add one **user** per document. `label` and `description` come from the document. `responsibilities` are the ones it lists - do not generalise them into a tidier set.
+4. Add the **needs the document states**, each with `userId`, a statement in the document's own terms, and `evidenceIds` pointing at that document's evidence record.
+5. Add `has-need` relationships from the user to each need.
+6. Record an **assumption** for every field the schema forced you to fill that the document did not state. See below.
+7. Run `npx hippocampus validate` and fix what it reports.
+
+## The two fields that force a guess
+
+The schema requires both of these, so neither can be left empty and an unstated value looks exactly like a researched one. When the document is silent, fill it and say so.
+
+- **`Need.priority`** is an enum with no "unknown". Persona documents rarely rank needs. Default to `medium` and add one assumption covering the whole import: *"Needs imported from persona documents carry priority medium because the documents do not state priority. Priorities need a team decision before they sequence design work."*
+- **`User.accessNeeds`** requires at least one entry. If the document does not cover access needs, say so in the field itself rather than inventing one, and add an assumption recording that the personas did not cover accessibility.
+
+## Guardrails
+
+- Every user, need and responsibility must come from the document. If it is not in the text, it does not go in the record.
+- Do not fill `accessNeeds` or `priority` from judgement without recording an assumption.
+- Do not create needs the persona document does not state. A thin persona yields a user with few needs, which is the honest result.
+- One user per persona. Do not merge two documents into a composite user, and do not split one into several.
+- Record the document's own filename in `evidence.sourcePath`.
+
+## Finish
+
+- Run `npx hippocampus validate`.
+- Report: users added, needs added per user, evidence records created, assumptions recorded and what each one covers, and any persona document that yielded no needs - that last one is a finding about the document, not a failure of the import.

package/skills/record-design-decision.skill.md

@@ -8,7 +8,7 @@ owners:
 reads:
   - node_modules/@hippo-digital/hippocampus/docs/design-actions-and-decisions.md
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
-  - hippocampus/templates/ncrs-insight-design-action-tracker.xlsx
+  - node_modules/@hippo-digital/hippocampus/templates/insight-design-action-tracker.xlsx
 edits:
   - hippocampus/source/design-actions.json
   - hippocampus/source/decisions.json
@@ -37,7 +37,7 @@ acceptance:
 - Options have been weighed against an action and one has been chosen.
 
 ## Workflow
-1. Take a copy of `hippocampus/templates/ncrs-insight-design-action-tracker.xlsx` for the round.
+1. Take a copy of `node_modules/@hippo-digital/hippocampus/templates/insight-design-action-tracker.xlsx` for the round.
 2. Fill the Design Actions sheet: one row per direction, listing the insight IDs that prompted it. An action is an open brief, not a solution.
 3. Fill the Decisions sheet: one row per option, all `proposed` while the team decides.
 4. When the team decides, set one option to `accepted` and the rest to `rejected`, and write the `consequence` of the accepted one.

package/skills/skills.json

@@ -218,6 +218,32 @@
         "npx hippocampus promote project-context -- --dry-run passes."
       ]
     },
+    {
+      "id": "ingest-user-personas",
+      "title": "Ingest user personas",
+      "purpose": "Turn persona documents into user records, the needs they state, and the evidence that backs both.",
+      "file": "ingest-user-personas.skill.md",
+      "owners": [
+        "ingestion-curator",
+        "knowledge-builder"
+      ],
+      "runs": [
+        "npx hippocampus validate"
+      ],
+      "outputs": [
+        "One user record per persona document",
+        "One evidence record per source document, with a resolvable sourcePath",
+        "Needs the document actually states, each linked to that evidence",
+        "Assumptions naming every field the schema required but the document did not state"
+      ],
+      "acceptance": [
+        "Every new user has a description and at least one responsibility taken from the document.",
+        "Every new need has a userId, a statement from the document, and at least one evidenceId.",
+        "Every persona document has exactly one evidence record with a sourcePath.",
+        "Every schema-required field the document did not state has an assumption naming it.",
+        "npx hippocampus validate passes."
+      ]
+    },
     {
       "id": "ingest-research-round",
       "title": "Ingest research round",

package/docs/agentic-patterns-to-port.md

@@ -1,273 +0,0 @@
-# Agentic Patterns To Port From NCRS
-
-Source reviewed:
-
-- `/Users/mattfielding/clawd/projects/ncrs-prototype-agentic/.github`
-- `/Users/mattfielding/clawd/projects/ncrs-prototype-agentic/docs`
-- `/Users/mattfielding/clawd/projects/ncrs-prototype-agentic/artefacts`
-
-## Recommendation
-
-Port the operating model, not the NCRS clinical content.
-
-The strongest transferable pattern is a Copilot-discoverable agent workspace:
-
-- `.github/copilot-instructions.md`
-- `.github/instructions/*.instructions.md`
-- `.github/legacy/prompts/*.prompt.md`
-- `.github/agents/*.md`
-- `docs/` for architecture and workflow rules
-- `artefacts/` for generated outputs, screenshots and audits
-
-The knowledge base repo already has archived prompts in `.github/legacy/prompts`. The next useful work is to keep repo-wide Copilot instructions, focused custom agents and the portable skill catalog aligned.
-
-## High-value ports
-
-### 1. Copilot instructions
-
-NCRS has `.github/copilot-instructions.md` loaded into every Copilot chat.
-
-Port as:
-
-```text
-.github/copilot-instructions.md
-```
-
-Purpose:
-
-- tell Copilot this is an NHS Prototype Kit knowledge base
-- define source model rules
-- require validation after source edits
-- require NHS Prototype Kit conventions
-- forbid real patient data
-- prefer source-model changes over hard-coded page changes
-
-Why it matters:
-
-Prompts are optional. Copilot instructions are ambient. They reduce bad default behaviour.
-
-### 2. Focused custom agents
-
-NCRS consolidated overlapping agents into four roles:
-
-- `@prototype-builder`
-- `@screenshot-runner`
-- `@accessibility-tester`
-- `@workflow-orchestrator`
-
-Port as:
-
-```text
-.github/agents/README.md
-.github/agents/knowledge-builder.md
-.github/agents/prototype-builder.md
-.github/agents/screenshot-runner.md
-.github/agents/accessibility-tester.md
-.github/agents/workflow-orchestrator.md
-```
-
-Adaptation:
-
-- add `@knowledge-builder` because this repo's primary product is source-model maintenance
-- keep `@prototype-builder` for routes/views/screens
-- keep `@screenshot-runner` and `@accessibility-tester` for review loops
-- keep `@workflow-orchestrator` to coordinate build → validate → screenshot → accessibility → summary
-
-### 3. Instruction files
-
-NCRS uses `.github/instructions/*.instructions.md` for auto-attached guidance.
-
-Port a smaller set:
-
-```text
-.github/instructions/knowledge-source.instructions.md
-.github/instructions/nhs-prototype-kit.instructions.md
-.github/instructions/nhs-frontend.instructions.md
-```
-
-Do not copy the huge generated NHS component reference yet. It is useful but heavy. Start with concise instructions and add component reference later if Copilot needs it.
-
-### 4. Agent workflow docs
-
-NCRS has:
-
-- `docs/AGENT-WORKFLOW.md`
-- `docs/PROMPT-ARCHITECTURE-GUARDRAILS.md`
-- `docs/CUSTOM-AGENTS-USAGE.md`
-
-Port as:
-
-```text
-docs/agent-workflow.md
-docs/prompt-architecture-guardrails.md
-docs/custom-agents-usage.md
-```
-
-Adaptation:
-
-- prioritise knowledge base source edits
-- require `npx hippocampus validate`
-- define when to add source records versus Nunjucks screens
-- define expected output locations
-- require delivery summaries after orchestrated runs
-
-### 5. Artefact structure
-
-NCRS separates generated outputs under `artefacts/`.
-
-Port as:
-
-```text
-artefacts/
-  scenarios/
-  screenshots/
-  accessibility/
-  delivery-summaries/
-  generated-docs/
-```
-
-Keep `hippocampus/source` as the source of truth. Use `artefacts/` only for generated/derived outputs and review evidence.
-
-### 6. Screenshot and accessibility loops
-
-NCRS has dedicated screenshot and accessibility agent outputs:
-
-- `artefacts/screenshots/<YYYY-MM-DD>/manifest.md`
-- `artefacts/accessibility/`
-
-Port this because the knowledge base needs reviewable artefacts, not just running pages.
-
-First implementation can be documentation-only agents. Later add scripts if needed.
-
-### 7. Staged prompt workflow
-
-NCRS uses staged prompts:
-
-1. scenario and problem statement
-2. personas
-3. journeys
-4. prototype build
-5. screenshots/accessibility
-
-Port the staged shape, but adapt it:
-
-1. source-model slice
-2. user needs and scenarios
-3. journeys and blueprint view model
-4. prototype screens
-5. generated documentation
-6. screenshots/accessibility
-
-The current prompt pack partly covers this already. The missing pieces are persona/archetype generation and orchestrated delivery summary.
-
-## Medium-value ports
-
-### Persona generation
-
-NCRS has a substantial persona-generation prompt for M365 Copilot Researcher.
-
-Port a lighter version for the knowledge base:
-
-- generate user groups and archetypes
-- link each archetype to needs and scenarios
-- avoid patient/public persona generation unless the service slice is patient-facing
-- ask for evidence or mark assumptions
-
-This would extend the current model, because `users.json` is currently user groups, not full personas.
-
-### Journey map artefact output
-
-NCRS build prompts require generated journey maps in Markdown and JSON.
-
-Port this as:
-
-```text
-artefacts/journey-maps/<journey-id>.md
-artefacts/journey-maps/<journey-id>.json
-```
-
-This is useful because the knowledge base can then preserve a review snapshot separate from live source data.
-
-### Delivery summaries
-
-NCRS orchestrator writes:
-
-```text
-docs/<YYYY-MM-DD>-delivery-summary.md
-```
-
-Port this as:
-
-```text
-artefacts/delivery-summaries/<YYYY-MM-DD>-<topic>.md
-```
-
-This keeps generated delivery notes separate from source documentation.
-
-## Low-value or defer
-
-### Clinical FHIR fixture workflow
-
-Do not port now.
-
-It is powerful but NCRS-specific and would pull the knowledge base toward clinical data testing before the service design model is proven.
-
-Revisit only if a slice needs structured clinical data provenance, source contradiction or fixture generation.
-
-### Large generated NHS Frontend component reference
-
-Useful, but heavy.
-
-Start with concise NHS Frontend instructions. Add the full reference only if Copilot repeatedly gets component syntax wrong.
-
-### Dependabot and release workflows
-
-Defer until there is a GitHub remote and a clearer package/release direction.
-
-## Suggested next commits
-
-### Commit 1
-
-`Add Copilot instructions and knowledge source guidance`
-
-Files:
-
-- `.github/copilot-instructions.md`
-- `.github/instructions/knowledge-source.instructions.md`
-- `.github/instructions/nhs-prototype-kit.instructions.md`
-- `docs/agent-workflow.md`
-- `docs/prompt-architecture-guardrails.md`
-
-### Commit 2
-
-`Add focused custom agents for knowledge base workflow`
-
-Files:
-
-- `.github/agents/README.md`
-- `.github/agents/knowledge-builder.md`
-- `.github/agents/prototype-builder.md`
-- `.github/agents/screenshot-runner.md`
-- `.github/agents/accessibility-tester.md`
-- `.github/agents/workflow-orchestrator.md`
-- `docs/custom-agents-usage.md`
-
-### Commit 3
-
-`Add generated artefact workspace`
-
-Files:
-
-- `artefacts/README.md`
-- `hippocampus/source-artefacts/scenarios/README.md`
-- `artefacts/screenshots/README.md`
-- `artefacts/accessibility/README.md`
-- `artefacts/delivery-summaries/README.md`
-- `artefacts/generated-docs/README.md`
-
-## Best next move
-
-Start with commit 1.
-
-Copilot instructions and source guidance will improve every later prompt and agent. Agents are useful, but ambient instructions are more foundational.
-

package/docs/copilot-ncrs-research-curator-agent.md

@@ -1,298 +0,0 @@
-# NCRS Research Curator Copilot Agent
-
-This agent is intended to connect to NHS SharePoint research material and produce reviewable documents that are a good fit for Hippocampus ingestion.
-
-It should not directly mutate Hippocampus source data. Its job is to find, structure, cite and package material so a human can review it before ingestion.
-
-## Recommended Agent Name
-
-NCRS Research Curator
-
-## Purpose
-
-Help service designers, researchers and product teams turn scattered NCRS SharePoint material into structured, evidence-backed documents that can be reviewed and ingested into Hippocampus.
-
-The agent should support two lanes:
-
-- **Research ingestion**: research rounds, participants, findings, insights and design actions.
-- **Project context ingestion**: service overview, purpose, vision, problem statements, policy context, constraints, channels, risks, milestones and key facts.
-
-## Knowledge Sources
-
-Connect the agent only to approved NCRS SharePoint locations, for example:
-
-- research reports
-- show-and-tell decks
-- interview notes
-- usability testing notes
-- service maps
-- journey maps
-- policy and governance summaries
-- decision logs
-- design history decks
-- prototype review documents
-
-Prefer narrower SharePoint folders over a broad tenant-wide connection.
-
-## Core Instruction
-
-Paste this into the custom agent instructions:
-
-```text
-You are the NCRS Research Curator.
-
-Your job is to help prepare NHS service design and user research material for Hippocampus ingestion.
-
-Hippocampus is a structured project memory. It stores project context, users, needs, scenarios, evidence, research rounds, participants, insights, design actions, journeys, screens, decisions and explicit relationships between those records.
-
-You must not invent findings, sources, participant evidence, dates, decisions or relationships.
-
-You must use only the connected SharePoint material and the user’s current prompt. If evidence is weak, missing or ambiguous, say so.
-
-Your main outputs are reviewable documents, not final source data. A human must review the document before it is ingested.
-
-Always separate:
-
-1. Project context
-   Purpose, vision, problem statement, service proposition, policy context, constraints, channels, risks, milestones and source facts.
-
-2. Research material
-   Research rounds, participants, findings, insights, evidence, design actions and recommendations.
-
-3. Unknown or weak material
-   Claims that need review, missing source details, unsupported assumptions, duplicate or conflicting findings.
-
-For every claim, include source detail:
-
-- source document title
-- SharePoint link if available
-- page, slide, heading or section
-- date if available
-- author or team if available
-
-Use UK English. Use "artefact" consistently.
-
-When producing a document for Hippocampus ingestion, use the exact output templates provided in your instructions. Keep the structure stable so downstream tools can extract it.
-```
-
-## Conversation Starters
-
-Use these starter prompts in Copilot Studio:
-
-- Find NCRS research material about a specific user group and prepare an ingestion-ready research summary.
-- Turn this SharePoint folder into a Hippocampus project context draft.
-- Compare these research decks and identify repeated insights, contradictions and gaps.
-- Create an evidence-backed design action summary from these research notes.
-- Check whether this material is ready to ingest into Hippocampus.
-
-## Research Output Template
-
-Use this when the source material is a research round, interview set, usability test, show-and-tell, synthesis deck or research report.
-
-```text
-# Research ingestion draft
-
-## Import classification
-
-Type: research
-Recommended inbox: hippocampus/inbox/research/
-Fit: good | needs review | poor
-
-## Source material
-
-Source:
-SharePoint link:
-Date:
-Author or team:
-Pages or slides reviewed:
-
-## Research round
-
-Title:
-Date:
-Summary:
-
-## Participants
-
-Participant: [label] - [role or user group]
-Participant: [label] - [role or user group]
-
-## Findings and insights
-
-Insight: [short evidence-backed insight]
-Summary: [what was observed, by whom, and why it matters]
-Evidence: [source document, page/slide/section]
-Confidence: high | medium | low
-
-Insight: [short evidence-backed insight]
-Summary: [what was observed, by whom, and why it matters]
-Evidence: [source document, page/slide/section]
-Confidence: high | medium | low
-
-## Design actions
-
-Action: [specific design or content action]
-Rationale: [which insight or evidence supports it]
-Status: proposed
-
-Action: [specific design or content action]
-Rationale: [which insight or evidence supports it]
-Status: proposed
-
-## Suggested graph links
-
-Existing entity:
-Relationship:
-New entity:
-Evidence:
-
-## Assumptions or gaps
-
-- [Anything uncertain, missing or requiring human review]
-```
-
-## Project Context Output Template
-
-Use this when the source material is a project overview, mapping board, policy summary, proposition deck, service map or general briefing.
-
-```text
-# Project context ingestion draft
-
-## Import classification
-
-Type: project context
-Recommended inbox: hippocampus/inbox/project/
-Fit: good | needs review | poor
-
-## Source material
-
-Source:
-SharePoint link:
-Date:
-Author or team:
-Pages or slides reviewed:
-
-## Overview
-
-Purpose:
-Vision:
-Problem statement:
-Service proposition:
-
-## Users
-
-User: [user group]
-Group: external | internal | data consumer | other
-Description:
-
-User: [user group]
-Group: external | internal | data consumer | other
-Description:
-
-## Channels
-
-Channel: [channel name]
-Usage:
-Description:
-
-Channel: [channel name]
-Usage:
-Description:
-
-## Policies and regulations
-
-Policy: [policy or regulation name]
-Summary:
-Source:
-
-## Constraints
-
-Constraint: [constraint]
-Detail:
-Impact:
-
-## Risks
-
-Risk: [risk]
-Detail:
-Severity: high | medium | low
-
-## Milestones
-
-Milestone: [milestone]
-Date:
-Detail:
-
-## Facts
-
-Fact: [fact label]
-Value:
-Detail:
-Source:
-
-## Assumptions or gaps
-
-- [Anything uncertain, missing or requiring human review]
-```
-
-## Ingestion Readiness Check
-
-Before the agent says a document is ready, it must check:
-
-- The document has a clear classification: research or project context.
-- Every important claim has a source reference.
-- Research material includes findings or insights, not just raw notes.
-- Design actions are linked to evidence or insights.
-- Project context does not include invented strategy or unverified policy detail.
-- Duplicates and contradictions are called out.
-- Sensitive material is not copied unnecessarily.
-- The output uses stable headings and UK spelling.
-
-## Recommended Workflow
-
-1. Ask the agent to inspect a specific SharePoint folder or set of documents.
-2. Ask it to classify the material as research, project context or mixed.
-3. Ask it to produce one ingestion draft per coherent artefact or theme.
-4. Export the draft as a document or PDF.
-5. Put the exported document into the matching Hippocampus inbox:
-
-   ```text
-   hippocampus/inbox/research/
-   hippocampus/inbox/project/
-   ```
-
-6. Run the matching sync command:
-
-   ```bash
-   npx hippocampus research sync -- --no-promote
-   npx hippocampus import project-context -- --no-promote
-   ```
-
-7. Review the generated `.review.md` and `.json` files.
-8. Promote only after review.
-
-## Guardrails
-
-The agent must not:
-
-- treat SharePoint search results as evidence without opening the source
-- invent dates, participants, roles or decisions
-- collapse conflicting findings into a false consensus
-- expose confidential or sensitive material outside the approved workspace
-- create final Hippocampus source data without review
-- use US spelling for artefacts
-
-## Good First Pilot
-
-Start with a narrow SharePoint folder and one question:
-
-```text
-Review the NCRS research material in this folder and produce one Hippocampus research ingestion draft for the strongest repeated findings about [user group or journey].
-```
-
-Then test:
-
-- whether the sources are cited well enough
-- whether the output fits `research:sync`
-- whether a designer or researcher can review it quickly
-- whether the agent separates evidence from assumptions

package/docs/gp-connect-real-data-to-production.md

@@ -1,66 +0,0 @@
-# GP Connect: Real Data → Production Workflow
-
-This doc connects four repos into one pipeline: pulling real GP Connect/PDS data, rendering and reviewing it in `ncrs-prototype-agentic`, capturing the resulting UI decisions where they belong, and making those decisions available to production builds in `ncrs-ui`. Hippocampus integration is a later, explicitly deferred stage — see Stage 6.
-
-If anything here conflicts with `ncrs-prototype-agentic/ARCHITECTURE.md`, that file wins.
-
-## Repos involved
-
-| Repo | Role in this workflow |
-| --- | --- |
-| `gpconnect-ui-testdata` | Bruno collection for pulling real bundles from GP Connect providers (JWT pre-request script, TLS-MA). Also a scratch space for prototyping a new edge case before it's formalised. |
-| `ncrs-prototype-agentic` | Renders bundles, hosts the canonical synthetic-fixture pipeline, and is where edge-case-driven UI decisions get written down. |
-| `ncrs-ui` | Production React build. Its Copilot skills read `ncrs-prototype-agentic`'s decision records when porting a component. |
-| `nhs-prototype-hippocampus` (this repo) | Structured design knowledge base. Not yet wired to clinical/FHIR content — see Stage 6. |
-
-## Stage 1 — Acquire real bundles
-
-Use the Bruno collection in `gpconnect-ui-testdata/bruno`. It has a working `alg: none` JWT pre-request script and environments for Integration and the local demonstrator.
-
-Blocked on: NHS integration credentials (`sspPrefix`, `providerFhirBase`, `consumerAsid`/`providerAsid`, `consumerOdsCode`, `sdsUserId`, `sdsRoleProfileId`) via your org's assurance process. Client cert for TLS-MA if calling a real provider rather than the local demonstrator.
-
-SystmOne-in-Parallels is a secondary reality check for one specific quirk, not the main data loop — it validates on entry and won't produce most of the interesting edge cases.
-
-## Stage 2 — Bring bundles into ncrs-prototype-agentic
-
-Two landing spots, depending on shape:
-
-- **Single-patient real/reference bundles** → `app/data/gpud-data-*.json`, wired up via `getGpConnectDataFileName()` in `app/lib/gpconnect/core.js`. Fine for one-off "does this real bundle render" checks.
-- **Multi-source, scenario-driven synthetic bundles** → the canonical fixture pipeline: `test-data/clinical-scenarios/*.json` → `scripts/build-clinical-fixtures.mjs` → `test-data/generated/<scenario-id>/`. See `docs/CLINICAL-DATA-FIXTURES.md` (in `ncrs-prototype-agentic`) for the full model (persona / canonical truth / per-source includes-overrides-omits).
-
-**Decision on blood pressure specifically:** the BP generator in `gpconnect-ui-testdata/generate.js` was built before `ncrs-prototype-agentic`'s fixture pipeline was reviewed. `docs/plans/synthetic-fhir-test-suite-builder.md` (in `ncrs-prototype-agentic`) already scoped `Observation` into the canonical builder from the start. Fold the 15 BP scenarios into `test-data/clinical-scenarios/` as `Observation`-based scenario specs (persona/truth/source-matrix shape) rather than maintaining `generate.js` as a second system long-term. Keep `gpconnect-ui-testdata` for the Bruno collection and for prototyping the *next* new edge case idea before it's formalised there.
-
-## Stage 3 — Render, review, check
-
-In `ncrs-prototype-agentic`:
-
-- Follow `docs/GP-CONNECT-UI-CHANGE-CHECKLIST.md` before touching the live GP Connect surfaces.
-- Run `npm run test:clinical-fixtures` for scenario-driven work (build → audit → compare against `expected-clusters.json`).
-- Use `@screenshot-runner` / `@accessibility-tester` per `docs/AGENT-WORKFLOW.md` for the review loop.
-
-## Stage 4 — Capture the decision
-
-Each edge case forces a "what should the UI do here" decision. Write it into `ncrs-prototype-agentic`'s `docs/components/<component>.md` using the existing template (`docs/components/template.md`) — not a new artefact type. The template's **Design intent**, **Parameters**, and **Testing and validation → Regression risks** sections are exactly where FHIR-edge-case behaviour belongs (e.g. `dataAbsentReason` handling, the `Observation.related` escape hatch, qualifiers flattened into `comment`).
-
-This is the load-bearing step: it's the only thing `ncrs-ui`'s skills read in Stage 5.
-
-## Stage 5 — Production skills consume the decision
-
-`ncrs-ui/.github/prompts/port-ncrs-nunjucks-component.prompt.md` currently inspects only the Nunjucks source when porting a component. Extend it (or add a paired skill) to read the matching `ncrs-prototype-agentic/docs/components/<component>.md` first, and to check whether the documented edge cases are represented in the ported component's tests/Storybook states.
-
-Adopt the portable skill format this repo already built and validated — `.skill.md` + YAML front matter (`id`, `purpose`, `owners`, `reads`, `edits`, `runs`, `outputs`, `guardrails`, `acceptance`), checked by `npx hippocampus skills validate`. It's plain Markdown/JSON, works today as a Copilot custom prompt, and is the actual answer to "tool-agnostic" — no need to invent a second format for `ncrs-ui`. See `.github/skills/SKILL-FORMAT.md`.
-
-## Stage 6 — Hippocampus integration (deferred)
-
-`docs/agentic-patterns-to-port.md` (this repo) already flags the clinical FHIR fixture workflow as low-value/defer: it is powerful but NCRS-specific and would pull the knowledge base toward clinical data testing before the service design model is proven. Don't revisit until Stage 4 has produced enough decision records across GP Connect sections (not just BP) to be worth making queryable that way, or a slice specifically needs structured clinical data provenance / source contradiction / fixture generation surfaced through hippocampus.
-
-`ncrs-prototype-agentic/ARCHITECTURE.md` step 7 ("optional evidence-linked handoff") already anticipates a hippocampus link via `hippocampus/prototype-maps/<journey-slug>.json` — that's the hook to extend when this stage is triggered, not a new integration point.
-
-## Cross-references
-
-- `ncrs-prototype-agentic/docs/CLINICAL-DATA-FIXTURES.md` — canonical fixture pipeline
-- `ncrs-prototype-agentic/docs/plans/synthetic-fhir-test-suite-builder.md` — original design scope (includes `Observation`)
-- `ncrs-prototype-agentic/docs/GP-CONNECT-UI-CHANGE-CHECKLIST.md` — before changing live GP Connect UI
-- `ncrs-prototype-agentic/docs/components/template.md` — decision-capture template
-- `.github/skills/SKILL-FORMAT.md` — portable skill contract
-- `docs/agentic-patterns-to-port.md` — deferral rationale for Stage 6