Re-validate the doc tree: fix disproven claims, refresh the backlogs, adopt a what-not-why standard#149
Open
kyleve wants to merge 8 commits into
Open
Re-validate the doc tree: fix disproven claims, refresh the backlogs, adopt a what-not-why standard#149kyleve wants to merge 8 commits into
kyleve wants to merge 8 commits into
Conversation
Plan step: Rewrite disproven Project.swift comments + fix stale anchor. PR #145 corrected the root AGENTS.md — nothing in this project is a dynamic framework; the local package links statically into each consumer — but the code comments it points at still taught the old mechanism. - Project.swift: the WhereUITests and WhereIntentsTests comments no longer claim WhereUI is a dynamic framework or that several .xctest bundles co-load into one StuffTestHost process (each bundle gets its own). Both now cite the corrected anchor ("Never double-link a product WhereUI already carries") and PR #145 for the mechanism. - SnapshotCaptureFlagProbe.swift / WhereStylesheet.swift: dropped the "(a dynamic framework)" parentheticals from two doc comments found by the tree-wide sweep. Comment-only changes; no behavior. Verified with ./ide --no-open (project generates).
Plan step: Run bumper lint/test; delete false bootstrap paragraphs in .bumper/RULES.md. .bumper/RULES.md claimed three calendar violations and some preview-coverage violations were deliberately left visible "during this bootstrap". Neither exists: swift run bumper lint . reports no architecture violations (all 15 rule fixture tests green), and 52f0136 closed the preview ones. The paragraphs read as an enforced-drift demonstration that the tree no longer backs. Closes the docs(Bumper) P0 sub-item in TODOs.md (moved to Completed); the parent P0 — where.gregorian_calendar matches only an explicit Calendar base and so enforces nothing — was re-confirmed and stays open.
Plan step: Correct the ~10 confirmed-wrong AGENTS.md claims. Each claim was re-verified against Project.swift / Package.swift / source before editing: - Where/AGENTS.md: Where is an iOS/iPadOS app (destinations are iPhone/iPad; Catalyst is RegionViewer only), and App Intents run in the app process — WhereIntents is a library product linked into the app, not an extension with its own process. - WhereCore/AGENTS.md: widgets never talk to WhereServices; they read the App Group WidgetSnapshot. - Where/Where/AGENTS.md: attribution-sources.json lives at the module root, not beside Resources/attribution.json. - WhereShareExtension/AGENTS.md: the extension's compose/save path is its own ShareEvidenceModel (untested, tracked in Where/TODOs.md), not a WhereUI compose model. Closes that half of the Where/TODOs.md stale-doc-claims item. - RegionViewer/AGENTS.md: geometry-catalog coverage is RegionKitTests.RegionGeometryCatalogTests; RegionMapView coverage is WhereUISnapshotTests. - SnapshotKitTesting/AGENTS.md: StuffSnapshotTests is a scheme, not a bundle — consumers are the three per-module image bundles plus SnapshotKitTestingTests; ConcurrentCaptureTests and LargeViewCaptureTests live in SnapshotKitTestingTests; SnapshotCaptureFlagProbeTests lives in WhereUISnapshotTests; the SnapshotKit double-embed applies only to the WhereUI bundle. - Broadway/AGENTS.md + BroadwayCatalog/AGENTS.md: BroadwayCatalogTests is hosted by the BroadwayCatalog app, not StuffTestHost. - SwiftDataInspector/AGENTS.md: the fixture-name-clash caveat now states the measured per-bundle host-process model. - PeriscopeTools/AGENTS.md: dropped the 'were it ever dynamic' framing; nothing in this project builds as a dynamic framework. - CreditKit/AGENTS.md: SampleReport.json is a string constant on the SampleReport enum, not a fixture file.
Plan step: Refresh TODOs.md files: close stale/wrong items, fix drifted citations, merge duplicates. Every open item across the five touched backlogs was re-verified against source; citations below were checked at the cited line before rewriting. - Where/TODOs.md: deleted the open P0 'Remove waitForOneRunloop' — its call sites are gone and the Completed section already records the closure, so the open copy was a leftover duplicate (the never-delete rule protects completed entries, which stay). Moved the P2 'launch can park behind a permission prompt' to Completed as invalidated: reconcileTracking() (WhereSession.swift:282-293) only reads the current authorizationStatus and never requests authorization. Cross- linked the Elsewhere-inflection P1 with its pinned broken-snapshots reference. Noted the RootView 'four screens' half of the stale-doc- claims item as already fixed (RootView.swift now reads three tabs). Refreshed ~15 drifted file:line citations. - Shared/Periscope/TODOs.md: fixed the survivesRelaunch citations (policy SpanExit.swift:83-91, warn LogSpan.swift:569) and corrected the hosting-smoke item's stale one-bundle claims — the PeriscopeToolsSnapshotTests bundle now exists per the one-bundle-per- module shape (#143). Cross-linked the same debt in SwiftDataInspector. - Shared/LifecycleKit/TODOs.md: the duplicate-gate precondition moved to LifecycleKitUI/Sources/LifecycleContainer.swift:101; added citations. - Shared/CreditKit/TODOs.md: generate-attribution.rb citations were off by ~15 lines (regex :91, API interpolation :82).
Plan step: Codify the what-not-why rule format in the root AGENTS.md Per-module docs section. Adds the editorial standard the rest of this branch applies: a rule is an imperative sentence, at most one clause of consequence, and a pointer to the proof (guard test, PR/commit — squash merges keep PR bodies in git log — or a TODOs.md entry). Tripwires, diagnostic signatures, and decision rules stay at one line each; history narration, mechanism walkthroughs, and persuasion move to the PR that proved them. Pure groundwork: no behavior change; the shortening commits that follow execute against this standard.
Plan step: Rewrite Where-side AGENTS.md files to what-not-why. Fact-neutral rewrite per the codified policy: every rule, tripwire, and diagnostic signature survives; mechanism essays, history narration, and persuasion move to their proof (PR bodies reachable via git log, guard tests, TODOs.md entries). - Where/AGENTS.md 303 -> 189 lines: layering/logging rules compressed to imperatives + consequences; the About-screen design narrative reduced to its rules with a pointer to PR #140; localization and dates keep every rule, lose the rationale; install section points at --help. - WhereUI/AGENTS.md 175 -> 93: the design-system tutorial (using/adding tokens, RegionStyle resolver wiring, trait derivations) moved into README.md's Design system section, which previously pointed here for it; AGENTS.md keeps the rules and the capture-determinism seams (MotionIsStatic, WhereDatePicker). - WhereCore/AGENTS.md 174 -> 110: collaborator catalogs become pointers; the CalendarDay invariant keeps both halves (identity rule + the GPS-rebucketing scope boundary) as short rules. - WhereIntents/AGENTS.md 105 -> 80: the IntentServices handoff keeps its decision rules (parks, no self-open fallback, re-fired on relaunch); the perform()-untestable section keeps both measured traps. - Where/Where/AGENTS.md: attribution bullet tightened. - RegionKit and WhereWidgets already met the standard; untouched. Cross-file anchors into the edited files verified resolving (#layering, #testing, #swiftui-views--previews, #installing-to-a-device, #design-system--wherestylesheet).
Plan step: Rewrite Shared-side AGENTS.md files to what-not-why. Fact-neutral rewrite per the codified policy — every rule, tripwire, and guard-test pointer survives; mechanism essays and history move to their proof (Project.swift comments, PR #145, source doc comments, TODOs.md). - SnapshotKitTesting 129 -> 81: the process-model and double-embed essays become rules + tripwire, pointing at the snapshot-bundle comment in Project.swift (the one home for the topology); every guard test stays named (ConcurrentCaptureTests, LargeViewCaptureTests, SnapshotRenderingSupportTests, SnapshotCaptureFlagProbeTests). - PeriscopeCore 100 -> 77: each invariant keeps its one consequence clause; explanatory tails trimmed. - PeriscopeTools 109 -> 73: layout catalog collapsed to a line; design system keeps its rules; incremental-refresh invariant keeps the O(accumulated) note and TODO pointer. - CreditKit 81 -> 54: invariants keep their consequence clause, lose the persuasion. - LifecycleKitUI 64 -> 53 and LifecycleKit 87 -> 78: view-identity and identity-domain rules compressed; the deliberate-cost notes and the displayedSurfaceIdentity trap stay. - SnapshotKit 56 -> 50: hybrid-accessor mechanics now point at SnapshotCaptureFlag.swift's own docs, keeping the don't-simplify rule. - SwiftDataInspector, TestHostSupport, Periscope group, Broadway group: light trims (deleted-module history, meta sections, root-owned wiring restatements). - Untouched, already at the standard: StuffTestHost, JournalKit, BroadwayCore/UI/Catalog, PeriscopeUI, StuffCore, JournalBenchmark. No cross-file anchors point into the edited files; verified by grep.
Plan step: Apply the policy to the root AGENTS.md section by section. Fact-neutral compression, 764 -> 661 lines. Every rule, tripwire, and diagnostic signature survives; the arguments move to their proof: - Double-link section: the correction essay and measured symbol- coalescing nuance become the rule + the guard-test authority line + a PR #145 pointer (the mechanism also lives at the Project.swift call sites since c5aa927). - Targets: the snapshot process-model bullet keeps the measurement fact and the re-measure tripwire, pointing at the snapshot-bundle comment in Project.swift for the topology. - Attribution, agent-skills sync, version stamping, xcstrings: rules + pointers; each 'because' cut to one clause. - Conventions: identifier/keys and observer bullets compressed; Modeling state keeps the full smells list; Composition keeps all four rules with one consequence clause each. - Simulator section: both failure-mode signatures (Busy, Mach -308), the UDID-only rule, and the CI 3.5-5h boot signature all stay; narration trimmed. - Untouched: Per-module docs (owns the standard), Repo-level docs, Working in this repo / GitHub, Generating the Xcode project. Cross-file anchors into the root verified resolving (#targets, #never-double-link-a-product-whereui-already-carries, #layering, #composition-create-once-inject-down, #version-and-build-metadata, #managing-app-icons, #attribution, #formatting, #testing, the simulator anchor).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A full re-validation pass over every
TODOs.md, everyAGENTS.md, and the source comments they point at, prompted by the weekend's findings (#143–#148) that several load-bearing build claims were inherited rather than verified. Eight commits, one per step; docs and comments only — the sole.swiftchanges are comment text.1. The disproven build story is fully swept
PR #145 corrected the root
AGENTS.mdbut not the code comments it points at.Project.swift'sWhereUITests/WhereIntentsTestscomments no longer claim WhereUI is a dynamic framework or that bundles co-load into oneStuffTestHostprocess, and now cite the corrected anchor + PR #145; a tree-wide grep caught two more survivors in WhereUI doc comments. Verified with./ide --no-open.2. Bumper's catalog no longer describes violations that don't exist
swift run bumper lint .reports no architecture violations and all 15 rule fixture tests pass — so the two.bumper/RULES.mdparagraphs claiming calendar and preview violations were "left visible during this bootstrap" were false and are deleted. Closes thedocs(Bumper)P0 sub-item; the parent P0 (where.gregorian_calendarmatches only an explicitCalendarbase and so enforces nothing) was re-confirmed and stays open.3. ~10 factually wrong AGENTS.md claims corrected
Each re-verified against
Project.swift/Package.swift/ source at edit time. Highlights: Where is an iOS/iPadOS app (not macOS); App Intents run in the app process, not their own; widgets never talk toWhereServices;StuffSnapshotTestsis a scheme, not a bundle, and three test suites were credited to the wrong bundles;BroadwayCatalogTestsis hosted by the catalog app, notStuffTestHost.4. TODO backlogs re-verified item by item
Of ~90 open items across the five touched files, the large majority checked out VALID and are untouched. Fixed: one open P0 that duplicated its own Completed entry (deleted; the never-delete rule protects completed entries, which stay), one P2 whose claim was wrong (
reconcileTracking()never requests authorization — moved to Completed as invalidated, reasoning preserved), ~20 driftedfile:linecitations re-verified against source, one cross-file duplicate merged into a bidirectional link, and one more stale rule found mid-pass: the Periscope hosting item still forbade thePeriscopeToolsSnapshotTestsbundle that #143 deliberately created.5. The AGENTS.md tree adopts "what, not why"
The root
AGENTS.mdnow codifies the rule format: an imperative sentence, at most one clause of consequence, and a pointer to the proof (guard test, PR/commit — squash merges keep PR bodies ingit log— or aTODOs.mdentry). Kept at one line each: tripwires (re-measure conditions), diagnostic signatures (literal error text likeApplication failed preflight checks (Busy)), and decision rules. Banned: history narration, mechanism walkthroughs, persuasion.Applied fact-neutrally across the tree — no rule changed meaning, none was deleted, and claims in tension were kept as recorded rather than harmonized:
AGENTS.mdWhere/AGENTS.mdWhereUIWhereCoreSnapshotKitTestingPeriscopeToolsWhereIntentsPeriscopeCoreStill-true tutorial content was relocated, not deleted: WhereUI's design-system how-to moved into its
README.md, which had pointed atAGENTS.mdfor exactly that. Files already at the standard (RegionKit, WhereWidgets, StuffTestHost, JournalKit, the Broadway children) were left alone. Cross-file#anchorlinks were verified resolving after each commit.Verification
./ide --no-opengreen (manifest compiles after the comment rewrite).swift run bumper lint . --timingsandswift run bumper test .green../swiftformat --lintclean../sync-agentsrun; all 29CLAUDE.mdmirrors verified byte-fresh.Deliberately not done
sync-agentson post-merge/post-checkout) was skipped per the plan — the pre-commit hook already regenerates mirrors on every commit, so the only stale window is agit pullwith no subsequent local commit.where.gregorian_calendarrule widening (the open P0) is code work outside this docs pass.