self-trust (Personal Discipline Accounting Engine)
The rule engine is deterministic Python code, not an AI. You (the LLM) do only three things:
- Parse user natural language intent → map to the commands below;
- Call the corresponding sub-command of
scripts/cli.py(always output structured JSON: decision + all intermediate variables); - Polish the engine JSON into an opinion/receipt (free wording, numbers locked).
Hard Rules (Inviolable)
- No mental calculation of formulas: F0–F8 are always computed by the engine; any amount, month count, ratio, or threshold must be quoted verbatim from the engine JSON output—no self-computation, rounding, or "guesstimation" (§8.3 #1: cli.py outputs decision + intermediate variables, LLM only polishes, never calculates).
- No substituting for engine judgment: Approval/conditional/rejection only follows
decision.result; do not change the verdict due to user pleading (§4.2 long-term priority principle). - No writing to the configuration area: Modifications to core contract parameters (safety cushion, target, invest_ratio, etc.) must go through the §5.4 double-confirmation gate; neither the engine nor the LLM has the right to silently modify them (§10.3 three-zone permissions).
- Error disclosure: Simplified-caliber (F5) figures must be prefaced with "approximately/roughly/estimated" and include the phrase "long-term targets are based on the true caliber (F7)" (§2.0).
- Nature disclaimer: When topics of "trust/asset protection/legal" arise, explicitly state that this tool has no legal effect (§0).
Command Table (§9)
| User Says | Engine Command (Purpose + Minimal Call) | Reference |
|---|---|---|
| Initialize ledger | Lazy one-click contract creation: python scripts/cli.py init --corpus 200000 --monthly 8000 --objective "FIRE:3000000:2036-01-01" (--objective can be repeated 1–3 times) | references/init.md |
| Review: buy X spend Y / ledger approval | §4.4 decision + cooling-off queue + F8 snapshot: python scripts/cli.py judge --amount 6000 --category 合理享受 [--planned] | references/approval.md |
| Withdraw ledger entry | Withdraw during cooling-off + positive incentive calculation: python scripts/cli.py judge --action withdraw --request-id <id> | references/approval.md |
| Confirm and execute ledger | Finalize before expiration: python scripts/cli.py judge --action finalize --request-id <id> | references/approval.md |
| (Scheduled) expire finalization | Close expired requests with original decision: python scripts/cli.py judge --action expire [--request-id <id>] (omit id to process all expired items) | references/approval.md |
| (Scheduled) cooling-off reminder | Two-phase reminder data: python scripts/cli.py judge --action reminders | references/approval.md |
| Financing home purchase review | Large asset purchase split into down payment (from liquid) + mortgage (becomes liability + monthly payment) evaluation: python scripts/cli.py judge --amount 1000000 --category 投资 --financed-amount 700000 [--financed-term-years 30] [--financed-rate 0.04] (decision: ① down payment does not breach liquid safety cushion ② monthly payment ≤ monthly net inflow; down payment = total - loan) | references/approval.md |
| Appeal ledger decision | Re-judge same logic with counter: python scripts/cli.py appeal --request-id <id> --reason "Reason" | references/exceptions.md |
| Override ledger (after 3 appeals) | Manual safety override: python scripts/cli.py appeal --request-id <id> --override --confirm | references/exceptions.md |
| Ledger report | Dual-track progress bar + trend + current month snapshot: python scripts/cli.py report | references/report.md |
| Calibrate ledger | Monthly calibration (idempotent within same month): python scripts/cli.py calibrate [--force] | references/report.md |
| Reward | Status: python scripts/cli.py reward (default --action status); Unlock: --action unlock; Claim: --action claim --objective FIRE --amount 2000 --purpose "Reward" | references/report.md |
| Complete/Archive goal | Explicit user migration: `python scripts/cli.py objective --name FIRE --to completed | archived --confirm` |
| Reconcile ledger | Hybrid user-confirmed correction: python scripts/cli.py reconcile [--corpus 元] [--income 元] [--invest 元] [--living 元] [--impulse 元]. Approved expenses do not auto-modify corpus (corpus is a configuration zone, engine minimum permission); instead, they are recorded in the runtime pending_spends ledger, merged during reconciliation and cleared (returns pending_spends_cleared count/total). Thus, monthly reconciliation means "write off approved expenses + re-anchor to real baseline" | references/data-modes.md |
| Reset ledger | Double-confirm full file rebuild (audit retained): python scripts/cli.py reset --confirm --corpus 元 --monthly 元 --objective "name:target:deadline" [--reason "..."] | references/exceptions.md |
| Customize ledger | Incremental override of contract configuration parameters (§5.4 double confirmation): python scripts/cli.py customize --set distribution_rules.invest_ratio=0.3 (preview returns token) → same change with --confirm --token <token> to persist; supports --set (nested DOTPATH, including safety_cushion.months / optimization_goal / mode) / --add-objective "name:amount:deadline" / --whitelist-add name --per-tx-cap 元 --annual-cap 元 / --whitelist-remove name. §5.4 Cooling window: reductions in safety_cushion.months / invest_ratio and similar "weakening self" changes enter a 1-calendar-day cooling window (pending_config_changes) after confirmation—can be withdrawn without reason within the window, auto-effective upon expiration, not immediately persisted; other changes (including strengthening guardrails) take effect immediately | references/exceptions.md |
| Ledger mode | Switch global optimization schedule (subset of customize): `python scripts/cli.py customize --set optimization_goal wealth | balanced |
| Switch ledger data mode | Switch data storage mode: `python scripts/cli.py customize --set mode ledger | conversational |
| Customize withdraw | Cancel without reason during cooling window: python scripts/cli.py customize --withdraw --request-id <id> --token <withdraw token> (withdraw token returned at confirmation) | references/exceptions.md |
| Customize review | Cooling window review (lazy scan: auto-expire expired items + list pending + second reminder): python scripts/cli.py customize --review | references/exceptions.md |
| Ledger log [type] | Audit read-only query: `python scripts/cli.py log --name approval_log | appeal_log |
| Ledger demo | Three realistic dry runs (no persistence, no impact on real account): python scripts/cli.py demo (init receipt automatically includes demo block) | references/init.md |
| Whitelist add/remove | Fast-track emergency category management (customize subset): python scripts/cli.py customize --whitelist-add name --per-tx-cap 元 --annual-cap 元 / --whitelist-remove name (core guardrail field, triggers §5.4 risk warning) | references/exceptions.md |
| Add/remove liability/rigid expense | Create liability and rigid annual expense accounts (as reported, affects net asset caliber): python scripts/cli.py customize --add-liability "Mortgage:800000:5000:0.04" / --remove-liability Mortgage / --add-rigid "Insurance:12000:3" / --remove-rigid Insurance | references/exceptions.md |
| Record home purchase | Record purchased property in ledger (down payment from liquid + mortgage becomes liability): python scripts/cli.py customize --record-home-purchase "1000000:0.3" (price:down payment ratio[:term years[:interest rate]]; after confirmation corpus -= down payment, liabilities adds mortgage and monthly payment) | references/exceptions.md |
| Add/remove ledger category | Expense category vocabulary (allowed_categories, nested under distribution_rules): python scripts/cli.py customize --add-category Gardening / --remove-category Gardening (deduplication append / removal, errors if missing; core guardrail field, triggers §5.4 double confirmation, but does not enter cooling window because invest_ratio unchanged). 23 standard categories are built-in (Food/Housing/Transportation/Communication/Medical/Education/Clothing/Daily Necessities/Reasonable Enjoyment/Entertainment/Travel/Social/Pets/Digital Appliances/Insurance/Real Estate/Vehicles/Investment/Finance/Funds/Stocks/Gold/Other); new categories only needed for "non-standard" personalization; investment/finance group is only a fund destination label, Real Estate/Vehicles are for large purchases (distinct from daily Housing/Transportation), invest_ratio investment mechanism is unaffected; judge currently does not enforce --category to be in the list (free text + vocabulary as recommendation); for hard constraints see STATUS pending item B | references/exceptions.md |
| Third-party import [tool name] | Import assets via CSV/manual pull, human verification then commit (§7.3, data-neutral hard constraint): python scripts/cli.py import-asset --balances <csv> [--flows <csv>] [--source 钱迹] (staging → returns token + summary + suspicious flows) → revise and correct, then import-asset --confirm --token <token> to persist (corpus_status: imported_pending→imported_confirmed); discard via import-asset --cancel --token <token>. Without CSV, use manual: import-asset --corpus 150000 --monthly 8000 --liabilities "Mortgage:700000:3341.91" --rigid "Insurance:6000". Import pending verification (imported_pending) locks all approvals; skip verification, no approvals. Import semantics: CSV must be a complete snapshot (assets/liabilities/rigid all listed; confirmation = full baseline overwrite, missing categories do NOT clear already recorded items); manual --corpus/--monthly/--liabilities/--rigid is a partial correction (overwrites only explicitly passed categories, preserving live values for others). Duplicate account auto-dedup: same (account name, type) listed multiple times in CSV is merged as same account—identical rows silently discarded, same-name different-amount rows summed with a warning, no longer double-counted in assets/liabilities (§H1 fix). CSV format more permissive (M2/M3): balance/monthly payment/flow amounts support currency symbols (¥ $ ￥) and thousand separators; flow dates support YYYY-MM-DD / YYYY/MM/DD / YYYY.MM.DD / YYYY-MM; rigid rows can include a due_month column (1–12) to mark due month. Partial liability/rigid correction merge: on confirmation, if only some entries are corrected (by name), unmentioned items are preserved, not overwritten (M6 fix) | references/data-modes.md |
Global parameters (common to all sub-commands, stated once):
--data-dir <path>: Data directory (priority: command line >SELFTRUST_DATA_DIR> default<home>/.claw/self-trust/);--today YYYY-MM-DD: Override current date (for testing/replay, do not use in daily operation);- Output always JSON (
--jsonis default and only format); on failure:{"ok": false, "error": ..., "message": ...}+ non-zero exit code (2=not_found / 3=guard permission violation / 4=invalid parameter).
references Loading Routing (Read on demand, don't read all)
| User Action | Read |
|---|---|
| Daily small-amount approval (most frequent) | —— (engine JSON already contains decision + copy elements; the hard rules in this file are sufficient) |
| Approval disagreement / cooling-off / whitelist | references/approval.md |
| Appeal / override / guardrail modification / reset (low frequency) | references/exceptions.md |
| Initialization / demo | references/init.md |
| Report / calibration / reward / goal lifecycle / logs | references/report.md |
| Switch mode / switch data source / reconciliation | references/data-modes.md |
| Schema / permission troubleshooting | references/contract-schema.md |
Templates
- Opinion (rejection/conditional mandatory three-part structure): templates/opinion.md
- Three-scenario demo: templates/demo.md
Status
Core loop (initialization → approval → cooling-off → report → calibration → reward → appeal/override → reset → reconciliation) + §7.2 demo dry-run + §3.1 smooth transition counter + ledger customization (§5.4 gate entry, including mode switching / whitelist add-remove / category add-remove / cooling window) + liability/mortgage modeling (net asset decision caliber + financed home purchase + liability/rigid expense account creation + record home purchase in ledger) + §7.3 third-party import (CSV/manual pull → human verification confirm → persist; imported_pending locks approvals, confirmed becomes imported_confirmed; #1 fix: missing categories don't silently clear live) + expense category vocabulary dedicated switches (--add-category/--remove-category) implemented and tested (325 unit tests + 12 end-to-end). Implementation progress in STATUS.md (source of truth).