docs(android): M12 phase 8 as landed, and the two defects AC-5 found #119

wtclaude · 2026-08-08T16:05:00Z

wtclaude commented

2026-08-08 16:05:00 +00:00

What & why

Documents M12 phase 8 (Android-app#40) — the last phase of the Android theming & nav milestone.

Phase 8 was scoped as docs, coverage and the cutover. The AC-5 walk turned it into a phase with code in it, which is the outcome the walk existed to produce, so the record is longer than a phase-8 note would normally be.

android/THEMING_AND_NAV.md gains "Phase 8 as landed":

what the walk confirmed on device — including the Custom Tab checked in dumpsys rather than by eye, and AC-3 holding at every role rung;
the two defects and why they are phase 2's trap repeating (Material takes some themed values as default arguments, not from the theme — phase 2 found this for elevation and swept Card(; nobody asked whether colour and shape had the same problem);
why the card fix changes the untouched app, and why there is no variant that spares it;
the role sweep — which ColorScheme roles are still unmapped, which of them have a live reader (one: surfaceContainerHighest), and that scrim stays Material's black on purpose. Written so nobody redoes the measurement;
the coverage-glob narrowing;
an adb reverse rig note for the next walk, including not adding 10.0.2.2 to the debug network-security config.

It also amends the phase 2 note, which claimed the card shadow was the milestone's only visible change to an untouched instance. It is now one of three. The third has no code behind it and is purely a correction to the record: an untouched instance draws a hero on Home, because brand.hero carries the BRAND_HERO_IMAGE env default, so "the admin has set nothing" is not the same as "the slot is empty". Nothing is wrong — the website's own Home shows the same emblem and §5.6's blank-slot rule still holds — but a shard operator upgrading the app sees it without having touched Appearance.

android/PLAN.md's M12 entry stopped at phase 2. It now runs through phase 6, records phase 8 including both defects, and drops the same "one deliberate change" claim.

android/COVERAGE_PLAN.md gains an amendment section on why the ui/theme/** directory glob became wrong the moment M12 put three pure resolvers behind it — its own §5 already forbade excluding testable code — plus the general rule it suggests: prefer file globs to directory globs once a directory is mixed. ui/components/** stays a directory glob and correctly so.

Pairs with Android-app#40. Both target edge; the cutover is a separate edge → main PR.

How it was tested

Documentation only — no code in this repo. The claims recorded here were verified in the paired PR: 477 unit tests green, lintDebug and assembleDebug clean, and a two-pass AC-5 walk on an AVD against a local website, with both fixes re-verified on device afterwards. The Material role facts (FilledCardTokens.ContainerColor, and the token classes of every component the app draws) were read out of the material3 1.3.0 artifact's bytecode rather than assumed, the same method phases 1 and 2 used.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand
every change, and take responsibility for it. AI-authored commits are
marked with a Co-Authored-By / Assisted-By trailer.

License

I agree that my contribution is licensed under this project's license
(GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Documents **M12 phase 8** (Android-app#40) — the last phase of the Android theming & nav milestone. Phase 8 was scoped as docs, coverage and the cutover. The AC-5 walk turned it into a phase with code in it, which is the outcome the walk existed to produce, so the record is longer than a phase-8 note would normally be. **`android/THEMING_AND_NAV.md`** gains "Phase 8 as landed": - what the walk confirmed on device — including the Custom Tab checked in `dumpsys` rather than by eye, and AC-3 holding at every role rung; - **the two defects and why they are phase 2's trap repeating** (Material takes some themed values as default arguments, not from the theme — phase 2 found this for elevation and swept `Card(`; nobody asked whether colour and shape had the same problem); - **why the card fix changes the untouched app**, and why there is no variant that spares it; - **the role sweep** — which `ColorScheme` roles are still unmapped, which of them have a live reader (one: `surfaceContainerHighest`), and that `scrim` stays Material's black on purpose. Written so nobody redoes the measurement; - the coverage-glob narrowing; - an `adb reverse` rig note for the next walk, including *not* adding `10.0.2.2` to the debug network-security config. It also **amends the phase 2 note**, which claimed the card shadow was the milestone's only visible change to an untouched instance. It is now one of three. The third has no code behind it and is purely a correction to the record: **an untouched instance draws a hero on Home**, because `brand.hero` carries the `BRAND_HERO_IMAGE` env default, so "the admin has set nothing" is not the same as "the slot is empty". Nothing is wrong — the website's own Home shows the same emblem and §5.6's blank-slot rule still holds — but a shard operator upgrading the app sees it without having touched Appearance. **`android/PLAN.md`**'s M12 entry stopped at phase 2. It now runs through phase 6, records phase 8 including both defects, and drops the same "one deliberate change" claim. **`android/COVERAGE_PLAN.md`** gains an amendment section on why the `ui/theme/**` directory glob became wrong the moment M12 put three pure resolvers behind it — its own §5 already forbade excluding testable code — plus the general rule it suggests: **prefer file globs to directory globs once a directory is mixed**. `ui/components/**` stays a directory glob and correctly so. Pairs with **Android-app#40**. Both target `edge`; the cutover is a separate `edge` → `main` PR. ## How it was tested Documentation only — no code in this repo. The claims recorded here were verified in the paired PR: 477 unit tests green, `lintDebug` and `assembleDebug` clean, and a two-pass AC-5 walk on an AVD against a local website, with both fixes re-verified on device afterwards. The Material role facts (`FilledCardTokens.ContainerColor`, and the token classes of every component the app draws) were read out of the material3 1.3.0 artifact's bytecode rather than assumed, the same method phases 1 and 2 used. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` / `Assisted-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-08-08 16:05:01 +00:00

docs(android): M12 phase 8 as landed, and the two defects AC-5 found 6305d86a01

Phase 8 was scoped as docs, coverage and the cutover. The AC-5 walk turned it
into a phase with code in it, which is the outcome the walk existed to produce -
so the record is longer than a phase-8 note would normally be.

THEMING_AND_NAV.md gains "Phase 8 as landed": what the walk confirmed, the two
defects it found and why they are phase 2's trap repeating, the role sweep that
says which Material roles are still unmapped and which of them have a reader, the
coverage-glob narrowing, and the adb-reverse rig note for the next walk. The
phase 2 note is amended where it claimed the card shadow was the milestone's only
visible change to an untouched instance - it is now one of three, and the third
(an untouched instance drawing a hero, because brand.hero carries the env
default) is a correction to the record with no code behind it.

PLAN.md's M12 entry stopped at phase 2; it now runs through 6, records phase 8
including the defects, and drops the same "one deliberate change" claim.

COVERAGE_PLAN.md gains an amendment section explaining why the ui/theme/**
directory glob became wrong the moment M12 put three pure resolvers behind it,
and the general rule it suggests: prefer file globs to directory globs once a
directory is mixed. Its own §5 already forbade excluding testable code.

Pairs with Android-app phase 8.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech approved these changes 2026-08-08 16:06:23 +00:00

whitlocktech merged commit 433a3b920b into edge

2026-08-08 16:06:30 +00:00

whitlocktech deleted branch docs/android-theming-nav-phase-8

2026-08-08 16:06:31 +00:00

whitlocktech referenced this issue from a commit

2026-08-08 16:06:31 +00:00

Merge pull request 'docs(android): M12 phase 8 as landed, and the two defects AC-5 found' (#119) from docs/android-theming-nav-phase-8 into edge

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#119