Feat/prior auth enterprise v2

.env.example

@@ -0,0 +1,9 @@
+PA_COPILOT_LOG_LEVEL=WARNING
+PA_COPILOT_RULES_PATH=rules/payer_rules.yaml
+PA_COPILOT_PROVENANCE_PATH=rules/provenance.yaml
+PA_COPILOT_POLICY_SOURCES_PATH=rules/policy_sources.yaml
+PA_COPILOT_SNAPSHOT_ROOT=policy_snapshots
+PA_COPILOT_SYNTHETIC_CASES_PATH=inputs/synthetic_cases.json
+PA_COPILOT_ARTIFACTS_DIR=docs/artifacts
+PA_COPILOT_API_HOST=127.0.0.1
+PA_COPILOT_API_PORT=8000

.github/workflows/ci.yml

@@ -5,7 +5,7 @@ on:
   pull_request:
 
 jobs:
-  pytest:
+  quality:
     runs-on: ubuntu-latest
 
     steps:
@@ -22,5 +22,14 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install -r requirements.txt
 
+      - name: Run Ruff
+        run: ruff check .
+
       - name: Run pytest
         run: pytest -q
+
+      - name: Generate demo artifacts
+        run: python -m scripts.generate_artifacts
+
+      - name: Generate golden outputs
+        run: python -m scripts.generate_golden_outputs

.gitignore

@@ -14,3 +14,18 @@ __pycache__/
 policy_snapshots/**/__pycache__/
 policy_snapshots/**/*.pyc
 policy_snapshots/**/.DS_Store
+
+# Internal planning / audit residue
+WORKLOG.md
+IMPLEMENTATION_PLAN.md
+SECOND_PASS_PLAN.md
+MARATHON_PASS_PLAN.md
+FINAL_FREEZE_AUDIT.md
+PUSH_SUMMARY.md
+RELEASE_NOTES_LAST_3_SPRINTS.md
+PUBLIC_DOCS_AUDIT.md
+PUBLIC_REPO_CLEANUP_SUMMARY.md
+inputs/test_plan.md
+docs/notes/
+docs/LOCAL_WORKFLOW.md
+docs/REFUSAL_IS_A_FEATURE.md

DESIGN_DECISIONS.md

@@ -0,0 +1,68 @@
+# Design Decisions
+
+## 1. Deterministic Before LLM
+
+Reason:
+
+- easier to defend in interviews
+- easier to audit
+- easier to regression test
+
+Tradeoff:
+
+- narrower extraction coverage
+- less tolerance for messy phrasing
+
+## 2. `CANNOT_DETERMINE` As A First-Class Result
+
+Reason:
+
+- missing documentation should not be silently inferred away
+
+Tradeoff:
+
+- more refusals
+- less superficially impressive throughput
+
+## 3. Shared Service Layer Instead Of Rewriting The Engine
+
+Reason:
+
+- the original deterministic core was already credible
+- the real weakness was orchestration inside the UI
+
+Tradeoff:
+
+- some engine modules still use dictionary-shaped internals under the service boundary
+
+## 4. FastAPI And CLI Added, No Database Added
+
+Reason:
+
+- interview-friendly product shape
+- no need for persistence in the current scope
+
+Tradeoff:
+
+- no multi-user state
+- no historical run store
+
+## 5. Governance-Only Drift Monitoring
+
+Reason:
+
+- useful enterprise signal without pretending to solve policy lifecycle management
+
+Tradeoff:
+
+- humans must still update rules and tests after drift
+
+## 6. Synthetic Fixtures Reused Everywhere
+
+Reason:
+
+- one source of truth across demo, tests, CLI, API, and artifact generation
+
+Tradeoff:
+
+- realism is intentionally bounded

EXTRACTION_CONTRACT.md

@@ -5,7 +5,7 @@ Scope: Deterministic extraction only
 Current repo status: implemented and deterministic; no LLM is used anywhere in the extraction path  
 Output: `(facts, evidence_map)`
 
-This document describes the extraction behavior implemented in [engine/extract.py](/Users/nicholasleko/projects/PriorAuthorizationCopilot/engine/extract.py).
+This document describes the extraction behavior implemented in [engine/extract.py](engine/extract.py).
 
 ## 1. Core Rules
 
@@ -55,6 +55,16 @@ Current behavior:
 - `inconclusive` when imaging is mentioned without a usable result, or when findings are normal, unclear, unknown, or otherwise non-blocking.
 - Imaging mention without a result is treated as documented `inconclusive`, not `null`.
 
+### `mechanical_symptoms_documented`
+
+Type: `bool | null`
+
+Current behavior:
+- Returns `True` when supported mechanical symptom phrasing such as `locking`, `catching`, `buckling`, `giving way`, or `instability` is explicitly present.
+- Returns `False` when those symptoms are explicitly denied with supported negation phrasing.
+- Returns `null` when the note does not explicitly address the supported symptom phrases.
+- Positive phrasing takes precedence if the note contains both denial and later affirmative mechanical-symptom language.
+
 ### `osa_diagnosis`
 
 Type: `bool | null`
@@ -100,6 +110,7 @@ Current behavior:
 - `Denies weakness. No saddle anesthesia.` -> `neuro_red_flags_documented = True`
 - `Prior MRI reviewed` -> `prior_imaging_result = "inconclusive"`
 - `No prior imaging yet` -> `prior_imaging_result = "none"`
+- `Denies locking or instability` -> `mechanical_symptoms_documented = false`
 - `Sleep study completed 2024-05-18` -> `sleep_study_date = True`
 - `AHI 22 documented` -> `ahi_documented = True`
 - `AHI not stated` -> `ahi_documented = null`

INTERVIEW_TALKING_POINTS.md

@@ -0,0 +1,94 @@
+# Interview Talking Points
+
+## 30-Second Summary
+
+This repo is a deterministic prior authorization readiness copilot for synthetic demo cases. It checks administrative readiness against narrow, versioned payer rules, returns blocker-level reasoning and evidence mapping, exposes the same workflow through Streamlit, FastAPI, and a CLI, and now includes a lightweight rulebook and governance layer. It does not make clinical judgments, predict approval, or act autonomously.
+
+## 2-Minute Walkthrough
+
+1. A synthetic request enters through the UI, API, or CLI.
+2. The shared service validates scope and normalizes the request.
+3. Deterministic extraction pulls a narrow fact set and evidence spans from note text.
+4. Deterministic evaluation applies versioned payer requirements and returns `READY`, `NOT_READY`, or `CANNOT_DETERMINE`.
+5. The result includes blockers, requirement-level reasoning, extracted facts, audit metadata, and a deterministic administrative letter option.
+6. Separate governance surfaces track policy drift and rulebook promotion without mutating runtime logic automatically.
+7. The third pass added a non-spine knee MRI pathway, versioned rulebook snapshots, stale-source reporting, and golden acceptance checks.
+
+## Why This Matters In Healthcare Admin Workflows
+
+- many prior auth delays are administrative documentation failures, not deep clinical disagreements
+- deterministic readiness checks can reduce preventable back-and-forth before submission
+- refusal-first behavior is safer than pretending certainty when documentation is incomplete
+- auditable outputs matter because reviewers need to know exactly why a request is blocked
+
+## Why Deterministic Before LLM Here
+
+- the supported scope is intentionally narrow
+- requirement semantics matter more than broad language flexibility
+- deterministic outputs are easier to test, explain, diff, and govern
+- the repo is meant to show disciplined product framing, not prompt theater
+
+## Safety And Governance Rationale
+
+- synthetic-only inputs avoid PHI and production-readiness theater
+- `CANNOT_DETERMINE` is an explicit safety feature
+- unsupported scope is rejected instead of guessed through
+- rulebook promotion is human-driven
+- drift monitoring is governance-only and never auto-updates runtime rules
+
+## What Changed Across The Three Passes
+
+### v1
+
+- pulled orchestration out of the Streamlit app
+- added typed service, API, CLI, artifacts, and stronger docs
+
+### v2
+
+- added cervical MRI
+- strengthened provenance metadata and registry surfaces
+- added Streamlit sanity coverage and richer artifacts
+
+### v3
+
+- added a non-spine knee MRI pathway with one new extractor field
+- introduced reviewed vs active rulebook snapshots and release diffs
+- surfaced stale drift baselines and review reasons
+- added golden acceptance snapshots for representative product outputs
+
+## Limitations
+
+- one payer only
+- four supported procedures only
+- pattern-based extraction only
+- one monitored policy source only
+- no persistence, auth, or deployment stack
+- not production-ready for real healthcare operations
+
+## Next Real Product Steps
+
+- add a second monitored source only with a clean offline baseline
+- expand procedure coverage only when a new pathway can stay equally deterministic
+- tighten the human review workflow around rulebook promotion
+- add structured intake adapters before adding any storage layer
+
+## Tradeoffs Intentionally Made
+
+- chose explainability over broad coverage
+- chose one narrow non-spine pathway over a larger procedure list
+- chose a lightweight rulebook over a full workflow platform
+- chose acceptance snapshots over more speculative feature work
+- chose to skip Docker, auth, and databases because they would add explanation burden faster than credibility
+
+## Top 10 Talking Points
+
+1. The repo solves administrative readiness, not approval prediction.
+2. `CANNOT_DETERMINE` is a deliberate refusal mode, not a failure.
+3. Deterministic logic was chosen because the supported scope is narrow and fully defensible.
+4. The same workflow powers Streamlit, FastAPI, CLI, exported artifacts, and golden acceptance snapshots.
+5. The third pass added a non-spine knee MRI pathway without turning the repo into a generic imaging engine.
+6. Evidence spans and structured provenance make outputs auditable instead of opaque.
+7. The rulebook shows reviewed vs active rule snapshots and release diffs without pretending to be a platform.
+8. Drift monitoring exists, but it is governance-only and never auto-promotes rule changes.
+9. Synthetic-only data keeps the repo safe to share and easy to test.
+10. The architecture stays intentionally compact: no database, no auth, no LLM layer, no fake enterprise complexity.

LIMITATIONS.md

@@ -0,0 +1,32 @@
+# Limitations
+
+## Scope Limits
+
+- only a small number of procedures are supported
+- payer coverage is intentionally narrow
+- supported sites of care are constrained
+
+## Extraction Limits
+
+- extraction is pattern-based, not language-model-based
+- unusual phrasing can remain unparsed
+- the system prefers missingness over aggressive inference
+
+## Governance Limits
+
+- drift monitoring is partial
+- only configured sources are monitored
+- rules are still curated offline
+
+## Product Limits
+
+- no persistence
+- no authentication
+- no user management
+- no deployment packaging beyond local/demo use
+
+## Healthcare Limits
+
+- not validated for real-world clinical or administrative operations
+- not suitable for real PHI workflows as currently packaged
+- not a substitute for payer policy review or human chart review

Makefile

@@ -1,15 +1,46 @@
-PYTHON ?= python3.12
+PYTHON ?= python3
 VENV_PYTHON ?= .venv/bin/python
+CASE ?= MRI-01-complete
+RUN_PYTHON := $(if $(wildcard $(VENV_PYTHON)),$(VENV_PYTHON),$(PYTHON))
 
-.PHONY: install run test
+.PHONY: install run api test lint format artifacts cli-status verify smoke-ui evaluate-case acceptance goldens
 
 install:
 	$(PYTHON) -m venv .venv
 	$(VENV_PYTHON) -m pip install --upgrade pip
 	$(VENV_PYTHON) -m pip install -r requirements.txt
 
 run:
-	$(VENV_PYTHON) -m streamlit run app.py
+	$(RUN_PYTHON) -m streamlit run app.py
+
+api:
+	$(RUN_PYTHON) -m uvicorn api:app --reload
+
+cli-status:
+	$(RUN_PYTHON) cli.py status
+
+evaluate-case:
+	$(RUN_PYTHON) cli.py evaluate --demo-case $(CASE)
 
 test:
-	$(VENV_PYTHON) -m pytest -q
+	$(RUN_PYTHON) -m pytest -q
+
+acceptance:
+	$(RUN_PYTHON) -m pytest -q test/test_acceptance_snapshots.py
+
+smoke-ui:
+	$(RUN_PYTHON) -m pytest -q test/test_streamlit_app.py
+
+lint:
+	$(RUN_PYTHON) -m ruff check .
+
+format:
+	$(RUN_PYTHON) -m ruff format .
+
+artifacts:
+	$(RUN_PYTHON) -m scripts.generate_artifacts
+
+goldens:
+	$(RUN_PYTHON) -m scripts.generate_golden_outputs
+
+verify: lint test artifacts goldens

NEXT_STEPS.md

@@ -0,0 +1,26 @@
+# Next Steps
+
+## Near-Term Realistic Next Steps
+
+1. Add a second monitored policy source only if it has a clean offline snapshot baseline and an equally honest governance story.
+2. Add one more supported procedure only if it can stay as deterministic and interview-defensible as the current four.
+3. Tighten the rulebook workflow with a real draft snapshot only when there is a concrete candidate change worth reviewing.
+4. Add a lightweight screenshot capture path only if it stays reproducible and dependency-light.
+
+## Intentionally Deferred
+
+1. Structured upstream intake adapters.
+2. Human analyst annotation and review queues outside the deterministic core.
+3. More explicit governance dashboards or operational telemetry.
+4. Additional browser-level smoke coverage beyond Streamlit AppTest.
+
+## Low-ROI Ideas Rejected On Purpose
+
+- LLM-first extraction
+- approval prediction
+- autonomous action
+- a database-backed platform rewrite
+- auth and deployment machinery
+- broad procedure expansion without a defendable rule contract
+
+Those ideas would widen the product story faster than they would improve credibility.