Skip to content

chore: publication cleanup — strip review residue, correct five stale claims, and say what was designed rather than built - #20

Merged
karolkulesza merged 15 commits into
mainfrom
chore/strip-internal-review-references
Aug 20, 2026
Merged

karolkulesza merged 15 commits into
mainfrom
chore/strip-internal-review-references

Conversation

@karolkulesza

@karolkulesza karolkulesza commented Aug 20, 2026 •

Copy link
Copy Markdown
Owner

Applies the publication review, points 1 and 3–7. Point 2 (rewriting Claude-Session: trailers out of history) is left alone as recommended.

1 · Strip the private-reference layer

~900 references across lib/, test/, integration_test/ and docs/ to things no reader of this repo can resolve: finding IDs (R0-F1, M19), "the reviewer", "review round N", and Task N.M pointing at a sprint plan that does not ship here.

The rule throughout was keep the claim, delete the provenance. Where a comment said "…because review finding R0-F8.3 refuted that", it now says why. Where it said "Task 1.8 measured…", it names the device. The hardest case was no_fake_in_production_test.dart, whose entire argument is the nine times it was wrong — each of those is now named by what it was (the wrapper that laundered a reference, the conditional import whose second URI was never read, the scripted InferenceHost that answered through the real engine) rather than by a ledger id.

TC-XXX-NN requirement ids are kept — they read as a traceability matrix.

3 · Doc staleness — five contradictions, all verified against the code

  • noRetry sites. The table covered eleven; there are fourteen. The three speech-path sites were measured here for the first time (delete the policy, run the whole suite) and all three survive, so the split is six bound / eight unbound.
  • Golden figures. Taken before form_autofill and before the second tool joined the registry, which widened every prompt. 933 chars/14 lines → 1283/15; widest 2363 → 2713; "five of six goldens carry an em dash" → all seven (no_manual_match gained one from the work-order tool's instruction).
  • TC-VOICE-FILL-01 said three different things in three files. It has since been run on hardware and passes; all four places now record the pass, and the README status row drops its caveat. The first-attempt failure is kept where it is instructive — the fixture delivered nothing until asked, so the screen reached listening after the assertion rather than before, and the app was right while the double was wrong.
  • stt_test.dart was "written and unrun" in testing.md while speech-to-text.md recorded it passing 3/3 on 2026-07-12. Corrected.
  • demo-screen.md narrated an unmerged PR Task 1.10: llm_golden snapshot suite — pinning the whole transcript, not a property of it #11 that merged long ago.

4 · README over-claims

  • "No network is required at any point after install" → no network at inference time; the 2.59GB first-run download is named.
  • "Every measured figure names the device it came from" → most do; where one does not, that is said.
  • The mutation harness is not in this repo, so its survivor counts are reported rather than reproducible from a clone. Stated in the README beside the claim.

Per your instruction, the "the reviewer is a second model session" sentence was not added.

5 · Dead scaffolding

VisionEngine and PlatformTelemetry — interfaces, fakes, providers and tests — had zero production consumers and go. lib/engines/providers.dart also still called the app a "skeleton" and streamed "FieldOps Copilot skeleton is running on the fake engine"; it now explains what its two remaining providers are for and why the device bindings live elsewhere. Host suite: 1179 → 1177.

6 · Platform and config

  • Apple DEVELOPMENT_TEAM blanked at all three sites in project.pbxproj.
  • Android label field_ops_copilot → Field Ops Copilot, matching iOS.
  • The two Flutter-template TODOs in build.gradle.kts replaced by the actual reasoning.
  • pubspec.yaml loses the generated boilerplate and the dead fonts block.
  • analysis_options.yaml was the stock template with every rule commented out. It now enables the analyzer's three strict modes plus a chosen rule set, each with its reason. The strict modes pass with zero findings — no implicit dynamic leaking through lib/ despite two FFI boundaries and a SendPort. Two rules are off with a stated reason; test/ and integration_test/ carry their own options file relaxing three production-lifecycle rules that misfire on a test double, while lib/ keeps all three.

7 · docs/testing.md rebuilt

The README sent readers there for tiers, mutation testing and the live-STT suite, and the page had none of the three. It now opens with what each tier cannot answer, states the mutation method and the three rules that make a result quotable, lists every recorded run including the one with eight survivors, and carries the CI story — the Flutter pin (a freshness gate that fires on Google's release is a gate people learn to ignore) and the codegen gate, including why git diff --exit-code alone is not enough.

Also: five dangling "see above" references from the monolith split are now real links, the three integration files the list never mentioned are added, "Tier 0/1/2" is gone everywhere, and four recursive self-correction passages are trimmed to their findings.

Added

A "Designed, not built" section in the README — eight decisions a fleet deployment forces, marked as design rather than code. Key management leads, because the honest answer is unflattering: the cipher is real and the key is a constant named not-a-secret, which protects a stolen file and not a stolen device. The Keychain/Keystore answer already has its seam, and so does the credential-delivery equivalent one layer out.

Verification

flutter analyze clean, dart format clean, 1177 host tests green. Generated sources regenerated so the codegen freshness gate still reports clean.

Doc comments referenced an internal task plan and review-finding ids that
are not part of this repository. Rewritten in place: pointers now name the
class, file or measurement they meant.
The docs carried finding IDs, review-round numbering and sprint-plan task
references that no reader of this repo can resolve. Every one of them was
attached to a claim that stands on its own, so the claim stays and the
provenance goes: "because review finding R0-F8.3 refuted that" becomes the
reason itself, and "Task 1.8 measured" becomes the device the measurement
came from.
Same treatment as the docs, applied to the dartdoc in lib/: finding IDs and
"the reviewer" attributions are replaced by the evidence they pointed at, so
a comment explaining why the code is shaped this way now explains it rather
than citing a ledger the reader cannot open.
…ked for them

Four groups in diagnose_screen_test.dart were named "R0-F1:" and friends,
which told a reader which review round produced them and nothing about what
they assert. They are now named after the behaviour under test. The same
substitution runs through the rest of the suite's comments.
no_fake_in_production_test.dart, mic_capture_test.dart and agent_loop_test.dart
all argue from the times they were wrong, and that argument is the point — but
it was told in finding IDs. Each defect is now named by what it was: the wrapper
that laundered a reference, the conditional import whose second URI was never
read, the scripted InferenceHost that answered through the real engine.
Every remaining "Task N.M" pointed at a plan no reader of this repo has. Each
one was standing in for something concrete — the retrieval router, the pinned
recogniser, the provisioner — so the concrete thing is named instead. Generated
sources regenerated so the codegen freshness gate still reports clean.
integration_test/ was the last directory still citing sprint-plan task numbers
and a review finding. The device suites are the ones a reader is most likely to
open first — they are where the measured figures live — so the same rule
applies: name the thing that was measured, not the task that measured it.
Four claims had gone stale, and they matter more than usual because these docs
argue from measurement:

- the noRetry table covered eleven sites; there are fourteen. The three speech
  ones are measured here for the first time and all three survive, so the split
  is six bound / eight unbound.
- the golden figures were taken before form_autofill and before the second tool
  joined the registry, which widened every prompt: 933/14 chars is now 1283/15,
  the widest is 2713 not 2363, and "five of six" goldens carrying an em dash is
  now all seven.
- TC-VOICE-FILL-01 said three different things in three files. It ran once,
  failed on its own fixture, was fixed, and was never re-run — which is what all
  three now say, README included.
- demo-screen.md narrated an unmerged PR that merged long ago.

Also corrects three README claims: no network is required at *inference* time,
not "at any point after install"; not every figure names its device; and the
mutation harness lives outside this repo, so its survivor counts are reported
rather than reproducible from a clone.
… language with them

Both interfaces, both fakes and both providers had zero production consumers:
vision/OCR was a stretch idea that was never started, and telemetry never got a
backend. Dead ambition reads worse than absent ambition, so they go.

lib/engines/providers.dart also still called the app a skeleton and streamed
'FieldOps Copilot skeleton is running on the fake engine' — from a file whose two
remaining providers are a deliberate host-test default, not an unfinished
binding. It now says which it is, and why the device bindings live elsewhere.
…sidue

analysis_options.yaml was the stock template — every rule commented out. It now
turns on the analyzer's three strict modes and a chosen rule set, each with the
reason it is there. The strict modes pass with zero findings, which is the useful
part: an app that crosses two FFI boundaries and a SendPort had no implicit
dynamic leaking through lib/.

Two rules are off with a stated reason (comment_references and
avoid_slow_async_io — the latter is backwards for an app whose argument is that
the UI isolate must not block), and test/ and integration_test/ carry their own
options file relaxing three production-lifecycle rules that misfire on a test
double. lib/ keeps all three.

Also: the Apple DEVELOPMENT_TEAM id is blanked at all three sites, the Android
label matches iOS's "Field Ops Copilot", the two Flutter-template TODOs in
build.gradle.kts are replaced by the actual reasoning, and pubspec.yaml loses
the generated boilerplate and the dead fonts block.
…it covered

The README sent readers here for tiers, mutation testing and the live-STT suite,
and the page had none of the three. It now opens with what each tier cannot
answer — which is why the next one exists — and the mutation section states the
method, the three rules that make a result quotable, and every recorded run
including the one with eight survivors, because eight published survivors say
more than a table of zeros.

The CI story moves here too: the Flutter pin (a freshness gate that fires on
Google's release is a gate people learn to ignore) and the codegen gate,
including why 'git diff --exit-code' alone is not enough and why a warm
build_runner cache makes a local pass prove nothing.

Also fixes the five dangling 'see above' references left from splitting the
monolith, adds the three integration files the list had never mentioned, and
corrects stt_test.dart from 'written and unrun' to the device pass that
speech-to-text.md had already recorded. 'Tier 0/1/2' is gone everywhere — it was
sprint-plan vocabulary that meant nothing to a reader here.
The distance between a working demo and a deployable product is mostly the
decisions this section names, and a README that omits them is quietly claiming
to have closed it. Eight of them, each marked as design rather than code.

Key management leads, because it is the first thing an enterprise-mobile reader
will ask and the honest answer is unflattering: the cipher is real and the key is
a constant named 'not-a-secret', which protects a stolen file and not a stolen
device. The Keychain/Keystore answer already has its seam —
databaseEncryptionKeyProvider — and so does the credential-delivery equivalent
one layer out. Naming the seam is what makes the design answer checkable rather
than a wish.
Four passages spent more words on the history of the sentence than on the fact
it states — a guard auditing the guard that audits it, a count corrected by
explaining how it was miscounted. Past the third instance that reads as house
style rather than as rigour, which undercuts the instances where it earns its
place. The findings stay; the recursion goes. Also drops the last commit SHA
cited from a doc.
The run has happened. All four places that said it never had — the test's own
doc, voice-and-work-order.md, device-test-scenarios.md and the README status
footnote — now record the pass, and the README row drops its asterisk.

The first-attempt failure stays where it is useful, because what it demonstrated
is the reason the device tier exists: the fixture delivered nothing until asked,
so the screen reached 'listening' after the assertion rather than before, and the
app was right while the double was wrong. A double gentler than the hardware is a
test that cannot fail.

Also renames speech-to-text.md's 'Owed on a device' heading, which had said owed
since the run it records passing.
@karolkulesza
karolkulesza merged commit 18537e1 into main Aug 20, 2026
1 check passed
karolkulesza added a commit that referenced this pull request Aug 20, 2026
…references

chore: publication cleanup — strip review residue, correct five stale claims, and say what was designed rather than built
@karolkulesza
karolkulesza deleted the chore/strip-internal-review-references branch August 21, 2026 14:05
karolkulesza added a commit that referenced this pull request Aug 22, 2026
…references

chore: publication cleanup — strip review residue, correct five stale claims, and say what was designed rather than built
karolkulesza added a commit that referenced this pull request Aug 23, 2026
…references

chore: publication cleanup — strip review residue, correct five stale claims, and say what was designed rather than built
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant