Skip to content

Commit fa3b9bc

Browse files
flyingrobotsflyingrobots
authored
Merge pull request #29 from git-stunts/docs/tr-010-planning-index-consistency-review
docs: add planning index consistency review
2 parents a01b0e7 + dd02a7f commit fa3b9bc

11 files changed

Lines changed: 215 additions & 8 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1414
- **`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.
1515
- **`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.
1616
- **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.
17+
- **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.
1718
- **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.
1819
- **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.
1920
- **Workflow model** — added [WORKFLOW.md](./WORKFLOW.md), explicit legends/backlog/invariants directories, and a cycle-first planning model for fresh work.

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,9 @@ If the answer is unclear, the work probably belongs in
124124
Before opening a doc-heavy pull request, run the short maintainer pass in
125125
[docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md).
126126

127+
If the branch touches planning surfaces, include the planning-index review in
128+
that checklist pass.
129+
127130
## Directory Model
128131

129132
New planning work uses:

‎WORKFLOW.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,28 @@ of the workflow, not optional cleanup.
154154

155155
If a file moves lifecycle state, update the relevant indexes in the same change.
156156

157+
### Planning Index Consistency Review
158+
159+
Run a planning-index consistency review whenever a branch:
160+
161+
- changes backlog, design, archive, or legend indexes
162+
- moves a backlog card between live and archived state
163+
- closes a cycle and prepares the merged post-merge truth state
164+
- discovers drift on `main`
165+
166+
This does not need a fixed calendar cadence. Run it when planning surfaces
167+
change and as a Truth maintenance pass when drift is found.
168+
169+
The minimum review must confirm:
170+
171+
- the live backlog only lists pending, in-cycle, or unresolved follow-on work
172+
- landed cycle docs are represented in `docs/design/`
173+
- archived backlog history matches delivered or retired cards
174+
- legend summaries agree with the current backlog and design surfaces
175+
- empty-state wording stays consistent with the existing house style, such as
176+
`- none currently` in [docs/design/README.md](./docs/design/README.md),
177+
instead of inventing a new empty-list phrase for the same condition
178+
157179
## Cycle Workflow
158180

159181
1. Design docs first, using the human and agent IBM Design Thinking passes.

‎docs/BACKLOG/README.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@ Current backlog items:
3333
- [TR-007 — Security Doc Discoverability Audit](./TR-007-security-doc-discoverability-audit.md)
3434
- [TR-008 — Empty-State Phrasing Consistency](./TR-008-empty-state-phrasing-consistency.md)
3535
- [TR-009 — Pre-PR Doc Cross-Link Audit](./TR-009-pre-pr-doc-cross-link-audit.md)
36-
- [TR-010 — Planning Index Consistency Review](./TR-010-planning-index-consistency-review.md)
3736
- [TR-011 — Streaming Encrypted Restore](./TR-011-streaming-encrypted-restore.md)
3837

3938
Archived delivered backlog items:

‎docs/DOCS_CHECKLIST.md‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,25 @@ truth and discoverability failures that keep surfacing late in review.
3030
If a summary doc repeats claims that are already maintained elsewhere, reduce
3131
it to a short summary plus a link instead of maintaining two full narratives.
3232

33+
## Planning Index Review
34+
35+
Run this extra pass whenever a branch changes:
36+
37+
- `docs/BACKLOG/README.md`
38+
- `docs/design/README.md`
39+
- `docs/archive/BACKLOG/README.md`
40+
- a legend's current-cycle summary
41+
- a backlog card's lifecycle state
42+
43+
Confirm all of the following before review:
44+
45+
- live backlog entries are still pending, in cycle, or carrying unresolved
46+
follow-on work
47+
- landed cycle docs are represented in `docs/design/`
48+
- archived backlog history reflects moved or retired backlog cards
49+
- legend summaries agree with the current backlog and design surfaces
50+
- empty-state wording does not introduce a new house style accidentally
51+
3352
## Use It On These Files
3453

3554
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:
4261
- [docs/THREAT_MODEL.md](./THREAT_MODEL.md)
4362
- [docs/BENCHMARKS.md](./BENCHMARKS.md)
4463
- planning indexes under [`docs/BACKLOG/`](./BACKLOG/README.md),
45-
[`docs/design/`](./design/README.md), and [`docs/legends/`](./legends/README.md)
64+
[`docs/design/`](./design/README.md),
65+
[`docs/archive/BACKLOG/`](./archive/BACKLOG/README.md), and
66+
[`docs/legends/`](./legends/README.md)
4667

4768
## Exit Criteria
4869

‎docs/archive/BACKLOG/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,5 @@ Landed archived backlog items:
2727
- landed as [TR-004 — Truth: Design Doc Lifecycle](../../design/TR-004-design-doc-lifecycle.md)
2828
- [TR-006 — Docs Maintainer Checklist](./TR-006-docs-maintainer-checklist.md)
2929
- landed as [TR-006 — Truth: Docs Maintainer Checklist](../../design/TR-006-docs-maintainer-checklist.md)
30+
- [TR-010 — Planning Index Consistency Review](./TR-010-planning-index-consistency-review.md)
31+
- landed as [TR-010 — Truth: Planning Index Consistency Review](../../design/TR-010-planning-index-consistency-review.md)

‎docs/archive/BACKLOG/TR-006-docs-maintainer-checklist.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Legend
44

5-
- [TR — Truth](../legends/TR-truth.md)
5+
- [TR — Truth](../../legends/TR-truth.md)
66

77
## Why This Exists
88

@@ -31,7 +31,7 @@ same doc review hazards from comments.
3131

3232
## Linked Invariants
3333

34-
- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
34+
- [I-001 — Determinism, Trust, And Explicit Surfaces](../../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
3535

3636
## Notes
3737

docs/BACKLOG/TR-010-planning-index-consistency-review.md renamed to docs/archive/BACKLOG/TR-010-planning-index-consistency-review.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Legend
44

5-
- [TR — Truth](../legends/TR-truth.md)
5+
- [TR — Truth](../../legends/TR-truth.md)
66

77
## Why This Exists
88

@@ -29,7 +29,7 @@ instead of inferring around index drift.
2929

3030
## Linked Invariants
3131

32-
- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
32+
- [I-001 — Determinism, Trust, And Explicit Surfaces](../../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
3333

3434
## Notes
3535

‎docs/design/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ Landed cycle docs:
4444
- [TR-003 — Truth: Benchmark Baselines](./TR-003-benchmark-baselines.md)
4545
- [TR-004 — Truth: Design Doc Lifecycle](./TR-004-design-doc-lifecycle.md)
4646
- [TR-006 — Truth: Docs Maintainer Checklist](./TR-006-docs-maintainer-checklist.md)
47+
- [TR-010 — Truth: Planning Index Consistency Review](./TR-010-planning-index-consistency-review.md)
4748

4849
Archived or retired cycle docs:
4950

‎docs/design/TR-010-planning-index-consistency-review.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# TR-010 — Truth: Planning Index Consistency Review
2+
3+
## Status
4+
5+
Landed
6+
7+
## Linked Legend
8+
9+
- [TR — Truth](../legends/TR-truth.md)
10+
11+
## Linked Invariants
12+
13+
- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
14+
15+
## Context
16+
17+
The planning model now spans several linked surfaces:
18+
19+
- the live backlog
20+
- landed design history
21+
- archived backlog history
22+
- legend summaries
23+
24+
Those files can drift even when the underlying work is correct. The failure
25+
mode is usually small but costly:
26+
27+
- a landed cycle stays listed in the live backlog
28+
- a legend summary lags the current design surface
29+
- archive state and design state stop matching
30+
31+
The repo already says indexes are part of the workflow. This cycle makes the
32+
review pass explicit enough to run reliably.
33+
34+
## Human Users, Jobs, And Hills
35+
36+
### Users
37+
38+
- maintainers
39+
- contributors closing cycles or moving planning artifacts
40+
- reviewers checking whether planning docs tell the truth
41+
42+
### Jobs
43+
44+
- verify that planning surfaces agree before opening or merging a PR
45+
- catch backlog, design, archive, and legend drift without manual spelunking
46+
- keep the planning model trustworthy without adding ceremony for its own sake
47+
48+
### Hill
49+
50+
A maintainer can run one short planning-index review and know that the backlog,
51+
design, archive, and legend surfaces agree with the real lifecycle state.
52+
53+
## Agent Users, Jobs, And Hills
54+
55+
### Users
56+
57+
- coding agents
58+
- documentation agents
59+
- review agents
60+
61+
### Jobs
62+
63+
- check planning-surface alignment explicitly instead of inferring around drift
64+
- know when a planning-index review is required
65+
- distinguish live work from landed history and archived intent reliably
66+
67+
### Hill
68+
69+
An agent can treat the planning surfaces as one coherent system because the repo
70+
defines both the review triggers and the minimum consistency checks.
71+
72+
## Human Playback
73+
74+
- Is it obvious when a planning-index review must run?
75+
- Does the review stay short enough to use on every cycle-closing PR?
76+
- Does it say exactly what must match across backlog, design, archive, and
77+
legends?
78+
79+
## Agent Playback
80+
81+
- Can an agent tell when a branch must review planning-index consistency?
82+
- Can it enumerate the minimum alignment checks without inventing its own list?
83+
- Does the doctrine stay pragmatic instead of turning into calendar-driven
84+
ceremony?
85+
86+
## Explicit Non-Goals
87+
88+
- no attempt to build automated linting for every planning surface in this cycle
89+
- no requirement for a fixed calendar schedule
90+
- no broad rewrite of unrelated legacy planning artifacts
91+
92+
## Decisions
93+
94+
### Use The Existing Docs Checklist
95+
96+
The planning-index review should live inside
97+
[docs/DOCS_CHECKLIST.md](../DOCS_CHECKLIST.md), not as a separate maintainer
98+
ritual disconnected from the normal docs review pass.
99+
100+
### Define Trigger Conditions In Workflow
101+
102+
[WORKFLOW.md](../../WORKFLOW.md) should say when the planning-index review is
103+
required:
104+
105+
- when a branch changes backlog, design, archive, or legend indexes
106+
- when a backlog card moves lifecycle state
107+
- when a cycle-closing PR is preparing the post-merge truth state
108+
- when drift is discovered on `main`
109+
110+
### Define The Minimum Alignment Matrix
111+
112+
The review should verify, at minimum:
113+
114+
- live backlog items are still pending, in cycle, or carrying unresolved
115+
follow-on work
116+
- landed cycle docs appear in `docs/design/`
117+
- archived backlog history matches landed or retired cards
118+
- legend current-cycle summaries agree with the backlog and design surfaces
119+
- empty-state wording does not invent a new house style accidentally
120+
121+
## Implementation Outline
122+
123+
1. Add this cycle doc.
124+
2. Extend [docs/DOCS_CHECKLIST.md](../DOCS_CHECKLIST.md) with a planning-index
125+
review section and the minimum alignment checks.
126+
3. Update [WORKFLOW.md](../../WORKFLOW.md) and
127+
[CONTRIBUTING.md](../../CONTRIBUTING.md) so the planning-index review is
128+
both required and discoverable from tracked doctrine.
129+
4. Archive the consumed backlog card, update the Truth indexes, and record the
130+
cycle in [CHANGELOG.md](../../CHANGELOG.md).
131+
132+
## Tests To Write First
133+
134+
No new executable tests.
135+
136+
This is a documentation-truth cycle. Verification is:
137+
138+
- direct cross-check of backlog, design, archive, and legend surfaces after the
139+
edits
140+
- formatting validation for touched Markdown files
141+
- whitespace and diff validation
142+
143+
## Risks And Unknowns
144+
145+
- a manual review can still be skipped if contributors ignore the doctrine
146+
- the repo may eventually want automated linting for some of these checks
147+
- legacy historical docs outside the legends model can still drift without
148+
violating this cycle directly
149+
150+
## Retrospective
151+
152+
This is the right follow-through after the earlier Truth cycles.
153+
154+
The workflow already said indexes mattered. What was missing was a clear,
155+
repeatable pass for keeping those indexes aligned when real branches land. The
156+
small drift that showed up on `main` after the previous cycle was exactly the
157+
kind of failure this review is meant to catch quickly.

0 commit comments

Comments
 (0)