@hippo-digital/hippocampus 1.0.0-rc.1

package/assets/javascript/blueprint.js

@@ -0,0 +1,123 @@
+const controls = document.querySelector('[data-blueprint-controls]')
+
+if (controls) {
+  const lensButtons = Array.from(controls.querySelectorAll('[data-lens]'))
+  const laneToggles = Array.from(controls.querySelectorAll('[data-lane-toggle]'))
+  const laneGroups = new Map()
+
+  for (const lane of document.querySelectorAll('[data-lane]')) {
+    const key = lane.dataset.lane
+    if (!laneGroups.has(key)) laneGroups.set(key, [])
+    laneGroups.get(key).push(lane)
+  }
+
+  const lensLaneKeys = new Map()
+  for (const button of lensButtons) {
+    const lens = button.dataset.lens
+    if (lens === 'all') continue
+    const keys = new Set()
+    for (const [key, lanes] of laneGroups) {
+      const lenses = (lanes[0].dataset.lenses || '').split(' ').filter(Boolean)
+      if (lenses.includes(lens)) keys.add(key)
+    }
+    lensLaneKeys.set(lens, keys)
+  }
+
+  const setLaneVisibility = (key, visible) => {
+    for (const lane of laneGroups.get(key) || []) {
+      lane.hidden = !visible
+    }
+    const toggle = laneToggles.find((input) => input.dataset.laneToggle === key)
+    if (toggle) toggle.checked = visible
+  }
+
+  const setActiveLens = (lens) => {
+    for (const button of lensButtons) {
+      button.setAttribute('aria-pressed', String(button.dataset.lens === lens))
+    }
+  }
+
+  const syncActiveLensFromToggles = () => {
+    const visibleKeys = new Set(
+      laneToggles.filter((input) => input.checked).map((input) => input.dataset.laneToggle)
+    )
+
+    if (visibleKeys.size === laneGroups.size) {
+      setActiveLens('all')
+      return
+    }
+
+    for (const [lens, keys] of lensLaneKeys) {
+      if (keys.size === visibleKeys.size && [...keys].every((key) => visibleKeys.has(key))) {
+        setActiveLens(lens)
+        return
+      }
+    }
+
+    setActiveLens(null)
+  }
+
+  for (const button of lensButtons) {
+    button.addEventListener('click', () => {
+      const lens = button.dataset.lens
+
+      for (const key of laneGroups.keys()) {
+        const visible = lens === 'all' || (lensLaneKeys.get(lens) || new Set()).has(key)
+        setLaneVisibility(key, visible)
+      }
+
+      setActiveLens(lens)
+    })
+  }
+
+  for (const toggle of laneToggles) {
+    toggle.addEventListener('change', () => {
+      setLaneVisibility(toggle.dataset.laneToggle, toggle.checked)
+      syncActiveLensFromToggles()
+    })
+  }
+}
+
+const minimap = document.querySelector('[data-blueprint-minimap]')
+
+if (minimap) {
+  const steps = Array.from(document.querySelectorAll('[data-step-id]'))
+  const links = new Map(
+    Array.from(minimap.querySelectorAll('[data-minimap-step]')).map((link) => [link.dataset.minimapStep, link])
+  )
+  const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches
+
+  const setActiveStep = (stepId) => {
+    for (const [id, link] of links) {
+      link.classList.toggle('is-active', id === stepId)
+    }
+  }
+
+  for (const [stepId, link] of links) {
+    link.addEventListener('click', (event) => {
+      const target = document.getElementById(`step-${stepId}`)
+      if (!target) return
+      event.preventDefault()
+      target.scrollIntoView({ behavior: prefersReducedMotion ? 'auto' : 'smooth', block: 'start' })
+      history.replaceState(null, '', `#step-${stepId}`)
+      setActiveStep(stepId)
+    })
+  }
+
+  if (steps.length) {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const visible = entries
+          .filter((entry) => entry.isIntersecting)
+          .sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top)
+
+        if (visible.length) {
+          setActiveStep(visible[0].target.dataset.stepId)
+        }
+      },
+      { rootMargin: '-20% 0px -60% 0px' }
+    )
+
+    for (const step of steps) observer.observe(step)
+  }
+}

package/bin/hippocampus.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+const path = require('path')
+const { spawnSync } = require('child_process')
+const packagePaths = require('../lib/package-paths')
+
+// Every public command is a compatibility promise, so this list is deliberately
+// shorter than the scripts directory. Things that are internal (the blueprint
+// spreadsheet importer) or better folded into another command (smoke routes,
+// which belongs inside doctor) are not exposed here.
+const COMMANDS = {
+  init: 'init.js',
+  doctor: 'doctor.js',
+  eject: 'eject.js',
+  validate: 'validate-knowledge.js',
+  migrate: 'migrate-knowledge.js',
+  'research sync': 'sync-research-artefacts.js',
+  'research triage': 'triage-research-corpus.js',
+  'research batch': 'import-research-batch.js',
+  'import research-deck': 'import-research-deck.js',
+  'import project-context': 'import-project-context.js',
+  'import design-actions': 'import-design-actions.js',
+  'promote research': 'promote-research-draft.js',
+  'promote project-context': 'promote-project-context-draft.js',
+  'link insight-needs': 'link-insights-to-needs.js',
+  'source index': 'index-source-artefacts.js',
+  'source audit': 'audit-provenance.js',
+  'skills install': 'install-skills.js',
+  'skills validate': 'validate-skills.js'
+}
+
+const { version } = require('../package.json')
+
+function usage () {
+  console.log(`hippocampus ${version}\n`)
+  console.log('hippocampus <command> [options]\n')
+  console.log('Commands:')
+  for (const name of Object.keys(COMMANDS)) console.log(`  ${name}`)
+  console.log('\nOptions:')
+  console.log('  --root <dir>   the project to act on (default: nearest project above the cwd)')
+  console.log('  --version      print the installed version')
+  console.log('  --help         this message')
+  console.log('\nEvery command resolves a project root the same way; run `hippocampus validate`')
+  console.log('from anywhere with --root to check a project you are not standing in.')
+}
+
+function main (argv) {
+  if (!argv.length || argv[0] === '--help' || argv[0] === '-h') {
+    usage()
+    process.exit(0)
+  }
+
+  if (argv[0] === '--version' || argv[0] === '-v') {
+    console.log(version)
+    process.exit(0)
+  }
+
+  // Two-word commands first, so `research sync` wins over a bare `research`.
+  const twoWord = argv.slice(0, 2).join(' ')
+  const name = COMMANDS[twoWord] ? twoWord : argv[0]
+  const script = COMMANDS[name]
+
+  if (!script) {
+    console.error(`Unknown command: ${argv.slice(0, 2).join(' ')}\n`)
+    const suggestion = closest(argv[0])
+    if (suggestion) console.error(`Did you mean \`hippocampus ${suggestion}\`?\n`)
+    usage()
+    process.exit(1)
+  }
+
+  const rest = argv.slice(name.split(' ').length)
+  const result = spawnSync(
+    process.execPath,
+    [path.join(packagePaths.scriptsDir, script), ...rest],
+    { stdio: 'inherit' }
+  )
+
+  process.exit(result.status === null ? 1 : result.status)
+}
+
+// A mistyped command should point at the right one rather than just listing
+// everything and leaving the reader to spot the difference.
+function closest (input) {
+  if (!input) return null
+  const names = Object.keys(COMMANDS)
+  const scored = names
+    .map((name) => ({ name, distance: distance(input, name.split(' ')[0]) }))
+    .sort((a, b) => a.distance - b.distance)
+  return scored[0] && scored[0].distance <= 3 ? scored[0].name : null
+}
+
+function distance (a, b) {
+  const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)])
+  for (let j = 0; j <= b.length; j++) rows[0][j] = j
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      rows[i][j] = Math.min(
+        rows[i - 1][j] + 1,
+        rows[i][j - 1] + 1,
+        rows[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      )
+    }
+  }
+  return rows[a.length][b.length]
+}
+
+main(process.argv.slice(2))

package/docs/agent-roadmap.md

@@ -0,0 +1,217 @@
+# Agent Roadmap
+
+This roadmap keeps future AI-workflow improvements aligned with the project's original intent.
+
+## Intent Sources
+
+Use these as the baseline before changing the agent model:
+
+- `README.md`
+- `docs/agentic-patterns-to-port.md`
+- `docs/research-knowledge-graph.md`
+- `docs/repeatable-research-round-ingestion.md`
+- `docs/prompt-architecture-guardrails.md`
+- `docs/agent-workflow.md`
+- `docs/source-model.md`
+- `.github/legacy/prompts/`
+
+## Intended End State
+
+- Copilot-first discovery through `.github/copilot-instructions.md`, `.github/instructions/` and `.github/agents/`.
+- Portable task recipes through `.github/skills/skills.json` and `*.skill.md` files.
+- Review-first ingestion: script extracts -> skill structures -> human reviews -> promotion validates.
+- Source-first editing: `hippocampus/source/` stays canonical and `artefacts/` stays generated only.
+- Traceability stays visible from research and project context through needs, journeys, screens and decisions.
+
+## Current Baseline
+
+Already in place:
+
+- repo-level Copilot instructions and concise auto-attached instruction files
+- focused role agents under `.github/agents/`
+- portable skill catalog under `.github/skills/`
+- archived prompt history under `.github/legacy/prompts/`
+- delivery summary pattern under `artefacts/delivery-summaries/`
+- smoke-tested research and project-context ingestion lanes using dry-run promotion
+- documentation-first screenshot, accessibility, and route-review workflows under `.github/skills/` and `artefacts/`
+
+## Priority Roadmap
+
+### Phase 1: Close skill coverage gaps
+
+**Why**
+
+The original prompt guardrails describe staged workflows that are still slightly fragmented across low-level skills.
+
+**Work**
+
+- Add higher-level orchestration skills for:
+  - full research round ingestion
+  - full project-context ingestion
+  - service-slice delivery from source records through prototype screens
+  - delivery-summary production
+- Add a coverage matrix mapping original prompt intent -> current skill -> role agent.
+
+**Likely files**
+
+- `.github/skills/skills.json`
+- new `*.skill.md` files in `.github/skills/`
+- `.github/skills/README.md`
+- `docs/custom-agents-usage.md`
+
+**Acceptance signals**
+
+- Common multi-step workflows have a single entrypoint skill.
+- Active docs no longer require users to manually chain low-level skills for routine tasks.
+- The old prompt archive is historical only, not needed to complete normal work.
+
+### Phase 2: Tighten skill portability
+
+**Status:** baseline complete
+
+**Why**
+
+The project goal is Copilot-first but not Copilot-only.
+
+**Work**
+
+- Freeze the skill card contract around explicit fields such as:
+  - `id`
+  - `title`
+  - `purpose`
+  - `reads`
+  - `edits`
+  - `runs`
+  - `outputs`
+  - `guardrails`
+  - `acceptance`
+- Keep `skills.json` as the discovery layer and validate it with `skills.schema.json`.
+- Add one or two worked examples showing how a non-Copilot agent should consume a skill.
+- Keep `npx hippocampus skills validate` as the shared check after changing skill cards, the catalog, schema, or examples.
+
+**Likely files**
+
+- `.github/skills/SKILL-FORMAT.md`
+- `.github/skills/skills.schema.json`
+- `.github/skills/skills.json`
+- `.github/skills/README.md`
+- `docs/custom-agents-usage.md`
+
+**Acceptance signals**
+
+- A non-Copilot agent can resolve a task from `skills.json` without reading Copilot-only docs.
+- All skill files use the same required metadata fields.
+- Schema validation catches missing or malformed skill metadata.
+- Worked examples show the catalog-first path for non-Copilot agents.
+
+### Phase 3: Restore review loops as first-class workflows
+
+**Status:** baseline complete
+
+**Why**
+
+`docs/agentic-patterns-to-port.md` explicitly called out screenshots, accessibility checks and delivery summaries as review artefacts, not optional extras.
+
+**Work**
+
+- Define the active workflow for `screenshot-runner` and `accessibility-tester`.
+- Add documentation-first or script-backed skills for:
+  - screenshot capture packs
+  - accessibility review notes
+  - route-review summaries
+- Standardise artefact paths and filenames.
+- Optionally add script-backed capture or audit tooling later if repeated manual steps become painful.
+
+**Likely files**
+
+- `.github/agents/screenshot-runner.md`
+- `.github/agents/accessibility-tester.md`
+- new skills in `.github/skills/`
+- `artefacts/screenshots/README.md`
+- `artefacts/accessibility/README.md`
+- `artefacts/delivery-summaries/README.md`
+
+**Acceptance signals**
+
+- Visible prototype changes can produce review artefacts without inventing a one-off process.
+- Orchestrated work leaves evidence in `artefacts/`, not just in commit history.
+- Review packs can honestly distinguish between screenshots and notes-only evidence.
+
+### Phase 4: Prove the source-authoring lane end to end
+
+**Status:** baseline complete
+
+**Why**
+
+The ingestion lanes are proven. The source-authoring workflow still needs one full skills-first exercise.
+
+**Work**
+
+- Run one fictional service-slice exercise using:
+  - `generate-service-slice`
+  - `add-user-needs`
+  - `add-scenario`
+  - `create-journey-from-scenario`
+  - `add-prototype-screen`
+- Capture a delivery summary under `artefacts/delivery-summaries/`.
+- Validate with `npx hippocampus validate` and `npx hippocampus doctor`.
+- Keep the proof slice small and source-backed; the current baseline proof is `route-review-workflow` plus `/hippocampus/route-review`.
+
+**Likely files**
+
+- `hippocampus/source/*.json`
+- `app/routes.js`
+- `app/views/**/*.html`
+- `artefacts/delivery-summaries/*.md`
+
+**Acceptance signals**
+
+- A new slice can be added without consulting archived prompts.
+- Validation passes and the smoke test covers the new routes.
+- A delivery summary records the records, route, validation results and follow-up notes for the proof slice.
+- The graph and trace views show meaningful links from need -> scenario -> journey -> screen -> evidence or decision.
+
+### Phase 5: Reduce documentation drift
+
+**Status:** baseline complete
+
+**Why**
+
+The repo now has enough agent-facing documentation that overlap will become a maintenance problem.
+
+**Work**
+
+- Keep one canonical explanation of the staged ingestion model.
+- Keep one canonical explanation of the skill format.
+- Use `README.md` and `AGENTS.md` as navigation docs, not full duplicates of deeper guidance.
+- Make overlapping docs say explicitly which deeper file wins.
+
+**Likely files**
+
+- `README.md`
+- `AGENTS.md`
+- `.github/copilot-instructions.md`
+- `.github/skills/README.md`
+- `docs/research-knowledge-graph.md`
+- `docs/repeatable-research-round-ingestion.md`
+
+**Acceptance signals**
+
+- No active docs disagree about where to start or which files are canonical.
+- Shallow docs link to deep docs instead of duplicating them.
+- The staged ingestion and skill contract each have one named source-of-truth doc.
+
+## Do Not Regress
+
+- 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.
+
+## Recommended Next Commits
+
+1. Add orchestration skills and a coverage matrix.
+2. Add screenshot and accessibility review workflows.
+3. Prove the source-authoring lane with a small fictional slice and a delivery summary.
+

package/docs/agent-workflow.md

@@ -0,0 +1,56 @@
+# Agent Workflow
+
+Use this workflow when making material changes to the knowledge base.
+
+## 1. Understand The Request
+
+- Identify whether the change is a source-model change, prototype change, documentation change or generated artefact.
+- Read `docs/source-model.md` for source-model work.
+- Read the relevant files under `hippocampus/source` before editing linked records.
+
+## 2. Edit The Source First
+
+For service-design content, update `hippocampus/source` before views.
+
+Use this order:
+
+1. Users
+2. User needs
+3. Evidence or assumptions
+4. Scenarios
+5. Journeys and journey steps
+6. Screens
+7. Decisions
+
+## 3. Render Or Extend Views
+
+Only edit routes or Nunjucks views when the existing renderer cannot show the source model.
+
+Keep route handlers small and reuse knowledge helpers.
+
+Read `docs/components.md` before adding repeated Nunjucks markup.
+
+## 4. Validate
+
+Run:
+
+```bash
+npx hippocampus validate
+npx hippocampus doctor
+```
+
+Validation failures are blockers for source-model work.
+Route smoke-test failures are blockers for view, route and component work.
+
+## 5. Review
+
+For visible prototype changes, smoke-test affected routes. For larger journeys, capture screenshots or notes under `artefacts/`.
+
+## 6. Summarise
+
+Finish with:
+
+- records, routes or docs changed
+- validation result
+- assumptions added
+- remaining risks or follow-up work