# HomeTill · Phase 0 UI spec v0

**Date:** 2026-09-27  
**Authorship:** John Jeremy (TsiRiaK) · KaiRis Systems  
**Class:** product + engineering spec  
**Epistemic tier:** **B** (buildable) · money path **C** (simulated until W5)  
**Authorized:** Jeremy — `make it so`  
**North star:** `processes/2026-09-26_PortAbleRI_HomeTill_Zip-Chapter_North-Star_v0.md`  
**Pilot ZIP:** `processes/2026-09-27_Home-Till_Pilot-ZIP-Selection_v0.md`  
**Law:** `hometill_disbursement_enabled` **false** · accrual **simulated** · export always  
**Entity:** Build as **HomeTill** product surface; PortAbleRI = **affiliation adapter** only — `processes/2026-09-27_HomeTill_PortAbleRI_Separate-Affiliated-Entities_Direction_v0.md`  
**Canonical host:** **https://www.hometillzip.com** — `processes/2026-09-27_HomeTill_Canonical-Domain_HomeTillZip_v0.md`

---

## 1 · Phase 0 goal

Ship **ZIP chapter experience** end-to-end in software: membership binding, requests, Family cull/finish, edit window, publish, weighted vote, period export + aggregate hash — **without** disbursement, affiliate remittance, or Stripe till routing.

**Success:** one **demo or 03878** chapter completes a **full monthly cycle** in staging with verifiable export bundle.

---

## 2 · Out of scope (hard)

- Real escrow, ACH, Stripe Connect till routes  
- `hometill_disbursement_enabled` · affiliate **Qualifying Gross** remittance  
- White Flag W3 briefing · public coalition mic  
- Production PII beyond verify tier needed for staging  

---

## 3 · Core entities (chapter record)

```text
ZipChapter        { id, zip, display_name, status, pool_simulated_balance, created_at }
ChapterMember     { id, chapter_id, user_id, class: paid|free_approved|enterprise,
                    vote_weight, address_verify_ref, ri_flags[] }
GovernancePeriod  { id, chapter_id, label, state: intake|cull|edit|publish|vote|closed,
                    opens_at, closes_at, aggregate_hash }
Request           { id, period_id, submitter_member_id, body_original, created_at,
                    eligibility_tags[], charter_tier?, status: submitted|culled|on_ballot|rejected }
CullSession       { id, period_id, family_roles[], audit_log[], selected_request_ids[3] }
EditSuggestion    { id, request_id, member_id, body, created_at, merge_status }
BallotFinish      { id, period_id, slot: 1|2|3, title, body_plain, cost_band, publish_at }
Vote              { id, period_id, member_id, finish_id, weight }
RiFlag            { id, member_id|request_id, code, severity, note }
AffiliateLedgerRow  (schema only Phase 0) { period, affiliate_id, gross, till_pct, zip_chapter_id, amount, verify_hash }
```

**Provenance:** `body_original` immutable; staff merges **append** to audit log; no silent overwrite.

---

## 4 · State machine (monthly cycle)

```mermaid
stateDiagram-v2
  [*] --> intake
  intake --> cull: period close intake
  cull --> edit: Family publishes 3 candidates
  edit --> publish: 7d elapsed · Family finishes 3
  publish --> vote: hash published
  vote --> closed: vote window end
  closed --> [*]
```

**Threshold:** winner needs **≥34%** of **weighted votes cast** (configurable constant).

---

## 5 · Screens / routes (v0)

**Deploy on:** `https://www.hometillzip.com` (path prefix below).

| Route | Actor | Function |
|-------|--------|----------|
| `/` | Public | Home · ZIP lookup · affiliate program intro |
| `/affiliate` | Public / partner | Affiliate program · declared till % · onboarding hollow |
| `/affiliate/:affiliate_id` | Public | Transparency · declared % · monthly hash |
| `/zip/:zip` | Public | Chapter home · simulated balance · period status · RI public aggregates only |
| `/zip/:zip/join` | Neighbor | Free approved apply · address-in-ZIP verify hook |
| `/zip/:zip/request` | Member | Submit request · Z-tag checklist self-attest |
| `/zip/:zip/period/:id` | Member | View intake list (original text) · edit suggestions when open |
| `/zip/:zip/family/cull` | Family role | Reduce to 3 · audit log |
| `/zip/:zip/family/finish` | Family role | Merge edits → 3 **BallotFinish** rows |
| `/zip/:zip/vote/:periodId` | Member | Weighted vote · show published hash first |
| `/zip/:zip/export/:periodId` | HOST / auditor | JSON + CSV bundle + sidecar SHA-256 |

**Badge copy (simulated money):** “Accrued (simulated) — not disbursed until White Flag W5.”

---

## 6 · Eligibility UX (north star v0.2)

- Submit form: checklist **Z-1–Z-10** + optional **charter tier** (Established / Audited / Proposed)  
- Family cull: show auto-hints for **N-1–N-14** · counsel red lines from W1 when loaded  
- Reject/return requires **reason code** in audit log  

---

## 7 · RI layer (assist only)

- Duplicate address · velocity · border-ZIP pattern → `RiFlag` surfaced to Family · not auto-veto in Phase 0  
- Export includes `ri_flags.json`  

---

## 8 · Export bundle (period close)

| File | Contents |
|------|----------|
| `period.json` | GovernancePeriod + finishes + vote totals |
| `requests.json` | Original submissions + append-only audit |
| `votes.csv` | `member_id, weight, finish_id` (no street address) |
| `ledger_sim.csv` | Simulated accrual rows `{subscriber_id, period, till_pct, amount}` |
| `aggregate.sha256` | Hash over canonical JSON concatenation |

Verify script stub: `scripts/verify_home_till_period.sh` (Phase 0 TODO in engineering thread).

---

## 9 · Feature flags

| Flag | Phase 0 |
|------|---------|
| `home_till_ui_enabled` | **true** (staging) |
| `hometill_disbursement_enabled` | **false** |
| `home_till_simulated_accrual` | **true** |
| `home_till_affiliate_checkout` | **false** |

---

## 10 · Build order (engineering)

1. `ZipChapter` + `GovernancePeriod` + public chapter page  
2. Member + request intake + export of originals  
3. Family cull/finish (role-gated)  
4. Edit window + publish hash gate before vote  
5. Weighted vote + close + export bundle  
6. RI flags read-only  
7. Affiliate ledger row **types only** (no UI checkout)  

---

## 11 · Acceptance tests (manual v0)

- [ ] Paid member weight **1.0** · free approved **0.1** on same ballot  
- [ ] Vote blocked until `aggregate_hash` displayed  
- [ ] Original request text unchanged after edit merge  
- [ ] Simulated balance unchanged by vote (no disbursement)  
- [ ] Export reproduces hash locally  

---

## 12 · Pointers

- Counsel: `processes/2026-09-27_Home-Till_White-Flag-W1_Counsel-Packet_v0.md`  
- Affiliate terms (hollow): `processes/2026-09-26_Home-Till_Affiliate-Program-Terms-Skeleton_v0.md`  
- Public headline (Tier C): see Family send-ready doc  

---

*Phase 0 proves the chapter record. Phase 1 binds **03878** + escrow.*