Skip to content

Commit db548b3

Browse files
committed
docs(plans): drop "What was checked" and "Needs" from the walkthroughs
Each walkthrough repeated rows of the index's "What was checked" table, and nothing kept the copies in step with it. The opening line of each page still links the index, which holds the one table. A "Needs" line mostly pointed back at the section before it, which the order of the page already shows. Also stop saying "carries" in prose. Claude-Session: https://claude.ai/code/session_016Usf7cQGY6ULWGyZ4NHQEB
1 parent 0be1773 commit db548b3

12 files changed

Lines changed: 4 additions & 304 deletions

File tree

‎docs/plans/2026-10-04-plan-builder/accounts/README.md‎

Lines changed: 0 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@ It shows what `stashgen` is planned to write.
1919

2020
- **Purpose:** Understand how one tag covers an embedded struct from another package.
2121
- **Related:** [The plan's embedded struct design](../../2026-10-04-plan-builder.md#embedded-structs-unexported-fields-and-other-tags), [the plan's printing design](../../2026-10-04-plan-builder.md#printing)
22-
- **Needs:** Nothing
2322

2423
The `stash:",passthrough"` tag stores every `gorm.Model` field as a passthrough field.
2524
`Email` becomes one Encrypt Query Language (EQL) column with the `TextEq` type.
@@ -64,7 +63,6 @@ The `token` field uses `stash:"-"`, so it is an omitted field and produces no wa
6463

6564
- **Purpose:** Follow copied tags and fields that are not stored into the generated file.
6665
- **Related:** [The plan's generated file design](../../2026-10-04-plan-builder.md#what-stashgen-writes), [the plan's embedded struct design](../../2026-10-04-plan-builder.md#embedded-structs-unexported-fields-and-other-tags)
67-
- **Needs:** Understand the account tags.
6866

6967
The generated comment names `cache`, and `EncryptedAccount` embeds the same `gorm.Model`.
7068
The encrypted `Email` field retains its GORM and JSON tags.
@@ -105,7 +103,6 @@ var codec = gensupport.New(gensupport.Generated[Account, EncryptedAccount]{
105103
106104
- **Purpose:** See what the `-redact` flag adds to `Account`.
107105
- **Related:** [The plan's printing design](../../2026-10-04-plan-builder.md#printing)
108-
- **Needs:** Understand that the tagged struct contains plaintext values.
109106
110107
`-redact` asks `stashgen` to add `String` and `LogValue` methods to `Account`.
111108
These methods show `gorm.Model` and hide `Email`.
@@ -127,7 +124,6 @@ func (a Account) LogValue() slog.Value {
127124
128125
- **Purpose:** Follow a slice through encryption and into GORM.
129126
- **Related:** [The plan's database design](../../2026-10-04-plan-builder.md#databases)
130-
- **Needs:** Understand `EncryptedAccount`.
131127
132128
`EncryptedAccount.TableName` maps the encrypted type to the `accounts` table.
133129
`Create` encrypts the whole slice before GORM receives it.
@@ -145,32 +141,3 @@ func Create(ctx context.Context, db *gorm.DB, cipher *encrypt.Cipher, accounts [
145141
return db.WithContext(ctx).Create(&encrypted).Error
146142
}
147143
```
148-
149-
## What was checked
150-
151-
- **Every Go file type-checks:**
152-
Run.
153-
`go vet ./...` passes against a stub of the SDK.
154-
The stub is not in this repository, and it has signatures only.
155-
- **A change to a tagged struct, a model or a type in another package stops the build:**
156-
Run.
157-
Each change fails `go build` with "cannot convert".
158-
- **A generated file from another version does not compile:**
159-
Run.
160-
A file that names an unknown version constant fails `go build`.
161-
- **The files `stashgen` writes:**
162-
Not run.
163-
`stashgen` does not exist, and the five `_stash.go` files are written by hand.
164-
- **The SDK can be built with these signatures:**
165-
Not run.
166-
- **The guest returns an EQL value for a field with `encrypt_into`:**
167-
Not run.
168-
The target form and the dispatch do not exist.
169-
- **`stashgen` checks a declaration with the embedded guest:**
170-
Not run.
171-
- **The code works with a database, GORM or pgx:**
172-
Not run.
173-
Nothing here has connected to a database.
174-
- **The EQL types, and the value the guest returns for them:**
175-
Not run.
176-
`eql-codegen` does not write Go yet, and the examples use a stub of `eql.TextEq`.

‎docs/plans/2026-10-04-plan-builder/cmd/genencrypt/README.md‎

Lines changed: 0 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@ The [Go example index](../../README.md) lists every example and what was checked
1414

1515
- **Purpose:** Follow the three inputs to the planned library generator.
1616
- **Related:** [The plan's policy declarations](../../../2026-10-04-plan-builder.md#declarations-from-a-policy), [the rules walkthrough](../../rules/README.md), [the individuals walkthrough](../../individuals/README.md)
17-
- **Needs:** Read the `rules.Individuals` policy first.
1817

1918
`protosource.New()` supplies protobuf descriptors and field options.
2019
`rules.Individuals` supplies the field decisions.
@@ -40,29 +39,8 @@ The `stashgen`, `protosource`, and policy packages do not exist yet.
4039

4140
- **Purpose:** See how reviewers inspect policy changes without running rules in the application.
4241
- **Related:** [The generated individuals walkthrough](../../individuals/README.md), [the rules walkthrough](../../rules/README.md)
43-
- **Needs:** Understand the generator inputs.
4442

4543
The [`rules` package](../../rules/README.md) runs this command through `go generate`.
4644
The application calls the resulting `individuals.Encrypt` and `individuals.Decrypt` functions.
4745
A rule change changes `individual_stash.go`, which gives a reviewer a concrete generated diff.
4846
The application never runs the rules.
49-
50-
## What was checked
51-
52-
- **Every Go file type-checks:**
53-
Run.
54-
`go vet ./...` passes against a stub of the SDK.
55-
The stub is not in this repository, and it has signatures only.
56-
- **The policy example compiles against real protobuf code:**
57-
Run.
58-
buf v1.50.0 and `protoc-gen-go` wrote `internal/pb/`, and `go vet` passes.
59-
- **The protobuf source reads the field options, and the rules run:**
60-
Not run.
61-
Neither the source nor the generator exists.
62-
- **The files `stashgen` writes:**
63-
Not run.
64-
`stashgen` does not exist, and the five `_stash.go` files are written by hand.
65-
- **The SDK can be built with these signatures:**
66-
Not run.
67-
- **`stashgen` checks a declaration with the embedded guest:**
68-
Not run.

‎docs/plans/2026-10-04-plan-builder/contacts/README.md‎

Lines changed: 0 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@ It shows what `stashgen` is planned to write.
2121

2222
- **Purpose:** Connect a tag declaration in your own package to `crm.Contact`.
2323
- **Related:** [The `crm.Contact` type in another package](../crm/README.md), [the plan's design for types in another package](../../2026-10-04-plan-builder.md#types-in-another-package)
24-
- **Needs:** Understand that the program does not own `crm.Contact`.
2524

2625
The `-for crm.Contact` flag makes `contactStash` declare tags for a type in another package.
2726
The generator is planned to match fields by name and type.
@@ -72,7 +71,6 @@ type contactShape struct {
7271

7372
- **Purpose:** See how each encrypted field holds a ciphertext and its declared search terms.
7473
- **Related:** [The plan's column layouts](../../2026-10-04-plan-builder.md#columns), [the plan's generated file design](../../2026-10-04-plan-builder.md#what-stashgen-writes)
75-
- **Needs:** Understand the `contactStash` tags.
7674

7775
`EncryptedContact` nests one encrypted type for each encrypted field.
7876

@@ -127,7 +125,6 @@ It cannot add methods to `crm.Contact` because Go requires methods to belong to
127125

128126
- **Purpose:** Flatten nested encrypted outputs into one field for each database column.
129127
- **Related:** [The plan's model design](../../2026-10-04-plan-builder.md#models)
130-
- **Needs:** Understand the separate encrypted outputs.
131128

132129
`-model Rows=ContactRow` asks for `EncryptRows` and `DecryptRows`.
133130
`ContactRow` is a model with one tagged field for each column.
@@ -183,7 +180,6 @@ func DecryptRows(ctx context.Context, d encrypt.Decrypter, rows []ContactRow) ([
183180

184181
- **Purpose:** Compare direct column writes with a model-based GORM write.
185182
- **Related:** [The plan's database design](../../2026-10-04-plan-builder.md#databases)
186-
- **Needs:** Understand both encrypted layouts.
187183

188184
`Create` passes each nested output to `database/sql`.
189185

@@ -222,7 +218,6 @@ func CreateWithGORM(ctx context.Context, db *gorm.DB, cipher *encrypt.Cipher, li
222218
223219
- **Purpose:** Derive and use the equality search term for a separate column.
224220
- **Related:** [The plan's call design](../../2026-10-04-plan-builder.md#calls), [the plan's terminology](../../2026-10-04-plan-builder.md#terminology)
225-
- **Needs:** Understand the `phone_number_eq` column.
226221
227222
`Fields.PhoneNumber.Equality` derives an `encrypt.EqualityTerm` search term.
228223
The query compares that search term with the `phone_number_eq` column.
@@ -240,26 +235,3 @@ func IDByPhone(ctx context.Context, db *sql.DB, cipher *encrypt.Cipher, phone st
240235
return id, err
241236
}
242237
```
243-
244-
## What was checked
245-
246-
- **Every Go file type-checks:**
247-
Run.
248-
`go vet ./...` passes against a stub of the SDK.
249-
The stub is not in this repository, and it has signatures only.
250-
- **A change to a tagged struct, a model or a type in another package stops the build:**
251-
Run.
252-
Each change fails `go build` with "cannot convert".
253-
- **A generated file from another version does not compile:**
254-
Run.
255-
A file that names an unknown version constant fails `go build`.
256-
- **The files `stashgen` writes:**
257-
Not run.
258-
`stashgen` does not exist, and the five `_stash.go` files are written by hand.
259-
- **The SDK can be built with these signatures:**
260-
Not run.
261-
- **`stashgen` checks a declaration with the embedded guest:**
262-
Not run.
263-
- **The code works with a database, GORM or pgx:**
264-
Not run.
265-
Nothing here has connected to a database.

‎docs/plans/2026-10-04-plan-builder/crm/README.md‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@ The [Go example index](../README.md) lists every example and what was checked.
1717

1818
- **Purpose:** Understand why `crm.Contact` stays free of encryption tags.
1919
- **Related:** [The plan's design for types in another package](../../2026-10-04-plan-builder.md#types-in-another-package), [the contacts walkthrough](../contacts/README.md)
20-
- **Needs:** Nothing
2120

2221
`crm.Contact` contains only the fields supplied by the stand-in package.
2322

@@ -54,7 +53,6 @@ type contactStash struct {
5453

5554
- **Purpose:** See how a change to `crm.Contact` stops the contacts package from building.
5655
- **Related:** [The contacts walkthrough](../contacts/README.md), [the plan's design for types in another package](../../2026-10-04-plan-builder.md#types-in-another-package)
57-
- **Needs:** Understand the fields of `crm.Contact`.
5856

5957
The generated file converts `crm.Contact` to `contactShape` at compile time.
6058
The conversion fails when `crm.Contact` gains, loses, reorders, or retypes a field.
@@ -72,13 +70,3 @@ type contactShape struct {
7270
Internal string
7371
}
7472
```
75-
76-
## What was checked
77-
78-
- **Every Go file type-checks:**
79-
Run.
80-
`go vet ./...` passes against a stub of the SDK.
81-
The stub is not in this repository, and it has signatures only.
82-
- **A change to a tagged struct, a model or a type in another package stops the build:**
83-
Run.
84-
Each change fails `go build` with "cannot convert".

‎docs/plans/2026-10-04-plan-builder/documents/README.md‎

Lines changed: 0 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@ It shows what `stashgen` is planned to write.
1818

1919
- **Purpose:** Understand why the document fields have no individual tags.
2020
- **Related:** [The plan's struct tags](../../2026-10-04-plan-builder.md#struct-tags), [the plan's column layouts](../../2026-10-04-plan-builder.md#columns)
21-
- **Needs:** Nothing
2221

2322
The `opaque` option is part of the encryption context tag.
2423
It tells the planned generator to encrypt the complete `Document` as one value.
@@ -43,7 +42,6 @@ Nothing inside the document can be read or searched independently through this l
4342

4443
- **Purpose:** Follow the opaque tag into the encrypted type and declaration.
4544
- **Related:** [The plan's generated file design](../../2026-10-04-plan-builder.md#what-stashgen-writes)
46-
- **Needs:** Understand the opaque tagged struct.
4745

4846
`EncryptedDocument` has one `Sealed` ciphertext field.
4947

@@ -84,7 +82,6 @@ var codec = gensupport.New(gensupport.Generated[Document, EncryptedDocument]{
8482
8583
- **Purpose:** See why `Save` uses a cipher and `Load` uses the client.
8684
- **Related:** [The plan's call design](../../2026-10-04-plan-builder.md#calls), [the root example program](../main.go)
87-
- **Needs:** Understand `EncryptedDocument.Sealed`.
8885
8986
`Save` encrypts one document by passing a one-element slice.
9087
It stores `encrypted[0].Sealed` in the `body` column.
@@ -124,26 +121,3 @@ func Load(ctx context.Context, db *sql.DB, client *encrypt.Client, id int64) (Do
124121
return docs[0], nil
125122
}
126123
```
127-
128-
## What was checked
129-
130-
- **Every Go file type-checks:**
131-
Run.
132-
`go vet ./...` passes against a stub of the SDK.
133-
The stub is not in this repository, and it has signatures only.
134-
- **A change to a tagged struct, a model or a type in another package stops the build:**
135-
Run.
136-
Each change fails `go build` with "cannot convert".
137-
- **A generated file from another version does not compile:**
138-
Run.
139-
A file that names an unknown version constant fails `go build`.
140-
- **The files `stashgen` writes:**
141-
Not run.
142-
`stashgen` does not exist, and the five `_stash.go` files are written by hand.
143-
- **The SDK can be built with these signatures:**
144-
Not run.
145-
- **`stashgen` checks a declaration with the embedded guest:**
146-
Not run.
147-
- **The code works with a database, GORM or pgx:**
148-
Not run.
149-
Nothing here has connected to a database.

‎docs/plans/2026-10-04-plan-builder/individuals/README.md‎

Lines changed: 0 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@ It shows what `stashgen.Generate` is planned to write.
1919

2020
- **Purpose:** Connect policy decisions to the encrypted type and declaration.
2121
- **Related:** [The rules walkthrough](../rules/README.md), [the plan's policy declarations](../../2026-10-04-plan-builder.md#declarations-from-a-policy)
22-
- **Needs:** Understand `rules.Individuals`.
2322

2423
`Id` and `Nickname` are passthrough fields.
2524
`Name` has one ciphertext, while `Email` has a ciphertext and two search terms.
@@ -66,7 +65,6 @@ var declaration = gensupport.Declare("individuals").
6665

6766
- **Purpose:** Understand why protobuf messages do not use the usual shape check.
6867
- **Related:** [The generated protobuf walkthrough](../internal/pb/README.md), [the plan's design for types in another package](../../2026-10-04-plan-builder.md#types-in-another-package)
69-
- **Needs:** Know that `pb.Individual` contains unexported protobuf fields.
7068

7169
The codec takes `*pb.Individual` values.
7270
It reads each field through a generated getter because direct struct conversion cannot include unexported fields.
@@ -102,7 +100,6 @@ CI runs `go generate ./...` and fails when a generated file differs from the com
102100
103101
- **Purpose:** Follow protobuf pointers and the Medicare field through the generated API.
104102
- **Related:** [The plan's call design](../../2026-10-04-plan-builder.md#calls), [the generation command walkthrough](../cmd/genencrypt/README.md)
105-
- **Needs:** Understand the codec's pointer type.
106103
107104
`Encrypt` accepts a slice of `*pb.Individual` pointers.
108105
`Decrypt` returns the same pointer form.
@@ -156,7 +153,6 @@ func (f MedicareNoField) Query(ctx context.Context, c *encrypt.Cipher, v string)
156153
157154
- **Purpose:** Map each storage layout to its database columns and query.
158155
- **Related:** [The plan's database design](../../2026-10-04-plan-builder.md#databases)
159-
- **Needs:** Understand the mixed encrypted type.
160156
161157
`Create` passes the passthrough fields, ciphertexts, search terms, and EQL value to their columns.
162158
@@ -191,40 +187,3 @@ func IDByMedicare(ctx context.Context, db *sql.DB, cipher *encrypt.Cipher, medic
191187
return id, err
192188
}
193189
```
194-
195-
## What was checked
196-
197-
- **Every Go file type-checks:**
198-
Run.
199-
`go vet ./...` passes against a stub of the SDK.
200-
The stub is not in this repository, and it has signatures only.
201-
- **The policy example compiles against real protobuf code:**
202-
Run.
203-
buf v1.50.0 and `protoc-gen-go` wrote `internal/pb/`, and `go vet` passes.
204-
- **A field added to the protobuf message does not stop the build:**
205-
Run.
206-
It builds, as the plan says: CI finds that change.
207-
- **A struct from another package with an unexported field cannot convert:**
208-
Run, with `sync.Once`.
209-
- **A generated file from another version does not compile:**
210-
Run.
211-
A file that names an unknown version constant fails `go build`.
212-
- **The protobuf source reads the field options, and the rules run:**
213-
Not run.
214-
Neither the source nor the generator exists.
215-
- **The files `stashgen` writes:**
216-
Not run.
217-
`stashgen` does not exist, and the five `_stash.go` files are written by hand.
218-
- **The SDK can be built with these signatures:**
219-
Not run.
220-
- **The guest returns an EQL value for a field with `encrypt_into`:**
221-
Not run.
222-
The target form and the dispatch do not exist.
223-
- **`stashgen` checks a declaration with the embedded guest:**
224-
Not run.
225-
- **The code works with a database, GORM or pgx:**
226-
Not run.
227-
Nothing here has connected to a database.
228-
- **The EQL types, and the value the guest returns for them:**
229-
Not run.
230-
`eql-codegen` does not write Go yet, and the examples use a stub of `eql.TextEq`.

‎docs/plans/2026-10-04-plan-builder/internal/pb/README.md‎

Lines changed: 0 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ The [Go example index](../../README.md) lists every example and what was checked
1616

1717
- **Purpose:** Identify the generators, versions, and the command that generates the package again.
1818
- **Related:** [The protobuf source walkthrough](../../proto/README.md)
19-
- **Needs:** Install buf and `protoc-gen-go`.
2019

2120
buf v1.50.0 ran `protoc-gen-go` v1.26.0 to write these files.
2221
The generated header reports the `protoc` version as unknown.
@@ -42,7 +41,6 @@ package pb
4241

4342
- **Purpose:** Identify the generated values that the individuals example reads.
4443
- **Related:** [The generated individuals walkthrough](../../individuals/README.md), [the plan's design for types in another package](../../../2026-10-04-plan-builder.md#types-in-another-package)
45-
- **Needs:** Understand the `Individual` message fields.
4644

4745
`pb.Individual` includes three unexported protobuf fields before its exported data fields.
4846

@@ -89,7 +87,6 @@ The examples do not use protobuf internals such as `file_individual_proto_rawDes
8987

9088
- **Purpose:** Connect the protobuf option to the planned policy source.
9189
- **Related:** [The rules walkthrough](../../rules/README.md), [the plan's policy declarations](../../../2026-10-04-plan-builder.md#declarations-from-a-policy)
92-
- **Needs:** Understand the `data_categories` option.
9390

9491
`classification.pb.go` exports `E_DataCategories` for the repeated field option.
9592

@@ -106,21 +103,3 @@ var (
106103
```
107104

108105
The planned `protosource` package reads this option through protobuf descriptors.
109-
110-
## What was checked
111-
112-
- **Every Go file type-checks:**
113-
Run.
114-
`go vet ./...` passes against a stub of the SDK.
115-
The stub is not in this repository, and it has signatures only.
116-
- **The policy example compiles against real protobuf code:**
117-
Run.
118-
buf v1.50.0 and `protoc-gen-go` wrote `internal/pb/`, and `go vet` passes.
119-
- **A field added to the protobuf message does not stop the build:**
120-
Run.
121-
It builds, as the plan says: CI finds that change.
122-
- **A struct from another package with an unexported field cannot convert:**
123-
Run, with `sync.Once`.
124-
- **The protobuf source reads the field options, and the rules run:**
125-
Not run.
126-
Neither the source nor the generator exists.

0 commit comments

Comments
 (0)