144 lines
4.1 KiB
Markdown
144 lines
4.1 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 question --question "What is the standard deduction?" --tax-year 2025 --style memo --format markdown
|
|
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` supports:
|
|
- `--style conversation`
|
|
- `--style memo`
|
|
- `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
|
|
|
|
## Question Engine
|
|
|
|
Current `question` implementation:
|
|
|
|
- loads the cached tax-year corpus
|
|
- searches a small IRS-first topical rule set
|
|
- returns one canonical analysis object
|
|
- renders that analysis as:
|
|
- conversational output
|
|
- memo output
|
|
- marks questions outside the current topical rule set as requiring primary-law escalation
|
|
|
|
Current implemented topics:
|
|
|
|
- standard deduction
|
|
- Schedule C / sole proprietorship reporting trigger
|
|
|
|
## 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.
|