docs(read): ordering contract + skill sweep for the read-shape doctrine (PR 5) - #379
Merged
Conversation
…ne (PR 5) Final PR of the read-shape doctrine (ruling #C6) — docs only, no behavior change. - docs/contract.md: new "Read views — shapes and orderings" section documenting every view's data shape + each kept bucket's ordering, flagging the two presentation-derived orders (trash recency, search relevance) vs the real user-controlled axes. (The envelope schema models only the envelope layer — the data payload is an open coverage boundary — so orderings live in prose.) - things-cli skill (SKILL.md, references/model.md, references/contracts.md) swept for the flat shapes across PRs 1-4: today flat items[] + meta.counts (no badge/sections); project card flat items + heading catalog + flat logbook (no anytime/upcoming/someday/logbookHeadings); area card flat items + projects; corrected stage-drop and heading-ref rules. - docs/things-app-oddities.md §5o lede: "desktop GUI is stricter" -> platform- accurate "the GUI is stricter" (observed on iOS; macOS presumed unverified — the residual flagged in #373). - read-shape-doctrine.md marked fully implemented (all five PRs landed). Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RYbJensXxHpJK1v1VDXYUD
This was referenced Aug 3, 2026
mikegreiling
added a commit
that referenced
this pull request
Aug 5, 2026
… re-audit (#398) * Revert "docs(read): ordering contract + skill sweep for the read-shape doctrine (PR 5) (#379)" This reverts commit debbe6f. * Revert "feat(read): area-view direct to-dos dissolve to flat items[] (read-shape doctrine PR 4) (#378)" This reverts commit 044ffd0. * Revert "feat(read): project-view headings catalog + logbook flatten (read-shape doctrine PR 3) (#377)" This reverts commit 94f1dda. * Revert "feat(read): project-view children dissolve to flat items[] (read-shape doctrine PR 2) (#376)" This reverts commit 57321bc. * Revert "feat(read): today dissolve — flat items[] + meta.counts; badge purge (read-shape doctrine PR 1) (#375)" This reverts commit ce4fa4d. * chore(read): post-revert bookkeeping — CHANGELOG, doctrine status, skill floor Follow-up to the five read-shape doctrine reverts (#375-#379): - CHANGELOG: add a breaking Unreleased entry documenting the wholesale revert and the return to pre-0.13.0 bucketed today/project/area shapes; meta.counts removed. Clean revert, no compat shims (ALPHA-CONTRACT). - docs/design/read-shape-doctrine.md: restored (the PR-1 revert deleted it) with its status changed to REVERTED (dated) — retained as the input to a design re-audit of the read-shape approach. - skills/things-cli/SKILL.md: reconcile the npx floor sentence. The skill again teaches the bucketed read shapes, which 0.13.0 does NOT have; anchor the floor to the skill's publish-stamped version (the release that ships these shapes) instead of the now-false "below 0.13.0" literal. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01C1g2PkB43exMAfFdg6QnMT --------- Co-authored-by: Claude <noreply@anthropic.com>
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.
Fifth and final PR of the read-shape doctrine (
docs/design/read-shape-doctrine.md, ruling #C6). Branched from PR 4 (#378). Docs only — no code or behavior change.What changed
docs/contract.md— new "Read views — shapes and orderings" section. Every view'sdatashape + the exact ordering of each kept bucket, in one table, flagging the two presentation-derived orders (trashrecency,searchrelevance) as such vs. the real user-controlled axes (drag order, sidebar rank, schedule, child/heading index). The envelope JSON Schema models only the envelope layer — thedatapayload is an open coverage boundary — so the per-bucket orderings are documented in prose there, as the schema section already states.things-cliskill swept (SKILL.md,references/model.md,references/contracts.md) for the flat shapes landed across PRs 1–4 — one coherent pass: the flattodayitems[]+meta.counts(nobadge/sections); the project card's flatitems+ heading catalog + flatlogbook(noanytime/upcoming/someday/logbookHeadings); the area card's flatitems+projects; and the correctedstage-drop / heading-ref rules.docs/things-app-oddities.md§5o lede corrected: "the desktop GUI is stricter" → platform-accurate "the GUI is stricter" (the observation was iOS; macOS presumed but unverified — the residual flagged in docs(oddities): correct §5o (a)-(c) attribution to iOS (macOS presumed, unverified) #373).read-shape-doctrine.mdmarked fully implemented (all five PRs landed).Verification
npm run checkgreen (typecheck + oxlint + fmt:check + 2313 tests) — the banned-vocabulary + surface-copy contract tests confirm the swept copy stays clean.🤖 Generated with Claude Code