06 — Honesty Contract

Scope: [P0-06]. This doc is the single source of truth for what every feature is allowed to claim, in-app and in marketing. It does not re-derive OS facts or threat models — it cites them. Authoritative inputs:

• docs/research/03-os-constraints.md — the CAN / CANNOT / CAN-BUT-SHOULDN’T table. Any classification below that touches an OS capability traces to a row there.
• docs/research/04-reclaim-audit.md — measured bytes, regrowth class, and module-priority ranking from one real machine. Any classification below that claims a byte win cites a rank there.
• docs/research/05-trust-strategy.md — banned scareware/dark-pattern list (§6), the Review-screen mandate (§2), and the “no number before the itemized list” rule. This doc extends §6’s Banned Patterns with feature-specific bans.
• docs/research/02-competitors.md — what CleanMyMac/MacKeeper/PureMac/etc. actually market today, used to name the exact placebo claims we must not repeat.

Working decision from the task spec: the Maintenance suite ships. The rule governing it is not “cut it” — it’s “measure it, and never let it lie.”

Definitions used throughout:

• REAL — a measurable byte or time win we can prove per-item, at the moment we claim it.
• COSMETIC — users expect it, it does something real and harmless, but it has no provable byte/time win. May ship. Must carry an honest one-line description and must never contribute to a headline number.
• FALSE — cannot work as advertised, or is a category of claim macOS itself contradicts (03) or the trust strategy bans outright (05 §6). Must not ship as marketed; a narrower, honestly-relabeled version may ship instead, noted per row.

1. Per-feature claim table

Tally (rows 1–36): REAL 25 · COSMETIC 6 · FALSE 4 · not-shipped-at-all 1 (.lproj stripping).

2. Maintenance module — script by script

The Maintenance module ships (user decision). Every entry below is a real, individually-named script or system call — never a bundled “Run Maintenance” button that hides what actually ran. None of these contribute to the headline number except the two rows marked REAL, and even those carry their own caveats.

Evidence for this section: 03 items 6, 8, 9 (snapshots CAN; repair-permissions and free-RAM CANNOT-as-claims); 04 rank 17 (snapshot count confirmed, sizes unmeasured — privileged).

3. FORBIDDEN CLAIMS — exact phrases the app and marketing may never use

Extends the mechanical string-scan in 05 §6. Any occurrence anywhere in shipped .strings/.stringsdict resources, SwiftUI string literals, App Store copy, screenshots, or marketing copy is a release blocker.

1. “Repair permissions” / “fix permissions” (row: Maintenance §2 — no-op since 10.11).
2. “Free up RAM” / “boost memory” / “clear RAM” as a speed or performance claim (row 7 in §2’s table may say “recompression,” never “speeds up” or “frees memory” as a benefit).
3. “Reclaim purgeable space” / “free purgeable space” / any button whose action claims to reduce the APFS purgeable-space figure (03: no third-party API can force this; competitors who claim it — CleanMyMac, MacKeeper — are explicitly named as doing the wrong thing in 02).
4. “Speed up your Mac” / “optimize your Mac” / “boost your Mac” / “supercharge” as a blanket, un-itemized claim tied to cache clearing (05 §6.10).
5. “Mac Health Score,” any numeric/letter-grade aggregate, or a red/yellow/green gauge not backed by an individually-listed, inspectable metric (05 §6.5; row 33 above).
6. “Virus found,” “infected,” “threat detected,” “malware removed” — or any badge/counter implying them — outside a real, narrowly-scoped, honestly- labeled persistence audit (row 31; never claims “malware,” ever, 05 §6.5).
7. “Fixes app crashes” / “improves stability” attached to preference-file cleanup (row 7 — the causal claim is unverifiable; only the mechanical “unreadable file removed” fact may be stated).
8. Photos “junk” as a claim implying we distinguish cache from your actual photo library (row 15) unless scoped to Photos.app’s own documented cache subpath and labeled as such.
9. Any pre-scan, estimated, or rounded-up “GB found” / “reclaim up to N GB” number (05 §6.3) — see the headline-number rule in §4 below for the only number that is ever allowed.
10. “At risk,” “warning,” “danger,” “critical issue found,” “act now,” “immediately” applied to a normal, harmless condition (05 §6.1) — the only exception is a genuine, manifest-sourced per-item reasoning string on the Review screen (05 §2).
11. Countdown timers, “offer expires in,” “your discount ends in,” or any artificial deadline (05 §6.2).
12. “Clean Now” / “Optimize” / “Boost” as a confirm-button label — the button must state the literal action (“Delete N items (X GB)”), per 05 §2.
13. Any claim of automatic, unattended, or scheduled deletion — “Smart Clean,” “Auto-Clean,” “runs in the background so you don’t have to” applied to deletion (not scanning) — banned per 05 §6.7 and row 36 above.

Mechanical check adds these tokens to 05’s existing CI string-scan: repair permission, free.{0,3}ram, purgeable, health score, mac score, virus, infected, malware(?! audit), threat detected, fixes app crash, smart clean, auto[- ]clean, with the same allowlist-file exception process 05 already defines for genuine, manifest-sourced Review-screen strings.

4. Headline number definition — “X GB reclaimable”

The precise, auditable rule for the one number the app is allowed to show as its primary, prominent figure (home screen, notification, App Store screenshot):

The headline number is the exact sum, in bytes, of every row currently present on a completed Review screen (05 §2) for features classified REAL in §1 of this document, and only those rows.

Concretely:

1. Only REAL rows may contribute. COSMETIC and FALSE rows contribute zero, always, even when they mechanically produce nonzero bytes (row 7’s tiny plist bytes, row 8’s login-item change, etc.) — see the “Counts toward headline?” column in §1/§2, which is binding.
2. No number before the itemized list exists. Per 05 §2, scanning never pre-computes an estimate; the headline number is a sum of already-listed items, never a teaser shown before the scan finishes.
3. Surface-only categories (rows 20, 22, 23, 24, 25) count only after per-item user confirmation on the Review screen — never as a raw scan total, since these are judgment-call categories by design.
4. Async-reclaim categories (Maintenance §2’s snapshot thinning) are shown on their own line with their own disclaimer and are never summed into the same-second headline total, since macOS reclaims that space in the background after the call returns (03 item 6).
5. Never included, under any circumstance: APFS purgeable space (row — see 03’s dedicated CANNOT row), Photos “junk” (row 15), any Maintenance §2 script’s incidental bytes, “issues found” counts from the persistence audit (row 31), or anything from a diagnostic-only row (rows 9’s helper log, verify-disk, performance diagnostics).
6. Scheduled/background scans (row 35) may compute this same number for a notification (“Scheduled scan found 4.2 GB to review”) but that notification must deep-link straight to the Review screen — it is never a trigger for unattended deletion (row 36).
7. Exact bytes and item count, never rounded up (05 §2) — “12.4 GB across 1,204 items,” never “up to 40 GB.”

5. Audit procedure for P4-08

How a reviewer mechanically checks every shipped string against this contract, before any release:

1. Run the extended CI string-scan (§3’s token list layered on 05 §6’s existing scan) over every .strings/.stringsdict resource, every SwiftUI string literal reachable by a repo-wide grep for Text(/LocalizedStringKey, and all marketing copy in the public/App Store-facing repos. Any hit not in the reviewed allowlist file blocks the release.
2. Row-by-row string diff. For every feature screen in the shipped app, open the matching row in §1 or §2 of this doc and confirm the actual UI string is the allowed string (or a straightforward localization of it) — not a marketing-rewritten variant that drifted from the honest description. Flag and file any drift as a bug, not a doc update, unless the feature’s real behavior changed (in which case this doc updates first).
3. Headline-number trace. Grep the codebase for the function/reducer that computes the number shown as the primary headline figure. Confirm every contributing term traces to a rule id whose feature is classified REAL in §1, and that no COSMETIC/FALSE rule id, Maintenance-script byte count, or pre-scan estimate can reach that accumulator — structurally, not just “it’s unchecked by default.” This mirrors 05 §1’s principle that no path may exist in code that isn’t in the published manifest.
4. FALSE-feature absence check. Grep the full source tree (not just reachable UI) for the banned feature names in §1/§2 marked FALSE or NOT SHIPPED (repair permissions, .lproj stripping, malware/virus signature scanning, health-score aggregation, auto-delete scheduling, Photos-library- wide junk cleaning, purgeable-space “reclaim” actions). Existence in code even if unreachable from the UI is a release blocker — dead code here is a supply-chain and audit-trust risk (05 §4), not just clutter.
5. Screenshot walk. Manually step through every screen in a built, notarized dev copy, screenshotting each, and check each screenshot against the Banned Patterns list in 05 §6 (pre-checked “select all,” disabled Skip/No-thanks, health gauges, before/after imagery, countdowns) — this catches visual/layout violations the string-scan can’t (e.g. a disabled- looking decline button that isn’t literally disabled).
6. Maintenance-module isolation check. Specifically re-verify §2’s rule: run a Maintenance action in a debug build and confirm the app’s own internal event log shows it did not touch the headline-number accumulator or the Review-screen item list — this is the one module most likely to regress silently since its actions are scripts, not file deletes.
7. Sign-off record. The reviewer records the exact git commit SHA of this doc and of the app checked against it, alongside the release notes — so “which version of the honesty contract gated this release” is itself auditable later, matching the versioning discipline 05 §1 requires for the rules manifest.