From 3f9375188e29d4290e944df554f93e8e85a68a08 Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 30 Mar 2026 11:52:29 -0700 Subject: [PATCH 1/2] docs: add planning index consistency review --- CHANGELOG.md | 1 + CONTRIBUTING.md | 3 + WORKFLOW.md | 20 +++ docs/BACKLOG/README.md | 1 - docs/DOCS_CHECKLIST.md | 23 ++- docs/archive/BACKLOG/README.md | 2 + .../TR-006-docs-maintainer-checklist.md | 4 +- ...R-010-planning-index-consistency-review.md | 4 +- docs/design/README.md | 1 + ...R-010-planning-index-consistency-review.md | 157 ++++++++++++++++++ docs/legends/TR-truth.md | 5 +- 11 files changed, 213 insertions(+), 8 deletions(-) rename docs/{ => archive}/BACKLOG/TR-010-planning-index-consistency-review.md (85%) create mode 100644 docs/design/TR-010-planning-index-consistency-review.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c5a243..907497a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **`git cas agent vault rotate`** — added a machine-facing vault passphrase rotation flow so Relay can rotate encrypted vault state with explicit commit, KDF, and rotated/skipped-entry results. - **`git cas agent vault init|remove`** — added machine-facing vault lifecycle commands so Relay can initialize encrypted or plaintext vaults and remove entries without scraping human CLI output. - **Docs maintainer checklist** — added [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md) as the short pre-review pass for doc-heavy branches, covering boundary clarity, canonical-source links, index hygiene, and empty-state wording discipline. +- **Planning-index consistency review** — added an explicit planning-surface review to [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md) and [WORKFLOW.md](./WORKFLOW.md), defining when to verify backlog, design, archive, and legend alignment. - **Benchmark baselines doc** — added [docs/BENCHMARKS.md](./docs/BENCHMARKS.md) with the first published chunking baseline, including fixed-size versus CDC throughput, dedupe reuse results, and refresh instructions. - **Threat model doc** — added [docs/THREAT_MODEL.md](./docs/THREAT_MODEL.md) as the canonical statement of attacker models, trust boundaries, exposed metadata, and explicit non-goals. - **Workflow model** — added [WORKFLOW.md](./WORKFLOW.md), explicit legends/backlog/invariants directories, and a cycle-first planning model for fresh work. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8867ecf..e947bf6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -124,6 +124,9 @@ If the answer is unclear, the work probably belongs in Before opening a doc-heavy pull request, run the short maintainer pass in [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md). +If the branch touches planning surfaces, include the planning-index review in +that checklist pass. + ## Directory Model New planning work uses: diff --git a/WORKFLOW.md b/WORKFLOW.md index 340d5fd..1a519ab 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -154,6 +154,26 @@ of the workflow, not optional cleanup. If a file moves lifecycle state, update the relevant indexes in the same change. +### Planning Index Consistency Review + +Run a planning-index consistency review whenever a branch: + +- changes backlog, design, archive, or legend indexes +- moves a backlog card between live and archived state +- closes a cycle and prepares the merged post-merge truth state +- discovers drift on `main` + +This does not need a fixed calendar cadence. Run it when planning surfaces +change and as a Truth maintenance pass when drift is found. + +The minimum review must confirm: + +- the live backlog only lists pending, in-cycle, or unresolved follow-on work +- landed cycle docs are represented in `docs/design/` +- archived backlog history matches delivered or retired cards +- legend summaries agree with the current backlog and design surfaces +- empty-state wording stays consistent with the existing house style + ## Cycle Workflow 1. Design docs first, using the human and agent IBM Design Thinking passes. diff --git a/docs/BACKLOG/README.md b/docs/BACKLOG/README.md index c8070a3..961d264 100644 --- a/docs/BACKLOG/README.md +++ b/docs/BACKLOG/README.md @@ -33,7 +33,6 @@ Current backlog items: - [TR-007 — Security Doc Discoverability Audit](./TR-007-security-doc-discoverability-audit.md) - [TR-008 — Empty-State Phrasing Consistency](./TR-008-empty-state-phrasing-consistency.md) - [TR-009 — Pre-PR Doc Cross-Link Audit](./TR-009-pre-pr-doc-cross-link-audit.md) -- [TR-010 — Planning Index Consistency Review](./TR-010-planning-index-consistency-review.md) - [TR-011 — Streaming Encrypted Restore](./TR-011-streaming-encrypted-restore.md) Archived delivered backlog items: diff --git a/docs/DOCS_CHECKLIST.md b/docs/DOCS_CHECKLIST.md index b37407f..08cb437 100644 --- a/docs/DOCS_CHECKLIST.md +++ b/docs/DOCS_CHECKLIST.md @@ -30,6 +30,25 @@ truth and discoverability failures that keep surfacing late in review. If a summary doc repeats claims that are already maintained elsewhere, reduce it to a short summary plus a link instead of maintaining two full narratives. +## Planning Index Review + +Run this extra pass whenever a branch changes: + +- `docs/BACKLOG/README.md` +- `docs/design/README.md` +- `docs/archive/BACKLOG/README.md` +- a legend's current-cycle summary +- a backlog card's lifecycle state + +Confirm all of the following before review: + +- live backlog entries are still pending, in cycle, or carrying unresolved + follow-on work +- landed cycle docs are represented in `docs/design/` +- archived backlog history reflects moved or retired backlog cards +- legend summaries agree with the current backlog and design surfaces +- empty-state wording does not introduce a new house style accidentally + ## Use It On These Files This checklist is most useful when a change touches files like: @@ -42,7 +61,9 @@ This checklist is most useful when a change touches files like: - [docs/THREAT_MODEL.md](./THREAT_MODEL.md) - [docs/BENCHMARKS.md](./BENCHMARKS.md) - planning indexes under [`docs/BACKLOG/`](./BACKLOG/README.md), - [`docs/design/`](./design/README.md), and [`docs/legends/`](./legends/README.md) + [`docs/design/`](./design/README.md), + [`docs/archive/BACKLOG/`](./archive/BACKLOG/README.md), and + [`docs/legends/`](./legends/README.md) ## Exit Criteria diff --git a/docs/archive/BACKLOG/README.md b/docs/archive/BACKLOG/README.md index e02cf8e..6aa035e 100644 --- a/docs/archive/BACKLOG/README.md +++ b/docs/archive/BACKLOG/README.md @@ -27,3 +27,5 @@ Landed archived backlog items: - landed as [TR-004 — Truth: Design Doc Lifecycle](../../design/TR-004-design-doc-lifecycle.md) - [TR-006 — Docs Maintainer Checklist](./TR-006-docs-maintainer-checklist.md) - landed as [TR-006 — Truth: Docs Maintainer Checklist](../../design/TR-006-docs-maintainer-checklist.md) +- [TR-010 — Planning Index Consistency Review](./TR-010-planning-index-consistency-review.md) + - landed as [TR-010 — Truth: Planning Index Consistency Review](../../design/TR-010-planning-index-consistency-review.md) diff --git a/docs/archive/BACKLOG/TR-006-docs-maintainer-checklist.md b/docs/archive/BACKLOG/TR-006-docs-maintainer-checklist.md index 073cd47..5cb719a 100644 --- a/docs/archive/BACKLOG/TR-006-docs-maintainer-checklist.md +++ b/docs/archive/BACKLOG/TR-006-docs-maintainer-checklist.md @@ -2,7 +2,7 @@ ## Legend -- [TR — Truth](../legends/TR-truth.md) +- [TR — Truth](../../legends/TR-truth.md) ## Why This Exists @@ -31,7 +31,7 @@ same doc review hazards from comments. ## Linked Invariants -- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md) +- [I-001 — Determinism, Trust, And Explicit Surfaces](../../invariants/I-001-determinism-trust-and-explicit-surfaces.md) ## Notes diff --git a/docs/BACKLOG/TR-010-planning-index-consistency-review.md b/docs/archive/BACKLOG/TR-010-planning-index-consistency-review.md similarity index 85% rename from docs/BACKLOG/TR-010-planning-index-consistency-review.md rename to docs/archive/BACKLOG/TR-010-planning-index-consistency-review.md index 3d99c5b..723289e 100644 --- a/docs/BACKLOG/TR-010-planning-index-consistency-review.md +++ b/docs/archive/BACKLOG/TR-010-planning-index-consistency-review.md @@ -2,7 +2,7 @@ ## Legend -- [TR — Truth](../legends/TR-truth.md) +- [TR — Truth](../../legends/TR-truth.md) ## Why This Exists @@ -29,7 +29,7 @@ instead of inferring around index drift. ## Linked Invariants -- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md) +- [I-001 — Determinism, Trust, And Explicit Surfaces](../../invariants/I-001-determinism-trust-and-explicit-surfaces.md) ## Notes diff --git a/docs/design/README.md b/docs/design/README.md index 9c60ed1..ba35ee0 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -44,6 +44,7 @@ Landed cycle docs: - [TR-003 — Truth: Benchmark Baselines](./TR-003-benchmark-baselines.md) - [TR-004 — Truth: Design Doc Lifecycle](./TR-004-design-doc-lifecycle.md) - [TR-006 — Truth: Docs Maintainer Checklist](./TR-006-docs-maintainer-checklist.md) +- [TR-010 — Truth: Planning Index Consistency Review](./TR-010-planning-index-consistency-review.md) Archived or retired cycle docs: diff --git a/docs/design/TR-010-planning-index-consistency-review.md b/docs/design/TR-010-planning-index-consistency-review.md new file mode 100644 index 0000000..a14e061 --- /dev/null +++ b/docs/design/TR-010-planning-index-consistency-review.md @@ -0,0 +1,157 @@ +# TR-010 — Truth: Planning Index Consistency Review + +## Status + +Landed + +## Linked Legend + +- [TR — Truth](../legends/TR-truth.md) + +## Linked Invariants + +- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md) + +## Context + +The planning model now spans several linked surfaces: + +- the live backlog +- landed design history +- archived backlog history +- legend summaries + +Those files can drift even when the underlying work is correct. The failure +mode is usually small but costly: + +- a landed cycle stays listed in the live backlog +- a legend summary lags the current design surface +- archive state and design state stop matching + +The repo already says indexes are part of the workflow. This cycle makes the +review pass explicit enough to run reliably. + +## Human Users, Jobs, And Hills + +### Users + +- maintainers +- contributors closing cycles or moving planning artifacts +- reviewers checking whether planning docs tell the truth + +### Jobs + +- verify that planning surfaces agree before opening or merging a PR +- catch backlog, design, archive, and legend drift without manual spelunking +- keep the planning model trustworthy without adding ceremony for its own sake + +### Hill + +A maintainer can run one short planning-index review and know that the backlog, +design, archive, and legend surfaces agree with the real lifecycle state. + +## Agent Users, Jobs, And Hills + +### Users + +- coding agents +- documentation agents +- review agents + +### Jobs + +- check planning-surface alignment explicitly instead of inferring around drift +- know when a planning-index review is required +- distinguish live work from landed history and archived intent reliably + +### Hill + +An agent can treat the planning surfaces as one coherent system because the repo +defines both the review triggers and the minimum consistency checks. + +## Human Playback + +- Is it obvious when a planning-index review must run? +- Does the review stay short enough to use on every cycle-closing PR? +- Does it say exactly what must match across backlog, design, archive, and + legends? + +## Agent Playback + +- Can an agent tell when a branch must review planning-index consistency? +- Can it enumerate the minimum alignment checks without inventing its own list? +- Does the doctrine stay pragmatic instead of turning into calendar-driven + ceremony? + +## Explicit Non-Goals + +- no attempt to build automated linting for every planning surface in this cycle +- no requirement for a fixed calendar schedule +- no broad rewrite of unrelated legacy planning artifacts + +## Decisions + +### Use The Existing Docs Checklist + +The planning-index review should live inside +[docs/DOCS_CHECKLIST.md](../DOCS_CHECKLIST.md), not as a separate maintainer +ritual disconnected from the normal docs review pass. + +### Define Trigger Conditions In Workflow + +[WORKFLOW.md](../../WORKFLOW.md) should say when the planning-index review is +required: + +- when a branch changes backlog, design, archive, or legend indexes +- when a backlog card moves lifecycle state +- when a cycle-closing PR is preparing the post-merge truth state +- when drift is discovered on `main` + +### Define The Minimum Alignment Matrix + +The review should verify, at minimum: + +- live backlog items are still pending, in cycle, or carrying unresolved + follow-on work +- landed cycle docs appear in `docs/design/` +- archived backlog history matches landed or retired cards +- legend current-cycle summaries agree with the backlog and design surfaces +- empty-state wording does not invent a new house style accidentally + +## Implementation Outline + +1. Add this cycle doc. +2. Extend [docs/DOCS_CHECKLIST.md](../DOCS_CHECKLIST.md) with a planning-index + review section and the minimum alignment checks. +3. Update [WORKFLOW.md](../../WORKFLOW.md) and + [CONTRIBUTING.md](../../CONTRIBUTING.md) so the planning-index review is + both required and discoverable from tracked doctrine. +4. Archive the consumed backlog card, update the Truth indexes, and record the + cycle in [CHANGELOG.md](../../CHANGELOG.md). + +## Tests To Write First + +No new executable tests. + +This is a documentation-truth cycle. Verification is: + +- direct cross-check of backlog, design, archive, and legend surfaces after the + edits +- formatting validation for touched Markdown files +- whitespace and diff validation + +## Risks And Unknowns + +- a manual review can still be skipped if contributors ignore the doctrine +- the repo may eventually want automated linting for some of these checks +- legacy historical docs outside the legends model can still drift without + violating this cycle directly + +## Retrospective + +This is the right follow-through after the earlier Truth cycles. + +The workflow already said indexes mattered. What was missing was a clear, +repeatable pass for keeping those indexes aligned when real branches land. The +small drift that showed up on `main` after the previous cycle was exactly the +kind of failure this review is meant to catch quickly. diff --git a/docs/legends/TR-truth.md b/docs/legends/TR-truth.md index c19934d..e47aa7e 100644 --- a/docs/legends/TR-truth.md +++ b/docs/legends/TR-truth.md @@ -76,6 +76,7 @@ Current Truth design docs: - [TR-003 — Truth: Benchmark Baselines](../design/TR-003-benchmark-baselines.md) - [TR-004 — Truth: Design Doc Lifecycle](../design/TR-004-design-doc-lifecycle.md) - [TR-006 — Truth: Docs Maintainer Checklist](../design/TR-006-docs-maintainer-checklist.md) +- [TR-010 — Truth: Planning Index Consistency Review](../design/TR-010-planning-index-consistency-review.md) Current Truth backlog items: @@ -83,7 +84,6 @@ Current Truth backlog items: - [TR-007 — Security Doc Discoverability Audit](../BACKLOG/TR-007-security-doc-discoverability-audit.md) - [TR-008 — Empty-State Phrasing Consistency](../BACKLOG/TR-008-empty-state-phrasing-consistency.md) - [TR-009 — Pre-PR Doc Cross-Link Audit](../BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md) -- [TR-010 — Planning Index Consistency Review](../BACKLOG/TR-010-planning-index-consistency-review.md) - [TR-011 — Streaming Encrypted Restore](../BACKLOG/TR-011-streaming-encrypted-restore.md) Truth work under this legend is currently focused on: @@ -95,7 +95,8 @@ Truth work under this legend is currently focused on: - evaluating service decomposition where the current boundary is under strain - improving documentation review hygiene through a shared maintainer checklist - improving cross-link discoverability -- keeping planning indexes and empty-state language consistent over time +- running planning-index consistency reviews and keeping empty-state language + consistent over time - investigating lower-memory restore paths for encrypted and compressed assets ## Explicit Non-Goals From dd02a7f4476c479e250aa6b979adef6c9597cfed Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 30 Mar 2026 12:54:36 -0700 Subject: [PATCH 2/2] docs: clarify planning index empty states --- WORKFLOW.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/WORKFLOW.md b/WORKFLOW.md index 1a519ab..e49f86a 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -172,7 +172,9 @@ The minimum review must confirm: - landed cycle docs are represented in `docs/design/` - archived backlog history matches delivered or retired cards - legend summaries agree with the current backlog and design surfaces -- empty-state wording stays consistent with the existing house style +- empty-state wording stays consistent with the existing house style, such as + `- none currently` in [docs/design/README.md](./docs/design/README.md), + instead of inventing a new empty-list phrase for the same condition ## Cycle Workflow