feat: add us-cpa preparation workflow

docs/us-cpa.md

@@ -4,14 +4,18 @@
 
 ## Current Milestone
 
-Milestone 2 now adds the first tax-year corpus layer:
+Current implementation now includes:
 
 - deterministic cache layout under `~/.cache/us-cpa` by default
 - `fetch-year` download flow for the bootstrap IRS corpus
 - source manifest with URL, hash, authority rank, and local path traceability
 - authority ranking hooks for IRS materials and future primary-law escalation
+- case-folder intake and conflict-stop handling
+- question workflow with conversation and memo output
+- prepare workflow for the current supported 1040 subset
+- e-file-ready draft export payload generation
 
-Tax logic, case workflows, rendering, and review logic are still pending.
+Review logic and broader form coverage are still pending.
 
 ## CLI Surface
 
@@ -102,7 +106,10 @@ Behavior:
 - `question` supports:
   - `--style conversation`
   - `--style memo`
-- `question`, `prepare`, `review`, `extract-docs`, `render-forms`, and `export-efile-ready` still emit scaffold payloads with `status: "not_implemented"`
+- `question` emits answered analysis output
+- `prepare` emits a prepared return package summary
+- `export-efile-ready` emits a draft e-file-ready payload
+- `review` is still scaffolded
 - `fetch-year` emits a downloaded manifest location and source count
 
 ## Question Engine
@@ -138,6 +145,41 @@ Current review rule:
 
 - overlay-rendered artifacts are marked `reviewRequired: true`
 
+## Preparation Workflow
+
+Current `prepare` implementation:
+
+- loads case facts from `extracted/facts.json`
+- normalizes them into the current supported 2025 federal return model
+- computes the current supported 1040 subset
+- resolves required forms for the current supported subset
+- writes:
+  - `return/normalized-return.json`
+  - `output/artifacts.json`
+  - `reports/prepare-summary.json`
+
+Current supported calculation inputs:
+
+- `filingStatus`
+- `wages`
+- `taxableInterest`
+- `businessIncome`
+- `federalWithholding`
+
+## E-file-ready Export
+
+`export-efile-ready` writes:
+
+- `output/efile-ready.json`
+
+Current export behavior:
+
+- draft-only
+- includes required forms
+- includes refund or balance due summary
+- includes attachment manifest
+- includes unresolved issues
+
 ## Scope Rules
 
 - U.S. federal individual returns only in v1