# us-cpa

`us-cpa` is a Python CLI plus OpenClaw skill wrapper for U.S. federal individual tax work.

## Current Milestone

Milestone 2 now adds the first tax-year corpus layer:

- 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

Tax logic, case workflows, rendering, and review logic are still pending.

## CLI Surface

```bash
skills/us-cpa/scripts/us-cpa question --question "What is the standard deduction?" --tax-year 2025
skills/us-cpa/scripts/us-cpa prepare --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
skills/us-cpa/scripts/us-cpa review --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
skills/us-cpa/scripts/us-cpa fetch-year --tax-year 2025
skills/us-cpa/scripts/us-cpa extract-docs --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe --create-case --case-label "Jane Doe" --facts-json ./facts.json
skills/us-cpa/scripts/us-cpa render-forms --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
skills/us-cpa/scripts/us-cpa export-efile-ready --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
```

## Tax-Year Cache

Default cache root:

```text
~/.cache/us-cpa
```

Override for isolated runs:

```bash
US_CPA_CACHE_DIR=/tmp/us-cpa-cache skills/us-cpa/scripts/us-cpa fetch-year --tax-year 2025
```

Current `fetch-year` bootstrap corpus for tax year `2025` is verified against live IRS `irs-prior` PDFs for:

- Form 1040
- Schedules 1, 2, 3, A, B, C, D, SE, and 8812
- Form 8949
- General Form 1040 instructions and selected schedule/form instructions

## Interaction Model

- `question`
  - stateless by default
  - optional case context
- `prepare`
  - requires a case directory
  - if none exists, OpenClaw should ask whether to create one and where
- `review`
  - requires a case directory
  - can operate on an existing or newly-created review case

## Planned Case Layout

```text
<case-dir>/
  input/
  extracted/
  return/
  output/
  reports/
  issues/
  sources/
```

Current implementation writes:

- `case-manifest.json`
- `extracted/facts.json`
- `issues/open-issues.json`

## Intake Flow

Current `extract-docs` supports:

- `--create-case`
- `--case-label`
- `--facts-json <path>`
- repeated `--input-file <path>`

Behavior:

- creates the full case directory layout when `--create-case` is used
- copies input documents into `input/`
- stores normalized user-statement facts in `extracted/facts.json`
- appends document registry entries to `case-manifest.json`
- stops with a structured issue and non-zero exit if a new fact conflicts with an existing stored fact

## Output Contract

- JSON by default
- markdown available with `--format markdown`
- `question`, `prepare`, `review`, `extract-docs`, `render-forms`, and `export-efile-ready` still emit scaffold payloads with `status: "not_implemented"`
- `fetch-year` emits a downloaded manifest location and source count

## Scope Rules

- U.S. federal individual returns only in v1
- official IRS artifacts are the target output for compiled forms
- conflicting facts must stop the workflow for user resolution

## Authority Ranking

Current authority classes are ranked to preserve source hierarchy:

- IRS forms
- IRS instructions
- IRS publications
- IRS FAQs
- Internal Revenue Code
- Treasury regulations
- other primary authority

Later research and review flows should consume this ranking rather than inventing their own.