Skip to content

Commit 8e46e04

Browse files
committed
docs(adr): keep the decision-history line optional and align FORMAT owners with the issue
Review repairs for #3744 wording: the Decision history line stays a permission, PR logs and status change-logs route to the umbrella issue, the 8 KB figure reads as an approximate upper aim, and the AGENTS.md qualifiers return with meaning-neutral compressions.
1 parent c8a6668 commit 8e46e04

2 files changed

Lines changed: 8 additions & 8 deletions

File tree

‎AGENTS.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ The daemon owns sessions. Registry declarations route commands to platform runti
55

66
## Task routing
77

8-
Read only the row for your current task. Follow other links only when they apply.
8+
Read only your task's row. Follow other links only when they apply.
99

1010
| When the task involves | Read |
1111
| --- | --- |
@@ -48,12 +48,12 @@ The versioned CLI help owns command semantics. To drive an app, start with the s
4848
- In a new worktree, run `pnpm install --frozen-lockfile && pnpm build` before you test.
4949
- Do not change other worktrees, devices, sessions, dirty files, or experiments. Do not use `git stash`; all worktrees share it.
5050
- Do not copy `.env` into a worktree. For host credentials, source the main checkout's file by its absolute path.
51-
- Give each parallel worker different files and a different device. `pnpm check:affected --run` and `pnpm check` run one at a time.
51+
- Give each parallel worker different files and a different device. `pnpm check:affected --run` and `pnpm check` run one at a time automatically.
5252
- The layering scan reads only tracked files. Stage new modules before you trust its result.
5353
- When you rename a file, move its Fallow baseline entry. Do not regenerate unrelated baselines.
5454

55-
The validation lock automatically reclaims owners that are provably dead. An unknown owner continues to block.
56-
If the wait times out, report the printed owner and the lock state. Do not remove the lock.
55+
The validation lock automatically reclaims provably dead owners. An unknown owner continues to block.
56+
If the wait times out, report the printed owner and the lock state. Do not remove the lock manually.
5757

5858
## Agent docs
5959

‎docs/adr/FORMAT.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,19 +36,19 @@ Do not record these in an ADR. Send each to its owner:
3636
- Implementation inventories and file maps: the registries, types, and gates that own them.
3737
- Measurements: `docs/evidence/`.
3838
- Rollout and migration plans: the package docs, the help, or the umbrella issue.
39-
- PR logs and status change-logs: delete them. Git history keeps them.
39+
- PR logs and status change-logs: the umbrella issue.
4040

4141
Do not repeat general repo guidance that `AGENTS.md` already gives.
4242

4343
## The record stays current
4444

45-
An ADR states the current truth. It is not a log of the discussion around the decision. If the direction really changed, add one dated "Decision history" line with its reason and a link.
45+
An ADR states the current truth. It is not a log of the discussion around the decision. An optional dated "Decision history" line records a real change of direction. If the direction really changed, you may add one such line with its reason and a link.
4646

4747
## Before you amend
4848

4949
1. Check the current code against the decision the record intends to keep.
5050
2. Check the code comments and issues that cite the record.
51-
3. If the code changed on purpose: update the record to the new truth. Record the reason. Add a "Decision history" line when the direction changed.
51+
3. If the code changed on purpose: update the record to the new truth. Record the reason. When the direction changed, you may add the optional "Decision history" line.
5252
4. If the code drifted by mistake: record the drift in an issue. Keep the constraint in the record.
5353
5. Preserve constraints that the code cannot show.
5454
6. If you change a section name or a decision number, update the code citations that point at it.
@@ -63,6 +63,6 @@ An amendment that changes the modality, scope, or exceptions of an accepted deci
6363

6464
## Size and naming
6565

66-
Keep each ADR near 8 KB. Prefer less.
66+
Keep ADRs short. Aim below about 8 KB.
6767

6868
Name files `NNNN-slug.md` in `docs/adr/`. Scan the directory and use the next number. Add a row to the index in `docs/adr/README.md`.

0 commit comments

Comments
 (0)