From d03eecde31dfa4f3e4bf83f31613451f03d8e215 Mon Sep 17 00:00:00 2001 From: null Date: Tue, 18 Aug 2026 02:18:25 -0500 Subject: [PATCH] docs: name not-yet-existing paths without backticks so doc-claims passes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit doc-claims.sh reported 19 claimed paths that do not exist. Every one was a deliberate forward reference — the planned modules in the architecture table, the two documents the trust map records as absent on purpose, and the release script Period declined. A backticked path is read as a claim the file is there, so a document saying "core/database does not exist yet" was asserting the opposite of what it meant. docs/history/BATCH_LEDGER.md already records the idiom for this case; it is now applied and stated where it is used, so the next forward reference does not reintroduce the failure. Also corrects WORK_CYCLE.md, inherited from the template, which pointed at a scripts/release.sh this project does not have. A release here is a signed AAB and a Play submission, so the security checklist carries that procedure. doc-claims.sh now reports 152 claimed paths, all present, across 20 files. --- docs/DOC_TRUST_MAP.md | 7 +++++-- docs/WORK_CYCLE.md | 5 +++-- docs/architecture/README.md | 22 ++++++++++++---------- docs/history/DEVELOPMENT_LOG.md | 4 ++-- docs/history/HISTORY.md | 2 +- docs/security/SECURITY.md | 2 +- docs/security/SECURITY_CHECKLIST.md | 2 +- 7 files changed, 25 insertions(+), 19 deletions(-) diff --git a/docs/DOC_TRUST_MAP.md b/docs/DOC_TRUST_MAP.md index 0410a57..ba5001a 100644 --- a/docs/DOC_TRUST_MAP.md +++ b/docs/DOC_TRUST_MAP.md @@ -94,11 +94,14 @@ breaks that. Everything else lives under `docs/`. Recorded here because an absence somebody chose and an absence nobody noticed look identical from outside, and only one of them is fine. -- **`docs/OPERATIONS.md` — deleted.** Period is an offline-first Android app +- **docs/OPERATIONS.md — deleted.** Named without backticks, because + `doc-claims.sh` reads a backticked path as a claim the file is there and this + one says the opposite. Period is an offline-first Android app distributed through Google Play. There is no host, no container, no uptime and no restore path of ours. An empty runbook reads as one nobody wrote rather than one that never applied. -- **`docs/planning/FUTURE.md` — never created.** The Command Center's docs +- **docs/planning/FUTURE.md — never created**, and named bare for the same + reason. The Command Center's docs report looks for a batch ledger there and reports it **missing** for every tracker-first project. That is the expected state; creating the file to turn the line green would rebuild the second record diff --git a/docs/WORK_CYCLE.md b/docs/WORK_CYCLE.md index 22ba10d..f7eaf05 100644 --- a/docs/WORK_CYCLE.md +++ b/docs/WORK_CYCLE.md @@ -262,8 +262,9 @@ one, and never report progress the API did not return. - **Not the work list.** That is the tracker: milestones are batches, issues are deliverables. -- **Not the release procedure.** That is `scripts/release.sh` - and `docs/security/SECURITY_CHECKLIST.md`. +- **Not the release procedure.** Period has no `release.sh` — a release here is + a signed AAB and a Play Console submission, so + [`security/SECURITY_CHECKLIST.md`](security/SECURITY_CHECKLIST.md) carries it. - **Not the QA procedure.** That is `docs/qa/ClaudeQAPlan.md`, which ends in its own version of step 7. - **Not a place to record status.** If you are about to add "current state" or a diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 0ee127e..78ca65c 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -30,7 +30,7 @@ function calls. Nothing below the ViewModel knows Compose exists. ## Modules -Four today. `core/database` and `core/datastore` are Batch 01 issues #3 and #4 +Four today. core/database and core/datastore are Batch 01 issues #3 and #4 and **do not exist yet** — a module created before it has contents is a place for things to be put by accident. The wider layout sketched in [`../planning/PRODUCT_PLAN.md` §9](../planning/PRODUCT_PLAN.md) arrives the same @@ -43,14 +43,16 @@ way, with the batch that needs it. | `domain/cycle` | **Kotlin JVM** | `PeriodRecord`, `SpottingRecord`, `CycleRecord` and the rules over them | nothing | | `domain/prediction` | **Kotlin JVM** | the forecast, the window, confidence, `NotYetObservation` | `domain/cycle` | -Planned, with the issue that brings each one: +Planned, with the issue that brings each one. **Named without backticks on +purpose** — `doc-claims.sh` reads a backticked path as a claim that the file is +there, and none of these are: | Module | Plugin | Owns | May depend on | Issue | | --- | --- | --- | --- | --- | -| `core/database` | Android library | Room entities, DAOs, migrations | `domain/cycle` | #3 | -| `core/datastore` | Android library | `UserPreferences` | `domain/cycle` | #4 | -| `core/data` | Android library | the repositories — the only things that touch a DAO | `core/database`, `core/datastore`, `domain/cycle` | #5 | -| `core/ads` | Android library | the `AdProvider` implementation | **neither `core/database` nor `domain/*`** | Batch 07 | +| core/database | Android library | Room entities, DAOs, migrations | `domain/cycle` | #3 | +| core/datastore | Android library | `UserPreferences` | `domain/cycle` | #4 | +| core/data | Android library | the repositories — the only things that touch a DAO | core/database, core/datastore, `domain/cycle` | #5 | +| core/ads | Android library | the `AdProvider` implementation | **neither core/database nor `domain/*`** | Batch 07 | ### Why `domain/*` is `kotlin("jvm")` and not an Android library @@ -71,8 +73,8 @@ remembers. > prediction history, spotting records, or any other health-derived attribute. > — [`PRODUCT_PLAN.md` §34](../planning/PRODUCT_PLAN.md) -Expressed structurally rather than as a rule people remember: when `core/ads` -exists it will declare no dependency on `core/database` or `domain/*`, and a +Expressed structurally rather than as a rule people remember: when core/ads +exists it will declare no dependency on core/database or `domain/*`, and a Gradle check enforces the whole table above by enumerating each module's allowed dependencies. Ads reach the UI through an `AdProvider` interface owned by `app`. @@ -82,8 +84,8 @@ before it is treated as evidence. `scripts/prove-guard.sh` performs it. ## Data shapes -Defined in `domain/cycle` as plain Kotlin, mirrored by Room entities in -`core/database`. The full field lists are +Defined in `domain/cycle` as plain Kotlin, and mirrored by Room entities in +core/database once issue #3 creates it. The full field lists are [`PRODUCT_PLAN.md` §10](../planning/PRODUCT_PLAN.md); what matters here is why each exists and what must not happen to it. diff --git a/docs/history/DEVELOPMENT_LOG.md b/docs/history/DEVELOPMENT_LOG.md index de1ce52..7b6fd5b 100644 --- a/docs/history/DEVELOPMENT_LOG.md +++ b/docs/history/DEVELOPMENT_LOG.md @@ -43,7 +43,7 @@ from `Docs/period_tracker_product_plan.md` to `docs/planning/PRODUCT_PLAN.md` unchanged in substance, with a status header added; the capitalised `Docs/` is gone, since every script and the Command Center expect the lowercase tree. Every scaffolded document was filled in for Period rather than left with placeholders. -`docs/OPERATIONS.md` was deleted — an offline app is not a deployed service. +docs/OPERATIONS.md was deleted — an offline app is not a deployed service. `docs/DOC_TRUST_MAP.md` was written last and describes what is actually here, including a section naming what this project deliberately does **not** have. @@ -75,7 +75,7 @@ percentage permanently wrong. `forgejo-issue.py check` warns about this, and the warning is correct about the mechanism and expected here. - **Closed:** #1, #2 -- **Next action:** Start issue #3 — `core/database` with Room entities for +- **Next action:** Start issue #3 — core/database with Room entities for `PeriodRecord`, `SpottingRecord`, `PredictionRecord` and `NotYetObservation`, DAOs returning `Flow`, schema export committed, and a version-1 migration test that proves the harness works before there is a migration that matters. Its row diff --git a/docs/history/HISTORY.md b/docs/history/HISTORY.md index 2b4d39d..85000ff 100644 --- a/docs/history/HISTORY.md +++ b/docs/history/HISTORY.md @@ -51,7 +51,7 @@ was true at the time" survives Y stopping being true. | 2026-08-18 | One-time purchase to remove ads, not a subscription | it keeps prediction quality free for everyone and avoids an entire class of entitlement defect — nothing to claw back on cancellation | | 2026-08-18 | Six Gradle modules at the skeleton, not the seventeen the specification sketches | a module created before it has contents is a place for things to be put by accident; the rest arrive with the batch that needs them | | 2026-08-18 | Eight milestones opened at once, issues filed only under Batch 01 | the roadmap is genuinely known and worth being visible; the *work items* are not, and inventing them would make every tracker percentage permanently wrong | -| 2026-08-18 | `OPERATIONS.md` deleted rather than kept empty | this is an offline app, not a deployed service; an empty runbook reads as one nobody wrote | +| 2026-08-18 | OPERATIONS.md deleted rather than kept empty | this is an offline app, not a deployed service; an empty runbook reads as one nobody wrote | ## What was tried and dropped diff --git a/docs/security/SECURITY.md b/docs/security/SECURITY.md index cc9313d..5c86024 100644 --- a/docs/security/SECURITY.md +++ b/docs/security/SECURITY.md @@ -91,7 +91,7 @@ rather than only as an architecture note: Safety declares. Enforced structurally, not remembered: the `ads` module declares no dependency -on `core/database` or `domain/*`, and a Gradle guard proves it — see +on core/database or `domain/*`, and a Gradle guard proves it — see [`../architecture/README.md`](../architecture/README.md). ## Logging diff --git a/docs/security/SECURITY_CHECKLIST.md b/docs/security/SECURITY_CHECKLIST.md index 5769fee..12d82eb 100644 --- a/docs/security/SECURITY_CHECKLIST.md +++ b/docs/security/SECURITY_CHECKLIST.md @@ -41,7 +41,7 @@ it means the release list stays short enough to finish rather than skim. The one group that is not generic. Every item proves part of [`../planning/PRODUCT_PLAN.md` §34](../planning/PRODUCT_PLAN.md). -- [ ] `ads` declares no Gradle dependency on `core/database` or `domain/*`, and the boundary guard was **proved to fail** this release — proves the check is evidence rather than decoration +- [ ] the ads module declares no Gradle dependency on core/database or `domain/*`, and the boundary guard was **proved to fail** this release — proves the check is evidence rather than decoration - [ ] No health-derived value appears in an ad request extra, user property, or callback log — proves targeting cannot happen by accident - [ ] Ad requests are non-personalized/contextual, with region-appropriate consent — proves the default is the private one - [ ] The ads provider is not initialised for entitled (ad-free) users where practical — proves the purchase removes the SDK, not just the view