[RobGrafrath]

What this changes and why

Rob Grafrath directed that anything specific to the United States belongs in a United States module or pack, and that the base decisions describe the mechanisms that packs configure. In his words, "Disputes are universal but the FDCPA is not." This pull request applies that direction to every base decision, as cluster 1 of the design review.

• HIVE-0007 (3.0) no longer states federal law. Its Decision and its section on several debts now describe two core mechanisms in terms of amounts: the consumer's allocation directions win over any default, and money the consumer did not direct never applies to an amount in dispute. A debt whose whole balance is disputed receives nothing from such money, a debt with a disputed part receives it only for the rest, and what cannot be applied becomes the consumer credit balance of HIVE-0006. No configuration relaxes either rule.
• The new MOD-US-0004 Federal Payment Allocation Across Debts carries the premises that HIVE-0007 stated as federal law. It quotes 15 U.S.C. 1692h, read on 2026-10-11, scopes the values to consumer debts, and flags each one for verification. Where the text is silent, the pack takes the cautious reading. A dispute counts whatever its form, a consumer debt with any disputed part is treated as disputed in whole for money the consumer did not direct, and a payment the consumer did not direct to a single wholly disputed debt becomes a credit balance. It also records Rob's answers that a directed excess is not spread to other debts under this pack and that the pack sets no deadline on a credit balance.
• The new MOD-US-0005 Interest and Fees carries the federal rule that a collector may add interest or a fee only when the agreement or the law permits it, from 15 U.S.C. 1692f(1) and 12 CFR 1006.22(b). MOD-UNSECURED-0001 stated that premise until now. Rates and caps that state law sets stay out of decisions and belong to the state packs.
• The sweep takes statute names out of WAX-0001's compliance rationale, WAX-0003's rationale, WAX-0011's planned packs and examples, and two open questions. Core text in WAX-0013, WAX-0014, WAX-0016, HIVE-0002, and HIVE-0003 now says national identity number where it said SSN. HIVE-0005 calls its since-date view the notice itemization, and "validation itemization" stays as the United States name in MOD-US-0001. HIVE-0004's side note names a notice that a jurisdiction requires. Labeled examples that point at the US modules stay, such as the US Locale Module's SSN in HIVE-0002's worked example, as Rob said they may.

The payment mechanisms that Rob described with this direction, namely disputed buckets, per-bucket interest settings, and a credit balance tied to no debt, come in a separate pull request stacked on this one. This pull request writes HIVE-0007's rules so that those mechanisms fit them.

Interacting decisions

• HIVE-0006: the consumer credit balance that receives money that cannot be applied.
• HIVE-0009: the declared regulatory nature that scopes MOD-US-0004 and MOD-US-0005 to consumer debts.
• WAX-0008, from Draw clean lines between modules, locale packs, compliance packs, and boilerplate packs #28: the default test, which this pull request applies. A question of law becomes a core mechanism with a cautious default, and the law's value lives in a pack, flagged.
• MOD-US-0001, from Rename account to debt and add multi-level debt grouping #27, and MOD-US-0003, from Add MOD-US-0003, federal contact times and call frequency #31: the same pattern for the validation notice and the contact values. MOD-US-0001 now says that its validation itemization is the United States form of HIVE-0005's notice itemization.
• MOD-UNSECURED-0001 (2.1): interest stays off by default as the cautious default, and the module links MOD-US-0005 instead of naming the FDCPA.

If this touches decisions/wax/

It touches WAX-0001, WAX-0003, WAX-0011, WAX-0013, WAX-0014, and WAX-0016. Every change is wording that names no statute, or that says national identity number instead of SSN, and no invariant changes. Hash chain integrity is untouched, because WAX-0013's periodic audit scan now looks for the identity number formats that the installed Locale Modules declare, which is a detection list and not part of the chain. Event immutability is untouched. Schema ownership is reinforced, because national identity numbers are Locale Module satellite fields under core schema neutrality, and WAX-0014's encryption list and WAX-0016's example now say so instead of naming a US field as if it were core. Module boundaries are untouched.

Version bumps

HIVE-0007 goes to 3.0 because its Decision text changes. HIVE-0002, HIVE-0003, HIVE-0004, HIVE-0005, WAX-0001, WAX-0003, WAX-0011, WAX-0013, WAX-0014, WAX-0016, and MOD-UNSECURED-0001 take a minor bump because they change outside their Decision sections. MOD-US-0004 and MOD-US-0005 are new and Proposed at 0.1. MOD-US-0001 gains one sentence pointing at the new core name, and as a proposal not yet merged it takes no bump.

Choices this draft makes

1. HIVE-0007's rules speak of amounts in dispute, not whole debts, so that a debt with a disputed part stays payable for the rest, as Rob's answer on partial disputes requires.
2. MOD-US-0004 takes three cautious readings. A dispute counts whatever its form. A consumer debt with any disputed part is treated as disputed in whole for money the consumer did not direct, until counsel settles whether such a debt is a "debt which is disputed" under the statute. A single wholly disputed debt receives no undirected money. The second reading needs a setting in the core's disputed-amount rule, which the payment mechanisms pull request will provide.
3. Interest and fees get their own decision, MOD-US-0005, instead of a section of MOD-US-0004, so that the federal rule and the US Boilerplate Pack's starting values for interest live in one place.
4. "Notice itemization" is the core name for the itemization that a required notice states, and "validation itemization" stays as the United States name.
5. Core text says national identity number. Labeled US Locale Module examples keep the SSN, and WAX-0005's naming example ("social_security_number, not ssn") stays because it illustrates the abbreviation rule and not law.
6. WAX-0011's closure reason example is "limitation period expired" instead of "statute of limitations", and its planned US packs become a general Compliance Packs entry that points at the United States module decisions.
7. MOD-US-0004 flags that a state's unclaimed property law may reach a credit balance held for a consumer, which needs research of its own. Rob's answer that the pack sets no deadline stands.

Stacked on #31

This pull request is based on #31, branch us-contact-values, which sits on #30, #29, #28, and #27, because it relies on the MOD-US family from #27 and the default test from #28. When #31 merges, its base moves on.

Checklist

• I read the decisions neighboring this change, not just the file I edited.
• New or retitled decisions have a matching line in INDEX.md, and front matter follows CONTRIBUTING.md.
• python3 scripts/validate.py --base main passes locally, or I am relying on CI to tell me.
• No pricing, rates, market or customer allocation, consumer data, or client-confidential information.
• Claims about law or regulation are flagged for verification, not asserted.
• Commits are signed off (DCO). If I forgot, I will post the retroactive sign-off comment per CONTRIBUTING.md.
• I license this contribution under CC BY 4.0 (prose) and Apache 2.0 (embedded code samples).

🤖 Generated with Claude Code