100 lines
2.8 KiB
Markdown
100 lines
2.8 KiB
Markdown
# 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
|
|
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/
|
|
```
|
|
|
|
## 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.
|