Deploy CP-UX-17: public demo hub, same-origin API, one design world

.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "carepath-site",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["--prefix", "scribe/frontend", "run", "dev", "--", "--port", "5173"],
+      "port": 5173
+    }
+  ]
+}

.dockerignore

@@ -0,0 +1,33 @@
+.agents/
+.claude/
+.codex/
+.git/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+.venv_labeling/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.env
+.env.*
+**/node_modules
+**/dist
+**/coverage
+**/playwright-report
+**/test-results
+**/*.db
+artifacts/
+data/labeling/
+models/
+tmp/
+*.wav
+*.mp3
+*.m4a
+*.aac
+*.flac
+*.ogg
+*.oga
+*.opus
+*.webm

.env.ckey.example

@@ -0,0 +1,38 @@
+# CarePath CKey runtime
+APP_ENV=local
+ASR_PROVIDER=gipformer
+ALLOW_MOCK_ASR=false
+
+# CKey uses the OpenAI-compatible chat/completions route.
+# Get the key from the CKey AI API Console and keep .env out of source control.
+LLM_PROVIDER=ckey
+LLM_BASE_URL=https://api.xah.io/v1
+LLM_MODEL=gpt-5.4
+LLM_API_KEY=sk-YOUR_API_KEY
+LLM_TIMEOUT_SECONDS=120
+# Demo safety net: if CKey fails/times out, serve the deterministic offline
+# generator instead of returning an error. Set to false to fail hard.
+LLM_FALLBACK_OFFLINE=true
+
+# Retrieval
+MEDICAL_LEXICON_PATH=data/medical_lexicon.json
+RETRIEVAL_TOP_K=5
+
+# Gipformer ASR
+GIPFORMER_QUANTIZE=int8
+GIPFORMER_NUM_THREADS=4
+GIPFORMER_DECODING_METHOD=modified_beam_search
+GIPFORMER_CHUNK_SECONDS=20
+
+# Abuse guard
+TEAM_CODE=
+SOAP_RATE_LIMIT_PER_IP_HOUR=3
+SOAP_RATE_LIMIT_PER_IP_DAY=10
+SOAP_RATE_LIMIT_GLOBAL_DAY=100
+
+# --- Interpreter module ---
+# Real translation over the same CKey gateway and key as the scribe half above.
+# Requires a non-default ADMIN_TOKEN; startup refuses "change-me".
+PROVIDER_MODE=ckey
+ADMIN_TOKEN=change-me-before-running-ckey
+DATABASE_URL=sqlite:///./carepath.db

.env.example

@@ -0,0 +1,103 @@
+# CarePath unified runtime — one FastAPI service, two products.
+# Defaults below are the keyless demo profile: the whole app must boot with no
+# API keys (mock interpreter providers, mock ASR + offline LLM for the scriber).
+# Ready-made profiles: .env.local.example (keyless demo), .env.ckey.example
+# (real Gipformer ASR + CKey LLM).
+
+# --- Scriber (scribe/carepath, routes /api/v1/*) ---
+APP_ENV=local
+ASR_PROVIDER=gipformer
+GIPFORMER_QUANTIZE=int8
+GIPFORMER_NUM_THREADS=4
+GIPFORMER_DECODING_METHOD=modified_beam_search
+GIPFORMER_CHUNK_SECONDS=20
+# Long-audio segmentation: overlap (default) | vad | fixed.
+#   overlap = overlapping windows merged with seam de-duplication (no word loss
+#             at chunk boundaries; no extra model).
+#   vad     = split on silence; requires GIPFORMER_VAD_MODEL (repo_id:filename or
+#             a local silero_vad.onnx path). Falls back to overlap if unavailable.
+#   fixed   = legacy non-overlapping 20s windows.
+GIPFORMER_SEGMENTATION=overlap
+GIPFORMER_OVERLAP_SECONDS=2
+GIPFORMER_MAX_SEGMENT_SECONDS=20
+GIPFORMER_VAD_MODEL=
+
+# Set LLM_PROVIDER=offline for a deterministic no-key fallback.
+# Set LLM_PROVIDER=ckey for CKey OpenAI-compatible chat completions.
+LLM_PROVIDER=offline
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL=gpt-4.1-mini
+LLM_API_KEY=
+LLM_TIMEOUT_SECONDS=60
+# If a network LLM provider fails, fall back to the offline generator so a
+# request never errors out (recommended for live demos).
+LLM_FALLBACK_OFFLINE=true
+
+# Vietnamese speech synthesis (patient -> clinician direction).
+# A default Windows or macOS install has no vi-VN browser voice, so without this
+# half of a bilingual visit is silent. Uses sherpa-onnx, which is already a
+# dependency for Gipformer ASR; no extra package. The 63 MB Piper voice
+# (VAIS-1000 corpus, CC BY 4.0) downloads on first use.
+# Keep TTS_MODEL_DIR SHORT: espeak-ng reads its data with a native call that
+# fails past the Windows MAX_PATH limit.
+TTS_PROVIDER=piper
+TTS_MODEL_DIR=models/vi-tts
+TTS_REPO_ID=csukuangfj/vits-piper-vi_VN-vais1000-medium
+
+# Some gateways hang when asked for response_format=json_object (measured on
+# CKey gpt-5.4). Off by default; the prompts demand JSON and parsers validate it.
+LLM_JSON_RESPONSE_FORMAT=false
+
+# Retrieval
+MEDICAL_LEXICON_PATH=data/medical_lexicon.json
+RETRIEVAL_TOP_K=5
+# Backend: lexical (default) | semantic | hybrid. semantic/hybrid use the
+# Vietnamese bi-encoder and need the optional sentence-transformers + pyvi deps.
+RETRIEVAL_BACKEND=lexical
+SEMANTIC_MODEL_NAME=bkai-foundation-models/vietnamese-bi-encoder
+
+# Safety/demo
+ALLOW_MOCK_ASR=false
+TEAM_CODE=
+SOAP_RATE_LIMIT_PER_IP_HOUR=3
+SOAP_RATE_LIMIT_PER_IP_DAY=10
+SOAP_RATE_LIMIT_GLOBAL_DAY=100
+# Cross-origin frontends for both APIs. Clear this value for same-origin-only
+# production; list every Vite development origin when developing against either API.
+CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
+
+# Public Vercel site used by the Interpreter's “Tất cả chức năng” link when
+# its frontend is built into the Space image. Set as a Docker build arg.
+VITE_PUBLIC_SITE_URL=https://carepath-omega.vercel.app
+
+# --- Interpreter (interpreter/app, routes /api/* + /ws/*) ---
+# PROVIDER_MODE=mock runs deterministic providers with zero keys. Note that
+#   mock "translation" is the source text with a "[vi->en] " prefix, so it is a
+#   plumbing check, not a demoable translation.
+# PROVIDER_MODE=demo replays a scripted consultation
+#   (interpreter/app/providers/demo_scenario.json) with realistic translations
+#   and no network. The normalizer, glossary, risk engine, confirmation gate and
+#   persistence all still run for real; only the model calls are scripted. Use
+#   it for rehearsal and as the fallback if the venue network dies.
+# PROVIDER_MODE=ckey runs real translation over the OpenAI-compatible CKey
+#   gateway and reuses the LLM_BASE_URL / LLM_MODEL / LLM_API_KEY values above,
+#   so one key configures both modules. Speech capture happens in the browser
+#   on this path; audio turns fail closed rather than inventing a transcript.
+# PROVIDER_MODE=cloud is the Anthropic + OpenAI track and needs the two keys
+#   below instead.
+# Both ckey and cloud require a non-default ADMIN_TOKEN (startup refuses
+# "change-me").
+PROVIDER_MODE=mock
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+ADMIN_TOKEN=change-me
+CONFIDENCE_THRESHOLD=0.7
+RETENTION_DAYS=30
+MAX_TURN_AUDIO_BYTES=10485760
+# sqlite is fine for the demo (ephemeral on HF Spaces); point at Postgres etc.
+# for anything that must survive a container restart.
+DATABASE_URL=sqlite:///./carepath.db
+OPENAI_TRANSCRIBE_MODEL=gpt-4o-transcribe
+CLAUDE_MT_MODEL=claude-sonnet-5
+CLAUDE_REVIEWER_MODEL=claude-sonnet-5
+PROVIDER_TIMEOUT_SECONDS=30

.env.local.example

@@ -0,0 +1,36 @@
+# CarePath local smoke/demo runtime
+APP_ENV=local
+ASR_PROVIDER=mock
+ALLOW_MOCK_ASR=true
+
+# Offline correction/SOAP fallback for local API contract testing.
+LLM_PROVIDER=offline
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL=gpt-4.1-mini
+LLM_API_KEY=
+LLM_TIMEOUT_SECONDS=60
+
+# Private Colab staging only. Production leaves these unset.
+# LLM_PROVIDER=scribe_local
+# SCRIBE_BUNDLE_PATH=/content/drive/MyDrive/carepath_artifacts/scribe_bundle
+# LLM_FALLBACK_OFFLINE=false
+
+# Retrieval
+MEDICAL_LEXICON_PATH=data/medical_lexicon.json
+RETRIEVAL_TOP_K=5
+
+# Gipformer settings are ignored while ASR_PROVIDER=mock.
+GIPFORMER_QUANTIZE=int8
+GIPFORMER_NUM_THREADS=4
+GIPFORMER_DECODING_METHOD=modified_beam_search
+GIPFORMER_CHUNK_SECONDS=20
+
+# Abuse guard
+TEAM_CODE=
+SOAP_RATE_LIMIT_PER_IP_HOUR=3
+SOAP_RATE_LIMIT_PER_IP_DAY=10
+SOAP_RATE_LIMIT_GLOBAL_DAY=100
+
+# --- Interpreter module (mock providers, zero keys) ---
+PROVIDER_MODE=mock
+DATABASE_URL=sqlite:///./carepath.db

.gitattributes

@@ -0,0 +1,2 @@
+# Playwright snapshots are byte-compared; never convert their line endings.
+site/tests/**/*-snapshots/** -text

.github/workflows/ci.yml

@@ -0,0 +1,102 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  unified-api:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install shared and API packages
+        run: python -m pip install -e ".[dev]" -e "./shared" -e "./interpreter[dev]"
+      - name: Scriber and combined-app tests
+        run: pytest
+      - name: Shared normalization characterization
+        run: python -m pytest shared/tests
+      - name: Regenerate term artifacts without drift
+        run: python scripts/build_term_artifacts.py && git diff --exit-code -- data/medical_lexicon.json interpreter/app/glossary/data/seed_glossary.csv
+      - name: Enforce serving/training import boundary
+        run: if rg -l 'from gec|import gec' scribe/carepath/; then exit 1; fi
+      - name: Scriber smoke test (mock ASR + offline LLM)
+        run: python scripts/smoke_backend.py
+
+  training-governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install CPU-only training proof dependencies
+        run: python -m pip install -e ".[dev]" -e "./shared"
+      - name: Test training governance and export smoke
+        run: python -m pytest scribe/training/tests
+      - name: Verify the committed frozen baseline report
+        run: python scribe/training/scripts/baseline_report.py
+
+  interpreter:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install shared and interpreter
+        run: python -m pip install -e "./shared" -e "./interpreter[dev]"
+      - name: Lint interpreter
+        working-directory: interpreter
+        run: ruff check .
+      - name: Test interpreter
+        working-directory: interpreter
+        run: pytest
+      - name: Eval regression
+        run: python interpreter/eval/run_eval.py --set interpreter/eval/fixtures/eval_starter.tsv --providers mock
+
+  # The interpreter console and its Playwright suite were removed: the bilingual
+  # visit at /kham-song-ngu/ in scribe/frontend replaced it, and the console was
+  # already a public 404. Its browser coverage now lives in the `site` job.
+
+  site:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: scribe/frontend/package-lock.json
+      - name: Install demo site
+        working-directory: scribe/frontend
+        run: npm ci
+      - name: Lint demo site
+        working-directory: scribe/frontend
+        run: npm run lint
+      - name: Test demo site
+        working-directory: scribe/frontend
+        run: npm test
+      - name: Test Vercel environment validation
+        working-directory: scribe/frontend
+        run: npm run test:deploy-env
+      - name: Build demo site
+        working-directory: scribe/frontend
+        run: npm run build
+      - name: Install Playwright browser
+        working-directory: scribe/frontend
+        run: npx playwright install --with-deps chromium
+      - name: Run demo site e2e
+        working-directory: scribe/frontend
+        run: npm run e2e
+      - name: Rebuild production demo site
+        working-directory: scribe/frontend
+        run: npm run build
+      - name: Audit demo site
+        working-directory: scribe/frontend
+        run: npm audit
+      - name: Run Lighthouse gates
+        working-directory: scribe/frontend
+        run: npm run lighthouse

.github/workflows/keepalive.yml

@@ -0,0 +1,17 @@
+name: Keep HF Space Awake
+
+on:
+  schedule:
+    - cron: "0 */12 * * *"
+  workflow_dispatch:
+
+jobs:
+  ping:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Ping health endpoint
+        env:
+          SPACE_URL: ${{ vars.SPACE_URL }}
+        run: |
+          test -n "$SPACE_URL"
+          curl -fsS "${SPACE_URL%/}/api/v1/health"

.gitignore

@@ -0,0 +1,50 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+artifacts/
+models/
+tmp/
+/scribe/research/papers/
+*.wav
+*.mp3
+*.m4a
+*.aac
+*.flac
+*.ogg
+*.oga
+*.opus
+*.webm
+
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+playwright-report/
+test-results/
+eval/reports/
+interpreter/eval/reports/
+
+*.db
+*.sqlite
+*.sqlite3
+
+# Harness durable layer
+harness.db
+harness.db-wal
+harness.db-shm
+scripts/bin/harness-cli
+scripts/bin/harness-cli.exe
+
+# Local QA evidence: 10MB of Playwright screenshots, regenerated by `npm run e2e`.
+.codex/
+
+# Per-developer Claude Code permissions; .claude/launch.json is shared.
+.claude/settings.local.json
+
+# setuptools build output (pip wheel / pip install .)
+build/

AGENTS.md

@@ -0,0 +1,335 @@
+# Agent instructions — CarePath unified
+
+CarePath is one unified medical AI product with two clearly separated user-facing modules:
+
+1. **Ghi chép bệnh án AI**
+   Internal/technical term: AI Scribe / scriber
+   Backend: `scribe/carepath`, `/api/v1/*`
+   Purpose: listen to a consultation and help generate structured clinical notes.
+
+2. **Phiên dịch khám bệnh trực tiếp**
+   Internal/technical term: Medical Interpreter / interpreter
+   Backend: `interpreter/app`, `/api/*` + `/ws/*`
+   Purpose: live two-way interpretation between Vietnamese doctors and English-speaking patients.
+
+The app is served by one FastAPI process plus two Vite frontends:
+
+* `scribe/frontend/` at `/`
+* `interpreter/frontend/` at `/phien-dich-y-khoa/` (`/console/` is a legacy redirect)
+
+## Interpreter status
+
+After restructure Phase 7, the Interpreter is on hold. Accept only bug fixes,
+safety fixes, and required operational maintenance there; new product work is
+focused on the Scribe training track unless the owner explicitly reopens it.
+
+`docs/history/PLAN.md` and `docs/history/DEMO-SITE-PLAN.md` are historical build
+plans for the interpreter and demo site. `docs/history/MERGE-PLAN.md` is the
+executed unification plan, M.0–M.8 done, and `docs/history/JUDGE.md` is its
+review protocol.
+`docs/research.md` holds the interpreter safety background.
+
+## Product UX contract
+
+CarePath must be Vietnamese-first.
+
+The target users may include Vietnamese doctors who are not comfortable with English medical software terms. Therefore, the UI must explain workflows by user intent, not by English product names.
+
+### Primary user-facing labels
+
+Use these as primary UI labels:
+
+* `Ghi chép bệnh án AI`
+* `Phiên dịch khám bệnh trực tiếp`
+
+Use these as primary CTAs:
+
+* `Bắt đầu ghi chép`
+* `Bắt đầu phiên dịch`
+
+Use this homepage framing:
+
+```text
+Bạn muốn hỗ trợ việc gì hôm nay?
+```
+
+### Secondary/internal labels
+
+The following English terms may appear only as secondary helper text, developer labels, comments, docs, or internal route/component names:
+
+* Scribe
+* AI Scribe
+* Interpreter
+* Medical Interpreter
+* Console
+* Transcript
+* Encounter
+* Session
+
+Do not use `Scribe` or `Interpreter` as primary labels on user-facing screens.
+
+### Required distinction between the two modules
+
+The landing page must make it obvious that these are two different workflows:
+
+#### Ghi chép bệnh án AI
+
+Explain as:
+
+```text
+AI nghe buổi khám và tạo ghi chú y khoa có cấu trúc.
+```
+
+Use when:
+
+```text
+Phù hợp khi bác sĩ muốn giảm thời gian nhập liệu sau khám.
+```
+
+Clarify that the doctor must review the output before use.
+
+#### Phiên dịch khám bệnh trực tiếp
+
+Explain as:
+
+```text
+Dịch hai chiều giữa bác sĩ tiếng Việt và bệnh nhân tiếng Anh trong lúc khám.
+```
+
+Use when:
+
+```text
+Phù hợp khi bác sĩ và bệnh nhân không cùng ngôn ngữ.
+```
+
+Clarify that the system translates only and must not provide medical advice.
+
+### Every user-facing screen must answer
+
+1. Tôi đang dùng chức năng nào?
+2. Chức năng này giúp việc gì?
+3. Tôi cần bấm gì tiếp theo?
+4. Có rủi ro hoặc giới hạn nào bác sĩ cần biết không?
+
+### Vietnamese copy rules
+
+* Vietnamese text must be clear, short, and professional.
+* Preserve Vietnamese diacritics.
+* Keep text NFC-normalized.
+* Avoid unnecessary English.
+* Avoid startup/marketing buzzwords on clinical workflow screens.
+* Prefer concrete action language over abstract product names.
+
+Good:
+
+```text
+Ghi chép bệnh án AI
+Phiên dịch khám bệnh trực tiếp
+Bắt đầu ghi chép
+Bắt đầu phiên dịch
+Bác sĩ nói tiếng Việt, bệnh nhân nghe tiếng Anh
+```
+
+Avoid as primary UI:
+
+```text
+Scribe
+Interpreter
+Session
+Encounter
+Transcript
+Start session
+Launch interpreter
+```
+
+## Non-negotiable safety invariants
+
+This file is the current safety contract. `docs/history/PLAN.md §2` preserves
+the original MVP source for historical context.
+
+1. Translate-only: never generate medical advice, diagnoses, or drug recommendations.
+2. High/critical-risk turns are blocked from patient display and TTS until doctor confirms.
+3. Low-confidence output is always visibly flagged, never silently delivered.
+4. Raw audio is never persisted. Use memory-only processing. No audio columns, no temp files.
+5. No mic capture before recorded consent.
+6. On any pipeline or reviewer failure, fail closed: keep the turn blocked, show the doctor raw source and translation, offer escalation. Never fail open to the patient.
+
+## Implementation workflow for agents
+
+For UX or product-flow changes, do not implement immediately.
+
+First produce or update a plan in `docs/ux-redesign-carepath.md` with:
+
+1. Current UX problem
+2. Proposed flow
+3. Affected routes/pages/components
+4. Vietnamese-first copy
+5. Implementation stories
+6. Dependencies between stories
+7. Acceptance criteria
+8. Validation commands
+9. Risks and fallback behavior
+
+Then implement one story at a time.
+
+### Recommended story order for UX redesign
+
+1. Update Vietnamese-first product naming and copy.
+2. Redesign the landing page into two clear workflow cards.
+3. Add or clarify separate entry routes for the two modules.
+4. Add pre-start onboarding/explanation screens.
+5. Improve empty/loading/error states in Vietnamese.
+6. Run QA for mobile, accessibility, safety copy, and route regressions.
+
+Do not combine homepage redesign, routing changes, and audio/backend logic changes in one large patch.
+
+### Agent behavior
+
+* Keep changes small and focused.
+* Preserve existing working functionality.
+* Do not rewrite backend, audio, risk, or websocket logic unless the current story explicitly requires it.
+* Do not introduce new dependencies without documenting why.
+* Prefer existing components and styling patterns.
+* When changing user-facing Vietnamese text, check diacritics and consistency.
+* When changing risk-engine behavior, update fixtures and evals.
+* When changing product copy only, avoid touching medical logic.
+
+## Commands
+
+### Combined service
+
+```bash
+uvicorn carepath.main:app --app-dir scribe --reload
+```
+
+Requires:
+
+```bash
+pip install -e ".[dev]" -e "./shared" -e "./interpreter[dev]"
+```
+
+### Scriber and combined tests
+
+```bash
+pytest
+python scripts/smoke_backend.py
+python scripts/build_term_artifacts.py --check
+```
+
+### Interpreter backend alone
+
+```bash
+cd interpreter && uvicorn app.main:app --reload
+pytest
+```
+
+### Console
+
+```bash
+cd interpreter/frontend && npm run dev
+npm test
+npx playwright test
+```
+
+### Demo site
+
+```bash
+cd scribe/frontend && npm run dev
+npm test
+npm run build
+npm run e2e
+```
+
+`npm run build` is also the diacritics gate.
+
+### Full mock-mode run
+
+Set this in `.env`:
+
+```bash
+PROVIDER_MODE=mock
+```
+
+Mock mode must work with no API keys.
+
+### Eval regression
+
+```bash
+python interpreter/eval/run_eval.py --set interpreter/eval/fixtures/eval_starter.tsv --providers mock
+```
+
+## Conventions
+
+* Python 3.12.
+* Python code must be ruff-formatted and type-hinted.
+* Use pure functions for normalization and risk rules.
+* TypeScript must be strict.
+* Components should be small.
+* Keep state minimal: context/zustand is allowed, Redux is not.
+* `shared/carepath_shared/terms/medical_terms.json` is the canonical medical
+  term source. Regenerate `data/medical_lexicon.json` and
+  `interpreter/app/glossary/data/seed_glossary.csv` with
+  `python scripts/build_term_artifacts.py`; do not hand-edit generated artifacts.
+* Risk lexicons under `interpreter/app/risk/lexicons/` remain separate
+  interpreter safety data. Clinicians edit data, not code.
+* Every risk-engine behavior change updates `interpreter/eval/fixtures/risk_cases.jsonl`.
+* The fixture run is the test.
+* Zero misses on critical fixtures is a hard gate.
+* Secrets only via env.
+* `.env` is gitignored.
+* `.env.example` must stay current.
+* No new dependencies without noting why in the PR.
+* Vietnamese text is data, not decoration: always NFC-normalized, diacritics preserved.
+* Tests must include diacritic-stripped variants where matching allows it.
+
+## Acceptance criteria for UX clarity changes
+
+A UX clarity change is not done un  less all of the following are true:
+
+1. A Vietnamese doctor can understand the two workflows without knowing the words `Scribe` or `Interpreter`.
+2. The landing page clearly separates:
+
+   * `Ghi chép bệnh án AI`
+   * `Phiên dịch khám bệnh trực tiếp`
+3. Each workflow has a distinct CTA.
+4. Each workflow explains when to use it.
+5. English terms appear only as secondary helper text, not primary labels.
+6. Mobile layout remains clear.
+7. Existing core functionality still works.
+8. Safety invariants remain unchanged.
+9. Build and relevant tests pass.
+
+<!-- HARNESS:START -->
+## Harness workflow
+
+This repository uses Repository Harness for durable task intake, proof, and
+decision records. This block adds to the CarePath instructions above; it does
+not replace them.
+
+Priority, highest first:
+
+1. The current user request and the safety and product rules in this file.
+2. Current product contracts in `docs/product/`.
+3. Selected story packets in `docs/stories/` and accepted decisions in
+   `docs/decisions/`.
+4. Executable tests and the Harness proof matrix.
+5. `docs/history/` as context only.
+
+Before any task, read `README.md`, `docs/HARNESS.md`, and
+`docs/FEATURE_INTAKE.md`; then run
+`.\scripts\bin\harness-cli.exe query matrix` on Windows. Classify and record
+the task as `tiny`, `normal`, or `high-risk` before changing code.
+
+- Tiny work records an intake and runs the relevant quick proof.
+- Normal work also updates one story packet and its proof record.
+- High-risk work uses `docs/templates/high-risk-story/`, records a decision
+  when it changes architecture, data, safety, APIs, or validation, and waits
+  for human direction if its scope is ambiguous.
+- A UX or product-flow task still must first update
+  `docs/ux-redesign-carepath.md`, then follow the Harness lane requirements.
+- Before a step that could use an external tool, query the available provider:
+  `.\scripts\bin\harness-cli.exe query tools --capability <capability> --status present`.
+  A missing provider is a clean skip, never a reason to invent a dependency.
+- Finish normal and high-risk work with a Harness trace that records the real
+  validation outcome and any friction. Do not claim proof that was not run.
+<!-- HARNESS:END -->

CLAUDE.md

@@ -0,0 +1,6 @@
+# CarePath
+
+@AGENTS.md
+@docs/FEATURE_INTAKE.md
+
+Use the Harness workflow in `AGENTS.md` before changing this repository.

Dockerfile

@@ -0,0 +1,43 @@
+# --- Stage 1: build the static frontend ---
+FROM node:22-slim AS frontends
+
+WORKDIR /build
+
+COPY scribe/frontend/package.json scribe/frontend/package-lock.json scribe/frontend/
+RUN cd scribe/frontend && npm ci
+COPY scribe/frontend scribe/frontend
+# site build also runs the Vietnamese diacritics gate.
+RUN cd scribe/frontend && npm run build
+
+# --- Stage 2: Python runtime serving both APIs and the built frontend ---
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    HF_HOME=/opt/hf-cache
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates libgomp1 libsndfile1 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml README.md ./
+COPY shared ./shared
+COPY scribe/carepath ./scribe/carepath
+COPY interpreter ./interpreter
+RUN python -m pip install --upgrade pip \
+    && python -m pip install . ./shared ./interpreter
+
+ARG GIPFORMER_QUANTIZE=int8
+ENV GIPFORMER_QUANTIZE=${GIPFORMER_QUANTIZE}
+RUN python -c "from carepath.services.asr import GipformerASR; from huggingface_hub import hf_hub_download; files = GipformerASR.onnx_files['${GIPFORMER_QUANTIZE}']; [hf_hub_download(repo_id=GipformerASR.repo_id, filename=name) for name in (*files.values(), 'tokens.txt')]"
+
+COPY data ./data
+COPY --from=frontends /build/scribe/frontend/dist ./scribe/frontend/dist
+ENV SITE_DIST_DIR=/app/scribe/frontend/dist
+
+EXPOSE 7860
+
+CMD ["uvicorn", "carepath.main:app", "--app-dir", "scribe", "--host", "0.0.0.0", "--port", "7860"]

README.hf-space.md

@@ -0,0 +1,45 @@
+---
+title: CarePath
+sdk: docker
+app_port: 7860
+---
+
+# CarePath Space
+
+This Space runs the unified CarePath product from the root `Dockerfile`, which
+builds one frontend (`scribe/frontend/`) and serves:
+
+- `/` — the public landing page
+- `/kham-song-ngu/` — the bilingual visit: two-way interpretation, document
+  reading, and the clinician confirmation gate
+- `/ghi-chep-lam-sang/` — the Scribe tool
+- `/api/v1/*` — Scribe API, including the visit bridge, document reading and
+  Vietnamese speech
+- `/api/*` and `/ws/*` — Interpreter API
+
+`/phien-dich-y-khoa/` and `/console/` are explicit 404s: the separate
+interpreter console was removed once `/kham-song-ngu/` replaced it.
+
+## Required Space secrets
+
+Scribe:
+
+- `LLM_PROVIDER=ckey`
+- `LLM_API_KEY=<your CKey key>`
+- `LLM_MODEL=gpt-5.4`
+- `TEAM_CODE=<shared internal bypass code>`
+- `APP_ENV=prod`
+
+Interpreter — one variable, **required for `/kham-song-ngu/` to translate**.
+Without it the module stays in mock mode and returns `[vi->en] …` echoes, which
+look like a broken product to a visitor. It reuses the `LLM_*` secrets above,
+so nothing else is needed:
+
+- `PROVIDER_MODE=ckey`
+
+Measured ckey latency across 50 turns: median 15s, p90 54s, max 206s. That is
+a gateway limit, not an architectural one, but it is what a live visitor will
+experience.
+
+Vietnamese text-to-speech is optional. The model is not baked into the image,
+so `/api/v1/speech` returns 503 and the browser voice is used instead.

README.md

@@ -0,0 +1,45 @@
+---
+title: CarePath
+sdk: docker
+app_port: 7860
+---
+
+# CarePath Space
+
+This Space runs the unified CarePath product from the root `Dockerfile`, which
+builds one frontend (`scribe/frontend/`) and serves:
+
+- `/` — the public landing page
+- `/kham-song-ngu/` — the bilingual visit: two-way interpretation, document
+  reading, and the clinician confirmation gate
+- `/ghi-chep-lam-sang/` — the Scribe tool
+- `/api/v1/*` — Scribe API, including the visit bridge, document reading and
+  Vietnamese speech
+- `/api/*` and `/ws/*` — Interpreter API
+
+`/phien-dich-y-khoa/` and `/console/` are explicit 404s: the separate
+interpreter console was removed once `/kham-song-ngu/` replaced it.
+
+## Required Space secrets
+
+Scribe:
+
+- `LLM_PROVIDER=ckey`
+- `LLM_API_KEY=<your CKey key>`
+- `LLM_MODEL=gpt-5.4`
+- `TEAM_CODE=<shared internal bypass code>`
+- `APP_ENV=prod`
+
+Interpreter — one variable, **required for `/kham-song-ngu/` to translate**.
+Without it the module stays in mock mode and returns `[vi->en] …` echoes, which
+look like a broken product to a visitor. It reuses the `LLM_*` secrets above,
+so nothing else is needed:
+
+- `PROVIDER_MODE=ckey`
+
+Measured ckey latency across 50 turns: median 15s, p90 54s, max 206s. That is
+a gateway limit, not an architectural one, but it is what a live visitor will
+experience.
+
+Vietnamese text-to-speech is optional. The model is not baked into the image,
+so `/api/v1/speech` returns 503 and the browser voice is used instead.

UI-FIX-PLAN.md

@@ -0,0 +1,154 @@
+# UI Fix Plan — carepath-omega.vercel.app (scribe/frontend/)
+
+Plan authored by Fable 5 after reviewing the live deploy and source. Executor: Opus 4.8.
+Scope: the Vite/React app in `scribe/frontend/` only. Do the fixes in order. Keep diffs minimal — no redesigns, no new dependencies.
+
+## How findings were verified (and how you re-verify)
+
+The live site was screenshotted and probed with the repo's own Playwright
+(`scribe/frontend/node_modules/playwright-core`, headless Chromium) at 1440/1100/900/800/390px widths.
+Re-run any probe the same way, e.g.:
+
+```js
+// node, from scribe/frontend/: require('playwright-core'), launch chromium,
+// newPage({ viewport }), goto https://carepath-omega.vercel.app/ (or local `npm run preview`)
+```
+
+Verify locally against `npm run dev`/`preview` in `scribe/frontend/` — do not deploy to verify.
+
+## Do NOT chase these (verified non-issues)
+
+Full-page/element screenshots of this site produce artifacts because of the sticky nav and
+GSAP scroll animations. Already confirmed fine:
+
+- Hero "Audio → SOAP" strip overhanging its card (`.hero__route--scribe { right: -3% }`) is an
+  intentional accent. `document.scrollWidth - clientWidth === 0` at all tested widths — no
+  horizontal overflow anywhere.
+- Grey band across the bottom of the safety bento in screenshots = GSAP scrub timeline
+  (`scribe/frontend/src/landing/useLandingMotion.ts:45-68`) caught mid-state. Renders correctly live.
+- Scribe chapter body text is complete in source (`scribe/frontend/src/content/strings.ts:340`); the
+  "truncation" seen in captures was the sticky nav bar overlaying a line during scroll-stitching.
+- Marquee is 48px tall and animates correctly; "clipped text" in captures is the same stitching
+  artifact.
+
+---
+
+## P0-1: Lead contact path is dead on production
+
+**Symptom:** Footer "Liên hệ chương trình thí điểm" renders `href="mailto:"` (no recipient).
+Submitting the pilot lead form opens a recipient-less mail draft and then shows the success-ish
+"mail opened" status. The site's only conversion path silently goes nowhere.
+
+**Root cause:** Neither `VITE_LEAD_ENDPOINT` nor `VITE_LEAD_EMAIL` is set in the Vercel project.
+`submitLead()` falls through to `buildLeadMailto(payload, email = "")`
+(`scribe/frontend/src/leads.ts:88-130`). The deploy gate `scribe/frontend/scripts/validate-deploy-env.mjs` only
+validates `VITE_API_BASE` + `VITE_CONSOLE_URL`, so the build passed anyway
+(`scribe/frontend/vercel.json` runs `npm run validate:deploy && npm run build`).
+
+**Fix (all three parts):**
+1. `scribe/frontend/scripts/validate-deploy-env.mjs`: require at least one lead channel — error if both
+   `VITE_LEAD_ENDPOINT` and `VITE_LEAD_EMAIL` are empty. Extend
+   `scribe/frontend/scripts/validate-deploy-env.test.mjs` accordingly (`npm run test:deploy-env`).
+2. UI guard, belt-and-suspenders:
+   - `scribe/frontend/src/leads.ts` / `scribe/frontend/src/LeadForm.tsx`: if no endpoint and no email, `submitLead`
+     must not open `mailto:` and the form must show the existing error status (`labels.failed`
+     path) instead of "mail opened". Never report success for a no-op.
+   - `scribe/frontend/src/LandingPage.tsx:476-478`: don't render the footer mailto link when
+     `VITE_LEAD_EMAIL` is empty (render the text non-linked, or drop it).
+   - Existing tests mock `leadEmail`/`endpoint` props (`scribe/frontend/src/LeadForm.test.tsx`,
+     `scribe/frontend/src/leads.test.ts`) — add the empty-config case.
+3. Tell the user to set `VITE_LEAD_EMAIL` (and optionally `VITE_LEAD_ENDPOINT`) in the Vercel
+   project settings — the value is a business decision; do not invent one. The code fix must be
+   correct with or without it.
+
+**Accept when:** with no lead env vars, footer shows no dead link and form submit shows an error,
+not success; `npm run test` and `npm run test:deploy-env` pass; with `VITE_LEAD_EMAIL` set the
+mailto contains the recipient.
+
+## P0-2: Mobile nav menu opens off-screen — links unusable on phones
+
+**Symptom:** At 390×844, opening the hamburger shows a white panel whose link labels are
+invisible. Measured panel box: `x = -108, width = 304` — a third of it (including all left-padded
+label text) is past the left viewport edge. At 900px the panel floats detached mid-nav
+(`x = 225`) under the centered button.
+
+**Root cause:** `scribe/frontend/src/styles.css:2267-2277` — `.site-nav__menu > div` is
+`position: absolute; right: 0` anchored to `.site-nav__menu` (`position: relative`, line 2248),
+i.e. to the 2.6rem hamburger itself, which sits mid-nav between the brand and the VI/EN toggle.
+The 19rem-wide panel extends leftward from there.
+
+**Fix:** Anchor the panel to the nav bar, not the button. `.site-nav` is `position: sticky`
+(styles.css:129-141) and therefore already a containing block for absolute descendants — the
+smallest fix is to drop `position: relative` from `.site-nav__menu` (line 2248) and give the
+panel a right offset matching the nav padding (`right: max(1.5rem, calc((100vw - var(--container)) / 2))`
+at ≥761px; `1rem`-ish at ≤760px — mirror the nav's own padding values). Keep
+`width: min(19rem, calc(100vw - 2rem))`.
+
+**Accept when:** at 320, 390, 760, and 900px widths the open panel's bounding box is fully inside
+the viewport, flush near the right edge below the bar, and every link label is visible.
+
+## P0-3: Menu never closes after navigating
+
+**Symptom:** Tap hamburger → tap "An toàn" → page scrolls to the section but the `<details>`
+panel stays open, covering the content just navigated to. Verified: `.site-nav__menu[open]`
+still present after link click.
+
+**Root cause:** Native `<details>` doesn't close on child anchor clicks
+(`scribe/frontend/src/LandingPage.tsx:60-63`).
+
+**Fix:** In `LandingPage.tsx`, close the details when a menu link is clicked (e.g. `onClick` on
+the wrapping div or each link that clears the `open` attribute via a ref). Keep it a few lines —
+no state library, no outside-click handler unless it's free.
+
+**Accept when:** tapping any menu link scrolls to the section AND the panel is closed.
+
+## P1-1: Evidence section headline wraps 2 words × 6 lines on desktop
+
+**Symptom:** At 1440px, "Xem cách mỗi sản phẩm giữ điểm cần duyệt ở đúng chỗ." renders 64px in a
+379px-wide column → 6 cramped lines. Measured: `{w: 379, fs: 64px, lines: 6}`; still 4 lines at
+1100px. Inside the carousel the slide `h3` (up to 2.6rem in a ~270px column,
+`.evidence-slide` col `minmax(13rem, 0.65fr)`, styles.css:2062-2094) wraps ~5 lines the same way.
+
+**Root cause:** `.evidence` grid gives the intro `minmax(16rem, 0.55fr)` of a 74rem container
+minus up to 8rem gap (styles.css:2049-2056), while `.section-intro h2` uses the global
+`clamp(2rem, 4.5vw, 4rem)` scale (styles.css:1615-1618) sized for full-width intros.
+
+**Fix:** Scoped override, not a layout rework — e.g.
+`.evidence .section-intro h2 { font-size: clamp(1.8rem, 2.2vw, 2.5rem); }` and similarly cap
+`.evidence-slide__copy h3` (~`clamp(1.4rem, 1.8vw, 1.9rem)`). Alternatively rebalance the column
+(`0.55fr → 0.75fr`) plus a smaller cap — pick whichever reads best live, but the acceptance bar
+is below. Don't touch other sections' headings.
+
+**Accept when:** at 1280–1600px the evidence h2 wraps ≤3 lines with ≥3 words per line, and each
+slide h3 wraps ≤3 lines; ≤1023px layouts (already fine) unchanged.
+
+## P2 (do only after P0/P1; each is a 1–2 line change)
+
+- **Sticky nav dissolves into the page while scrolling.** `--nav-bg` ≈ page beige at 0.92 alpha
+  with only a hairline border (styles.css:129-141), so the floating VI/EN pill + hamburger appear
+  to sit directly on content text mid-scroll (most visible on mobile). Add a subtle
+  `box-shadow` (or slightly stronger bottom border) to `.site-nav` so the bar reads as a surface.
+- **Marquee labels are 11.84px** (`.marquee__track span`, `font-size: 0.74rem`,
+  styles.css:780-791) — uppercase microtext below the 12px floor; bump to `0.78rem`.
+- **Demo controls wrap ragged on mobile:** in `.demo__controls`
+  (`scribe/frontend/src/demo/DemoPlayer.tsx:251`, styles for it in styles.css) "Phát lại" wraps to an orphan
+  row at 390px. Make the wrap intentional (consistent gap; buttons full-width or evenly split at
+  ≤760px — match `.product-chapter__actions`' existing pattern at styles.css:2429-2433).
+
+## Verification (run all from `scribe/frontend/`)
+
+1. `npm run lint`, `npm run test`, `npm run test:deploy-env` — all green.
+2. `npm run build` — green WITH lead env vars; FAILS with a clear message when both lead vars are
+   missing (new validator rule). `npm run dev` for visual checks.
+3. Playwright probe (as above) against local dev at 390 / 760 / 900 / 1440px:
+   menu panel fully in-viewport, closes on navigate; evidence h2 line counts within budget;
+   `scrollWidth === clientWidth` (no new horizontal overflow at any width).
+4. Both languages (VI default, EN toggle) and `#/scribe` route still render — `App.test.tsx`,
+   `LandingPage.test.tsx`, `ScribeTool.test.tsx` cover regressions.
+5. The build's `check-diacritics.mjs` runs inside `npm run build` — any copy you touch must keep
+   Vietnamese diacritics intact.
+
+## Out of scope
+
+Backend/`scribe/carepath`, the HF-space console (external `VITE_CONSOLE_URL` target), `interpreter/frontend/`
+(separate app), content rewrites, redesigns, new sections, dependencies.

data/medical_lexicon.json

@@ -0,0 +1,215 @@
+{
+  "terms": [
+    {
+      "term": "SpO2",
+      "category": "vital_sign",
+      "vietnamese": "độ bão hòa oxy",
+      "aliases": ["spo2", "saturation", "oxy máu"]
+    },
+    {
+      "term": "ECG",
+      "category": "test",
+      "vietnamese": "điện tâm đồ",
+      "aliases": ["ekg", "electrocardiogram"]
+    },
+    {
+      "term": "HbA1c",
+      "category": "biomarker",
+      "vietnamese": "đường huyết trung bình",
+      "aliases": ["hba1c", "a1c"]
+    },
+    {
+      "term": "glucose",
+      "category": "biomarker",
+      "vietnamese": "đường huyết",
+      "aliases": ["blood sugar", "đường máu"]
+    },
+    {
+      "term": "insulin",
+      "category": "medication",
+      "vietnamese": "insulin",
+      "aliases": ["in-su-lin"]
+    },
+    {
+      "term": "metformin",
+      "category": "medication",
+      "vietnamese": "metformin",
+      "aliases": ["met for min", "mét-pho-min"]
+    },
+    {
+      "term": "hypertension",
+      "category": "condition",
+      "vietnamese": "tăng huyết áp",
+      "aliases": ["cao huyết áp", "high blood pressure"]
+    },
+    {
+      "term": "diabetes mellitus",
+      "category": "condition",
+      "vietnamese": "đái tháo đường",
+      "aliases": ["tiểu đường", "diabetes"]
+    },
+    {
+      "term": "COPD",
+      "category": "condition",
+      "vietnamese": "bệnh phổi tắc nghẽn mạn tính",
+      "aliases": ["copd", "bệnh phổi tắc nghẽn"]
+    },
+    {
+      "term": "asthma",
+      "category": "condition",
+      "vietnamese": "hen phế quản",
+      "aliases": ["hen suyễn"]
+    },
+    {
+      "term": "BMI",
+      "category": "biometric",
+      "vietnamese": "chỉ số khối cơ thể",
+      "aliases": ["body mass index"]
+    },
+    {
+      "term": "creatinine",
+      "category": "biomarker",
+      "vietnamese": "creatinin",
+      "aliases": ["creatinin"]
+    },
+    {
+      "term": "eGFR",
+      "category": "biomarker",
+      "vietnamese": "mức lọc cầu thận ước tính",
+      "aliases": ["egfr", "gfr"]
+    },
+    {
+      "term": "CRP",
+      "category": "biomarker",
+      "vietnamese": "protein phản ứng C",
+      "aliases": ["c reactive protein"]
+    },
+    {
+      "term": "WBC",
+      "category": "biomarker",
+      "vietnamese": "bạch cầu",
+      "aliases": ["white blood cell", "leukocyte"]
+    },
+    {
+      "term": "hemoglobin",
+      "category": "biomarker",
+      "vietnamese": "huyết sắc tố",
+      "aliases": ["hb"]
+    },
+    {
+      "term": "platelet",
+      "category": "biomarker",
+      "vietnamese": "tiểu cầu",
+      "aliases": ["plt"]
+    },
+    {
+      "term": "sodium",
+      "category": "biomarker",
+      "vietnamese": "natri",
+      "aliases": ["na", "na+"]
+    },
+    {
+      "term": "potassium",
+      "category": "biomarker",
+      "vietnamese": "kali",
+      "aliases": ["k", "k+"]
+    },
+    {
+      "term": "ALT",
+      "category": "biomarker",
+      "vietnamese": "men gan ALT",
+      "aliases": ["sgpt"]
+    },
+    {
+      "term": "AST",
+      "category": "biomarker",
+      "vietnamese": "men gan AST",
+      "aliases": ["sgot"]
+    },
+    {
+      "term": "ultrasound",
+      "category": "test",
+      "vietnamese": "siêu âm",
+      "aliases": ["sonography"]
+    },
+    {
+      "term": "X-ray",
+      "category": "test",
+      "vietnamese": "x-quang",
+      "aliases": ["xray", "x quang"]
+    },
+    {
+      "term": "CT",
+      "category": "test",
+      "vietnamese": "chụp cắt lớp vi tính",
+      "aliases": ["ct scan", "computed tomography"]
+    },
+    {
+      "term": "MRI",
+      "category": "test",
+      "vietnamese": "chụp cộng hưởng từ",
+      "aliases": ["magnetic resonance imaging"]
+    },
+    {
+      "term": "pneumonia",
+      "category": "condition",
+      "vietnamese": "viêm phổi",
+      "aliases": ["lung infection"]
+    },
+    {
+      "term": "tachycardia",
+      "category": "finding",
+      "vietnamese": "nhịp tim nhanh",
+      "aliases": ["tim nhanh"]
+    },
+    {
+      "term": "bradycardia",
+      "category": "finding",
+      "vietnamese": "nhịp tim chậm",
+      "aliases": ["tim chậm"]
+    },
+    {
+      "term": "systolic",
+      "category": "vital_sign",
+      "vietnamese": "huyết áp tâm thu",
+      "aliases": ["tâm thu"]
+    },
+    {
+      "term": "diastolic",
+      "category": "vital_sign",
+      "vietnamese": "huyết áp tâm trương",
+      "aliases": ["tâm trương"]
+    },
+    {
+      "term": "testosterone",
+      "category": "hormone",
+      "vietnamese": "testosterone",
+      "aliases": ["testosteron"]
+    },
+    {
+      "term": "dihydrotestosterone",
+      "category": "hormone",
+      "vietnamese": "dihydrotestosterone",
+      "aliases": ["dht"]
+    },
+    {
+      "term": "Bartholin",
+      "category": "anatomy",
+      "vietnamese": "tuyến Bartholin",
+      "aliases": ["bartholins"]
+    },
+    {
+      "term": "methionine",
+      "category": "biochemistry",
+      "vietnamese": "methionin",
+      "aliases": ["methionin"]
+    },
+    {
+      "term": "glutathione",
+      "category": "biochemistry",
+      "vietnamese": "glutathion",
+      "aliases": ["glutathion"]
+    }
+  ]
+}
+

docs/ARCHITECTURE.md

@@ -0,0 +1,42 @@
+# CarePath Architecture
+
+CarePath is one FastAPI deployment with two separately named clinical workflows.
+The combined entrypoint is `scribe/carepath/main.py`; it owns the Scribe API,
+imports the Interpreter routers from `interpreter/app`, and mounts both built Vite
+frontends after API routes.
+
+## Product Boundaries
+
+| Workflow | Backend boundary | Browser surface |
+| --- | --- | --- |
+| Ghi chép bệnh án AI | `scribe/carepath`, `/api/v1/*` | `scribe/frontend/` at `/`, including `/ghi-chep-lam-sang/` |
+| Khám bệnh nhân nước ngoài | `interpreter/app`, `/api/*` and `/ws/*` | `scribe/frontend/` at `/kham-song-ngu/` |
+
+Both browser surfaces now ship from `scribe/frontend/`. The separate interpreter
+console was deleted when the bilingual visit replaced it; `/phien-dich-y-khoa/`
+and `/console/` return an explicit 404 for anyone holding an old link. The two
+API namespaces intentionally do not overlap.
+
+`scribe/training/` is exclusively the Scribe's offline DARAG/GEC training and quality
+track. It does not train or serve the Interpreter. `interpreter/eval/` is a
+separate deterministic translation-safety harness that stays with the
+Interpreter.
+
+## Boundaries That Must Stay Explicit
+
+- Scribe output is a clinician-reviewed draft; it does not replace clinical
+  judgment.
+- Interpreter output is translation only. High or critical risk stays blocked
+  from patient display and TTS until clinician confirmation.
+- Interpreter audio is memory-only: no raw-audio persistence, no microphone
+  capture before consent, and failures fail closed.
+- Risk lexicons and glossary seeds are editable JSON/CSV data, not code.
+- Providers, environment variables, HTTP/WebSocket payloads, uploaded files,
+  and database rows are trust boundaries and must be parsed before use.
+
+## Delivery and Proof
+
+The shared process serves built static assets in production; Vite dev servers
+remain the development path. Existing Python, eval, frontend, browser, build,
+and Lighthouse commands are the validation ladder. Do not add a second service,
+state framework, or test runner unless a selected story proves the need.

docs/CONTEXT_RULES.md

@@ -0,0 +1,19 @@
+# CarePath Context Rules
+
+Read enough to preserve the selected contract, not the entire repository.
+
+| Lane | Required context before implementation |
+| --- | --- |
+| Tiny | `AGENTS.md`, `docs/FEATURE_INTAKE.md`, matrix query, and exact files to change |
+| Normal | Tiny context plus relevant product contract, story, validation command, and architecture when a boundary changes |
+| High-risk | Normal context plus relevant decisions, high-risk template, safety/eval fixtures, and every affected module boundary |
+
+Always read the current task's validation evidence before recording its trace.
+For product or UX work, read the appropriate `docs/product/` contract; for UX
+flows also read `docs/ux-redesign-carepath.md`. For risk, consent, TTS, audio,
+or provider work, read `AGENTS.md` safety invariants and the affected tests and
+fixtures before editing.
+
+Stop reading unrelated history once the lane, contract, affected files, and
+proof path are clear. Search targeted paths with `rg` rather than loading broad
+archives.

docs/DEMO_RUNBOOK.md

@@ -0,0 +1,94 @@
+# Demo runbook
+
+One page. Everything measured, nothing assumed.
+
+## Before you leave
+
+```bash
+cd scribe/frontend && npm run build
+```
+
+**Always rebuild after `npm run e2e`.** The e2e build points the bundle at
+`https://carepath-e2e.example` and the served app silently breaks. This has cost
+an hour once already.
+
+Confirm the Vietnamese voice is staged at a **short** path:
+
+```bash
+ls models/vi-tts/espeak-ng-data
+```
+
+espeak-ng reads that directory with a native call that fails past the Windows
+`MAX_PATH` limit, so the model cannot live in the HuggingFace cache.
+
+## Run it
+
+```bash
+uvicorn carepath.main:app --app-dir scribe --port 8000
+```
+
+`.env` is already set to `PROVIDER_MODE=demo`. Open **Chrome** at
+`http://127.0.0.1:8000/kham-song-ngu/`.
+
+Demo mode is scripted and makes **zero outbound network calls** — verified by
+running the whole flow with the socket connect path poisoned. The venue wifi
+cannot break the demo.
+
+## The four minutes
+
+| Beat | What you do | What the judge sees |
+|---|---|---|
+| **Problem** | Open `/` first and **wait two seconds before speaking** | A Vietnamese prescription at full size, then the English resolving under each line. Scroll once: 29,5% against 49,1%, the three highest-risk moments, the two priced incumbents |
+| **Start** | Age 34, nam, "nổi mẩn da" | One screen, no login, no settings |
+| **Conversation** | Type or speak the scripted lines | English in, Vietnamese out, entity chips appearing |
+| **Safety** | *"I take 15 milligrams"* | Red gate, 42% confidence, back-translation. **The patient pane shows nothing.** Click **Sửa**, correct to 500 mg, confirm |
+| **Paper** | Photograph the prescription | Four lines read, each with drug / dose / frequency chips, all gated |
+| **Finish** | Kết thúc và tạo hồ sơ | Vietnamese record, English patient packet, medication list |
+
+Scripted lines are in `interpreter/app/providers/demo_scenario.json`. Anything
+off-script falls back to a visible `[en->vi] …` placeholder rather than failing.
+
+The landing page's opening animation is the whole pitch in two seconds — let it
+finish before you talk over it. It also sets up the **Paper** beat: the judge
+has already seen the object you are about to photograph.
+
+## What to say when asked
+
+**"Isn't this just Google Translate?"**
+The confirm endpoint returns 409 from any state but `awaiting_confirm`. 91 risk
+fixtures across 30 named failure modes, including cross-lingual number and
+negation mismatch. A translator has no state machine and no clinician.
+
+**"Did the AI decide that was dangerous?"**
+No. The vision model only transcribes. Every line goes through the same rule
+engine that guards spoken turns, so a look-alike drug name is caught by tested
+code, not a model's judgement.
+
+**"What are your numbers?"**
+A 50-case set through the live gateway: drug name, numbers, dose units and
+laterality all **100%**. Negation polarity **98%**.
+
+If asked about the missing 2%: one case, `Ngưng thuốc` → `Discontinue the
+medication`. The negation is preserved; `discontinue` simply is not in our cue
+list. We did not add it, because tuning the lexicon until the eval reads 100%
+would make the eval measure nothing. That turn was gated for clinician
+confirmation regardless — which is the actual point.
+
+Report at `interpreter/eval/reports/ckey/`. Numbers move slightly run to run;
+re-run before the pitch if you want the page to match exactly.
+
+## If something breaks
+
+| Symptom | Do this |
+|---|---|
+| Microphone denied or mis-hears | Type instead. Every turn has a typed input beside the mic |
+| A turn errors | Say it again. Turns are independent; nothing is lost |
+| Page reloads mid-visit | It resumes. The visit id is in `sessionStorage` and the server replays the transcript |
+| Document read fails | It adds nothing and says so. Move on to finishing the visit |
+| Everything is slow | You are on `ckey`. Set `PROVIDER_MODE=demo` and restart |
+
+## Showing the real AI path
+
+Set `PROVIDER_MODE=ckey` and restart. Measured across 50 turns: **median 15s,
+p90 54s, max 206s**. Do one turn, not a whole visit, and say the number out
+loud — it is a gateway limit, not an architectural one.

docs/FEATURE_INTAKE.md

@@ -0,0 +1,51 @@
+# CarePath Feature Intake
+
+Every implementation request is classified before code changes. Record the
+classification with `.\scripts\bin\harness-cli.exe intake`.
+
+## Input Types
+
+| Type | Use when | Typical artifact |
+| --- | --- | --- |
+| Change request | Bounded behavior, bug, copy, or UX refinement | Direct patch or story |
+| New initiative | A new product area spanning multiple stories | Initiative note and stories |
+| Maintenance request | Dependency, performance, delivery, or operational work | Story or decision |
+| Harness improvement | Process, proof, template, or instruction work | Harness docs and trace |
+
+## Lanes
+
+### Tiny
+
+Use for narrow docs, copy, or isolated maintenance with no safety, API, data,
+or multi-module impact. Record intake, patch directly, and run the relevant
+quick proof. A UX or product-flow change still updates
+`docs/ux-redesign-carepath.md` first.
+
+### Normal
+
+Use for a bounded change to one product surface or shared implementation. Create
+or update one story packet, define the validation, update proof flags, and
+record a standard trace.
+
+### High-Risk
+
+Use `docs/templates/high-risk-story/` and record a durable decision when the
+work changes safety behavior, architecture, data ownership, public API shape,
+or validation policy. Ask the user before implementing when the direction is
+ambiguous.
+
+## CarePath Hard Gates
+
+The following are always high-risk:
+
+- Consent, microphone capture, raw-audio handling, retention, or privacy.
+- Interpreter risk classification, confidence display, patient display, TTS,
+  escalation, or fail-closed behavior.
+- Medical advice boundaries, provider behavior, credentials, or external
+  clinical data.
+- Public API or WebSocket contract changes, database migrations, or changes
+  that span the Scribe and Interpreter modules.
+- Removing or weakening existing safety or validation requirements.
+
+Use the existing test and eval fixtures whenever a risk-engine rule changes;
+zero misses on critical fixtures remains a hard gate.

docs/GLOSSARY.md

@@ -0,0 +1,144 @@
+# Glossary
+
+## Agent
+
+An AI coding collaborator operating inside the repository.
+
+## Harness
+
+The repo-level operating system that tells humans and agents how to turn intent
+into safe product changes.
+
+## Product Contract
+
+The current expected behavior of the product. Product docs plus executable tests
+become the living contract once implementation exists.
+
+## Story Packet
+
+A story-sized work file or folder that describes the product contract, affected
+docs, design notes, and validation expectations for a feature.
+
+## Feature Intake
+
+The classification step that turns a prompt into tiny, normal, or high-risk
+work before implementation begins.
+
+## Component Taxonomy
+
+A map from Harness files and capabilities to the responsibilities they serve,
+used to evaluate coverage, attribute failures, and identify missing harness
+capabilities.
+
+## Maturity Level
+
+A verifiable stage in Harness capability, from H0 bare environment through H5
+self-improving harness. Each level has required files, criteria, and benchmark
+indicators.
+
+## Trace Quality Tier
+
+The expected depth of a task trace: minimal for tiny work, standard for normal
+work, and detailed for high-risk work.
+
+## Verification Gate
+
+An advisory Harness check that runs or inspects mechanical proof before a task
+is closed. In Phase 4, `story verify <id>` executes a story's `verify_command`,
+`story verify-all` runs all configured story proof commands, and
+`trace --story <id>` warns when that story's verification has not passed.
+
+## Tool Registry
+
+The compiled and registered tool manifest exposed by
+`scripts/bin/harness-cli query tools`. It lets agents discover available
+commands, arguments, responsibilities, and custom project tools.
+
+## Intervention
+
+A durable record of human, reviewer, CI, or agent feedback that corrected,
+overrode, escalated, or approved work. Interventions are stored separately from
+traces and feed improvement proposals.
+
+## Context Score
+
+The advisory result from `scripts/bin/harness-cli score-context <trace-id>`.
+It compares a trace's recorded `files_read` against compiled context rules and
+retrieval triggers.
+
+## Entropy Score
+
+The drift score printed by `scripts/bin/harness-cli audit`. Lower is better.
+It counts stale or incomplete durable records such as orphaned stories,
+unverified proof commands, missing backlog outcomes, and broken registered
+tools.
+
+## Improvement Proposal
+
+A structured recommendation generated by `scripts/bin/harness-cli propose` from
+repeated friction, intervention patterns, and audit findings. Proposals are
+advisory unless committed to the backlog with `--commit`.
+
+## Context Phase
+
+A phase of an agent task that changes what context should be read, such as
+intake, planning, implementation, validation, or trace recording.
+
+## Retrieval Trigger
+
+A condition that tells an agent to fetch additional context, such as touching a
+database schema, changing a public contract, or discovering missing validation.
+
+## Harness Delta
+
+A documentation, template, validation, backlog, or decision update that makes
+future agent work safer or easier.
+
+## Backlog Outcome Loop
+
+The feedback workflow for Harness improvements: record predicted impact when a
+backlog item is created, then record actual measured outcome when the item is
+closed so future agents can compare expectation with result.
+
+## Durable Layer
+
+The SQLite database and CLI (`scripts/bin/harness-cli`) that stores operational records
+(intakes, stories, decisions, backlog items, traces) as structured, queryable
+data. Policy docs describe how to work; the durable layer stores what happened.
+
+## Product Delta
+
+A product-facing change such as code, tests, API shape, data model, or product
+documentation.
+
+## Trace
+
+A structured record of what an agent did during a task: actions taken, files
+read, files changed, decisions made, errors encountered, outcome, and any
+harness friction discovered.
+
+## Tool Registry
+
+The compiled and user-registered tool manifest exposed by
+`scripts/bin/harness-cli query tools` and documented in `docs/TOOL_REGISTRY.md`.
+
+## Intervention
+
+A durable record of a human, reviewer, CI, or agent correction, override,
+escalation, or approval that is separate from the normal task trace.
+
+## Context Score
+
+The advisory result from `scripts/bin/harness-cli score-context <trace-id>`,
+which compares a trace's recorded reads against compiled context rules.
+
+## Entropy Score
+
+The drift score from `scripts/bin/harness-cli audit`. Lower scores mean fewer
+orphaned, stale, unverified, outcome-missing, or broken-tool records.
+
+## Improvement Proposal
+
+A structured proposal generated by `scripts/bin/harness-cli propose` from
+repeated friction, interventions, and audit drift. Proposals can be committed as
+backlog items with `--commit`.

docs/HARNESS.md

@@ -0,0 +1,65 @@
+# CarePath Harness
+
+CarePath uses Repository Harness to turn a request into safe, reviewable work.
+The application is what clinicians use; the Harness is the durable operating
+layer for humans and coding agents.
+
+## Sources of Truth
+
+Apply sources in this order:
+
+1. Current user instruction and the safety, Vietnamese-first, and UX rules in
+   `AGENTS.md`.
+2. The current contracts in `docs/product/`.
+3. The selected story packet in `docs/stories/` and accepted decisions in
+   `docs/decisions/`.
+4. Executable tests and the proof matrix.
+5. `docs/history/` and research as background, unless a current contract
+   explicitly incorporates them.
+
+No Harness document may weaken a CarePath safety invariant. If sources conflict,
+pause and ask the user rather than choosing a less-safe interpretation.
+
+## Durable Layer
+
+`scripts/bin/harness-cli.exe` manages the local, ignored `harness.db` using the
+versioned migrations in `scripts/schema/`. Initialize it once per clone:
+
+```powershell
+.\scripts\bin\harness-cli.exe init
+```
+
+The database records intake classifications, story proof, decisions, traces,
+and Harness friction. Markdown remains the reviewable product record; the
+database records what happened locally.
+
+## Task Loop
+
+1. Read `AGENTS.md`, this file, `docs/FEATURE_INTAKE.md`, and the current
+   matrix.
+2. Classify and record the request with `harness-cli.exe intake`.
+3. Read only the affected product contract, stories, decisions, and code.
+4. Define the proof before implementation.
+5. Implement only the selected lane.
+6. Update the product contract, story, and matrix when the change affects them.
+7. Run the applicable existing checks and record their actual result.
+8. Record a trace. Capture repeated missing context or proof as Harness
+   friction or a backlog item.
+
+For UX or product-flow work, `AGENTS.md` additionally requires an updated
+`docs/ux-redesign-carepath.md` before implementation. That requirement applies
+even when intake classifies the edit as tiny.
+
+## Tool Registry
+
+The registry is optional. Before relying on an external tool, query it by
+capability. If no present provider is registered, skip that optional step and
+record the limitation only when it affects proof. Do not add a dependency or
+tool registration merely to satisfy the Harness.
+
+## Done
+
+A task is done when its requested change is complete, relevant contracts and
+proof records are current, the applicable checks have real results, and the
+trace says what happened. A failed unrelated existing check is recorded as
+failed proof; repairing it requires separate scope.

docs/HARNESS_AUDIT.md

@@ -0,0 +1,38 @@
+# Harness Audit
+
+`scripts/bin/harness-cli audit` detects drift in durable Harness state and
+prints an entropy score. Lower is better.
+
+## Checks
+
+| Category | Meaning | Weight |
+| --- | --- | --- |
+| Orphaned stories | Planned or in-progress stories with no linked trace. | 10 |
+| Unverified stories | Active or implemented stories with `verify_command` but no recorded verification result. Retired stories are historical records and are not counted. | 5 |
+| Unverified decisions | Decisions with `verify_command` but no recorded verification result. | 5 |
+| Open backlog without outcomes | Implemented backlog items with predicted impact but no actual outcome. | 2 |
+| Stale stories | Unimplemented stories whose latest linked trace is more than 30 days old. | 3 |
+| Broken tools | Registered tools whose command is not found on disk or `PATH`. | 8 |
+
+## Score
+
+```text
+score = orphaned_stories * 10
+      + unverified_stories * 5
+      + unverified_decisions * 5
+      + backlog_without_outcomes * 2
+      + stale_stories * 3
+      + broken_tools * 8
+```
+
+The score is capped at 100.
+
+| Range | Interpretation |
+| --- | --- |
+| 0 | Perfect: records are traced, verified, and healthy. |
+| 1-25 | Healthy: minor housekeeping remains. |
+| 26-50 | Attention needed: drift is accumulating. |
+| 51-100 | Action required: stale state undermines Harness value. |
+
+Audit findings feed `scripts/bin/harness-cli propose`, which can turn repeated
+drift into proposed backlog items.

docs/HARNESS_BACKLOG.md

@@ -0,0 +1,62 @@
+# Harness Backlog
+
+Use this file when an agent discovers a missing harness capability but should
+not change the operating model immediately.
+
+## Template
+
+```md
+## Missing Harness Capability
+
+### Title
+
+Short name.
+
+### Discovered While
+
+Task or story that exposed the gap.
+
+### Current Pain
+
+What was hard, repeated, ambiguous, or unsafe?
+
+### Suggested Improvement
+
+What should be added or changed?
+
+### Risk
+
+Tiny, normal, or high-risk.
+
+CLI value: `--risk tiny`, `--risk normal`, or `--risk high-risk`.
+
+### Status
+
+proposed | accepted | implemented | rejected
+```
+
+## Items
+
+## Future Interpreter Risk-Lexicon Consolidation
+
+### Discovered While
+
+CP-RES-006 term-store consolidation.
+
+### Current Pain
+
+The Interpreter safety lexicons are also clinician-editable data, but they
+govern deterministic risk classification rather than medical-term retrieval.
+
+### Suggested Improvement
+
+Evaluate a separate, clinician-approved consolidation only with a safety-fixture
+and evaluation policy change. Do not merge them into the general term source.
+
+### Risk
+
+high-risk.
+
+### Status
+
+proposed

docs/HARNESS_COMPONENTS.md

@@ -0,0 +1,167 @@
+# Harness Components
+
+This taxonomy maps the current `repository-harness` repository to two
+component frameworks used by Phase 2 and updated by Phase 3 active
+observability work:
+
+- Runtime Substrate responsibilities: the 11 responsibility areas the harness
+  should cover.
+- NexAU decomposition: the seven implementation surfaces that influence agent
+  behavior.
+
+Status values:
+
+- **Covered**: the repository has an explicit file, command, or record for this
+  responsibility.
+- **Partial**: the repository has some support, but the support is incomplete,
+  manual, or not yet measured.
+- **Missing**: no meaningful support exists yet.
+
+## Responsibility Map
+
+| # | Responsibility | Status | Harness Files | Evidence | Gap |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Task specification | Covered | `AGENTS.md`, `docs/FEATURE_INTAKE.md`, `docs/templates/story.md`, `docs/templates/spec-intake.md`, `docs/templates/high-risk-story/*`, `docs/stories/*`, `intake` table, `story` table | Requests are classified by type and lane before implementation; normal and high-risk work have templates and durable story rows. | Keep story packets synchronized with future product docs. |
+| 2 | Context selection | Covered | `AGENTS.md`, `docs/CONTEXT_RULES.md`, `docs/ARCHITECTURE.md`, `docs/decisions/*`, `docs/product/README.md`, `scripts/bin/harness-cli score-context` | Phase 2 adds phase-by-lane context rules and retrieval triggers; Phase 5 adds context scoring against recorded trace reads. | Future automation could enforce context selection instead of only measuring it. |
+| 3 | Tool access | Covered | `scripts/bin/harness-cli`, `docs/TOOL_REGISTRY.md`, `tool` table, `crates/harness-cli/*`, `scripts/install-harness.sh`, `scripts/build-harness-cli-release.sh` | The Harness CLI exposes operational commands and a machine-readable tool manifest through `query tools`; external tools can be registered and removed. | Permission profiles and usage analytics remain future work. |
+| 4 | Project memory | Covered | `docs/HARNESS.md`, `docs/decisions/*`, `docs/GLOSSARY.md`, `docs/HARNESS_BACKLOG.md`, `docs/stories/*`, `harness.db`, `decision`, `backlog`, and `trace` tables | Decisions, backlog, stories, and traces preserve durable knowledge across tasks. | Future work should add staleness checks and summarize old traces. |
+| 5 | Task state | Covered | `scripts/bin/harness-cli query matrix`, `docs/TEST_MATRIX.md`, `intake` table, `story` table, `trace` table | Durable records track intake, story status, proof columns, and task traces. | Add lifecycle checks so in-progress stories cannot be forgotten. |
+| 6 | Observability | Partial | `docs/TRACE_SPEC.md`, `trace` table, `scripts/bin/harness-cli trace`, `scripts/bin/harness-cli score-trace`, `scripts/bin/harness-cli query traces`, `scripts/bin/harness-cli query friction`, `docs/HARNESS_MATURITY.md` | Traces are auto-scored when recorded, can be rescored by command, and can be reviewed with friction context. | No dashboard or benchmark ingestion exists in this repo. |
+| 7 | Failure attribution | Partial | `docs/HARNESS_COMPONENTS.md`, `docs/TRACE_SPEC.md`, `trace.errors`, `trace.harness_friction`, `docs/HARNESS_BACKLOG.md`, `backlog` table, `scripts/bin/harness-cli query friction` | Failures can be tied to files, components, friction, backlog proposals, and linked intake lane/type context. | No automated attribution from benchmark failures to harness components exists yet. |
+| 8 | Verification | Covered | `docs/TEST_MATRIX.md`, `scripts/bin/harness-cli query matrix`, `scripts/bin/harness-cli story verify`, `scripts/bin/harness-cli story verify-all`, `scripts/bin/harness-cli trace`, `scripts/bin/harness-cli score-trace`, `story.verify_command`, `story.last_verified_result`, `.github/workflows/harness-cli-release.yml`, `docs/templates/validation-report.md` | Stories can store and run mechanical proof commands individually or in batch, traces warn when linked story verification has not passed, trace quality can be checked mechanically, and release workflow verifies Rust CLI releases. | Benchmark ingestion remains future work. |
+| 9 | Permissions | Partial | `AGENTS.md`, `docs/HARNESS.md`, `docs/FEATURE_INTAKE.md`, `docs/ARCHITECTURE.md`, installer conflict handling in `scripts/install-harness.sh` | Policy describes when agents may update docs and when to ask before architecture or workflow changes. | Permissions are instruction-level only; no enforced policy layer or command allowlist exists. |
+| 10 | Entropy auditing | Covered | `docs/HARNESS_BACKLOG.md`, `docs/HARNESS_AUDIT.md`, `docs/IMPROVEMENT_PROTOCOL.md`, `backlog` table, `trace.harness_friction`, `scripts/bin/harness-cli audit`, `scripts/bin/harness-cli propose`, `docs/HARNESS_MATURITY.md` | Growth rule captures friction, audit detects drift and entropy score, backlog items compare predicted impact to actual outcome, and proposal generation can create reviewable backlog items. | Automated repair remains future work. |
+| 11 | Intervention recording | Covered | `intervention` table, `scripts/bin/harness-cli intervention add`, `scripts/bin/harness-cli query interventions`, `trace` table, `docs/decisions/*`, `docs/stories/*`, `docs/HARNESS.md` | Human, reviewer, CI, and agent interventions are separate durable records and can be filtered by trace, story, or type. | Capture is still manual and advisory. |
+
+## NexAU Cross-Reference
+
+| Component | Harness Equivalent | Status | Notes |
+| --- | --- | --- | --- |
+| System prompts | `AGENTS.md` plus Harness policy docs | Covered | `AGENTS.md` is the stable shim; `docs/HARNESS.md`, `docs/FEATURE_INTAKE.md`, and `docs/CONTEXT_RULES.md` carry evolving operating instructions. |
+| Tool descriptions | `docs/TOOL_REGISTRY.md`, `scripts/README.md`, `docs/HARNESS.md`, `docs/TRACE_SPEC.md`, CLI help from `crates/harness-cli/src/interface.rs`, `scripts/bin/harness-cli query tools` | Covered | Commands are documented in a standalone registry and exposed as compiled plus registered tool manifest entries. |
+| Tool implementations | `scripts/bin/harness-cli`, `crates/harness-cli/*`, `scripts/schema/001-init.sql`, `scripts/schema/002-story-verify.sql` | Covered | The Rust CLI is the primary durable-layer implementation and stable repo-local entrypoint. |
+| Middleware | installer safety logic, feature intake workflow | Partial | The installer and intake process mediate work, but there is no runtime middleware enforcing policies. |
+| Skills | `docs/templates/*`, `docs/FEATURE_INTAKE.md`, `docs/CONTEXT_RULES.md`, `docs/TRACE_SPEC.md` | Partial | Reusable procedures exist as markdown, not executable or installable agent skills. |
+| Sub-agents | None in this repository | Missing | No delegated specialist agents or sub-agent protocols exist. |
+| Long-term memory | `harness.db`, `docs/decisions/*`, `docs/stories/*`, `docs/HARNESS_BACKLOG.md`, `docs/GLOSSARY.md` | Covered | Durable records and markdown decisions preserve task history and project vocabulary. |
+
+## File Inventory
+
+Every tracked project file plus the Phase 2 input file is mapped to at least
+one Runtime Substrate responsibility.
+
+| File | Primary Responsibility | Secondary Responsibilities |
+| --- | --- | --- |
+| `.gitignore` | Tool access | Task state |
+| `AGENTS.md` | Context selection | Task specification, permissions |
+| `README.md` | Task specification | Project memory |
+| `CONTRIBUTING.md` | Intervention recording | Project memory |
+| `Cargo.toml` | Tool access | Verification |
+| `Cargo.lock` | Tool access | Verification |
+| `PHASE2.md` | Task specification | Observability, context selection |
+| `PHASE3.md` | Task specification | Observability, verification, entropy auditing |
+| `PHASE4.md` | Task specification | Verification, observability, task state |
+| `PHASE5.md` | Task specification | Verification, entropy auditing, intervention recording |
+| `crates/harness-cli/Cargo.toml` | Tool access | Verification |
+| `crates/harness-cli/src/main.rs` | Tool access | Tool implementation |
+| `crates/harness-cli/src/domain.rs` | Tool access | Task state, verification |
+| `crates/harness-cli/src/application.rs` | Tool access | Task state |
+| `crates/harness-cli/src/infrastructure.rs` | Tool access | Project memory, task state, observability |
+| `crates/harness-cli/src/interface.rs` | Tool access | Context selection, verification |
+| `docs/ARCHITECTURE.md` | Permissions | Context selection, task specification |
+| `docs/FEATURE_INTAKE.md` | Task specification | Permissions, context selection |
+| `docs/GLOSSARY.md` | Project memory | Context selection |
+| `docs/HARNESS.md` | Task specification | Project memory, task state, permissions |
+| `docs/HARNESS_BACKLOG.md` | Entropy auditing | Project memory, failure attribution |
+| `docs/HARNESS_COMPONENTS.md` | Failure attribution | Observability, entropy auditing |
+| `docs/HARNESS_MATURITY.md` | Entropy auditing | Observability, verification |
+| `docs/HARNESS_AUDIT.md` | Entropy auditing | Verification, task state |
+| `docs/IMPROVEMENT_PROTOCOL.md` | Entropy auditing | Failure attribution, permissions |
+| `docs/CONTEXT_RULES.md` | Context selection | Permissions, task specification |
+| `docs/TRACE_SPEC.md` | Observability | Failure attribution, intervention recording |
+| `docs/TOOL_REGISTRY.md` | Tool access | Context selection, verification |
+| `docs/README.md` | Project memory | Context selection |
+| `docs/TEST_MATRIX.md` | Verification | Task state |
+| `docs/decisions/0001-harness-first-development.md` | Project memory | Permissions |
+| `docs/decisions/0002-post-spec-product-lifecycle.md` | Project memory | Task specification |
+| `docs/decisions/0003-generic-spec-intake-harness.md` | Project memory | Task specification |
+| `docs/decisions/0004-sqlite-durable-layer.md` | Project memory | Observability, task state |
+| `docs/decisions/0005-prebuilt-rust-harness-cli.md` | Project memory | Tool access |
+| `docs/decisions/0006-phase-4-benchmark-triage.md` | Project memory | Verification |
+| `docs/decisions/0007-improvement-proposal-rules.md` | Project memory | Entropy auditing, permissions |
+| `docs/decisions/README.md` | Project memory | Context selection |
+| `docs/demo/README.md` | Task specification | Project memory |
+| `docs/product/README.md` | Task specification | Project memory |
+| `docs/review-fixes-1d30bf62-to-main.md` | Intervention recording | Failure attribution, verification |
+| `docs/stories/README.md` | Task specification | Project memory |
+| `docs/stories/US-001-install-harness.md` | Task specification | Verification, intervention recording |
+| `docs/stories/US-008-trace-quality-scoring.md` | Task specification | Observability, verification |
+| `docs/stories/US-009-enriched-friction-query.md` | Task specification | Failure attribution, observability |
+| `docs/stories/US-011-backlog-outcome-workflow.md` | Task specification | Entropy auditing, project memory |
+| `docs/stories/US-012-story-verify-command-field.md` | Task specification | Verification |
+| `docs/stories/US-015-story-verify-command.md` | Task specification | Verification |
+| `docs/stories/US-016-auto-trace-scoring-on-write.md` | Task specification | Observability, verification |
+| `docs/stories/US-017-pre-close-verification-gate.md` | Task specification | Verification, permissions |
+| `docs/stories/US-018-phase4-cli-ux-hardening.md` | Task specification | Tool access, verification |
+| `docs/stories/US-019-machine-readable-tool-registry.md` | Task specification | Tool access |
+| `docs/stories/US-020-batch-story-verification.md` | Task specification | Verification |
+| `docs/stories/US-021-intervention-recording-schema.md` | Task specification | Intervention recording |
+| `docs/stories/US-022-context-rule-measurement.md` | Task specification | Context selection |
+| `docs/stories/US-023-drift-detection-entropy-score.md` | Task specification | Entropy auditing |
+| `docs/stories/US-024-improvement-proposal-pipeline.md` | Task specification | Entropy auditing, permissions |
+| `docs/stories/backlog.md` | Task specification | Project memory |
+| `docs/stories/epics/README.md` | Task specification | Project memory |
+| `docs/stories/epics/E01-durable-layer/US-002-rust-harness-cli/overview.md` | Task specification | Project memory |
+| `docs/stories/epics/E01-durable-layer/US-002-rust-harness-cli/design.md` | Task specification | Tool access, permissions |
+| `docs/stories/epics/E01-durable-layer/US-002-rust-harness-cli/execplan.md` | Task specification | Verification, task state |
+| `docs/stories/epics/E01-durable-layer/US-002-rust-harness-cli/validation.md` | Verification | Intervention recording |
+| `docs/stories/epics/E02-phase-2-observability-taxonomy/phase-2-progress.md` | Task state | Intervention recording |
+| `docs/stories/epics/E03-phase-5-evolution-infrastructure/phase-5-progress.md` | Task state | Verification, entropy auditing |
+| `docs/templates/decision.md` | Project memory | Task specification |
+| `docs/templates/spec-intake.md` | Task specification | Context selection |
+| `docs/templates/story.md` | Task specification | Verification |
+| `docs/templates/validation-report.md` | Verification | Intervention recording |
+| `docs/templates/high-risk-story/overview.md` | Task specification | Context selection |
+| `docs/templates/high-risk-story/design.md` | Task specification | Permissions |
+| `docs/templates/high-risk-story/execplan.md` | Task state | Verification |
+| `docs/templates/high-risk-story/validation.md` | Verification | Failure attribution |
+| `scripts/README.md` | Tool access | Context selection |
+| `scripts/bin/harness-cli` | Tool access | Task state, observability |
+| `scripts/bin/harness-cli` | Tool access | Task state, observability |
+| `scripts/install-harness.sh` | Tool access | Permissions |
+| `scripts/build-harness-cli-release.sh` | Verification | Tool access |
+| `scripts/schema/001-init.sql` | Task state | Observability, project memory |
+| `scripts/schema/002-story-verify.sql` | Verification | Task state, project memory |
+| `scripts/schema/003-tool-registry.sql` | Tool access | Project memory |
+| `scripts/schema/004-intervention.sql` | Intervention recording | Failure attribution |
+| `.github/ISSUE_TEMPLATE/agent-failure-case.md` | Failure attribution | Entropy auditing |
+| `.github/ISSUE_TEMPLATE/pattern-request.md` | Entropy auditing | Intervention recording |
+| `.github/ISSUE_TEMPLATE/real-world-example.md` | Project memory | Intervention recording |
+| `.github/workflows/harness-cli-release.yml` | Verification | Tool access |
+
+## Coverage Summary
+
+- Covered: 8/11 responsibilities.
+- Partial: 3/11 responsibilities.
+- Missing: 0/11 responsibilities.
+
+Covered responsibilities:
+
+- Task specification.
+- Context selection.
+- Tool access.
+- Project memory.
+- Task state.
+- Verification.
+- Entropy auditing.
+- Intervention recording.
+Partial responsibilities:
+
+- Observability.
+- Failure attribution.
+- Permissions.
+
+Phase 5 converts tool access, entropy auditing, and intervention recording into
+covered responsibilities with a registry, drift audit, proposal loop, and
+intervention schema. Later phases should focus on benchmark ingestion,
+component-level attribution, permission enforcement, and tool usage analytics.

docs/HARNESS_MATURITY.md

@@ -0,0 +1,316 @@
+# Harness Maturity Ladder
+
+This ladder defines how `repository-harness` should progress from static
+agent instructions to measurable harness improvement.
+
+The levels are intentionally verifiable. A level is achieved only when its
+criteria can be inspected in repository files, durable Harness records, or
+benchmark output.
+
+## Levels
+
+### H0 - Bare Environment
+
+The model operates with no repository harness. It receives a prompt and may
+produce a patch, but the repo does not tell it how to classify, validate, or
+record work.
+
+Criteria:
+
+- No `AGENTS.md` Harness block exists.
+- No feature intake policy exists.
+- No story, decision, validation, or trace artifact exists.
+
+Required files:
+
+- None.
+
+Benchmark indicators:
+
+- Functional score is the only meaningful metric.
+- Harness compliance: 0%.
+- Trace quality: 0/3.
+
+Current status:
+
+- Passed. This repository is beyond H0.
+
+Activated responsibilities:
+
+- None.
+
+### H1 - Scaffolding And Policy
+
+The repository contains static operating instructions, templates, risk lanes,
+and source-of-truth rules. Agents can follow a documented workflow, but durable
+state may still be manual or incomplete.
+
+Criteria:
+
+- `AGENTS.md` points agents to the Harness operating docs.
+- `docs/HARNESS.md`, `docs/FEATURE_INTAKE.md`, and `docs/ARCHITECTURE.md`
+  exist.
+- Story, decision, and validation templates exist under `docs/templates/`.
+- `docs/TEST_MATRIX.md` defines proof columns and status meanings.
+
+Required files:
+
+- `AGENTS.md`
+- `docs/HARNESS.md`
+- `docs/FEATURE_INTAKE.md`
+- `docs/ARCHITECTURE.md`
+- `docs/TEST_MATRIX.md`
+- `docs/templates/story.md`
+- `docs/templates/decision.md`
+- `docs/templates/validation-report.md`
+
+Benchmark indicators:
+
+- Harness compliance: 20-40%.
+- Lane accuracy improves when agents read the intake policy.
+- Trace quality remains low unless traces are separately requested.
+
+Current status:
+
+- Achieved. H1 files exist and are used by current Harness instructions.
+
+Activated responsibilities:
+
+- Task specification.
+- Permissions.
+- Project memory.
+- Verification.
+
+### H2 - Durable State And Observability
+
+The repository has structured operational records and explicit observation
+rules. Agents can record what happened, connect work to stories, and write
+traces with predictable depth.
+
+Criteria:
+
+- `scripts/bin/harness-cli` can record intake, story, decision, backlog, and trace
+  data in `harness.db`.
+- `scripts/schema/001-init.sql` defines durable tables for intake, story,
+  decision, backlog, and trace records.
+- `docs/HARNESS_COMPONENTS.md` maps files and responsibilities.
+- `docs/HARNESS_MATURITY.md` defines H0-H5 with measurable criteria.
+- `docs/TRACE_SPEC.md` defines trace fields, quality tiers, and friction
+  capture.
+- `docs/CONTEXT_RULES.md` defines phase-by-lane context rules.
+- `AGENTS.md` and `docs/HARNESS.md` reference the Phase 2 operating docs.
+
+Required files:
+
+- `scripts/bin/harness-cli`
+- `scripts/schema/001-init.sql`
+- `docs/HARNESS_COMPONENTS.md`
+- `docs/HARNESS_MATURITY.md`
+- `docs/TRACE_SPEC.md`
+- `docs/CONTEXT_RULES.md`
+
+Benchmark indicators:
+
+- Harness compliance: 75-90%.
+- Trace quality: at least 2.0/3 on normal-lane tasks.
+- Lane accuracy: 6/6 on the current benchmark suite.
+- Friction captured: at least 4/6 benchmark tasks when friction exists.
+
+Current status:
+
+- Achieved. Durable state exists, and the Phase 2 docs define the
+  observability and context specification. Phase 3 active scoring builds on
+  this layer.
+
+Activated responsibilities:
+
+- Task state.
+- Observability.
+- Failure attribution.
+- Context selection.
+- Entropy auditing.
+
+### H3 - Active Observability And Evolution
+
+The harness can evaluate its own operational data and turn repeated failures
+into prioritized improvements.
+
+Criteria:
+
+- Trace quality can be scored by a repeatable command or benchmark step.
+- Harness friction can be grouped by component from `docs/HARNESS_COMPONENTS.md`.
+- Backlog items include predicted impact and actual outcome after completion.
+- Benchmark comparison output identifies which harness responsibility moved or
+  regressed.
+
+Required files:
+
+- H2 files.
+- A benchmark protocol or report that references maturity levels.
+- A documented trace quality scoring method.
+- A documented friction-to-backlog review loop.
+
+Benchmark indicators:
+
+- Harness compliance: 85-95%.
+- Trace quality: 2.3-2.7/3.
+- Friction captured and classified by component for most failed or awkward
+  tasks.
+- Regressions include an attributed harness component.
+
+Current status:
+
+- Partially achieved by Phase 3. `scripts/bin/harness-cli score-trace` scores trace
+  quality against tier rules, `query friction` includes linked intake context,
+  the `trace` command now prints that score at write time, and the backlog
+  outcome loop documents predicted impact versus actual outcome. Full H3 still
+  requires benchmark comparison output that attributes moved or regressed
+  responsibilities.
+
+Activated responsibilities:
+
+- Observability.
+- Failure attribution.
+- Entropy auditing.
+- Intervention recording.
+
+### H4 - Automated Verification
+
+The harness can run or orchestrate proof checks consistently and can reject or
+flag incomplete work before the final response.
+
+Criteria:
+
+- A documented verification command or protocol runs the expected checks for a
+  selected story and lane.
+- Stories can store and execute a `verify_command`.
+- Trace recording warns when a linked story has a verification command that has
+  not passed.
+- Missing validation evidence is surfaced before a task is marked implemented.
+
+Required files:
+
+- H3 files.
+- A verification protocol or command reference.
+- Validation report examples tied to story proof columns.
+- Story verification command documentation.
+
+Benchmark indicators:
+
+- Functional score remains stable.
+- Harness compliance: at least 90%.
+- Fewer false "done" claims in benchmark review.
+- Missing proof is detected before merge or final response.
+
+Current status:
+
+- Achieved by Phase 5. `scripts/bin/harness-cli story verify <id>` runs
+  story-level proof commands, records pass/fail state, `trace --story` warns
+  before close when verification has not passed, and
+  `scripts/bin/harness-cli story verify-all` runs all configured story proof
+  commands in one pass. Proof-column automation remains a future enhancement,
+  but H4's required automated verification gate is now present.
+
+Activated responsibilities:
+
+- Verification.
+- Task state.
+- Permissions.
+- Intervention recording.
+
+### H5 - Self-Improving Harness
+
+The harness can use traces, benchmark results, and backlog outcomes to propose
+or apply safe improvements to itself.
+
+Criteria:
+
+- Repeated friction patterns are summarized into proposed harness changes.
+- Proposed changes include predicted impact, risk, validation plan, and rollback
+  criteria.
+- Completed changes compare predicted impact with actual benchmark or trace
+  outcomes.
+- High-risk harness changes pause for human confirmation before changing source
+  hierarchy, architecture direction, or validation requirements.
+
+Required files:
+
+- H4 files.
+- Self-improvement protocol.
+- Historical improvement reports.
+- Backlog outcome reviews.
+
+Benchmark indicators:
+
+- Harness compliance remains at least 90% across repeated benchmark runs.
+- Trace quality remains at least 2.5/3.
+- Improvements show measurable positive deltas or are explicitly reverted.
+- Scope creep and validation weakening are caught by policy.
+
+Current status:
+
+- Partially achieved by Phase 5. `scripts/bin/harness-cli audit` detects
+  durable-state drift, `scripts/bin/harness-cli propose` generates structured
+  improvement proposals from friction, interventions, and audit results, and
+  `docs/IMPROVEMENT_PROTOCOL.md` defines the review loop. H5 is not fully
+  achieved until repeated benchmark outcomes prove proposed improvements create
+  measurable positive deltas or are explicitly reverted.
+
+Activated responsibilities:
+
+- Entropy auditing.
+- Failure attribution.
+- Intervention recording.
+- Permissions.
+
+## Current Assessment
+
+| Level | Status | Evidence |
+| --- | --- | --- |
+| H0 | Passed | Harness docs, templates, and durable records exist. |
+| H1 | Achieved | `AGENTS.md`, `docs/HARNESS.md`, `docs/FEATURE_INTAKE.md`, `docs/ARCHITECTURE.md`, `docs/templates/*`, and `docs/TEST_MATRIX.md` exist. |
+| H2 | Achieved | `scripts/bin/harness-cli`, `scripts/schema/001-init.sql`, durable story records, `docs/HARNESS_COMPONENTS.md`, `docs/HARNESS_MATURITY.md`, `docs/TRACE_SPEC.md`, and `docs/CONTEXT_RULES.md` define the Phase 2 surface. |
+| H3 | Partial | Phase 3 adds `scripts/bin/harness-cli score-trace`, enriched friction context, and the backlog outcome loop; Phase 4 auto-scores traces on write. Component-level benchmark attribution remains open. |
+| H4 | Achieved | Phase 4 adds story-level `verify_command`, `story verify`, and trace-time verification warnings. Phase 5 adds `story verify-all` for batch story proof. |
+| H5 | Partial | Phase 5 adds `audit`, `score-context`, `intervention add/query`, `propose`, `docs/HARNESS_AUDIT.md`, and `docs/IMPROVEMENT_PROTOCOL.md`; repeated benchmark outcome proof remains open. |
+
+## Responsibility Activation
+
+| Responsibility | H0 | H1 | H2 | H3 | H4 | H5 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Task specification | Missing | Covered | Covered | Covered | Covered | Covered |
+| Context selection | Missing | Partial | Covered | Covered | Covered | Covered |
+| Tool access | Missing | Partial | Partial | Partial | Covered | Covered |
+| Project memory | Missing | Covered | Covered | Covered | Covered | Covered |
+| Task state | Missing | Partial | Covered | Covered | Covered | Covered |
+| Observability | Missing | Missing | Partial | Covered | Covered | Covered |
+| Failure attribution | Missing | Missing | Partial | Covered | Covered | Covered |
+| Verification | Missing | Partial | Partial | Partial | Covered | Covered |
+| Permissions | Missing | Partial | Partial | Partial | Covered | Covered |
+| Entropy auditing | Missing | Missing | Partial | Covered | Covered | Covered |
+| Intervention recording | Missing | Partial | Partial | Covered | Covered | Covered |
+
+## Phase 3 Interpretation
+
+Phase 3 starts the H2 to H3 transition. It claims active trace scoring and a
+documented improvement feedback loop, but it does not claim full H3 because
+benchmark comparison and component-level regression attribution are explicitly
+outside this repository's Phase 3 scope.
+
+## Phase 4 Interpretation
+
+Phase 4 starts the H3 to H4 transition. It gives stories the same mechanical
+verification pattern that decisions already had, records story verification
+results in the durable layer, auto-scores traces when they are written, and
+warns before close when a linked story's verification has not passed. It does
+not claim full H4 because benchmark execution, batch verification, and automatic
+proof-column updates remain separate work.
+
+## Phase 5 Interpretation
+
+Phase 5 completes H4 by adding batch story verification and starts H5 by adding
+tool discovery, intervention records, context scoring, drift audit, and
+deterministic proposal generation. The repository may claim H5 partial only
+when those commands and docs are present and validated; it must not claim full
+H5 until benchmark runs or trace outcomes prove the proposal loop improves the
+harness over time.

docs/IMPROVEMENT_PROTOCOL.md

@@ -0,0 +1,57 @@
+# Improvement Protocol
+
+Phase 5 starts the self-improvement loop:
+
+```text
+friction + interventions + audit findings
+  -> harness-cli propose
+  -> proposed backlog item
+  -> human review
+  -> implementation with predicted impact
+  -> close with actual outcome
+```
+
+## Generate Proposals
+
+```bash
+scripts/bin/harness-cli propose
+```
+
+The command is rule-based. It looks for:
+
+- repeated trace friction,
+- repeated intervention patterns,
+- non-zero audit categories.
+
+Each proposal includes title, component, evidence, predicted impact, risk,
+suggested action, validation plan, and confidence.
+
+## Commit Proposals
+
+```bash
+scripts/bin/harness-cli propose --commit
+```
+
+Committed proposals become `proposed` backlog items. Humans review them with:
+
+```bash
+scripts/bin/harness-cli query backlog --open
+```
+
+## Review Rules
+
+- Tiny proposals may be implemented directly when they only clarify docs.
+- Normal proposals need a story packet or clear backlog acceptance.
+- High-risk proposals need a durable decision record before changing source
+  hierarchy, architecture direction, validation requirements, or risk policy.
+- Completed proposal work must close the backlog item with actual outcome
+  evidence.
+
+## Validation
+
+After implementation, compare the predicted impact with:
+
+- `scripts/bin/harness-cli audit`,
+- `scripts/bin/harness-cli query friction`,
+- `scripts/bin/harness-cli query interventions`,
+- benchmark trace quality and harness compliance when benchmark proof applies.

docs/README.md

@@ -0,0 +1,40 @@
+# CarePath Documentation
+
+Start every task with `AGENTS.md`. This index directs agents to the smallest
+relevant context rather than every document in the repository.
+
+## Current Product and Work
+
+- `product/` — accepted contracts for CarePath, Ghi chép bệnh án AI, and Phiên
+  dịch khám bệnh trực tiếp.
+- `ux-redesign-carepath.md` — current Vietnamese-first UX implementation
+  backlog; required before UX or product-flow implementation.
+- `onboarding-ux-fix-tasks.md` — current visual onboarding execution backlog.
+- `../UI-FIX-PLAN.md` — current public-site issue plan.
+- `deploy.md` — Hugging Face Space deployment instructions.
+
+## Harness: Read for Daily Work
+
+- `HARNESS.md` — source hierarchy, task loop, and done definition.
+- `FEATURE_INTAKE.md` — lane selection and CarePath hard gates.
+- `ARCHITECTURE.md` — module and delivery boundaries.
+- `CONTEXT_RULES.md` — minimum context by lane.
+- `TEST_MATRIX.md` — behavior-to-proof baseline.
+- `TRACE_SPEC.md` — durable completion evidence.
+- `stories/`, `decisions/`, and `templates/` — selected work, settled
+  tradeoffs, and new-work starters.
+
+## Harness: Read Only When Triggered
+
+- `TOOL_REGISTRY.md` — registering or using optional external tools.
+- `HARNESS_AUDIT.md`, `HARNESS_COMPONENTS.md`, and `HARNESS_MATURITY.md` —
+  audit, observability, maturity, or benchmark work.
+- `HARNESS_BACKLOG.md` and `IMPROVEMENT_PROTOCOL.md` — repeated Harness
+  friction or process improvements.
+- `GLOSSARY.md` — extending shared Harness terminology.
+
+## Evidence and History
+
+- `qa-evidence/` — versioned visual QA proof and its retention index.
+- `history/` — preserved MVP, demo-site, unification, and review documents.
+  These are context only; do not reopen completed tickets as current work.

docs/TEST_MATRIX.md

@@ -0,0 +1,19 @@
+# CarePath Test Matrix
+
+This matrix maps the current CarePath baseline to proof. Status changes only
+after the named evidence is actually run and recorded.
+
+| Story | Contract | Unit | Integration | E2E | Platform | Status | Evidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| CP-BASE-001 | Unified API and Ghi chép bệnh án AI remain available | yes | yes | no | no | implemented | 96 passed, 1 skipped; mock smoke passed (2026-07-12) |
+| CP-BASE-002 | Interpreter remains translate-only and fail-closed | yes | yes | yes | no | implemented | Ruff; 109 passed, 1 skipped; mock eval 50/50; 4 browser tests passed (2026-07-12) |
+| CP-BASE-003 | Public CarePath site remains Vietnamese-first and deployable | yes | no | yes | yes | implemented | 45 unit, 5 deploy-env, 7 browser tests; Lighthouse 100/100/100 (2026-07-12) |
+| CP-BASE-004 | Interpreter console remains buildable and usable | yes | no | yes | no | implemented | lint; 38 unit; build; 4 browser tests passed (2026-07-12) |
+| GEC-001 | Offline GEC training uses ViMedCSS and synthetic pairs without human-labeling tooling | no | yes | no | no | implemented | Ruff; 26 focused GEC tests; root 95 passed, 1 skipped (2026-07-12) |
+| HARN-001 | Agent work follows durable CarePath intake and proof rules | no | yes | no | no | implemented | pinned merge install, CLI 0.1.11, init, matrix, audit, trace (2026-07-12) |
+| CP-UX-10 | Public landing leads with Ghi chép bệnh án AI; Interpreter is visibly unavailable | yes | yes | yes | yes | implemented | lint; 46 unit; 5 deploy-env; build + NFC; 5 browser tests at 320–1440px; combined app 3 passed; Lighthouse 100/100/100 (2026-07-14) |
+| CP-UX-11 | Vietnamese-only landing starts with the doctor's documentation burden and teaches the Scribe workflow before upload | yes | yes | yes | yes | implemented | lint; 45 unit; 5 deploy-env; build + NFC; 8 browser tests at 320–1440px with Axe/light/dark/reduced-motion; combined app 3 passed; Lighthouse 100/100/100 (2026-07-15) |
+
+Proof labels mean the relevant layer has evidence for the baseline; they do not
+claim every historical behavior was retested. Story packets define the exact
+commands for future changes.

docs/TOOL_REGISTRY.md

@@ -0,0 +1,195 @@
+# Tool Registry
+
+The harness deals with two distinct kinds of "tool". Keep them separate.
+
+| | Capability manifest (outbound) | Inbound tool registry |
+| --- | --- | --- |
+| Direction | harness offers it to the agent | a project equips it for the harness to use |
+| Examples | the `harness-cli` subcommands below | gitnexus, c3, a linter, a deploy check |
+| Presence | always compiled in | optional; may be absent on any machine |
+| If missing | n/a (it is the harness) | clean skip; never blocks the main process |
+
+This document describes both. The **inbound registry** is the extension base:
+it is where the harness learns what extra capability is equipped, what purpose
+it serves, and whether it is actually present right now, so a workflow step can
+adapt to what is installed without the core ever depending on it.
+
+## Inbound Registry: Register A Tool
+
+```bash
+scripts/bin/harness-cli tool register \
+  --name deploy-check \
+  --kind cli \
+  --capability deploy-verification \
+  --command ./scripts/deploy-check.sh \
+  --description "Verify deploy health before release" \
+  --responsibility Verification \
+  --args "env:enum:required:staging,production"
+```
+
+Fields specific to inbound tools:
+
+- `--kind` — how the tool is reached and probed. One of `cli`, `binary`, `mcp`,
+  `skill`, `http`. Defaults to `cli`. The kind tells each agent runtime what it
+  can orchestrate (a non-Claude agent simply treats a `skill` it cannot run as
+  absent) and tells `tool check` which probe to use.
+- `--capability` — the workflow purpose a step looks the tool up by. Free-text
+  but normalized to kebab-case, so `Impact Analysis`, `impact_analysis`, and
+  `impact-analysis` all register as `impact-analysis`. This is the only coupling
+  between a step and a tool; steps reference the capability, never the tool name.
+- `--scan` — for `mcp`/`skill`/`http`, a declarative path or URL that
+  `tool check` resolves to decide presence (e.g. `.c3`, `~/.claude/skills/c3`,
+  `https://localhost:8080/health`). `cli`/`binary` are probed via their command.
+
+`--force` is only needed for `cli`/`binary` whose command is intentionally
+absent on the current machine. `mcp`/`skill`/`http` are not on `PATH` by nature,
+so they register without `--force`; their presence is resolved later by
+`tool check`.
+
+Registering an MCP server or a Claude skill (examples):
+
+```bash
+scripts/bin/harness-cli tool register --name gitnexus --kind mcp \
+  --capability impact-analysis --scan ".gitnexus" --command "mcp:gitnexus" \
+  --description "Code-graph blast radius" --responsibility Verification
+scripts/bin/harness-cli tool register --name c3 --kind skill \
+  --capability impact-analysis --scan ".c3" --command "skill:c3" \
+  --description "Component model and drift audit (Claude skill)" \
+  --responsibility Verification
+```
+
+Remove a tool with:
+
+```bash
+scripts/bin/harness-cli tool remove --name deploy-check
+```
+
+## Inbound Registry: Check Presence
+
+Registration records intent. `tool check` reconciles intent with reality by
+scanning each registered tool and persisting the verdict (`status` and
+`checked_at`). Run it at intake start so status reflects current reality.
+
+```bash
+scripts/bin/harness-cli tool check            # scan all registered tools
+scripts/bin/harness-cli tool check --name c3  # scan one
+scripts/bin/harness-cli tool check --json     # machine-readable for agents
+```
+
+Probe per kind:
+
+| Kind | Probe | `present` means |
+| --- | --- | --- |
+| `cli`, `binary` | command resolves on `PATH` or as a path | installed and runnable |
+| `mcp`, `skill` | `scan_target` path resolves (`~` expands) | equipped/configured on disk |
+| `http` | `scan_target` reachable over TCP (2s), else path | endpoint answers |
+
+`tool check` always exits `0`: a missing extension is a fact to report, not a
+CLI failure. A `cli`/`binary` is `present` when runnable. An `mcp`/`skill`/`http`
+`present` means **equipped** (config/file resolves), not **live this session** —
+the agent still confirms live usability at call time, since only the agent
+runtime can see whether its MCP server is actually connected. With no
+`scan_target`, the status is `unknown` and the agent must confirm.
+
+## Inbound Registry: Look Up By Capability
+
+A workflow step asks "what is present for this purpose?" rather than naming a
+tool:
+
+```bash
+scripts/bin/harness-cli query tools --capability impact-analysis
+scripts/bin/harness-cli query tools --capability impact-analysis --status present
+```
+
+The result is the set of providers. Multiple tools may provide one capability
+(gitnexus and c3 both serve `impact-analysis` and are complementary), so a step
+reads the set and degrades on how much of it is present.
+
+### Degrade Ladder
+
+The CLI reports facts (`status`); the agent applies policy. The generic rule,
+keyed on the present-provider count for a capability:
+
+| Providers present | Posture | Agent behavior |
+| --- | --- | --- |
+| none registered | Inactive | clean skip; note `capability X: inactive` in the trace. Not drift. |
+| registered but none/some present | Degraded | run with what resolves; set the `Weak proof` flag; note the gap. |
+| all present | Full | normal operation. |
+
+A registered tool that scans as `missing` is a failed validity gate, not a skip.
+A capability with no registered providers is simply inactive and is skipped
+without penalty — this is what keeps the core seamless on a fresh install.
+
+### Recommended Capability Vocabulary
+
+Capability is open (no code change to add one), but a step and its providers
+must agree on the exact string. Reuse these where they fit before coining a new
+one; coin new ones in kebab-case:
+
+```
+impact-analysis · deploy-verification · coverage · security-scan
+performance-benchmark · documentation-lookup
+```
+
+## Inspecting The Registry
+
+```bash
+scripts/bin/harness-cli query tools --summary
+scripts/bin/harness-cli query tools --json
+scripts/bin/harness-cli query tools --responsibility Verification
+```
+
+JSON records carry `kind`, `capability`, `scan_target`, `status`, and
+`checked_at` alongside the existing fields, so any agent can read the registry
+without parsing the human table.
+
+## Compiled Harness Commands (Outbound Manifest)
+
+| Command | Responsibility | Purpose | Arguments |
+| --- | --- | --- | --- |
+| `init` | Task state | Create the harness database. | none |
+| `migrate` | Task state | Apply pending schema migrations. | none |
+| `import brownfield` | Project memory | Seed durable records from markdown state. | none |
+| `intake` | Task specification | Record a feature intake classification. | `--type`, `--summary`, `--lane` |
+| `story add` | Task state | Create a durable story record. | `--id`, `--title`, `--lane`, optional `--verify` |
+| `story update` | Task state | Update story status, proof flags, evidence, or verification command. | `--id`, optional proof/status fields |
+| `story verify` | Verification | Run one story `verify_command` and record pass/fail. | story id |
+| `story verify-all` | Verification | Run all configured story verification commands and skip stories without one. | none |
+| `decision add` | Project memory | Create a durable decision record. | `--id`, `--title`, optional `--doc`, `--verify` |
+| `decision verify` | Verification | Run one decision verification command. | decision id |
+| `backlog add` | Entropy auditing | Record a harness improvement proposal. | `--title`, optional pain/suggestion/risk/predicted fields |
+| `backlog close` | Entropy auditing | Close a backlog item with outcome evidence. | `--id`, optional `--status`, `--outcome` |
+| `tool register` | Tool access | Register an external project tool. | `--name`, `--command`, `--description`, `--responsibility`, optional `--kind`, `--capability`, `--scan`, `--args`, `--force` |
+| `tool check` | Tool access | Scan registered tools and persist present/missing/unknown status. | optional `--name`, `--json` |
+| `tool remove` | Tool access | Remove a registered external tool. | `--name` |
+| `intervention add` | Intervention recording | Record a human, reviewer, CI, or agent intervention. | `--type`, `--description`, `--source`, optional `--trace`, `--story`, `--impact` |
+| `trace` | Observability | Record an agent execution trace and print trace quality. | `--summary`, optional trace fields |
+| `score-trace` | Observability | Score trace detail against lane requirements. | optional `--id` |
+| `score-context` | Context selection | Score trace reads against compiled context rules. | trace id |
+| `audit` | Entropy auditing | Run drift checks and compute entropy score. | none |
+| `propose` | Entropy auditing | Generate improvement proposals from friction, interventions, and audit findings. | optional `--commit` |
+| `query matrix` | Task state | Show durable story proof matrix. | optional `--numeric` |
+| `query backlog` | Entropy auditing | Show harness improvement backlog. | optional `--open`, `--closed` |
+| `query decisions` | Project memory | Show durable decision records. | none |
+| `query intakes` | Task specification | Show recent intake records. | none |
+| `query traces` | Observability | Show recent trace records. | none |
+| `query friction` | Failure attribution | Show traces with harness friction. | none |
+| `query tools` | Tool access | Show compiled and registered tool entries. | optional `--json`, `--summary`, `--responsibility`, `--capability`, `--status` |
+| `query interventions` | Intervention recording | Show intervention records. | optional `--trace`, `--story`, `--type` |
+| `query stats` | Task state | Show durable record counts. | none |
+| `query sql` | Tool access | Run arbitrary SQL against `harness.db`. | SQL text |
+| `db changeset apply` | Task state | Apply one semantic changeset idempotently. | changeset path |
+| `db rebuild` | Task state | Rebuild a fresh `harness.db` from semantic changesets. | `--from` changeset directory |
+
+## Validation Rules
+
+- Tool names must be unique among registered tools.
+- Descriptions must be 10-200 characters.
+- Responsibilities must match the Runtime Substrate responsibility list.
+- `--kind` must be one of `cli`, `binary`, `mcp`, `skill`, `http`.
+- `--capability` must be kebab-case (lowercase letters, digits, single hyphens);
+  spaces and underscores are normalized to hyphens.
+- `--args` entries must use `name:type:required` or
+  `name:type:required:help`, with `required` or `optional` as the third field.
+- For `cli`/`binary`, the command must exist as a path or on `PATH`, unless
+  `--force` is supplied. `mcp`/`skill`/`http` skip this check.

docs/TRACE_SPEC.md

@@ -0,0 +1,204 @@
+# Trace Specification
+
+The `trace` table records what happened during a Harness task. This document
+defines the expected depth and format for each field so traces are useful for
+review, benchmark scoring, failure attribution, and future harness evolution.
+
+The current schema lives in `scripts/schema/001-init.sql` under the `trace`
+table. The schema is not changed by Phase 2.
+
+## Field Reference
+
+| Field | Type | Required | Format | Example |
+| --- | --- | --- | --- | --- |
+| `id` | INTEGER | Automatic | SQLite autoincrement primary key. Do not set manually. | `42` |
+| `created_at` | TEXT | Automatic | SQLite `datetime('now')`. Do not set manually. | `2026-05-27 09:24:37` |
+| `task_summary` | TEXT | Yes | One sentence, at least 10 characters, naming the outcome or attempted outcome. | `Completed Phase 2 docs-only observability and taxonomy specification` |
+| `intake_id` | INTEGER | Standard+ when an intake was recorded | Integer id from the related `intake` row. | `36` |
+| `story_id` | TEXT | Standard+ when work maps to one story | Story id from the `story` table. Use the main story when one trace covers several; list the rest in `notes`. | `US-004` |
+| `agent` | TEXT | Optional for minimal; Standard+ expected | Short agent/tool name. | `codex` |
+| `actions_taken` | TEXT | Standard+ | JSON array text. With the current CLI, pass a comma-separated list and the CLI stores JSON text. | `["read PHASE2.md","drafted TRACE_SPEC.md","updated HARNESS.md"]` |
+| `files_read` | TEXT | Standard+ | JSON array text of paths or command names. With the current CLI, pass a comma-separated list. | `["PHASE2.md","docs/HARNESS.md","scripts/bin/harness-cli query matrix"]` |
+| `files_changed` | TEXT | Standard+ | JSON array text of changed file paths. With the current CLI, pass a comma-separated list; omit only when no files changed. | `["docs/TRACE_SPEC.md","docs/HARNESS.md"]` |
+| `decisions_made` | TEXT | Detailed | JSON array text of decision strings. Include scope decisions, validation choices, and explicit non-goals. | `["Kept Phase 2 docs-only; installer propagation remains out of scope"]` |
+| `errors` | TEXT | Standard+ if errors occurred; Detailed always | JSON array text of error or blocker strings. Until the CLI supports empty arrays directly, use `none` when a detailed trace needs explicit no-error evidence. | `["git diff --check failed before whitespace fix"]` |
+| `outcome` | TEXT | Yes before final response | One of `completed`, `blocked`, `partial`, or `failed`. | `completed` |
+| `duration_seconds` | INTEGER | Detailed when available | Positive integer estimate or measured duration. Leave null if unknown. | `1800` |
+| `token_estimate` | INTEGER | Detailed when available | Positive integer estimate. Leave null if unknown. | `24000` |
+| `harness_friction` | TEXT | Standard+ when friction exists; Detailed always | Free text naming what was hard, missing, ambiguous, or repeated. Use `none` only when the agent actively checked and found no friction. | `New Phase 2 docs are not in installer copy list; recorded as out-of-scope follow-up.` |
+| `notes` | TEXT | Optional | Free text for review context that does not fit other fields. | `Trace covers US-003, US-004, US-005, and US-006.` |
+
+## Quality Tiers
+
+### Minimal (score: 1)
+
+Minimum fields:
+
+- `task_summary` is filled and at least 10 characters.
+- `outcome` is filled before the final response.
+
+Acceptable for:
+
+- Tiny-lane tasks with no file changes or only low-risk copy/doc edits.
+
+Not acceptable for:
+
+- Normal or high-risk work.
+- Any work that discovered friction, errors, or a missing validation path.
+
+### Standard (score: 2)
+
+Minimum fields:
+
+- All Minimal fields.
+- `intake_id` when an intake was recorded.
+- `story_id` when the work maps cleanly to one story.
+- `agent`.
+- `actions_taken` as JSON array text.
+- `files_read` as JSON array text.
+- `files_changed` as JSON array text.
+- At least one of `errors` or `harness_friction`.
+
+Required for:
+
+- Normal-lane tasks.
+- Tiny tasks that changed Harness instructions, validation expectations, or
+  durable records.
+
+Standard traces may leave `duration_seconds`, `token_estimate`, and
+`decisions_made` empty when those details are not useful.
+
+### Detailed (score: 3)
+
+Minimum fields:
+
+- All Standard fields.
+- `decisions_made` as JSON array text.
+- `errors` as JSON array text, using `none` with the current CLI when no
+  errors occurred.
+- `harness_friction`, using `none` only after checking for friction.
+- `duration_seconds` or a note explaining why duration is unavailable.
+- `token_estimate` or a note explaining why token estimate is unavailable.
+- `notes` when one trace covers multiple stories, multiple risk flags, or
+  skipped validation.
+
+Required for:
+
+- High-risk tasks.
+- Changes touching architecture direction, source-of-truth hierarchy,
+  validation requirements, auth, authorization, data loss, audit/security, or
+  external provider behavior.
+- Benchmark or release work where later review needs precise proof.
+
+For high-risk work, `decisions_made` in the trace summarizes what was decided.
+It does not replace a durable decision record. If the work changes behavior,
+architecture, authorization, data ownership, API shape, or validation
+requirements, add a `docs/decisions/NNNN-*.md` file and record it with
+`scripts/bin/harness-cli decision add`.
+
+## Lane Mapping
+
+| Lane | Expected Tier | Minimum Trace Behavior |
+| --- | --- | --- |
+| Tiny | Minimal | Record summary and outcome; use Standard if friction or Harness docs changed. |
+| Normal | Standard | Record intake, actions, files read, files changed, outcome, and friction/errors. |
+| High-risk | Detailed | Record all fields or explicitly explain unavailable duration/token estimates. |
+
+## Friction Capture Protocol
+
+Populate `harness_friction` when any of these occur:
+
+- The agent had to infer a missing rule or source of truth.
+- Required validation was unclear, unavailable, or too expensive to run.
+- A document, durable record, or story packet was stale or contradictory.
+- The task revealed a repeated manual step that should become a template,
+  command, or checklist.
+- A requested change was out of scope but likely important later.
+- A benchmark or review failure could not be attributed to a component.
+
+How to write friction:
+
+- Name the concrete pain, not a vague mood.
+- Include the missing capability or contradiction.
+- If the friction should become work, also add or update a backlog item with
+  `scripts/bin/harness-cli backlog add`.
+- If there was no friction, use `none` only for Detailed traces.
+
+Good friction:
+
+```text
+New Phase 2 docs are not copied by scripts/install-harness.sh, but installer
+propagation is out of scope for docs-only Phase 2.
+```
+
+Weak friction:
+
+```text
+docs confusing
+```
+
+## Examples
+
+### Good Trace (Detailed)
+
+```bash
+scripts/bin/harness-cli trace \
+  --summary "Completed high-risk auth role migration with audit proof" \
+  --intake 51 \
+  --story US-014 \
+  --agent codex \
+  --outcome completed \
+  --duration 4200 \
+  --tokens 52000 \
+  --actions "read access-control docs,created migration,updated audit tests,ran integration suite" \
+  --read "docs/product/permissions.md,docs/decisions/0008-auth-boundary.md,src/auth/roles.ts" \
+  --changed "src/auth/roles.ts,src/audit/events.ts,tests/auth-roles.test.ts" \
+  --decisions "kept manager role scoped to workspace,recorded audit event on every role change" \
+  --errors "none" \
+  --friction "Existing permission docs did not define delegated admin; added backlog item for role glossary." \
+  --notes "Detailed trace required because the task touched authorization and audit behavior."
+```
+
+### Adequate Trace (Standard)
+
+```bash
+scripts/bin/harness-cli trace \
+  --summary "Added Phase 2 trace specification and Harness reference" \
+  --intake 36 \
+  --story US-004 \
+  --agent codex \
+  --outcome completed \
+  --actions "read PHASE2.md,drafted TRACE_SPEC.md,updated HARNESS.md,ran rg checks" \
+  --read "PHASE2.md,docs/HARNESS.md,scripts/schema/001-init.sql" \
+  --changed "docs/TRACE_SPEC.md,docs/HARNESS.md" \
+  --friction "none"
+```
+
+### Insufficient Trace
+
+```bash
+scripts/bin/harness-cli trace \
+  --summary "did phase 2" \
+  --outcome completed
+```
+
+Why this is insufficient for normal-lane Phase 2 work:
+
+- It does not identify actions.
+- It does not list files read or changed.
+- It does not connect to intake or stories.
+- It gives no friction or error signal.
+
+## Review Checklist
+
+Before the final response, check:
+
+- The trace tier matches the lane.
+- Review the score printed automatically by `scripts/bin/harness-cli trace`.
+  Use `scripts/bin/harness-cli score-trace --id N` when re-checking a specific
+  historical trace.
+- `files_changed` matches the actual changed-file set at a useful level.
+- `errors` names real blockers or is `none` for Detailed traces when the
+  current CLI is used.
+- `harness_friction` either names a concrete issue or is intentionally `none`.
+- Any friction that should become future work is recorded in the backlog.

docs/decisions/0001-harness-first-development.md

@@ -0,0 +1,48 @@
+# 0001 Harness-First Development
+
+Date: 2026-05-05
+
+## Status
+
+Accepted
+
+## Context
+
+The repository currently contains a product README and a large product
+specification. There is no application implementation yet.
+
+The project will likely involve human direction plus agent implementation over
+many evolving stories. A single massive specification is not enough for safe
+agent work because it becomes hard to locate current truth, risk, proof, and
+change history.
+
+## Decision
+
+Create Harness v0 before scaffolding product code.
+
+Harness v0 defines:
+
+- Agent entrypoint.
+- Product doc split.
+- Feature intake and risk lanes.
+- Story packet templates.
+- Decision records.
+- Test matrix.
+- Harness backlog.
+
+No application code, fake scripts, CI, or tests are created in this decision.
+
+## Consequences
+
+Positive:
+
+- Agents have a clear operating model before implementation starts.
+- Product truth can split away from the massive spec.
+- Risky work has a slower lane before code changes.
+- Harness growth becomes part of the work.
+
+Tradeoffs:
+
+- Some docs are placeholders until real stories exercise them.
+- Validation commands are only contracts until implementation begins.
+- The harness must stay small enough to revise from real friction.

docs/decisions/0002-post-spec-product-lifecycle.md

@@ -0,0 +1,54 @@
+# 0002 Seed Specification Product Lifecycle
+
+Date: 2026-05-05
+
+## Status
+
+Superseded by `0003-generic-spec-intake-harness.md`
+
+## Context
+
+Harness v0 originally assumed the repository would include one seed
+specification file for the first product. This decision explained how agents
+should decompose that initial specification into product docs, story packets,
+implementation, and validation proof, then continue working after the seed was
+exhausted.
+
+That approach fit a single project but made the harness less reusable.
+
+## Decision
+
+Treat the initial specification as a seed and historical snapshot, not the
+permanent living product plan.
+
+After the initial specification has been exhausted, new work should enter
+through the same harness loop as one of these input types:
+
+- Change request.
+- New initiative.
+- Maintenance request.
+- Harness improvement.
+
+Product docs under `docs/product/`, story packets under `docs/stories/`,
+validation evidence in `docs/TEST_MATRIX.md`, and decision records under
+`docs/decisions/` become the living operating surface.
+
+Large future product areas should be captured as scoped initiative notes instead
+of appended to the seed specification or rewritten as a second monolithic spec.
+
+## Consequences
+
+Positive:
+
+- The original specification remains stable as historical context.
+- Product truth moves into smaller, current, maintainable files.
+- Future work keeps using the same intake, story, proof, and harness-growth
+  loop.
+- Large ideas can still be planned without creating another oversized spec.
+
+Tradeoffs:
+
+- The repository will eventually need an initiative template if large new
+  product areas become common.
+- Agents must be careful to update product docs and tests rather than relying on
+  the seed specification after initial buildout.

docs/decisions/0003-generic-spec-intake-harness.md

@@ -0,0 +1,58 @@
+# 0003 Generic Spec Intake Harness
+
+Date: 2026-05-05
+
+## Status
+
+Accepted
+
+## Context
+
+Harness v0 originally shipped with a project-specific `SPEC.md`, product docs,
+candidate epics, architecture assumptions, and validation examples. That made
+the harness useful for the first project but too specific to reuse as the outer
+shell for a new project.
+
+The desired direction is a default harness that can wait for any user-provided
+spec, derive product docs from that spec, and then continue with the same
+intake, story, proof, and decision loop.
+
+## Decision
+
+Remove the tracked project-specific spec and pre-sliced product domains from
+Harness v0.
+
+The harness now starts with:
+
+- No baked-in `SPEC.md`.
+- Empty product docs except for intake guidance.
+- Generic story and epic examples.
+- Stack-neutral architecture discovery rules.
+- Stack-neutral validation columns.
+- A source hierarchy that treats a future user-provided spec as input material,
+  not permanent living truth.
+
+## Alternatives Considered
+
+1. Keep the original `SPEC.md` as an example. Rejected because examples can be
+   mistaken for current product truth.
+2. Move the original product docs into an examples folder. Rejected for now
+   because the user asked for a clean default harness.
+
+## Consequences
+
+Positive:
+
+- The repository is easier to reuse for any new project.
+- Future specs can define their own product domains and stack.
+- Agents are less likely to confuse template truth with product truth.
+
+Tradeoffs:
+
+- The harness has fewer concrete examples until the next spec is supplied.
+- The first spec intake must create product docs and candidate epics before
+  implementation planning can be precise.
+
+## Follow-Up
+
+- Add a spec-intake template if repeated projects reveal a stable format.

docs/decisions/0004-sqlite-durable-layer.md

@@ -0,0 +1,75 @@
+# 0004 SQLite Durable Layer
+
+Date: 2026-05-22
+
+## Status
+
+Accepted
+
+## Context
+
+Harness v0 stores all operational data in markdown files: `TEST_MATRIX.md` rows,
+`HARNESS_BACKLOG.md` items, decision records, and story status. This works for
+human reading but creates friction for agents:
+
+- Editing markdown tables is error-prone and hard to validate.
+- There is no structured way to query past intakes, traces, or friction reports.
+- The harness has no observability foundation for future evolution.
+
+Recent research on harness engineering (arXiv:2604.25850, arXiv:2605.13357,
+arXiv:2603.28052) identifies observability and structured traces as the
+foundation for harness improvement. All three approaches require queryable
+operational data, not prose documents.
+
+## Decision
+
+Add a SQLite database (`harness.db`) and a thin CLI (`scripts/bin/harness-cli`) as the
+durable layer for operational harness data.
+
+The database stores:
+
+- **Intake records**: classification of incoming work.
+- **Stories**: work packets and their validation proof status (replaces manual
+  `TEST_MATRIX.md` rows).
+- **Decisions**: durable records with optional verification commands.
+- **Backlog items**: harness improvement proposals with predicted and actual
+  impact.
+- **Traces**: agent execution records including actions, files, errors, outcome,
+  and harness friction.
+
+The schema is version-controlled under `scripts/schema/`. The database file is
+`.gitignore`d because each project instance generates its own operational data.
+
+Policy docs (`HARNESS.md`, `FEATURE_INTAKE.md`, `ARCHITECTURE.md`) remain as
+human-readable references. The database stores what agents produce, not what
+they should do.
+
+## Alternatives Considered
+
+1. Keep everything in markdown. Rejected because it prevents structured queries,
+   makes observability impossible, and forces agents to edit fragile tables.
+2. Use JSON files. Rejected because concurrent writes are unsafe and queries
+   require custom tooling.
+3. Use a full database server. Rejected because it adds deployment complexity
+   that does not match Harness v0 scope.
+
+## Consequences
+
+Positive:
+
+- Agents record structured data instead of editing markdown tables.
+- Intake, story, decision, backlog, and trace data is queryable.
+- The harness has an observability foundation for future evolution.
+- Schema migrations enable the durable layer to grow with the harness.
+
+Tradeoffs:
+
+- Requires `sqlite3` to be available in the environment.
+- The database is not version-controlled, so each instance starts empty.
+- Markdown docs and the database may drift if agents use one but not the other.
+
+## Follow-Up
+
+- Seed existing decisions (0001-0003) into the database during init.
+- Add context engineering rules keyed by task type and risk lane.
+- Add harness maturity ladder (H0-H4) once the durable layer proves useful.

docs/decisions/0005-prebuilt-rust-harness-cli.md

@@ -0,0 +1,91 @@
+# 0005 Prebuilt Rust Harness CLI
+
+Date: 2026-05-23
+
+## Status
+
+Accepted, amended 2026-05-31, amended 2026-06-09
+
+## Context
+
+The durable layer started as a thin shell wrapper around SQLite. That wrapper
+is now large enough to carry meaningful architecture risk: it mixes command
+parsing, SQL construction, migrations, import behavior, query rendering, and
+help text in one script.
+
+The previous installer copied a shell wrapper into target repositories. That
+kept Harness easy to install, but it also meant a Rust rewrite was not only an
+implementation change. It changed the distribution contract for every project
+that receives Harness.
+
+## Decision
+
+The future Rust implementation of the Harness CLI should be shipped as a
+prebuilt binary downloaded by the installer.
+
+The command path for users and agents is the installed Rust binary:
+
+```bash
+scripts/bin/harness-cli <command>
+```
+
+On Windows, the repository-local binary is installed as:
+
+```powershell
+.\scripts\bin\harness-cli.exe <command>
+```
+
+The installer should download, verify, and install the platform-specific Rust
+binary directly at that path. There should be no shell wrapper command contract.
+
+The Rust CLI should follow the existing architecture rules:
+
+- Domain: harness records, statuses, lanes, and value types.
+- Application: use cases for intake, stories, decisions, backlog, traces, and
+  queries.
+- Infrastructure: SQLite repositories and schema migrations.
+- Interface: command-line parsing, terminal output, and installer integration.
+
+Release automation now follows the same distribution contract. After a PR is
+merged to `main`, the post-merge maintenance workflow updates `CHANGELOG.md`.
+When the merged PR changed the Rust CLI source, schema, Cargo metadata, or CLI
+release packaging, it also bumps the CLI patch version, updates the installer
+release tag pin, creates a `harness-cli-v*` tag, and invokes the reusable
+Harness CLI release workflow for that tag.
+
+## Alternatives Considered
+
+1. Keep the shell CLI permanently. Rejected because the script has crossed from
+   a thin wrapper into a growing application surface with weak testability.
+2. Copy Rust source into every target project and build locally. Rejected
+   because it makes Harness installation depend on a local Rust toolchain and
+   increases setup friction for projects that only need the harness.
+3. Require users to install a global `harness` binary separately. Rejected
+   because Harness should remain repository-local for agents.
+4. Download a prebuilt binary through the installer. Accepted because it keeps
+   target repos simple while allowing the CLI internals to become typed,
+   testable, and platform-aware.
+
+## Consequences
+
+Positive:
+
+- The durable-layer CLI can move to typed command parsing and tested use cases.
+- Target projects do not need a Rust toolchain just to use Harness.
+- The `scripts/bin/harness-cli` command is the stable entrypoint for agents on
+  macOS/Linux; Windows uses the same repo-local path with the `.exe` suffix.
+- Prebuilt releases can include a known SQLite linkage strategy.
+
+Tradeoffs:
+
+- The installer must learn platform detection and binary download behavior.
+- Release artifacts need checksums or another integrity check.
+- Unsupported platforms need a clear error path.
+- The project needs a repeatable release process for supported platforms.
+
+## Follow-Up
+
+- Implement the migration through `US-002 Rust Harness CLI`.
+- Remove the old shell wrapper from installed project payloads.
+- Add checksum verification for downloaded binaries.
+- Treat the Rust CLI as the primary durable-layer implementation.

docs/decisions/0006-phase-4-benchmark-triage.md

@@ -0,0 +1,54 @@
+# 0006 Phase 4 Benchmark Triage
+
+Date: 2026-05-31
+
+## Status
+
+Accepted
+
+## Context
+
+The first Phase 4 benchmark re-run found that T4 authentication failed
+`decision_recorded` even though the trace included decisions text. The same run
+also showed command churn from agents trying `story update` proof flags with
+`yes` and `no`, and trying to use `story verify` as if it accepted proof flags.
+
+## Decision
+
+Harness instructions and CLI help must distinguish durable records from trace
+evidence and must show the current Rust CLI command shape at the point agents
+need it:
+
+- High-risk behavior changes require a markdown decision under
+  `docs/decisions/` and a durable `decision` row.
+- Trace `--decisions` is evidence for trace quality, not the decision log.
+- `story update` proof flags use `1` and `0`.
+- `story verify <id>` only runs the configured `verify_command`; proof flags
+  stay on `story update`.
+
+## Alternatives Considered
+
+1. Rely on trace auto-scoring to catch the missing T4 decision. Rejected because
+   trace scoring can confirm detailed trace content but cannot prove a durable
+   decision record exists.
+2. Change the CLI to accept `yes` and `no`. Deferred because v0.1.5 already has
+   a numeric command contract and the immediate benchmark issue is stale
+   guidance, not missing parser capability.
+
+## Consequences
+
+Positive:
+
+- High-risk agents get explicit decision-log instructions before closing work.
+- Command examples align with the Rust CLI v0.1.5 parser.
+- `story verify` and `story update` have separate mental models in docs.
+
+Tradeoffs:
+
+- Docs now duplicate a few command examples so the common path is visible
+  without repeated help discovery.
+
+## Follow-Up
+
+- Re-run the Phase 4 benchmark and check whether T4 records a durable decision.
+- Watch for remaining command churn around `story update` and `story verify`.

docs/decisions/0007-improvement-proposal-rules.md

@@ -0,0 +1,60 @@
+# 0007 Improvement Proposal Rules
+
+Date: 2026-06-04
+
+## Status
+
+Accepted
+
+## Context
+
+Phase 5 adds `harness-cli propose`, which changes the harness evolution model.
+The command must be useful without becoming an unchecked source of scope creep
+or circular recommendations.
+
+## Decision
+
+Improvement proposals are advisory, rule-based, and evidence-backed. The command
+may summarize repeated friction, repeated interventions, and audit drift. It may
+create `proposed` backlog items only when `--commit` is supplied.
+
+Every proposal must include:
+
+- affected Harness component,
+- concrete evidence,
+- predicted impact,
+- risk lane,
+- suggested action,
+- validation plan,
+- confidence level.
+
+High-risk proposal implementation still requires human review and a durable
+decision record when it changes source hierarchy, architecture direction,
+validation requirements, or risk policy.
+
+## Alternatives Considered
+
+1. Generate free-form LLM recommendations. Rejected because Phase 5 needs a
+   deterministic and auditable evolution role.
+2. Automatically apply proposed changes. Rejected because the harness must not
+   rewrite its own policy without review.
+3. Only report audit findings. Rejected because H5 requires proposed
+   improvements, not just drift detection.
+
+## Consequences
+
+Positive:
+
+- Repeated operational patterns can become backlog items.
+- Proposal output is explainable and testable.
+- Human review remains the gate for risky harness changes.
+
+Tradeoffs:
+
+- Rule-based grouping can miss semantically similar phrasing.
+- Audit-based proposals may be housekeeping rather than strategic evolution.
+
+## Follow-Up
+
+- Use benchmark runs and closed backlog outcomes to improve proposal quality in
+  later phases.

docs/decisions/0008-carepath-harness-adoption.md

@@ -0,0 +1,44 @@
+# 0008 CarePath Harness Adoption
+
+Date: 2026-07-12
+
+## Status
+
+Accepted
+
+## Context
+
+CarePath has two clinical workflows, strict safety invariants, multiple test
+surfaces, and historical plans. Future coding agents need a durable way to
+classify work, preserve those boundaries, and record actual proof.
+
+## Decision
+
+Adopt Repository Harness from upstream commit `14e6f102a4a645562d046f7c693c61401261cac6`
+with its pinned, checksum-verified Windows CLI v0.1.11. Keep `AGENTS.md` as the
+highest repository-level safety and UX instruction, tailor the Harness to the
+current CarePath contracts, and load the same instructions from `CLAUDE.md`.
+
+## Alternatives Considered
+
+1. Keep only historical plans and ad-hoc validation notes.
+2. Adopt a documentation-only workflow without durable local records.
+3. Replace the existing CarePath instructions with the generic upstream shim.
+
+## Consequences
+
+Positive:
+
+- New work has explicit risk lanes, proof expectations, and durable traces.
+- Codex and Claude Code share the same project contract.
+- The Harness introduces no product dependencies or CI changes.
+
+Tradeoffs:
+
+- Agents must perform a small intake and trace step for future work.
+- `harness.db` is local-only, so durable operational records are per clone.
+
+## Follow-Up
+
+- Upgrade the Harness only as a separately reviewed maintenance task.
+- Register optional tools only when a recurring validation need proves one.

docs/decisions/0009-restructure-target-layout.md

@@ -0,0 +1,56 @@
+# 0009 CarePath Restructure Target Layout
+
+Date: 2026-07-13
+
+## Status
+
+Superseded in part by 0016
+
+> Location update (2026-07-13): the approved Scribe training boundary now
+> resides at `scribe/training/`. The remaining Interpreter and shared-layout
+> decisions in this record remain accepted.
+
+## Context
+
+CarePath serves two independent clinical workflows from one process, while the
+repository currently places their runtime, frontends, tests, evaluation, and
+training assets in mixed top-level locations. The approved restructure requires
+a durable target layout without changing import names, routes, or safety
+behavior.
+
+## Decision
+
+Move runtime ownership into `scribe/` and `interpreter/`, and reserve `shared/`
+for the later shared package. Decision 0016 supersedes this record's original
+top-level GEC-training location. Keep the import names `carepath` and `app`,
+keep all public routes unchanged, and retain the root `pyproject.toml` as the
+Scribe distribution. Move the interpreter evaluation harness with
+`interpreter/`; it is not GEC training.
+
+Each relocation phase must update path math, packaging, CI, Docker, deployment
+documentation, and the affected product contracts, then pass its relevant
+existing proof before the next phase begins.
+
+## Alternatives Considered
+
+1. Leave the current mixed top-level layout.
+2. Rename both runtime imports to match their new directory names.
+3. Create separate Python distributions before the relocations.
+
+## Consequences
+
+Positive:
+
+- Runtime and training ownership are visible from the repository layout.
+- Existing imports and public API routes remain stable.
+- The risk-evaluation suite stays with the Interpreter that it validates.
+
+Tradeoffs:
+
+- Relative path calculations and deployment files must be audited after every move.
+- The Vercel project root setting requires owner action when `scribe/frontend/` moves.
+
+## Follow-Up
+
+- Record a separate high-risk Harness intake and trace for every phase.
+- Do not begin owner-led clinical-data collection without legal consent and data-handling approval.

docs/decisions/0010-shared-normalization-contract.md

@@ -0,0 +1,31 @@
+# 0010 Shared Normalization Contract
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+Interpreter, Scribe scoring, training scoring, and both lexical retrievers
+carried local normalization implementations. Their names overlapped, but their
+contracts differed: the Interpreter normalizes units, Vietnamese number words,
+and relative dates; scoring compares case-insensitively without semantic
+conversion; lexical retrieval additionally folds diacritics and punctuation.
+
+## Decision
+
+Create the installable `shared/carepath_shared` package. Move the Interpreter
+normalizer there unchanged as `normalize_text`, and make every former local
+normalizer a direct import from this package. Keep the existing scoring and
+retrieval semantics as the separately named `normalize_for_metrics` and
+`normalize_for_match` functions, rather than silently changing metric scores or
+term matching.
+
+## Consequences
+
+- Normalization algorithms have one owner and one characterization suite.
+- Existing module import paths remain compatible.
+- A future semantic consolidation must explicitly revise the characterization
+  suite and evaluation baseline; it is not part of this restructure.

docs/decisions/0011-canonical-medical-term-source.md

@@ -0,0 +1,30 @@
+# 0011 Canonical Medical-Term Source
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+Scribe retrieval reads `data/medical_lexicon.json`; Interpreter safety glossary
+seeding reads `interpreter/app/glossary/data/seed_glossary.csv`. Both are
+clinician-editable medical terminology, but their serving schemas differ.
+
+## Decision
+
+`shared/carepath_shared/terms/medical_terms.json` is the only authored source.
+Each row defines Vietnamese and English terms, kind, aliases, risk flags, and
+target-specific rendering metadata. `scripts/build_term_artifacts.py` emits
+both existing serving artifacts without changing either runtime reader.
+
+Interpreter risk lexicons remain independent safety data and are explicitly
+out of scope for this source.
+
+## Consequences
+
+- Serving paths and schemas stay stable.
+- CI regenerates artifacts and rejects source/artifact drift.
+- Any taxonomy or risk-flag meaning change now requires this decision's
+  characterization and safety proof to be revisited.

docs/decisions/0012-interpreter-runtime-hardening.md

@@ -0,0 +1,29 @@
+# 0012 Interpreter Runtime Hardening
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+The Interpreter compared admin tokens directly, purged retained sessions only
+at startup, and hard-coded development CORS origins. The combined FastAPI
+service duplicated the standalone Interpreter startup path.
+
+## Decision
+
+Use `hmac.compare_digest` for the admin token. Give the Interpreter one shared
+lifespan that seeds, purges on startup, runs a daily retention purge task, and
+cancels it on shutdown; the combined service enters the same lifespan. Parse
+CSV `CORS_ORIGINS` through Interpreter settings, with the existing two Vite
+origins as the default.
+
+## Consequences
+
+- Admin authentication avoids an avoidable timing leak.
+- Retention continues while a process stays up.
+- Standalone and combined Interpreter startup cannot drift.
+- Production operators configure allowed cross-origin development clients via
+  `.env`; same-origin deployment remains the default topology.

docs/decisions/0013-gec-training-data-governance.md

@@ -0,0 +1,30 @@
+# 0013 GEC Training Data Governance
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+GEC training previously accepted a dataset name and profile without a durable
+record of its source, consent status, immutable version, or deterministic run
+configuration. Clinical audio is sensitive personal data and cannot be sourced
+or approved by an agent.
+
+## Decision
+
+Use versioned JSON run configs with fixed seeds and a dataset-manifest reference.
+`run_pipeline.py` refuses every training stage until the referenced manifest has
+owner-approved consent and a non-placeholder SHA-256. Add a text-only frozen
+stratified evaluation fixture with a separate immutable hash; it contains no
+patient audio or identifiers.
+
+## Consequences
+
+- The agent can validate pipeline governance without collecting clinical data.
+- The owner must complete lawful sourcing, consent, de-identification, and hash
+  verification before a real training run.
+- Evaluation categories make drug, dosage, laterality, negation, number, and
+  diacritic regressions visible independently.

docs/decisions/0014-gec-safety-weighted-regression-gate.md

@@ -0,0 +1,31 @@
+# 0014 GEC Safety-Weighted Regression Gate
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+Aggregate WER can improve while a correction damages a medication name or a
+dosage. Those errors have a higher clinical cost than ordinary transcription
+differences. The training pipeline also lacked a versioned committed baseline
+that CI could validate without model or GPU dependencies.
+
+## Decision
+
+Commit a deterministic report for the hashed, text-only frozen GEC fixture.
+Require its report to stay reproducible in CI. A trained adapter must pass the
+existing aggregate gate and, before export, a frozen-fixture gate that rejects
+any regression in `drug_name.term_recall` or
+`dosage.number_unit_preservation` versus raw ASR.
+
+## Consequences
+
+- Overall WER alone can never approve an adapter that harms drug or dosage
+  preservation.
+- CI remains CPU-only: it validates the 12-row fixture, committed report, and
+  a fake-adapter export/injected-generation smoke test.
+- A real adapter run still needs the owner-approved training manifest and an
+  available GPU; this policy does not authorize data collection or training.

docs/decisions/0015-soap-note-measurement-gate.md

@@ -0,0 +1,32 @@
+# 0015 SOAP Note Measurement Gate
+
+Date: 2026-07-13
+
+## Status
+
+Superseded by [0017 In-House Testing Scope](0017-in-house-testing-scope.md)
+on 2026-07-13.
+
+## Context
+
+The Scribe SOAP output uses a hosted clinical LLM with an offline fallback.
+There is no legitimate basis to train or tune it from invented examples, and no
+clinical rating protocol existed to distinguish missing content, hallucination,
+and terminology errors.
+
+## Decision
+
+Before any SOAP fine-tuning decision, the owner must obtain at least 50
+de-identified pilot notes rated by clinicians under the documented rubric.
+The repository holds only a blank rating schema and a validator that accepts
+anonymous rating metadata; it must never hold source audio, transcripts,
+patient identifiers, or note text.
+
+## Consequences
+
+- The agent can make the measurement process reproducible without simulating
+  clinical evidence.
+- A rating summary makes serious hallucinations and unsafe dispositions visible
+  to the owner before choosing training, retrieval, prompting, or no change.
+- The clinical-data study, ratings, and any subsequent model decision remain
+  owner-led and require an approved environment.

docs/decisions/0016-scribe-training-ownership.md

@@ -0,0 +1,35 @@
+# 0016 Scribe Training Ownership
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+The offline DARAG/GEC training code, fixtures, reports, notebooks, and scripts
+already support the Scribe's Vietnamese clinical-note workflow. The top-level
+`training/` directory obscures that ownership and risks being confused with the
+Interpreter's safety evaluation harness at `interpreter/eval/`.
+
+## Decision
+
+Move the complete offline training boundary to `scribe/training/`. It contains
+the GEC package, configs, fixtures, manifests, reports, notebooks, scripts,
+tests, and SOAP measurement tooling. `interpreter/eval/` remains the
+Interpreter's independent safety regression harness.
+
+The Scribe serving package at `scribe/carepath/` must not import training code;
+the production image copies only the Scribe runtime package, not
+`scribe/training/`. Training keeps its standalone `gec.*` command-line import
+boundary without adding a distribution or dependency.
+
+This supersedes only the top-level training-location portion of decision 0009.
+
+## Consequences
+
+- Training commands and CI use `scribe/training/...` paths.
+- Runtime packaging stays independent of offline model-development artifacts.
+- The repository has a visibly separate Scribe training boundary and
+  Interpreter safety-evaluation boundary.

docs/decisions/0017-in-house-testing-scope.md

@@ -0,0 +1,40 @@
+# 0017 In-House Testing Scope
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+The restructure and public deployment work are complete. The remaining
+50-note clinician-rating target in decision 0015 would require an external
+clinical-evidence program that is outside the current in-house testing scope.
+
+## Decision
+
+Remove the 50-note clinician-rating target from the restructure completion
+criteria and from the SOAP review utility. In-house review is optional and
+informational: it may inspect synthetic or already-approved de-identified
+material with the existing score-only rubric, but it cannot authorize a SOAP
+fine-tuning, provider, or safety-policy change.
+
+No audio, transcript, patient identifier, or note text may enter this
+repository. A future clinical-evidence program or model decision requires a
+separate owner decision.
+
+## Consequences
+
+- The restructure can complete without external clinical-rating evidence.
+- The rubric remains available for bounded in-house quality checks, without a
+  minimum sample-size goal or readiness result.
+- CarePath makes no clinical-quality or model-readiness claim from in-house
+  testing.
+
+## Alternatives Considered
+
+1. Keep the 50-note gate: rejected because it conflicts with the current
+   owner-directed in-house scope.
+2. Delete the rubric and validator: rejected because they remain useful for
+   privacy-bounded internal QA.

docs/decisions/0018-research-only-scribe-model-development.md

@@ -0,0 +1,73 @@
+# 0018 Research-Only Scribe Model Development
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+The owner requested a research-led Vietnamese medical Scribe pipeline covering
+papers, direct ASR adaptation, runtime-compatible GEC, grounded SOAP training,
+and private Colab staging. Existing decisions authorize GEC governance and
+safety gates, while decision 0017 deliberately prevented optional in-house
+review from implicitly authorizing SOAP fine-tuning.
+
+On 2026-07-13 the owner stated, "I approve research-only use of the listed
+public datasets." This approves private research with ViMedCSS, VietMed,
+MTS-Dialog, ACI-BENCH, and MedEV. Public availability and this approval do not
+prove commercial data rights, and synthetic or translated SOAP supervision does
+not establish clinical validity.
+
+## Decision
+
+Authorize public/synthetic, research-only Scribe model development in private
+Google Colab runtimes under story CP-RES-013.
+
+- Compare the current Gipformer baseline, single-best GEC/RAC, and direct
+  Vietnamese medical ASR adapters on frozen overall and safety-weighted metrics.
+- Permit one Qwen3-4B QLoRA SOAP adapter used in two grounded passes: extract
+  source-supported facts, then write the existing SOAP schema from those facts.
+- Require immutable data manifests, source split provenance, artifact hashes,
+  and the labels `usage_scope=research_only` and
+  `promotion_status=blocked_research_only`.
+- Keep public benchmark audio in ephemeral Colab caches only. No CarePath
+  consultation audio, transcript, note, or identifier enters training.
+- Keep production providers, deployments, public routes, and response schemas
+  unchanged. Staging uses an in-process FastAPI client in Colab, not a public
+  endpoint.
+- Pin each public source to an immutable commit and verified hashes. Use
+  `tranth3truong/carepath-scribe-research` only as the private accepted-bundle
+  destination after an explicit upload command; this decision does not perform
+  or authorize public publication.
+
+MedEV's paper describes research and educational availability, but its dataset
+repository does not declare a standard license. VietMed's Hugging Face card and
+paper also present different license labels. Both therefore remain research-only
+and blocked from commercial or production promotion pending a separate rights
+decision.
+
+This decision supersedes decision 0017 only where it said in-house work could
+not authorize SOAP fine-tuning. Decision 0017's privacy boundary and prohibition
+on clinical-readiness claims remain in force.
+
+## Consequences
+
+- CPU/mock smoke tests can prove governance and safety logic locally; real model
+  metrics require owner-run Colab GPU evidence.
+- A successful research bundle still cannot be promoted without a separate data
+  rights decision, qualified Vietnamese clinician review, and production rollout
+  decision.
+- ROUGE and LLM judges remain diagnostic only. Unsupported critical facts,
+  medication/dose corruption, number/unit corruption, or negation corruption
+  block export.
+
+## Alternatives Considered
+
+1. Keep prompt-only SOAP indefinitely: rejected because it cannot test the
+   approved research hypothesis.
+2. Train a single end-to-end speech-to-note model: rejected because it weakens
+   attribution, comparison, and fail-closed safety evidence.
+3. Reproduce every paper ablation first: rejected because pilot evidence should
+   determine whether expensive experiments are warranted.

docs/decisions/0019-diacritic-sensitive-risk-matching.md

@@ -0,0 +1,67 @@
+# 0019 Diacritic-Sensitive Risk Matching
+
+Date: 2026-08-11
+
+## Status
+
+Accepted
+
+## Context
+
+The risk engine matched every lexicon term against diacritic-folded text, so
+that undiacritized ASR output ("toi bi di ung") would still reach the allergy
+gate. Folding is lossy in Vietnamese, and unrelated words collapse onto the
+same string:
+
+- `nhỏ tai` (ear drops, a route cue) and the `nhớ tái` in `nhớ tái khám`
+  (remember to come back) both fold to `nho tai`.
+- `nhẹ` (mild, a critical symptom-severity cue) and `nhé` (a friendly
+  sentence-final particle) both fold to `nhe`.
+
+Ordinary clinical courtesy therefore produced high and even critical risk
+tiers. `Nhớ tái khám nhé` classified as **critical**, gating a benign sentence
+behind clinician confirmation. Over-gating is the safe direction for a single
+turn, but at this rate the confirmation gate carries no signal: it fires on
+almost everything, so a clinician learns to dismiss it, which is exactly how a
+real dose error gets waved through.
+
+The existing 91-case fixture suite could not detect this. It asserts
+`expected_kinds <= produced_kinds`, a subset check, so it constrains recall
+only and is structurally blind to false positives.
+
+## Decision
+
+Match diacritic-sensitively first. Fall back to folded matching only where the
+matched region of the original text carries no diacritics of its own.
+
+The check is applied per matched region rather than per turn, so text that lost
+tone marks on only some words still matches on those words. `Tôi bị di ung
+penicillin` continues to reach the allergy gate.
+
+Word-anchor multi-word terms as well as single-word terms; previously only
+single-word terms were anchored and multi-word terms used an unanchored
+substring search.
+
+Add `interpreter/eval/fixtures/risk_precision_cases.jsonl` and
+`test_risk_precision_cases`, a second fixture set carrying `max_tier` and
+`forbidden_kinds` so false positives are assertable. It is kept separate from
+`risk_cases.jsonl` so the 30-failure-mode coverage contract there is untouched.
+
+## Consequences
+
+- Benign Vietnamese no longer gates. `Nhớ tái khám nhé` is `low`, not
+  `critical`; `Cảm ơn bác sĩ` is `medium`, not gated.
+- Recall on undiacritized and partially diacritized ASR text is preserved, and
+  is now asserted rather than assumed.
+- All 91 risk fixtures, the 6 risk engine tests, and the 50-row mock safety
+  eval pass unchanged. Zero misses on critical fixtures still holds.
+- False positives are now a testable property of the engine. Any future
+  matching change that reintroduces a folding collision fails
+  `test_risk_precision_cases`; the guard was verified by mutation, confirming
+  it fails when the fix is reverted.
+- Not addressed, and still open: `uống` (to take orally) is a route cue that
+  fires on any sentence about drinking, so `Tôi uống nước` is `high`; and
+  Vietnamese number words normalize to digits while English number words do
+  not, so `sau ba ngày` against `after three days` raises a false
+  `number_mismatch`. Both are lexicon and normalization concerns rather than
+  matching concerns, and are left for a separate decision.