From dd886a8a63ba144cdc8aea0bad928b7bf297557f Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 20 Oct 2026 09:27:49 -0400 Subject: [PATCH 01/12] Add design spec: Export an opened artifact as a clean, docket-free Markdown file --- ...-a-clean-docket-free-markdown-fi-design.md | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-20-export-an-opened-artifact-as-a-clean-docket-free-markdown-fi-design.md diff --git a/docs/superpowers/specs/2026-10-20-export-an-opened-artifact-as-a-clean-docket-free-markdown-fi-design.md b/docs/superpowers/specs/2026-10-20-export-an-opened-artifact-as-a-clean-docket-free-markdown-fi-design.md new file mode 100644 index 000000000..9a2c60590 --- /dev/null +++ b/docs/superpowers/specs/2026-10-20-export-an-opened-artifact-as-a-clean-docket-free-markdown-fi-design.md @@ -0,0 +1,126 @@ +# Export an opened artifact as a clean, docket-free Markdown file — design + +Change 0561 — Export an opened artifact as a clean, docket-free Markdown file + +Change #561, groomed 2026-10-20. + +## Problem + +People share docket artifacts with teammates who do not all use docket — most often a spec, sent as a Markdown file by email or Teams. Today the sender copies the file and deletes the docket parts by hand. As stored, every artifact carries machinery an outside reader cannot use: frontmatter, the ↩ backlink banner, the `## Artifacts` table, build-evidence blocks and their `` marker comments, links into files the reader cannot open, the spec's `Change #N, groomed …` stamp, and change references (`change #547`, `change 0559`, `the 0111 guard`) woven into sentences. + +## Goal + +One shell command a human runs (no agent session involved) that writes a clean Markdown copy of a change, its spec, its plan, or its results: nothing docket-specific is left outside prose and code, references read naturally, the heading structure is well formed, and the person is told about anything that slipped through. + +## Non-goals and anti-goals + +- **No board export.** The board is out of scope entirely (Daniel's decision). +- **No prose rewriting.** A sentence that talks about docket as a subject stays as written; the export removes docket's bookkeeping and, beyond step 6's change-reference conversions, does not edit the author's content. Mentions are reported instead (see *Self-check*). +- **No general Markdown reformatter.** The sources are already consistent (measured across 630 files: dash bullets only, no malformed headings, exactly one H1 first in every spec/plan/results file, no skipped heading levels). The export only cleans up what its own removals leave behind, adds the H1 an issue lacks, and reports heading-rule problems — it never renumbers headings or reflows tables. +- **No guessing at bare `#N`.** A `#N` with no `change` word before it stays exactly as written and is never warned about (Daniel's decision). The export cannot tell a change from a GitHub issue or PR, a step, or any other numbering: in this repository 1,639 of the 2,078 bare `#N` change references are numbers a real PR also has, and a repository that starts at change 1 collides with `#12` or `Step #3` just as easily. A word-list exclusion fails the other way (`fixes #515`, `case #559`, `rule #533` are real change references). The export is for a person to read; what they do with a `#N` afterwards is outside its job. +- **ADR references stay.** "ADR" is general vocabulary, not docket's: `ADR-0147` and `ADR-0065's` stay as written (Daniel's decision). Only a link around one is removed (step 5). +- **Never block.** A leftover is a warning, never a refusal to write (Daniel's decision; matches docket's visibility-only default for new checks). +- **No agent, no AI.** Every conversion is deterministic Go in the `docket` binary. +- No other export formats (.docx, PDF), no change to how artifacts are stored, no Windows support (docket ships only macOS and Linux; Windows is out entirely — Daniel's decision). + +## Command surface + +A flag on the existing command, not a new command (Daniel agreed; it reuses `docket open`'s target resolution; the longer `open` signature costs about 78 bytes of the 16 KB capability catalog — JSON escapes `<`/`>` and `--warnings` renders with its default — taking it from about 16,186 to about 16,264 of 16,384 bytes, so it fits without a ceiling raise): + +``` +docket open [] --export [--output-path ] [--warnings all|leftovers|mentions] [--print] +``` + +- `--export` writes the clean copy, then opens **that copy** with the platform opener (the default Markdown app), exactly as `open` launches a local file today. With `--print`, it writes the copy and prints its path without launching anything. +- `--export` always reads the **local metadata checkout** file — also in a shared repository and regardless of `open.artifacts` — through the existing `localArtifact` path (prepare first; a failed prepare adds today's staleness note and proceeds). +- `--output-path ` (Daniel's name; optional) overrides the destination. An existing directory means "put the file in here under its normal name"; anything else is the exact file path to write. A relative path resolves against the working directory. A parent directory that does not exist is refused with one line (`output-path-invalid` or similar; builder names it). +- `--warnings` (Daniel's addition; optional, default `all`) selects which warning lists are reported: `all`, `leftovers`, or `mentions`. Any other value is a usage error. +- Refusals (usage errors, nothing written): `--export` with `board` or `pr`; `--output-path` or `--warnings` without `--export`; an invalid `--warnings` value. Existing refusals (unknown change, artifact unset, file missing, path outside the repository) apply unchanged. +- No id: inferred from the checked-out branch, as today. + +## Destination and filename + +**Default directory** (Daniel's decision): `~/Downloads` on macOS, the home directory (`os.UserHomeDir`) on Linux. A missing `~/Downloads` on macOS is refused with one line naming `--output-path` (my call). + +**Filename** (Daniel's decision on the shape): `--.md`, where `` is `spec`, `plan`, `results`, or `issue` (for a change record). Examples from #559: + +| Export | Source basename | Exported filename | +|---|---|---| +| spec | `2026-10-17-close-a-change-to-done-without-a-pr-design.md` | `2026-10-17-spec-close-a-change-to-done-without-a-pr.md` | +| plan | `2026-10-17-close-a-change-to-done-without-a-pr.md` | `2026-10-17-plan-close-a-change-to-done-without-a-pr.md` | +| results | `2026-10-17-close-a-change-to-done-without-a-pr-results.md` | `2026-10-17-results-close-a-change-to-done-without-a-pr.md` | +| change | `2026-10-17-0559-close-a-change-to-done-without-a-pr.md` | `2026-10-17-issue-close-a-change-to-done-without-a-pr.md` | + +- spec/plan/results: `` is the source basename's leading `YYYY-MM-DD`; `` is the rest of the basename with a trailing `-design` (spec) or `-results` (results) removed (my call — the type word now carries that). A basename with no leading date takes the change's `created:` date and uses the whole stem as ``. +- change: `` is the record's `created:`; `` is its `slug` (my call — active record names carry no date, and `created:` matches how the other artifacts are dated). +- An existing file at the destination is replaced; the human output says so (my call — re-exporting after an edit is the common case). + +## The transform + +Input: the artifact's bytes from the metadata checkout, plus the pinned snapshot `docket open` already builds (`resolveOpenChange` → `repository.BuildSnapshot`), whose corpus already includes every change — the source of reference titles. + +**Fence and code awareness everywhere:** nothing inside a fenced code block or an inline code span is ever changed — no removal, no link rewrite, no reference substitution (the existing fence-aware scanners in `internal/document` and `internal/render/section.go` show the pattern). A link that wraps a code span (`` [`internal/app/open.go`](…) ``) is outside the code, so the link goes and the code span stays. + +Steps, in order: + +1. **Frontmatter.** Remove the leading `---…---` block (reuse `internal/document`'s frontmatter locator; never a bare column-0 `---` match). +2. **Managed blocks.** Remove every docket managed marker block — start marker, contents, end marker — in either namespace (`docket:` and the neutral `dckt:`; see `document.NeutralMarkerPrefix`): the backlink banner, the `## Artifacts` link block, `docket:build-evidence`, and any other block. Reuse the document package's fence-aware block scanner. A stray, unpaired marker line is removed too and reported as a leftover (it means the source is damaged). +3. **Issue only — keep the proposal.** For a change record, the body keeps **only** `## Why`, `## What changes`, `## Out of scope`, and `## Open questions`, in source order; every other H2 section is dropped (Daniel's decision: drop both docket bookkeeping — Reconcile log, Reclaim log, Build evidence, Closeout notes, Run halted, Finalize blocked, Auto-groom blocked — and the human-written reasons — Why deferred, Why killed, Why on hold). This is an **allowlist** on purpose (my call): the records carry ~30 one-off headings (e.g. "Why the run halted", "Triage note (…)") that a drop-list would leak; the cost is that rare hand-written extras like `## Design decisions` (20 old records) and `## Notes` (3) are dropped too. Then insert an H1 of the change's `title` at the top. +4. **Spec header stamps.** Docket's grooming has written a change stamp near the top of a spec in several shapes over time (my call to cover them all, since older specs get shared too). Remove, before step 6: + - a stamp sentence of the shape `Change #N, groomed YYYY-MM-DD.` or `Change N. Groomed YYYY-MM-DD.` (with an optional parenthetical such as `(interactive)`); when the line carries more text after the stamp sentence, only the stamp sentence goes and the rest of the line stays and continues to step 6 (`Change #N, groomed …. Found while building change #M (PR #K).` → `Found while building "" (PR #K).`); + - a line that is only `Change N.` or `Change #N.`; + - a line that is only `**Change:** N` / `**Change:** #N`, or a `·`-separated run of bold `**Key:** value` pairs that includes `**Change:**` (e.g. `**Change:** N · **Type:** feat · **Priority:** critical · **Date:** … · **Status:** …`). + Any other line beginning with a change reference goes through step 6 normally. +5. **Links — every one.** Every link is removed and its visible text kept, whatever it points at (Daniel's decision: the reader cannot follow docket links, and one rule needs no way to tell docket links from others — a docket-only rule would also have missed the ~700 links in older archived records that reach docket files through `github.com/…/blob/main/docs/…` URLs from when artifacts lived on main). Measured across the artifacts outside code and frontmatter: 1,742 relative links, ~700 `blob/main` links, 15 external, 13 metadata-branch, 6 autolinks, 1 PR link, 1 in-page anchor. + - an inline link `[text](target)` becomes `text` — relative, `https://`, `mailto:`, and in-page `#anchor` targets alike: `[Run Modes](https://cursor.com/docs/…)` → `Run Modes`, `[PR 265](https://github.com/…/pull/265)` → `PR 265`; + - an autolink `<https://…>` becomes the URL as plain text; + - an image `![alt](target)` becomes its alt text, and is removed when the alt text is empty; a reference-style link (`[text][ref]`, `[text][]`, or a `[text]` shortcut that matches a definition) becomes `text`, and every link-reference definition line (`[ref]: url`) is removed; an HTML `<a href="…">text</a>` becomes `text` (all my calls; none of these occur in the artifacts today); + - a bare URL typed into a sentence (`see https://go.dev/doc/toolchain`) is not link syntax: it stays as plain text (Daniel's decision), and viewers may still make it clickable. + The kept text then goes through step 6 like any other text: `[#559](../changes/…)` → `#559`, which stays; `[change 0154](…)` → a converted title. +6. **Change references.** Converted **only** where the text plainly names a docket change (Daniel's decision); everything else stays as written (see *Non-goals*: bare `#N`, `PR #N`, ADR references). The converted forms: + - the word `change`/`changes` (case-insensitive) followed by a number with or without `#`: `change 559`, `Change #547`, `change 0363`, and a list after the plural word, `changes #461 and #550` or `changes 0113, 0114 and 0120` (each number in the list); + - a zero-padded id, which is docket's own id format: `#0559`, `(0559)`, and a bare zero-padded id standing as its own word (`the 0111 guard`, `0282's`, `mirroring 0088` — my call), never when it is part of a path or filename such as `0561-export…md`. + A form converts **only** when its number is a change id present in the snapshot; an unknown number is left exactly as written. (Checked across the artifacts: of 268 unpadded `change N` uses whose N is a real change id, none is the verb — "change 3 files" — so the word form is safe.) How a converted reference reads: + - **Inside a parenthesis that holds only references** (with commas, `and`, whitespace): the converted references and their separators are removed, and the whole parenthetical, with the space before it, goes when nothing is left: `fields (0461, 0550)` → `fields`. A kept item stays in its parenthesis: `(0461, ADR-0012)` → `(ADR-0012)`; `(#461, ADR-0012)` is unchanged. + - **Followed by a spaced dash (` — `, ` – `, or ` - `) and that change's own title**: the reference and the dash are removed, leaving the title once: `# Change 0466 — Bring test_go_race back under its 60s row…` → `# Bring test_go_race back under its 60s row…` (three older specs open this way; my call). + - **Anywhere else**: the reference, including its `change`/`Change` word, becomes the change's title in straight double quotes: `Change #547 holds the full measurement` → `"Measure whether the 1h cache TTL cut implement-next's cost" holds the full measurement`; `from change 0363 forbids it` → `from "Remove main-mode compatibility from Go v1" forbids it`. A list becomes `"A", "B" and "C"`. (Daniel approved these readings.) + - **Inserted titles are cleaned once, never recursively** (my call). Some change titles contain change references ("Clear the unfixed review findings from change 0113") and some contain double quotes. Before a title is inserted — and for the issue's own H1 from step 3 — it gets one pass: a parenthetical holding only convertible references is removed, any other convertible change reference becomes `another issue`, or `other issues` for a list (`"Clear the unfixed review findings from another issue"`; Daniel's decision: wherever the export itself writes the word, it says "issue", the outside reader's word, matching the `issue` filename type), bare `#N` and ADR references inside it stay, and its double quotes become single quotes so the outer quotes stay unambiguous. No title is ever looked up from inside a title, so the pass always terminates, and an inserted title never re-triggers the self-check. +7. **Cleanup of what removal left.** Drop a heading whose section is now empty (nothing but blank lines before the next heading of the same or higher level — e.g. a change's `## Artifacts`); collapse runs of blank lines to one; no leading blank lines; exactly one trailing newline. + +## Self-check (warnings — never blocking) + +After the transform, the export scans **its own output** with a detector that is **implemented separately from the transform but checks the same rules this spec defines** (my call). It must not call or share the transform's patterns or code — otherwise it agrees with the transform by construction and can never find anything — but it must not flag what the transform keeps on purpose either (bare `#N`, `PR #N`, ADR references, unknown ids, bare URLs, text in code), or the zero-leftover corpus test could never pass. Where it reaches further than the transform, it does so only with structural checks the transform can satisfy (any marker text at all, any top-of-file `---` block, heading rules). It produces two lists: + +- **Leftovers** — docket machinery that should have been removed, each with its 1-based output line number and matched text. Outside code, at least: any `docket:`/`dckt:` marker text; a `---` frontmatter block at the top; a ↩ banner line; any link syntax at all (inline link, image, autolink, reference-style link or definition, HTML `<a`); any step-6 converted form whose number is a known change id; a stamp line. **Heading rules** are reported here too (my call — they are "the export did not produce clean output"): not exactly one H1, the H1 not the first heading, or a skipped level (H2 → H4). +- **Mentions** — every output line containing the word `docket` or `dckt`, prose **and** code (my call — teammates read both). Kept on purpose; listed so the person can review. Reported compactly: a count plus the line numbers. + +`--warnings` filters which lists are reported (human and JSON output alike — my call). Warnings never change the result: the file is written, the result is `applied`, exit 0. + +## Output + +- Human mode: stdout is exactly the exported file's path (so `--print` composes in command substitution); notes and warnings go to stderr as today's `note:` lines do (`Presenter.Present`), e.g. `note: replaced <path>`, `warning: leftover line 12: <text>`, `warning: 14 mentions of docket on lines 3, 9, …`. Exact wording is the builder's, in docket's plain-language finding style (what, whether it matters, what to do). +- JSON mode: `OpenResult` gains the export fields (builder names them; e.g. `exported_path`, `replaced`, `leftovers: [{line, text, rule}]`, `mentions: {count, lines}`), filtered by `--warnings`. `docket schema` reflects the new fields. + +## Test guard + +- **Frozen real corpus.** Copy a set of real artifacts from this repository's metadata branch into a test fixture directory — specs, plans, results, and change records, active and archived, chosen to cover every removal and reference form above (including a record with bookkeeping sections, a spec with a stamp line, a spec whose H1 opens `Change N — <title>`, a results file dense with references, an older archived record with `blob/main` docket links, a shared-repo absolute metadata-branch link, external links, an autolink, a bare URL, and code spans/fences containing reference-, link-, and marker-shaped text). Direct assertions also cover what must survive unchanged: bare `#N`, `PR #N`, ADR references, unknown ids, and bare URLs. Record the fixture's inventory (which rule each file exercises, and any category it does not contain) next to it. A test exports every fixture and asserts: zero leftovers from the self-check detector, plus direct assertions for each removal so the test does not rest on the detector alone. Inputs need a snapshot with the referenced ids/titles — build it from the fixture. +- **Mutation-tested.** Disabling any one transform step must turn the corpus test red, and the build records that it checked this. The self-check detector gets the same treatment against crafted inputs carrying each leftover kind. +- **Code is untouched.** A fixture with reference-, link-, and marker-shaped text inside fences and code spans must come out byte-identical in those regions. +- Unit tests per rule (each link form, each converted reference form, parenthetical removal, the own-title dash case, bare `#N` and ADR references left alone, unknown ids, title cleaning, filename derivation, destination resolution with injected home/GOOS, `--output-path` directory-vs-file, flag refusals) and CLI tests for the new flags. +- The capability catalog stays within 16,384 bytes (`TestCapabilitiesPayloadWithinByteBudget`); the `open` signature pinned in `TestRepresentativeSignatures` updates. + +## Docs + +`docs/reference/cli.md`'s `docket open` entry and the command's `--help` text gain the export flags, destinations, and what the export removes — current behavior only. + +## Calls left to the builder + +- Package placement (e.g. a pure `internal/export` package for the transform and a separate one, or file, for the detector) and type/field names. +- Finding/reason codes for the new refusals, minted from `internal/app/finding_codes.go` constants. +- Exact warning wording, within the plain-language style above. + +## Relations + +- Discovered from #559 (results artifacts made sharing results common). +- Builds on #542 (`docket open`); #573 removed `open`'s trivial refusal from the same file (`internal/app/open.go`). +- The leak scanner from #532 (`internal/leakscan`, ADR-0144) is prior art: its change-reference rule matches only zero-padded ids, by design, to avoid PR numbers — the same reasoning behind step 6's narrow forms. It is not reused as the detector: it has no `change N` or link rules and scans for a different job (private-mode leaks). From bb733b9db76c657f6526f164b2de95f3dc8e6c1e Mon Sep 17 00:00:00 2001 From: Daniel Hanold <danny@danielhanold.com> Date: Tue, 20 Oct 2026 09:38:16 -0400 Subject: [PATCH 02/12] feat(document): classify lines leniently for readers that must not trust marker balance --- internal/document/classify.go | 84 ++++++++++++++++++++++++ internal/document/classify_test.go | 100 +++++++++++++++++++++++++++++ 2 files changed, 184 insertions(+) create mode 100644 internal/document/classify.go create mode 100644 internal/document/classify_test.go diff --git a/internal/document/classify.go b/internal/document/classify.go new file mode 100644 index 000000000..d6f6c5618 --- /dev/null +++ b/internal/document/classify.go @@ -0,0 +1,84 @@ +package document + +// LineKind is the lenient class of one physical source line. +type LineKind int + +const ( + LineText LineKind = iota + LineFrontmatter // a line of the leading ---…--- block, both fences included + LineFence // a code-fence delimiter line, or a line inside a fenced block + LineMarkerStart // a well-formed start marker outside fences and frontmatter + LineMarkerEnd // a well-formed end marker outside fences and frontmatter + LineMarkerMalformed // opens like a marker (markerPrefixRE) but fails the grammar +) + +// LineInfo describes one physical line. +type LineInfo struct { + Kind LineKind + Name string // qualified block name (dckt: prefix kept) for start/end markers; "" otherwise +} + +// ClassifyLines returns one LineInfo per physical line, exactly as scanLines +// tiles src. It is the lenient counterpart of Parse's marker scan, for readers +// that must keep working on damaged sources: it never errors, an unclosed +// frontmatter opener is LineText, an unclosed fence runs to EOF, and marker +// balance is not checked. An end marker carrying an annotation is +// LineMarkerMalformed, as scanMarkers rejects it as malformed. +func ClassifyLines(src []byte) []LineInfo { + lines := scanLines(src) + if len(lines) == 0 { + return nil + } + out := make([]LineInfo, len(lines)) + first := 0 + if hasFM, _, closing, err := locateFrontmatter(src, lines); err == nil && hasFM { + for i := range lines { + out[i] = LineInfo{Kind: LineFrontmatter} + if lines[i].span == closing { + first = i + 1 + break + } + } + } + + fence := "" // the open fence's delimiter run; "" when not inside a fence + fenceChar := byte(0) // '`' or '~' + for i := first; i < len(lines); i++ { + text := src[lines[i].text.Start:lines[i].text.End] + if run, ok := fenceRun(text); ok { + switch { + case fence == "": + fence, fenceChar = run, run[0] + case run[0] == fenceChar && len(run) >= len(fence) && isBareFence(text, run): + fence, fenceChar = "", 0 + } + out[i] = LineInfo{Kind: LineFence} + continue + } + if fence != "" { + out[i] = LineInfo{Kind: LineFence} + continue + } + m := markerRE.FindSubmatch(text) + switch { + case m == nil && markerPrefixRE.Match(text): + out[i] = LineInfo{Kind: LineMarkerMalformed} + case m == nil: + out[i] = LineInfo{Kind: LineText} + default: + name := string(m[2]) + if string(m[1]) == "dckt" { + name = NeutralMarkerPrefix + name + } + switch { + case string(m[3]) == "start": + out[i] = LineInfo{Kind: LineMarkerStart, Name: name} + case len(m[4]) > 0: + out[i] = LineInfo{Kind: LineMarkerMalformed} + default: + out[i] = LineInfo{Kind: LineMarkerEnd, Name: name} + } + } + } + return out +} diff --git a/internal/document/classify_test.go b/internal/document/classify_test.go new file mode 100644 index 000000000..db2a0a359 --- /dev/null +++ b/internal/document/classify_test.go @@ -0,0 +1,100 @@ +package document + +import ( + "strings" + "testing" +) + +func TestClassifyLines(t *testing.T) { + text := LineInfo{Kind: LineText} + fm := LineInfo{Kind: LineFrontmatter} + fence := LineInfo{Kind: LineFence} + malformed := LineInfo{Kind: LineMarkerMalformed} + start := func(name string) LineInfo { return LineInfo{Kind: LineMarkerStart, Name: name} } + end := func(name string) LineInfo { return LineInfo{Kind: LineMarkerEnd, Name: name} } + + cases := []struct { + name string + src string + want []LineInfo + }{ + { + name: "frontmatter body and artifacts block", + src: "---\nid: 1\nstatus: proposed\n---\nbody\n" + + "<!-- docket:artifacts:start (generated) -->\nlink\n<!-- docket:artifacts:end -->\n", + want: []LineInfo{fm, fm, fm, fm, text, start("artifacts"), text, end("artifacts")}, + }, + { + name: "neutral namespace keeps its prefix", + src: "<!-- dckt:backlink:start -->\nx\n<!-- dckt:backlink:end -->", + want: []LineInfo{start("dckt:backlink"), text, end("dckt:backlink")}, + }, + { + name: "markers inside a backtick fence are fence lines", + src: "a\n```md\n<!-- docket:artifacts:start -->\n## Heading\n```\nb\n", + want: []LineInfo{text, fence, fence, fence, fence, text}, + }, + { + name: "tilde fence closed by a longer run", + src: "~~~\n<!-- docket:Bad -->\n```\n~~~~~\n<!-- docket:x:end -->\n", + want: []LineInfo{fence, fence, fence, fence, end("x")}, + }, + { + name: "a closer carrying an info string does not close", + src: "```\n``` go\n<!-- docket:x:start -->\n```\nafter\n", + want: []LineInfo{fence, fence, fence, fence, text}, + }, + { + name: "unclosed fence runs to EOF", + src: "```\n<!-- docket:x:start -->\ntext", + want: []LineInfo{fence, fence, fence}, + }, + { + name: "unclosed frontmatter opener is text", + src: "---\nid: 1\n<!-- docket:x:start -->\nbody\n", + want: []LineInfo{text, text, start("x"), text}, + }, + { + name: "end with no start and start with no end", + src: "<!-- docket:a:end -->\nmid\n<!-- docket:b:start -->\ntail\n", + want: []LineInfo{end("a"), text, start("b"), text}, + }, + { + name: "malformed markers", + src: "<!-- docket:Bad -->\n<!-- dckt:x:start\n<!-- docket:x:end (note) -->\n <!-- docket:x:start -->\n", + want: []LineInfo{malformed, malformed, malformed, text}, + }, + { + name: "frontmatter lines are never markers or fences", + src: "---\n<!-- docket:x:start -->\n```\n---\n<!-- docket:y:start -->\n", + want: []LineInfo{fm, fm, fm, fm, start("y")}, + }, + { + name: "empty source", + src: "", + want: nil, + }, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + check := func(t *testing.T, src string) { + t.Helper() + got := ClassifyLines([]byte(src)) + if n := len(scanLines([]byte(src))); len(got) != n { + t.Fatalf("len(ClassifyLines) = %d, scanLines = %d", len(got), n) + } + if len(got) != len(tc.want) { + t.Fatalf("got %d lines %v, want %d %v", len(got), got, len(tc.want), tc.want) + } + for i := range got { + if got[i] != tc.want[i] { + t.Errorf("line %d: got %+v, want %+v", i+1, got[i], tc.want[i]) + } + } + } + t.Run("LF", func(t *testing.T) { check(t, tc.src) }) + t.Run("CRLF", func(t *testing.T) { check(t, strings.ReplaceAll(tc.src, "\n", "\r\n")) }) + }) + } +} From bfd4f7d16ac710e3d84811e11259808adba9c558 Mon Sep 17 00:00:00 2001 From: Daniel Hanold <danny@danielhanold.com> Date: Tue, 20 Oct 2026 09:40:31 -0400 Subject: [PATCH 03/12] feat(export): mask inline code and remove every link form, keeping its text --- internal/export/doc.go | 7 + internal/export/inline.go | 319 +++++++++++++++++++++++++++++++++ internal/export/inline_test.go | 134 ++++++++++++++ 3 files changed, 460 insertions(+) create mode 100644 internal/export/doc.go create mode 100644 internal/export/inline.go create mode 100644 internal/export/inline_test.go diff --git a/internal/export/doc.go b/internal/export/doc.go new file mode 100644 index 000000000..8f594e0b6 --- /dev/null +++ b/internal/export/doc.go @@ -0,0 +1,7 @@ +// Package export turns a docket artifact (a change record, spec, plan, or results +// file) into a clean Markdown copy an outside reader can use: docket machinery is +// removed, links are reduced to their visible text, and explicit change references +// become the referenced change's title. Every rule is deterministic, and nothing +// inside a fenced code block or an inline code span is ever changed. The package is +// pure: it reads no files and writes none. +package export diff --git a/internal/export/inline.go b/internal/export/inline.go new file mode 100644 index 000000000..714c99954 --- /dev/null +++ b/internal/export/inline.go @@ -0,0 +1,319 @@ +package export + +import ( + "regexp" + "strings" + + "github.com/danielhanold/docket/internal/document" +) + +// Placeholder runes for a masked code span. All three come from the Unicode +// private-use area, so no later rule (links, change references) can match inside +// a placeholder: it holds no ASCII, no digits, and no Markdown punctuation. +const ( + maskOpen = '' + maskClose = '' + maskDigit = '' // maskDigit+0 … maskDigit+15 spell the span index in base 16 +) + +// maskCode replaces every inline code span in line with a placeholder made of +// private-use runes only (no digits, no ASCII), so later rules cannot match inside +// code. restore puts the original spans back byte-for-byte; it accepts any string +// derived from masked, so text around the placeholders may have changed. +// +// A code span follows CommonMark: a run of N backticks opens it and the next run +// of exactly N backticks closes it. A backslash-escaped backtick outside a span +// opens nothing, and a run with no matching closer stays plain text. +func maskCode(line string) (masked string, restore func(string) string) { + var spans []string + var b strings.Builder + i := 0 + for i < len(line) { + c := line[i] + if c == '\\' && i+1 < len(line) { + b.WriteString(line[i : i+2]) + i += 2 + continue + } + if c != '`' { + b.WriteByte(c) + i++ + continue + } + n := backtickRun(line, i) + end := closingRun(line, i+n, n) + if end < 0 { + b.WriteString(line[i : i+n]) + i += n + continue + } + b.WriteString(placeholder(len(spans))) + spans = append(spans, line[i:end]) + i = end + } + if len(spans) == 0 { + return line, func(s string) string { return s } + } + restore = func(s string) string { + for idx, span := range spans { + s = strings.ReplaceAll(s, placeholder(idx), span) + } + return s + } + return b.String(), restore +} + +// backtickRun returns the length of the backtick run starting at i. +func backtickRun(s string, i int) int { + n := 0 + for i+n < len(s) && s[i+n] == '`' { + n++ + } + return n +} + +// closingRun returns the index just past the first run of exactly n backticks at +// or after from, or -1 when there is none. +func closingRun(s string, from, n int) int { + for j := from; j < len(s); { + if s[j] != '`' { + j++ + continue + } + m := backtickRun(s, j) + if m == n { + return j + m + } + j += m + } + return -1 +} + +// placeholder spells span index idx as private-use runes. +func placeholder(idx int) string { + var digits []rune + for { + digits = append([]rune{maskDigit + rune(idx%16)}, digits...) + idx /= 16 + if idx == 0 { + break + } + } + return string(maskOpen) + string(digits) + string(maskClose) +} + +// linkDefRE matches a CommonMark link-reference definition: up to three spaces of +// indent, a bracketed label, a colon, a destination (angle-bracketed or bare), and +// an optional quoted or parenthesized title that ends the line. A label starting +// with "^" is a footnote, not a link, and is left alone. +var linkDefRE = regexp.MustCompile(`^ {0,3}\[((?:[^\[\]\\]|\\.)+)\]:[ \t]*(?:<[^<>\n]*>|[^\s<]\S*)(?:[ \t]+(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|\((?:[^()\\]|\\.)*\)))?[ \t]*$`) + +// isLinkDefinition reports a CommonMark link-reference definition line ("[ref]: url ..."). +func isLinkDefinition(line string) bool { + _, ok := definitionLabel(line) + return ok +} + +// definitionLabel returns the normalized label of a link-reference definition line. +func definitionLabel(line string) (string, bool) { + m := linkDefRE.FindStringSubmatch(strings.TrimRight(line, "\r\n")) + if m == nil || strings.HasPrefix(m[1], "^") { + return "", false + } + label := normalizeLabel(m[1]) + if label == "" { + return "", false + } + return label, true +} + +// normalizeLabel lower-cases a link label and collapses its whitespace, the way +// CommonMark matches a reference to its definition. +func normalizeLabel(s string) string { + return strings.ToLower(strings.Join(strings.Fields(s), " ")) +} + +// linkLabels collects the normalized (lower-cased, whitespace-collapsed) labels of every +// link-reference definition line outside fences. +func linkLabels(lines []string, info []document.LineInfo) map[string]bool { + labels := map[string]bool{} + for i, line := range lines { + if i < len(info) && (info[i].Kind == document.LineFence || info[i].Kind == document.LineFrontmatter) { + continue + } + if label, ok := definitionLabel(line); ok { + labels[label] = true + } + } + return labels +} + +var ( + // autolinkRE is a CommonMark autolink: <scheme:target>, a 2–32 character + // scheme, and no spaces or angle brackets in the target. + autolinkRE = regexp.MustCompile(`^<([A-Za-z][A-Za-z0-9+.\-]{1,31}:[^\s<>]*)>`) + // anchorRE is an HTML anchor element on one line. + anchorRE = regexp.MustCompile(`(?i)^<a(?:\s[^>]*)?>(.*?)</a\s*>`) +) + +// stripLinks removes every link form from a masked line and keeps its visible text: +// inline links and images, reference-style links and images whose label is in +// labels, autolinks, and HTML anchors. An image with empty alt text is removed. +// A bare URL is not link syntax and stays. +func stripLinks(masked string, labels map[string]bool) string { + var b strings.Builder + i := 0 + for i < len(masked) { + c := masked[i] + switch { + case c == '\\' && i+1 < len(masked): + b.WriteString(masked[i : i+2]) + i += 2 + continue + case c == '<': + if m := autolinkRE.FindStringSubmatch(masked[i:]); m != nil { + b.WriteString(m[1]) + i += len(m[0]) + continue + } + if m := anchorRE.FindStringSubmatch(masked[i:]); m != nil { + b.WriteString(stripLinks(m[1], labels)) + i += len(m[0]) + continue + } + case c == '[' || (c == '!' && i+1 < len(masked) && masked[i+1] == '['): + if text, end, ok := parseLink(masked, i, labels); ok { + b.WriteString(stripLinks(text, labels)) + i = end + continue + } + } + b.WriteByte(c) + i++ + } + return b.String() +} + +// parseLink parses a link or image starting at s[i] ("[" or "!["). It returns the +// visible text, the index just past the link, and whether s[i:] is a link at all. +func parseLink(s string, i int, labels map[string]bool) (text string, end int, ok bool) { + open := i + if s[i] == '!' { + open++ + } + closeIdx := matchBracket(s, open) + if closeIdx < 0 { + return "", 0, false + } + text = s[open+1 : closeIdx] + after := closeIdx + 1 + if after < len(s) && s[after] == '(' { + if end, ok := parseInlineTail(s, after); ok { + return text, end, true + } + } + if after < len(s) && s[after] == '[' { + refClose := matchBracket(s, after) + if refClose >= 0 { + ref := s[after+1 : refClose] + if ref == "" { + ref = text + } + if labels[normalizeLabel(ref)] { + return text, refClose + 1, true + } + // A full or collapsed reference with no definition is not a link, and + // its first bracket is not a shortcut either. + return "", 0, false + } + } + if labels[normalizeLabel(text)] && normalizeLabel(text) != "" { + return text, after, true + } + return "", 0, false +} + +// matchBracket returns the index of the "]" that closes the "[" at s[open], +// honoring nesting and backslash escapes, or -1. +func matchBracket(s string, open int) int { + depth := 0 + for j := open; j < len(s); j++ { + switch s[j] { + case '\\': + j++ + case '[': + depth++ + case ']': + depth-- + if depth == 0 { + return j + } + } + } + return -1 +} + +// parseInlineTail parses an inline link's "(destination "title")" starting at the +// "(" at s[i], and returns the index just past its ")". The destination is either +// angle-bracketed or a run of non-space characters with balanced parentheses; the +// title is "…", '…', or (…). +func parseInlineTail(s string, i int) (int, bool) { + j := skipSpace(s, i+1) + if j < len(s) && s[j] == '<' { + k := strings.IndexAny(s[j+1:], "<>") + if k < 0 || s[j+1+k] != '>' { + return 0, false + } + j += k + 2 + } else { + depth := 0 + dest: + for ; j < len(s); j++ { + switch c := s[j]; { + case c == '\\': + j++ + case c == ' ' || c == '\t': + break dest + case c == '(': + depth++ + case c == ')': + if depth == 0 { + break dest + } + depth-- + } + } + if depth != 0 { + return 0, false + } + } + k := skipSpace(s, j) + if k < len(s) && k > j && (s[k] == '"' || s[k] == '\'' || s[k] == '(') { + closer := s[k] + if closer == '(' { + closer = ')' + } + m := k + 1 + for ; m < len(s) && s[m] != closer; m++ { + if s[m] == '\\' { + m++ + } + } + if m >= len(s) { + return 0, false + } + k = skipSpace(s, m+1) + } + if k < len(s) && s[k] == ')' { + return k + 1, true + } + return 0, false +} + +// skipSpace returns the first index at or after i that is not a space or tab. +func skipSpace(s string, i int) int { + for i < len(s) && (s[i] == ' ' || s[i] == '\t') { + i++ + } + return i +} diff --git a/internal/export/inline_test.go b/internal/export/inline_test.go new file mode 100644 index 000000000..f64b62311 --- /dev/null +++ b/internal/export/inline_test.go @@ -0,0 +1,134 @@ +package export + +import ( + "strings" + "testing" + "unicode" + + "github.com/danielhanold/docket/internal/document" +) + +func TestMaskCode(t *testing.T) { + cases := []struct { + name string + in string + spans []string // the code spans that must be hidden from the masked string + }{ + {"single", "a `x [y](z)` b", []string{"`x [y](z)`"}}, + {"double backtick", "a `` a ` b `` c", []string{"`` a ` b ``"}}, + {"two spans", "`change 0559` and `#12`", []string{"`change 0559`", "`#12`"}}, + {"escaped backtick", "a \\` b [x](y)", nil}, + {"unmatched run", "a `` b ` c", nil}, + {"no code", "plain [x](y) text", nil}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + masked, restore := maskCode(tc.in) + for _, span := range tc.spans { + if strings.Contains(masked, span) { + t.Errorf("masked %q still contains span %q", masked, span) + } + } + if len(tc.spans) == 0 && masked != tc.in { + t.Errorf("masked = %q, want input unchanged", masked) + } + if got := restore(masked); got != tc.in { + t.Errorf("restore(masked) = %q, want %q", got, tc.in) + } + }) + } + + // The placeholder for a span is private-use runes only: no ASCII, no digits. + masked, _ := maskCode("a `x [y](z) 0559` b") + inner := strings.TrimSuffix(strings.TrimPrefix(masked, "a "), " b") + if inner == "" { + t.Fatalf("masked %q left no placeholder", masked) + } + for _, r := range inner { + if !unicode.Is(unicode.Co, r) { + t.Errorf("placeholder rune %U is not private-use (masked %q)", r, masked) + } + } +} + +func TestStripLinks(t *testing.T) { + labels := map[string]bool{"ref": true, "text": true, "a b": true} + cases := []struct{ in, want string }{ + {"[Run Modes](https://cursor.com/docs/x)", "Run Modes"}, + {"[PR 265](https://github.com/o/r/pull/265)", "PR 265"}, + {"[#559](../changes/archive/x.md)", "#559"}, + {"[text](#anchor)", "text"}, + {"[m](mailto:a@b.c)", "m"}, + {"[Foo](https://en.wikipedia.org/wiki/Foo_(bar)) end", "Foo end"}, + {"[a](u \"t\")", "a"}, + {"[a](u 't') and [b](<u v> (t))", "a and b"}, + {"<https://go.dev/x>", "https://go.dev/x"}, + {"![alt](p.png)", "alt"}, + {"![](p.png) x", " x"}, + {"[![badge](b.svg)](https://x)", "badge"}, + {"[text][ref]", "text"}, + {"[text][]", "text"}, + {"[ref]", "ref"}, + {"see [A B] here", "see A B here"}, + {"[note]", "[note]"}, + {"[text][missing]", "[text][missing]"}, + {"<a href=\"https://x\">text</a>", "text"}, + {"see https://go.dev/doc/toolchain", "see https://go.dev/doc/toolchain"}, + {"<!-- docket:x:start -->", "<!-- docket:x:start -->"}, + {"a \\[x](y) b", "a \\[x](y) b"}, + {"[unclosed](https://x", "[unclosed](https://x"}, + {"x < y and a <b> tag", "x < y and a <b> tag"}, + {"two [a](1) and [b](2).", "two a and b."}, + } + for _, tc := range cases { + if got := stripLinks(tc.in, labels); got != tc.want { + t.Errorf("stripLinks(%q) = %q, want %q", tc.in, got, tc.want) + } + } + + // A link wrapping a code span: the link goes, the code span stays. + in := "[`internal/app/open.go`](../x)" + masked, restore := maskCode(in) + if got, want := restore(stripLinks(masked, nil)), "`internal/app/open.go`"; got != want { + t.Errorf("code-wrapping link = %q, want %q", got, want) + } + // Link syntax inside a code span is untouched. + in = "keep `[x](y)` and drop [z](w)" + masked, restore = maskCode(in) + if got, want := restore(stripLinks(masked, nil)), "keep `[x](y)` and drop z"; got != want { + t.Errorf("code-span link = %q, want %q", got, want) + } +} + +func TestIsLinkDefinition(t *testing.T) { + cases := []struct { + in string + want bool + }{ + {"[ref]: https://x", true}, + {" [a b]: <u> \"t\"", true}, + {"[ref]: u 'title'", true}, + {"[ref]: u (title)", true}, + {"[ref] text", false}, + {" [ref]: u", false}, + {"[ref]:", false}, + {"[ref]: u trailing words", false}, + {"[^1]: a footnote", false}, + {"[ ]: u", false}, + } + for _, tc := range cases { + if got := isLinkDefinition(tc.in); got != tc.want { + t.Errorf("isLinkDefinition(%q) = %v, want %v", tc.in, got, tc.want) + } + } +} + +func TestLinkLabels(t *testing.T) { + src := "---\n[fm]: u\n---\n[Ref One]: https://x\n```\n[code]: u\n```\ntext\n" + info := document.ClassifyLines([]byte(src)) + lines := strings.Split(strings.TrimSuffix(src, "\n"), "\n") + got := linkLabels(lines, info) + if !got["ref one"] || len(got) != 1 { + t.Errorf("linkLabels = %v, want only {ref one}", got) + } +} From 7bf31bb8d43c55ea6d66bc5985c998becb8ab347 Mon Sep 17 00:00:00 2001 From: Daniel Hanold <danny@danielhanold.com> Date: Tue, 20 Oct 2026 09:43:16 -0400 Subject: [PATCH 04/12] feat(export): convert explicit change references to titles and clean inserted titles --- internal/export/refs.go | 396 +++++++++++++++++++++++++++++++++++ internal/export/refs_test.go | 116 ++++++++++ 2 files changed, 512 insertions(+) create mode 100644 internal/export/refs.go create mode 100644 internal/export/refs_test.go diff --git a/internal/export/refs.go b/internal/export/refs.go new file mode 100644 index 000000000..39aebeb32 --- /dev/null +++ b/internal/export/refs.go @@ -0,0 +1,396 @@ +package export + +import ( + "regexp" + "sort" + "strconv" + "strings" +) + +// Titles maps a known change id to its raw title. An id the snapshot cannot resolve +// to exactly one change is absent, so it reads as unknown. +type Titles map[int]string + +// A change reference is recognized in one of two forms; recognizing a form +// decides nothing on its own, since only a number present in Titles converts. +// +// - Word form: "change" (whole word, any case), whitespace, optional '#', digits. +// The plural "changes" takes a list of such numbers joined by ",", "and", or ", and". +// - Padded form: "#0ddd", or a bare "0ddd" standing as its own word, where the +// surrounding characters rule out paths, filenames, and ADR numbers. +// +// Bare unpadded "#N" and "PR #N" are never forms. +var ( + wordFormRE = regexp.MustCompile(`(?i)\bchange(s?)\s+#?(\d+)`) + listNextRE = regexp.MustCompile(`^(?:\s*,\s*and\s+|\s*,\s*|\s+and\s+)#?(\d+)`) + paddedFormRE = regexp.MustCompile(`#?0\d{3}`) + adrBeforeRE = regexp.MustCompile(`(?i)\bADR[- ]$`) + prBeforeRE = regexp.MustCompile(`\bPR $`) + // otherRefRE matches a reference token that is not a form: it may share a + // references-only parenthesis with forms, and it always stays as written. + otherRefRE = regexp.MustCompile(`^(?:PR #\d+|#\d+|(?i:ADR)[- ]\d+(?:'s)?)`) + // refSepRE matches the separators allowed between items of a parenthesis. + refSepRE = regexp.MustCompile(`^(?:\s*,\s*and\s+|\s*,\s*|\s+and\s+|\s+)`) +) + +// refItem is one number inside a reference, located by its byte range in the line. +type refItem struct { + start, end int + id int + known bool +} + +// refSpan is one recognized reference: a singular form, or a plural word-form list. +type refSpan struct { + start, end int + items []refItem + plural bool +} + +func (s refSpan) allKnown() bool { + for _, it := range s.items { + if !it.known { + return false + } + } + return true +} + +func (s refSpan) anyKnown() bool { + for _, it := range s.items { + if it.known { + return true + } + } + return false +} + +// findRefs returns every recognized reference in the masked line, in order and +// non-overlapping. Word forms win over the padded numbers they contain. +func findRefs(line string, titles Titles) []refSpan { + item := func(start, end int) refItem { + digits := strings.TrimPrefix(line[start:end], "#") + id, err := strconv.Atoi(digits) + _, ok := titles[id] + return refItem{start: start, end: end, id: id, known: err == nil && ok} + } + var spans []refSpan + for _, m := range wordFormRE.FindAllStringSubmatchIndex(line, -1) { + numStart := m[4] + if line[numStart-1] == '#' { + numStart-- + } + if !numberEnds(line, m[5]) { + continue + } + span := refSpan{start: m[0], end: m[1], items: []refItem{item(numStart, m[5])}, plural: m[3] > m[2]} + if span.plural { + for { + next := listNextRE.FindStringSubmatchIndex(line[span.end:]) + if next == nil || !numberEnds(line, span.end+next[3]) { + break + } + itemStart := span.end + next[2] + if line[itemStart-1] == '#' { + itemStart-- + } + span.items = append(span.items, item(itemStart, span.end+next[3])) + span.end += next[1] + } + } + spans = append(spans, span) + } + for _, m := range paddedFormRE.FindAllStringIndex(line, -1) { + start, end := m[0], m[1] + if overlaps(spans, start, end) || !paddedStandsAlone(line, start, end) { + continue + } + spans = append(spans, refSpan{start: start, end: end, items: []refItem{item(start, end)}}) + } + sort.Slice(spans, func(i, j int) bool { return spans[i].start < spans[j].start }) + return spans +} + +// numberEnds reports that the digits ending at end are a whole number, not the +// start of a longer word, path, or decimal. +func numberEnds(line string, end int) bool { + if end >= len(line) { + return true + } + c := line[end] + if isWordByte(c) { + return false + } + return !(c == '.' && end+1 < len(line) && isAlnum(line[end+1])) +} + +// paddedStandsAlone applies the padded form's boundary rules. +func paddedStandsAlone(line string, start, end int) bool { + if start > 0 && strings.ContainsRune("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_/.#-", rune(line[start-1])) { + return false + } + if end < len(line) { + c := line[end] + if isAlnum(c) || c == '_' || c == '/' || c == '-' { + return false + } + if c == '.' && end+1 < len(line) && isAlnum(line[end+1]) { + return false + } + } + before := line[:start] + return !adrBeforeRE.MatchString(before) && !prBeforeRE.MatchString(before) +} + +func overlaps(spans []refSpan, start, end int) bool { + for _, s := range spans { + if start < s.end && s.start < end { + return true + } + } + return false +} + +func isAlnum(c byte) bool { + return c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z' || c >= '0' && c <= '9' +} + +func isWordByte(c byte) bool { return isAlnum(c) || c == '_' } + +// refEdit replaces line[start:end] with text. +type refEdit struct { + start, end int + text string +} + +func applyEdits(line string, edits []refEdit) string { + sort.Slice(edits, func(i, j int) bool { return edits[i].start < edits[j].start }) + var b strings.Builder + pos := 0 + for _, e := range edits { + b.WriteString(line[pos:e.start]) + b.WriteString(e.text) + pos = e.end + } + b.WriteString(line[pos:]) + return b.String() +} + +// parenEdits applies the references-only parenthesis reading: a parenthesis whose +// whole content is reference items, at least one of them a fully convertible +// form, loses its convertible items; the rest re-join, and an emptied parenthesis +// goes with the one space before it. render gives a kept span's text. The spans +// it consumed are reported so no other reading touches them. +func parenEdits(line string, spans []refSpan, render func(refSpan) string) (edits []refEdit, consumed map[int]bool) { + consumed = map[int]bool{} + for open := strings.IndexByte(line, '('); open >= 0; { + closeRel := strings.IndexAny(line[open+1:], "()") + if closeRel < 0 { + break + } + closeAt := open + 1 + closeRel + if line[closeAt] == '(' { + open = closeAt + continue + } + if e, used, ok := parenReading(line, open, closeAt, spans, render); ok { + edits = append(edits, e) + for _, i := range used { + consumed[i] = true + } + } + next := strings.IndexByte(line[closeAt+1:], '(') + if next < 0 { + break + } + open = closeAt + 1 + next + } + return edits, consumed +} + +func parenReading(line string, open, closeAt int, spans []refSpan, render func(refSpan) string) (refEdit, []int, bool) { + type token struct { + text string + drop bool + sepAnd bool // the separator before this token held "and" + spanIdx int + } + var toks []token + var used []int + pos := open + 1 + sepAnd := false + for { + if sep := refSepRE.FindString(line[pos:closeAt]); sep != "" { + sepAnd = strings.Contains(sep, "and") + pos += len(sep) + } + if pos >= closeAt { + break + } + idx := -1 + for i, s := range spans { + if s.start == pos && s.end <= closeAt { + idx = i + break + } + } + switch { + case idx >= 0: + s := spans[idx] + toks = append(toks, token{text: render(s), drop: s.allKnown(), sepAnd: sepAnd, spanIdx: idx}) + used = append(used, idx) + pos = s.end + default: + m := otherRefRE.FindString(line[pos:closeAt]) + if m == "" { + return refEdit{}, nil, false + } + toks = append(toks, token{text: m, sepAnd: sepAnd, spanIdx: -1}) + pos += len(m) + } + sepAnd = false + } + dropped := false + var kept []token + for _, tk := range toks { + if tk.drop { + dropped = true + } else { + kept = append(kept, tk) + } + } + if !dropped { + return refEdit{}, nil, false + } + if len(kept) == 0 { + start := open + if start > 0 && line[start-1] == ' ' { + start-- + } + return refEdit{start: start, end: closeAt + 1}, used, true + } + lastAnd := toks[len(toks)-1].sepAnd + var b strings.Builder + b.WriteByte('(') + for i, tk := range kept { + switch { + case i == 0: + case i == len(kept)-1 && lastAnd: + b.WriteString(" and ") + default: + b.WriteString(", ") + } + b.WriteString(tk.text) + } + b.WriteByte(')') + return refEdit{start: open, end: closeAt + 1, text: b.String()}, used, true +} + +// convertRefs runs step 6 on one masked line: every recognized form whose number +// is a known change id is removed (references-only parenthesis, own-title dash) +// or replaced by that change's cleaned title in double quotes. +func convertRefs(masked string, titles Titles) string { + spans := findRefs(masked, titles) + if len(spans) == 0 { + return masked + } + quoted := func(id int) string { return `"` + cleanTitle(titles[id], titles) + `"` } + render := func(s refSpan) string { + if !s.anyKnown() { + return masked[s.start:s.end] + } + if s.plural && s.allKnown() { + parts := make([]string, len(s.items)) + for i, it := range s.items { + parts[i] = quoted(it.id) + } + return joinList(parts) + } + if !s.plural { + return quoted(s.items[0].id) + } + var edits []refEdit + for _, it := range s.items { + if it.known { + edits = append(edits, refEdit{start: it.start - s.start, end: it.end - s.start, text: quoted(it.id)}) + } + } + return applyEdits(masked[s.start:s.end], edits) + } + edits, consumed := parenEdits(masked, spans, render) + for i, s := range spans { + if consumed[i] || !s.anyKnown() { + continue + } + if end, ok := ownTitleDash(masked, s, titles); ok { + edits = append(edits, refEdit{start: s.start, end: end}) + continue + } + edits = append(edits, refEdit{start: s.start, end: s.end, text: render(s)}) + } + return applyEdits(masked, edits) +} + +// ownTitleDash reports a singular known reference followed by a spaced dash and +// text that begins with that change's raw title, returning where the dash ends. +func ownTitleDash(line string, s refSpan, titles Titles) (int, bool) { + if s.plural || len(s.items) != 1 || !s.items[0].known { + return 0, false + } + title := titles[s.items[0].id] + if title == "" { + return 0, false + } + rest := line[s.end:] + for _, dash := range []string{" — ", " – ", " - "} { + if strings.HasPrefix(rest, dash) && strings.HasPrefix(rest[len(dash):], title) { + return s.end + len(dash), true + } + } + return 0, false +} + +// joinList joins parts as `A, B and C`. +func joinList(parts []string) string { + if len(parts) == 1 { + return parts[0] + } + return strings.Join(parts[:len(parts)-1], ", ") + " and " + parts[len(parts)-1] +} + +// cleanTitle makes the one pass every inserted title gets: a references-only +// parenthesis of convertible forms is removed, any other convertible form +// becomes "another issue" ("other issues" for a plural list), "#N" and ADR +// references stay, and double quotes become single quotes. It never looks a +// title up, so it always terminates. Code spans in the title are left alone. +func cleanTitle(title string, titles Titles) string { + masked, restore := maskCode(title) + spans := findRefs(masked, titles) + render := func(s refSpan) string { + if !s.anyKnown() { + return masked[s.start:s.end] + } + if s.plural && s.allKnown() { + return "other issues" + } + if !s.plural { + return "another issue" + } + var edits []refEdit + for _, it := range s.items { + if it.known { + edits = append(edits, refEdit{start: it.start - s.start, end: it.end - s.start, text: "another issue"}) + } + } + return applyEdits(masked[s.start:s.end], edits) + } + edits, consumed := parenEdits(masked, spans, render) + for i, s := range spans { + if consumed[i] || !s.anyKnown() { + continue + } + edits = append(edits, refEdit{start: s.start, end: s.end, text: render(s)}) + } + out := applyEdits(masked, edits) + return restore(strings.ReplaceAll(out, `"`, "'")) +} diff --git a/internal/export/refs_test.go b/internal/export/refs_test.go new file mode 100644 index 000000000..2f799e666 --- /dev/null +++ b/internal/export/refs_test.go @@ -0,0 +1,116 @@ +package export + +import "testing" + +func refsTestTitles() Titles { + return Titles{ + 547: "Measure whether the 1h cache TTL cut implement-next's cost", + 363: "Remove main-mode compatibility from Go v1", + 461: "A", + 550: "B", + 113: "C", + 114: "D", + 120: "E", + 466: "Bring test_go_race back under its 60s row", + 111: "Guard", + 559: "Close a change to done without a PR", + 282: "X", + 88: "Y", + } +} + +func TestConvertRefs(t *testing.T) { + titles := refsTestTitles() + cases := []struct{ in, want string }{ + // Word form, singular, with and without '#'. + {"Change #547 holds the full measurement", `"Measure whether the 1h cache TTL cut implement-next's cost" holds the full measurement`}, + {"from change 0363 forbids it", `from "Remove main-mode compatibility from Go v1" forbids it`}, + {"see change 559 here", `see "Close a change to done without a PR" here`}, + // Plural lists. + {"changes #461 and #550", `"A" and "B"`}, + {"changes 0113, 0114 and 0120", `"C", "D" and "E"`}, + {"changes 0113, 0114, and 0120", `"C", "D" and "E"`}, + {"changes 0113, 9999 and 0120", `changes "C", 9999 and "E"`}, + // References-only parenthesis. + {"fields (0461, 0550)", "fields"}, + {"fields (0461, 0550) stay", "fields stay"}, + {"(0461, ADR-0012)", "(ADR-0012)"}, + {"(0461, #12 and ADR-0012)", "(#12 and ADR-0012)"}, + {"(#461, ADR-0012)", "(#461, ADR-0012)"}, + {"It landed (0559) today.", "It landed today."}, + {"(see change 0547)", `(see "Measure whether the 1h cache TTL cut implement-next's cost")`}, + // Own-title dash. + {"# Change 0466 — Bring test_go_race back under its 60s row budget", "# Bring test_go_race back under its 60s row budget"}, + {"# Change 0466 - Bring test_go_race back under its 60s row", "# Bring test_go_race back under its 60s row"}, + {"# Change 0466 — Something else", `# "Bring test_go_race back under its 60s row" — Something else`}, + // Padded form standing as its own word. + {"the 0111 guard", `the "Guard" guard`}, + {"0282's", `"X"'s`}, + {"mirroring 0088", `mirroring "Y"`}, + {"#0559", `"Close a change to done without a PR"`}, + {"done in 0559.", `done in "Close a change to done without a PR".`}, + // Left exactly as written. + {"#559", "#559"}, + {"PR #559", "PR #559"}, + {"PR #0559", "PR #0559"}, + {"ADR-0147", "ADR-0147"}, + {"ADR 0147", "ADR 0147"}, + {"adr 0559", "adr 0559"}, + {"ADR-0065's", "ADR-0065's"}, + {"change 9999", "change 9999"}, + {"0561-export.md", "0561-export.md"}, + {"docs/0561", "docs/0561"}, + {"0559.md", "0559.md"}, + {"v0559", "v0559"}, + {"change 3 files", "change 3 files"}, + {"exchange 559", "exchange 559"}, + {"0999 unknown", "0999 unknown"}, + {"12345 and 559", "12345 and 559"}, + } + for _, tc := range cases { + if got := convertRefs(tc.in, titles); got != tc.want { + t.Errorf("convertRefs(%q)\n got %q\nwant %q", tc.in, got, tc.want) + } + } +} + +func TestConvertRefsLeavesMaskedCode(t *testing.T) { + titles := refsTestTitles() + in := "a `change 0559` and change 0559" + masked, restore := maskCode(in) + got := restore(convertRefs(masked, titles)) + want := "a `change 0559` and \"Close a change to done without a PR\"" + if got != want { + t.Errorf("got %q, want %q", got, want) + } +} + +func TestCleanTitle(t *testing.T) { + titles := refsTestTitles() + titles[700] = "Rework change 0700 itself" + cases := []struct{ in, want string }{ + {"Clear the unfixed review findings from change 0113", "Clear the unfixed review findings from another issue"}, + {`Fix "quoted" bits (0461, 0550)`, "Fix 'quoted' bits"}, + {"Split changes 0113 and 0114", "Split other issues"}, + {"Follow #559 and ADR-0012", "Follow #559 and ADR-0012"}, + {"Rework change 0700 itself", "Rework another issue itself"}, + {"Mirror 0088 here", "Mirror another issue here"}, + {"Keep change 9999", "Keep change 9999"}, + } + for _, tc := range cases { + if got := cleanTitle(tc.in, titles); got != tc.want { + t.Errorf("cleanTitle(%q)\n got %q\nwant %q", tc.in, got, tc.want) + } + } +} + +// An inserted title is cleaned once: a reference inside it never pulls in a +// second title, even when the referenced change's own title holds references. +func TestConvertRefsCleansInsertedTitleOnce(t *testing.T) { + titles := Titles{1: "Follow up on change 0002", 2: "Follow up on change 0001"} + got := convertRefs("see change 0001", titles) + want := `see "Follow up on another issue"` + if got != want { + t.Errorf("got %q, want %q", got, want) + } +} From 971164c1096d235e7913150668b7026d7c4bcb9d Mon Sep 17 00:00:00 2001 From: Daniel Hanold <danny@danielhanold.com> Date: Tue, 20 Oct 2026 09:45:57 -0400 Subject: [PATCH 05/12] feat(export): transform an artifact into clean Markdown and name the exported file --- internal/export/export.go | 343 +++++++++++++++++++++++++++++++ internal/export/export_test.go | 230 +++++++++++++++++++++ internal/export/filename.go | 41 ++++ internal/export/filename_test.go | 29 +++ 4 files changed, 643 insertions(+) create mode 100644 internal/export/export.go create mode 100644 internal/export/export_test.go create mode 100644 internal/export/filename.go create mode 100644 internal/export/filename_test.go diff --git a/internal/export/export.go b/internal/export/export.go new file mode 100644 index 000000000..5ce168b25 --- /dev/null +++ b/internal/export/export.go @@ -0,0 +1,343 @@ +package export + +import ( + "regexp" + "strings" + + "github.com/danielhanold/docket/internal/document" +) + +// Kind is the artifact type being exported; its value is the filename's type word. +type Kind string + +const ( + KindIssue Kind = "issue" + KindSpec Kind = "spec" + KindPlan Kind = "plan" + KindResults Kind = "results" +) + +// Input is one artifact to export. +type Input struct { + Kind Kind + Source []byte // the artifact bytes from the metadata checkout + Title string // the change's raw title (the issue H1) + Titles Titles +} + +// Stray is an unpaired or malformed marker line that was removed. Its presence +// means the source is damaged. +type Stray struct { + SourceLine int // 1-based + Text string +} + +// Output is the exported Markdown plus the stray marker lines removed from it. +type Output struct { + Markdown []byte + Stray []Stray +} + +// step names one transform step, so a test can disable it and watch the +// independent check notice. +type step int + +const ( + stepFrontmatter step = iota + 1 + stepBlocks + stepIssueSections + stepStamps + stepLinks + stepRefs + stepCleanup +) + +var allSteps = []step{stepFrontmatter, stepBlocks, stepIssueSections, stepStamps, stepLinks, stepRefs, stepCleanup} + +// issueSections is the allowlist of H2 sections a change record keeps. +var issueSections = map[string]bool{ + "Why": true, + "What changes": true, + "Out of scope": true, + "Open questions": true, +} + +// line is one physical line moving through the pipeline. +type line struct { + text string + kind document.LineKind + name string + src int // 1-based source line +} + +func (l line) fenced() bool { return l.kind == document.LineFence } + +// Transform turns an artifact into clean, docket-free Markdown. It never fails: +// a damaged source loses only its damaged marker lines, which Output.Stray lists. +func Transform(in Input) Output { return transform(in, nil) } + +// transform is Transform with the steps in skip disabled. +func transform(in Input, skip map[step]bool) Output { + src := strings.ReplaceAll(string(in.Source), "\r\n", "\n") + lines := splitLines(src) + var out Output + + if !skip[stepFrontmatter] { + lines = filter(lines, func(l line) bool { return l.kind != document.LineFrontmatter }) + } + if !skip[stepBlocks] { + lines, out.Stray = removeBlocks(lines) + } + if in.Kind == KindIssue && !skip[stepIssueSections] { + lines = keepIssueSections(lines, cleanTitle(in.Title, in.Titles)) + } + if in.Kind == KindSpec && !skip[stepStamps] { + lines = removeStamps(lines) + } + lines = inlineSteps(lines, in.Titles, !skip[stepLinks], !skip[stepRefs]) + if !skip[stepCleanup] { + lines = cleanup(lines) + } + + var b strings.Builder + for _, l := range lines { + b.WriteString(l.text) + b.WriteByte('\n') + } + out.Markdown = []byte(b.String()) + return out +} + +// splitLines tiles src into lines the way document.ClassifyLines does and pairs +// each with its class. +func splitLines(src string) []line { + info := document.ClassifyLines([]byte(src)) + texts := strings.Split(src, "\n") + if strings.HasSuffix(src, "\n") || src == "" { + texts = texts[:len(texts)-1] + } + lines := make([]line, len(texts)) + for i, t := range texts { + lines[i] = line{text: t, src: i + 1} + if i < len(info) { + lines[i].kind, lines[i].name = info[i].Kind, info[i].Name + } + } + return lines +} + +func filter(lines []line, keep func(line) bool) []line { + out := lines[:0:0] + for _, l := range lines { + if keep(l) { + out = append(out, l) + } + } + return out +} + +// removeBlocks is step 2. Markers pair leniently in source order: a start opens a +// block that the next same-name end closes, and the whole block goes. A start that +// meets another start or EOF first, an end with no open start, and a malformed +// marker are each removed alone and reported, so damage never removes content. +func removeBlocks(lines []line) ([]line, []Stray) { + var kept []line + var stray []Stray + for i := 0; i < len(lines); i++ { + l := lines[i] + switch l.kind { + case document.LineMarkerStart: + if end := blockEnd(lines, i); end >= 0 { + i = end + continue + } + stray = append(stray, Stray{SourceLine: l.src, Text: l.text}) + case document.LineMarkerEnd, document.LineMarkerMalformed: + stray = append(stray, Stray{SourceLine: l.src, Text: l.text}) + default: + kept = append(kept, l) + } + } + return kept, stray +} + +// blockEnd returns the index of the end marker closing the start at lines[i], or +// -1 when another start or EOF comes first. +func blockEnd(lines []line, i int) int { + for j := i + 1; j < len(lines); j++ { + switch { + case lines[j].kind == document.LineMarkerStart: + return -1 + case lines[j].kind == document.LineMarkerEnd && lines[j].name == lines[i].name: + return j + } + } + return -1 +} + +func isH2(l line) bool { return !l.fenced() && strings.HasPrefix(l.text, "## ") } + +// keepIssueSections is step 3: only the allowlisted H2 sections stay, in source +// order, under an H1 of the cleaned change title. +func keepIssueSections(lines []line, title string) []line { + out := []line{{text: "# " + title}, {text: ""}} + keep := false + for _, l := range lines { + if isH2(l) { + keep = issueSections[strings.TrimSpace(l.text[len("## "):])] + } + if keep { + out = append(out, l) + } + } + return out +} + +var ( + // stampSentenceRE is a grooming stamp sentence at the start of a line. + stampSentenceRE = regexp.MustCompile(`^Change #?\d+[,.] [Gg]roomed \d{4}-\d{2}-\d{2}(?: \([^)]*\))?\.`) + changeOnlyRE = regexp.MustCompile(`^Change #?\d+\.$`) + boldChangeRE = regexp.MustCompile(`^\*\*Change:\*\* #?\d+$`) + boldPairRE = regexp.MustCompile(`^\*\*[^*]+:\*\* \S.*$`) +) + +// removeStamps is step 4: before the first H2 of a spec, every shape of the +// grooming change stamp goes, and the rest of a stamp sentence's line stays. +func removeStamps(lines []line) []line { + var out []line + for i, l := range lines { + if isH2(l) { + return append(out, lines[i:]...) + } + if l.fenced() { + out = append(out, l) + continue + } + if loc := stampSentenceRE.FindStringIndex(l.text); loc != nil { + l.text = strings.TrimLeft(l.text[loc[1]:], " \t") + } + if changeOnlyRE.MatchString(l.text) || boldChangeRE.MatchString(l.text) || isBoldChangeRun(l.text) { + continue + } + out = append(out, l) + } + return out +} + +// isBoldChangeRun reports a "·"-separated run of **Key:** value pairs that +// includes **Change:**. +func isBoldChangeRun(text string) bool { + parts := strings.Split(text, "·") + if len(parts) < 2 { + return false + } + hasChange := false + for _, p := range parts { + p = strings.TrimSpace(p) + if !boldPairRE.MatchString(p) { + return false + } + if strings.HasPrefix(p, "**Change:**") { + hasChange = true + } + } + return hasChange +} + +// inlineSteps runs steps 5 and 6 on every line outside fences: link-reference +// definitions go, then each line is code-masked, its links are stripped, and its +// change references are converted, before its code spans are restored. +func inlineSteps(lines []line, titles Titles, links, refs bool) []line { + if !links && !refs { + return lines + } + var labels map[string]bool + if links { + texts := make([]string, len(lines)) + info := make([]document.LineInfo, len(lines)) + for i, l := range lines { + texts[i], info[i] = l.text, document.LineInfo{Kind: l.kind, Name: l.name} + } + labels = linkLabels(texts, info) + lines = filter(lines, func(l line) bool { return l.fenced() || !isLinkDefinition(l.text) }) + } + for i, l := range lines { + if l.fenced() { + continue + } + masked, restore := maskCode(l.text) + if links { + masked = stripLinks(masked, labels) + } + if refs { + masked = convertRefs(masked, titles) + } + lines[i].text = restore(masked) + } + return lines +} + +// headingRE is an ATX heading; its first group is the level's run of "#". +var headingRE = regexp.MustCompile(`^ {0,3}(#{1,6})(?:[ \t]|$)`) + +func headingLevel(l line) int { + if l.fenced() { + return 0 + } + if m := headingRE.FindStringSubmatch(l.text); m != nil { + return len(m[1]) + } + return 0 +} + +func blank(l line) bool { return !l.fenced() && strings.TrimSpace(l.text) == "" } + +// cleanup is step 7: headings left with empty sections go (repeated until +// stable, so an emptied parent follows its emptied child), blank-line runs +// collapse to one, and no blank line leads or trails. Fenced lines are content +// and are never collapsed. +func cleanup(lines []line) []line { + for { + drop := map[int]bool{} + for i, l := range lines { + level := headingLevel(l) + if level == 0 { + continue + } + empty := true + for j := i + 1; j < len(lines); j++ { + if next := headingLevel(lines[j]); next > 0 && next <= level { + break + } + if !blank(lines[j]) { + empty = false + break + } + } + if empty { + drop[i] = true + } + } + if len(drop) == 0 { + break + } + var kept []line + for i, l := range lines { + if !drop[i] { + kept = append(kept, l) + } + } + lines = kept + } + var out []line + for _, l := range lines { + if blank(l) && (len(out) == 0 || blank(out[len(out)-1])) { + continue + } + out = append(out, l) + } + for len(out) > 0 && blank(out[len(out)-1]) { + out = out[:len(out)-1] + } + return out +} diff --git a/internal/export/export_test.go b/internal/export/export_test.go new file mode 100644 index 000000000..91ebca64d --- /dev/null +++ b/internal/export/export_test.go @@ -0,0 +1,230 @@ +package export + +import ( + "reflect" + "strings" + "testing" +) + +func assertMarkdown(t *testing.T, got Output, want string) { + t.Helper() + if string(got.Markdown) != want { + t.Fatalf("markdown mismatch\n--- got ---\n%s\n--- want ---\n%s", got.Markdown, want) + } +} + +func TestTransformSpec(t *testing.T) { + src := "<!-- docket:backlink:start (generated — do not hand-edit) -->\n" + + "> ↩ **[Change 0561 — Export](../../changes/active/0561-export.md)**\n" + + "<!-- docket:backlink:end -->\n" + + "\n" + + "# Export design\n" + + "\n" + + "Change #561, groomed 2026-10-20.\n" + + "\n" + + "## Why\n" + + "\n" + + "See [the docs](https://example.com/d) and change 0559.\n" + got := Transform(Input{ + Kind: KindSpec, + Source: []byte(src), + Titles: Titles{559: "Close a change to done without a PR", 561: "Export"}, + }) + assertMarkdown(t, got, "# Export design\n"+ + "\n"+ + "## Why\n"+ + "\n"+ + "See the docs and \"Close a change to done without a PR\".\n") + if len(got.Stray) != 0 { + t.Fatalf("Stray = %v, want none", got.Stray) + } +} + +func TestTransformSpecStampKeepsRest(t *testing.T) { + src := "# T\n" + + "\n" + + "Change #12, groomed 2026-01-02. Found while building change #13 (PR #14).\n" + + "\n" + + "Change 0373. Groomed 2026-09-02 (interactive). Priority high: x\n" + + "\n" + + "**Change:** 0003\n" + + "\n" + + "**Change:** 5 · **Type:** feat · **Priority:** high\n" + + "\n" + + "Change 12.\n" + + "\n" + + "## Body\n" + + "\n" + + "Change 12.\n" + got := Transform(Input{ + Kind: KindSpec, + Source: []byte(src), + Titles: Titles{12: "Twelve", 13: "Thirteen", 373: "Three seven three", 3: "Three", 5: "Five"}, + }) + assertMarkdown(t, got, "# T\n"+ + "\n"+ + "Found while building \"Thirteen\" (PR #14).\n"+ + "\n"+ + "Priority high: x\n"+ + "\n"+ + "## Body\n"+ + "\n"+ + "\"Twelve\".\n") +} + +func TestTransformSpecStampOnlyBeforeFirstH2(t *testing.T) { + // A non-spec artifact never loses a stamp-shaped line; it converts instead. + src := "# T\n\nChange 12.\n" + got := Transform(Input{Kind: KindPlan, Source: []byte(src), Titles: Titles{12: "Twelve"}}) + assertMarkdown(t, got, "# T\n\n\"Twelve\".\n") +} + +const issueFixture = "---\n" + + "id: 7\n" + + "title: Seven\n" + + "---\n" + + "\n" + + "# Preamble heading\n" + + "\n" + + "## Artifacts\n" + + "\n" + + "<!-- docket:artifacts:start -->\n" + + "| a | [b](x.md) |\n" + + "<!-- docket:artifacts:end -->\n" + + "\n" + + "## Why\n" + + "\n" + + "Because of change 0008.\n" + + "\n" + + "## What changes\n" + + "\n" + + "Things.\n" + + "\n" + + "## Reconcile log\n" + + "\n" + + "- log\n" + + "\n" + + "## Why deferred\n" + + "\n" + + "Later.\n" + + "\n" + + "## Out of scope\n" + + "\n" + + "None.\n" + +const issueWant = "# Seven\n" + + "\n" + + "## Why\n" + + "\n" + + "Because of \"Eight\".\n" + + "\n" + + "## What changes\n" + + "\n" + + "Things.\n" + + "\n" + + "## Out of scope\n" + + "\n" + + "None.\n" + +func TestTransformIssue(t *testing.T) { + got := Transform(Input{ + Kind: KindIssue, + Source: []byte(issueFixture), + Title: "Seven (0008)", + Titles: Titles{8: "Eight"}, + }) + assertMarkdown(t, got, issueWant) +} + +func TestTransformNormalizesCRLF(t *testing.T) { + crlf := strings.ReplaceAll(issueFixture, "\n", "\r\n") + got := Transform(Input{ + Kind: KindIssue, + Source: []byte(crlf), + Title: "Seven (0008)", + Titles: Titles{8: "Eight"}, + }) + assertMarkdown(t, got, issueWant) + if strings.Contains(string(got.Markdown), "\r") { + t.Fatalf("output still holds a carriage return: %q", got.Markdown) + } +} + +func TestTransformDamagedSourceKeepsContent(t *testing.T) { + cases := []struct { + name string + src string + want string + stray []Stray + }{ + { + name: "start with no end", + src: "# T\n\n<!-- docket:build-evidence:start -->\n\nLater prose.\n\n## More\n\nStill here.\n", + want: "# T\n\nLater prose.\n\n## More\n\nStill here.\n", + stray: []Stray{{SourceLine: 3, Text: "<!-- docket:build-evidence:start -->"}}, + }, + { + name: "end with no start", + src: "# T\n\nBefore.\n<!-- docket:build-evidence:end -->\nAfter.\n", + want: "# T\n\nBefore.\nAfter.\n", + stray: []Stray{{SourceLine: 4, Text: "<!-- docket:build-evidence:end -->"}}, + }, + { + name: "start closed only after another start", + src: "# T\n<!-- docket:a:start -->\nkept\n<!-- docket:b:start -->\ngone\n<!-- docket:b:end -->\n" + + "<!-- docket:Bad -->\ntail\n", + want: "# T\nkept\ntail\n", + stray: []Stray{ + {SourceLine: 2, Text: "<!-- docket:a:start -->"}, + {SourceLine: 7, Text: "<!-- docket:Bad -->"}, + }, + }, + { + name: "unclosed frontmatter opener", + src: "---\ntitle: x\n\nBody text.\n", + want: "---\ntitle: x\n\nBody text.\n", + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got := Transform(Input{Kind: KindPlan, Source: []byte(tc.src)}) + assertMarkdown(t, got, tc.want) + if !reflect.DeepEqual(got.Stray, tc.stray) { + t.Fatalf("Stray = %#v, want %#v", got.Stray, tc.stray) + } + }) + } +} + +func TestTransformFenceHeadingsAreContent(t *testing.T) { + fence := "```text\n" + + "## Reconcile log\n" + + "`change 0559`\n" + + "[x](y)\n" + + "\n" + + "\n" + + "<!-- docket:x:start -->\n" + + "```\n" + src := "---\ntitle: T\n---\n\n## Why\n\n" + fence + "\nMore.\n\n## Reconcile log\n\n- gone\n" + got := Transform(Input{Kind: KindIssue, Source: []byte(src), Title: "T", Titles: Titles{559: "Z"}}) + assertMarkdown(t, got, "# T\n\n## Why\n\n"+fence+"\nMore.\n") +} + +func TestTransformCleanup(t *testing.T) { + src := "\n\n# T\n\n## Artifacts\n\n\n\n## Body\n\nText\n\n\n\nMore\n\n" + + "## A\n\n### B\n\n## C\n\nx\n\n\n" + got := Transform(Input{Kind: KindPlan, Source: []byte(src)}) + assertMarkdown(t, got, "# T\n\n## Body\n\nText\n\nMore\n\n## C\n\nx\n") +} + +func TestTransformSkipStepKeepsItsMachinery(t *testing.T) { + // The unexported skip set lets the corpus mutation guard disable one step. + src := "<!-- docket:a:start -->\nx\n<!-- docket:a:end -->\n# T\n" + got := transform(Input{Kind: KindPlan, Source: []byte(src)}, map[step]bool{stepBlocks: true}) + if !strings.Contains(string(got.Markdown), "docket:a:start") { + t.Fatalf("skipping stepBlocks still removed the block: %q", got.Markdown) + } + if len(allSteps) != 7 { + t.Fatalf("allSteps has %d steps, want 7", len(allSteps)) + } +} diff --git a/internal/export/filename.go b/internal/export/filename.go new file mode 100644 index 000000000..8defe6827 --- /dev/null +++ b/internal/export/filename.go @@ -0,0 +1,41 @@ +package export + +import ( + "path/filepath" + "regexp" + "strings" +) + +// leadingDateRE splits a basename stem into its leading YYYY-MM-DD date and the rest. +var leadingDateRE = regexp.MustCompile(`^(\d{4}-\d{2}-\d{2})-(.+)$`) + +// FileName returns the exported file's name, <date>-<type>-<name>.md. +// +// For a change record (KindIssue) the date is created and the name is slug. For a +// spec, plan, or results artifact the date is the source basename's leading +// YYYY-MM-DD and the name is the rest of the stem; a stem with no leading date +// takes created and keeps the whole stem. A spec's trailing "-design" and a +// results file's trailing "-results" are dropped, since the type word carries +// them. created is "YYYY-MM-DD" or ""; with no date at all the name starts with +// the type word. +func FileName(kind Kind, sourcePath, created, slug string) string { + date, name := created, slug + if kind != KindIssue { + base := filepath.Base(sourcePath) + name = strings.TrimSuffix(base, filepath.Ext(base)) + if m := leadingDateRE.FindStringSubmatch(name); m != nil { + date, name = m[1], m[2] + } + switch kind { + case KindSpec: + name = strings.TrimSuffix(name, "-design") + case KindResults: + name = strings.TrimSuffix(name, "-results") + } + } + out := string(kind) + "-" + name + ".md" + if date != "" { + out = date + "-" + out + } + return out +} diff --git a/internal/export/filename_test.go b/internal/export/filename_test.go new file mode 100644 index 000000000..1fddd03da --- /dev/null +++ b/internal/export/filename_test.go @@ -0,0 +1,29 @@ +package export + +import "testing" + +func TestFileName(t *testing.T) { + cases := []struct { + kind Kind + source, created, s string + want string + }{ + {KindSpec, "docs/superpowers/specs/2026-10-17-close-a-change-to-done-without-a-pr-design.md", "2026-10-17", "close-a-change-to-done-without-a-pr", + "2026-10-17-spec-close-a-change-to-done-without-a-pr.md"}, + {KindPlan, "docs/superpowers/plans/2026-10-17-close-a-change-to-done-without-a-pr.md", "2026-10-17", "close-a-change-to-done-without-a-pr", + "2026-10-17-plan-close-a-change-to-done-without-a-pr.md"}, + {KindResults, "docs/superpowers/results/2026-10-17-close-a-change-to-done-without-a-pr-results.md", "2026-10-17", "close-a-change-to-done-without-a-pr", + "2026-10-17-results-close-a-change-to-done-without-a-pr.md"}, + {KindIssue, "docs/changes/archive/2026-10-17-0559-close-a-change-to-done-without-a-pr.md", "2026-10-17", "close-a-change-to-done-without-a-pr", + "2026-10-17-issue-close-a-change-to-done-without-a-pr.md"}, + {KindSpec, "docs/foo-design.md", "2026-01-02", "foo", "2026-01-02-spec-foo.md"}, + {KindSpec, "docs/foo-design.md", "", "foo", "spec-foo.md"}, + {KindPlan, "docs/2026-10-17-design-notes-design.md", "2026-01-02", "x", "2026-10-17-plan-design-notes-design.md"}, + {KindIssue, "docs/changes/active/0559-x.md", "", "x", "issue-x.md"}, + } + for _, tc := range cases { + if got := FileName(tc.kind, tc.source, tc.created, tc.s); got != tc.want { + t.Errorf("FileName(%s, %q, %q, %q) = %q, want %q", tc.kind, tc.source, tc.created, tc.s, got, tc.want) + } + } +} From 2133e584f92d30db1ec7f9ee7c0c5e55c785a720 Mon Sep 17 00:00:00 2001 From: Daniel Hanold <danny@danielhanold.com> Date: Tue, 20 Oct 2026 09:50:22 -0400 Subject: [PATCH 06/12] feat(exportcheck): independent self-check for export leftovers, heading rules, and mentions --- internal/exportcheck/check.go | 628 ++++++++++++++++++++++ internal/exportcheck/check_test.go | 168 ++++++ internal/exportcheck/independence_test.go | 46 ++ 3 files changed, 842 insertions(+) create mode 100644 internal/exportcheck/check.go create mode 100644 internal/exportcheck/check_test.go create mode 100644 internal/exportcheck/independence_test.go diff --git a/internal/exportcheck/check.go b/internal/exportcheck/check.go new file mode 100644 index 000000000..d6b4b0c75 --- /dev/null +++ b/internal/exportcheck/check.go @@ -0,0 +1,628 @@ +// Package exportcheck is the export's self-check: it scans an exported Markdown +// file for docket machinery the export should have removed, and lists the lines +// that mention docket by name. +// +// It is written from the export rules, not from the transform, and it shares no +// code or patterns with it (TestDetectorSharesNothingWithTransform): a detector +// built from the transform's own patterns would agree with it by construction and +// could never find anything. It has its own fence and code-span awareness for the +// same reason. +package exportcheck + +// Rule names a kind of leftover. +const ( + RuleMarker = "marker" + RuleFrontmatter = "frontmatter" + RuleBanner = "banner" + RuleLink = "link" + RuleChangeRef = "change-reference" + RuleStamp = "stamp" + RuleHeading = "heading" +) + +// Leftover is one piece of docket machinery found in the output. +type Leftover struct { + Line int // 1-based output line + Text string // the matched text + Rule string +} + +// Mentions lists the lines, code included, that name docket or dckt as a word. +type Mentions struct { + Count int + Lines []int +} + +// Report is the self-check's result. +type Report struct { + Leftovers []Leftover + Mentions Mentions +} + +// Check scans md. known reports whether a number is a real change id; only a +// change-reference form whose number is known is a leftover, since the export +// leaves unknown numbers as written. +func Check(md []byte, known func(id int) bool) Report { + lines := splitLines(string(md)) + code := fencedLines(lines) + var r Report + + for i, line := range lines { + if containsWord(line, "docket") || containsWord(line, "dckt") { + r.Mentions.Count++ + r.Mentions.Lines = append(r.Mentions.Lines, i+1) + } + } + + seenH2 := false + for i, line := range lines { + if code[i] { + continue + } + n := i + 1 + add := func(rule, text string) { + r.Leftovers = append(r.Leftovers, Leftover{Line: n, Text: text, Rule: rule}) + } + if level, _ := headingLevel(line); level == 2 { + seenH2 = true + } + plain := maskSpans(line) + + if text, ok := findMarker(line, plain); ok { + add(RuleMarker, text) + } + if i == 0 && trimRight(line) == "---" { + add(RuleFrontmatter, "---") + } + if idx := indexOf(plain, "↩"); idx >= 0 { + add(RuleBanner, trimRight(line)) + } + if text, ok := findLink(line, plain); ok { + add(RuleLink, text) + } + if text, ok := findChangeRef(line, plain, known); ok { + add(RuleChangeRef, text) + } + if !seenH2 && isStamp(plain) { + add(RuleStamp, trimRight(line)) + } + } + + r.Leftovers = mergeByLine(r.Leftovers, headingLeftovers(lines, code)) + return r +} + +// splitLines splits on LF, dropping a CR before it and the empty piece after a +// final newline. +func splitLines(s string) []string { + var lines []string + start := 0 + for i := 0; i < len(s); i++ { + if s[i] == '\n' { + lines = append(lines, trimCR(s[start:i])) + start = i + 1 + } + } + if start < len(s) { + lines = append(lines, trimCR(s[start:])) + } + return lines +} + +func trimCR(s string) string { + if len(s) > 0 && s[len(s)-1] == '\r' { + return s[:len(s)-1] + } + return s +} + +func trimRight(s string) string { + end := len(s) + for end > 0 && (s[end-1] == ' ' || s[end-1] == '\t') { + end-- + } + return s[:end] +} + +func indexOf(s, sub string) int { + for i := 0; i+len(sub) <= len(s); i++ { + if s[i:i+len(sub)] == sub { + return i + } + } + return -1 +} + +func isDigit(c byte) bool { return c >= '0' && c <= '9' } +func isLetter(c byte) bool { return c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z' } +func isWord(c byte) bool { return isLetter(c) || isDigit(c) || c == '_' } + +func lower(c byte) byte { + if c >= 'A' && c <= 'Z' { + return c + 'a' - 'A' + } + return c +} + +// hasFoldAt reports s[i:] starting with word, ignoring ASCII case. +func hasFoldAt(s string, i int, word string) bool { + if i < 0 || i+len(word) > len(s) { + return false + } + for j := 0; j < len(word); j++ { + if lower(s[i+j]) != word[j] { + return false + } + } + return true +} + +// containsWord reports word (lower case) in s as a whole word, ignoring case. +func containsWord(s, word string) bool { + for i := 0; i+len(word) <= len(s); i++ { + if hasFoldAt(s, i, word) && (i == 0 || !isWord(s[i-1])) && (i+len(word) == len(s) || !isWord(s[i+len(word)])) { + return true + } + } + return false +} + +// fencedLines marks every line that is a code-fence delimiter or sits inside a +// fenced block. A fence opens with three or more backticks or tildes indented at +// most three spaces, and closes with a run of the same character at least as +// long and nothing after it; an unclosed fence runs to the end. +func fencedLines(lines []string) []bool { + code := make([]bool, len(lines)) + var fenceChar byte + fenceLen := 0 + for i, line := range lines { + indent := 0 + for indent < len(line) && indent < 4 && line[indent] == ' ' { + indent++ + } + run, char := 0, byte(0) + if indent <= 3 && indent < len(line) && (line[indent] == '`' || line[indent] == '~') { + char = line[indent] + for indent+run < len(line) && line[indent+run] == char { + run++ + } + } + rest := line[min(len(line), indent+run):] + if fenceLen == 0 { + if run >= 3 && !(char == '`' && indexOf(rest, "`") >= 0) { + fenceChar, fenceLen = char, run + code[i] = true + } + continue + } + code[i] = true + if char == fenceChar && run >= fenceLen && trimRight(rest) == "" { + fenceLen = 0 + } + } + return code +} + +// maskSpans blanks every inline code span, backticks included, with NUL bytes of +// the same length, so offsets still index the original line. A backslash-escaped +// backtick does not open a span, and a backtick run with no closing run of the +// same length is literal text. +func maskSpans(line string) string { + b := []byte(line) + for i := 0; i < len(b); { + if b[i] == '\\' { + i += 2 + continue + } + if b[i] != '`' { + i++ + continue + } + open := i + for i < len(b) && b[i] == '`' { + i++ + } + n := i - open + closeAt := -1 + for j := i; j < len(b); { + if b[j] != '`' { + j++ + continue + } + k := j + for k < len(b) && b[k] == '`' { + k++ + } + if k-j == n { + closeAt = k + break + } + j = k + } + if closeAt < 0 { + continue + } + for j := open; j < closeAt; j++ { + b[j] = 0 + } + i = closeAt + } + return string(b) +} + +// findMarker finds managed-block marker text: an HTML comment that opens with a +// docket: or dckt: name. +func findMarker(line, plain string) (string, bool) { + for i := 0; i+4 <= len(plain); i++ { + if plain[i:i+4] != "<!--" { + continue + } + j := i + 4 + for j < len(plain) && (plain[j] == ' ' || plain[j] == '\t') { + j++ + } + for _, ns := range []string{"docket:", "dckt:"} { + if j+len(ns) <= len(plain) && plain[j:j+len(ns)] == ns { + end := indexOf(plain[j:], "-->") + if end < 0 { + return line[i:], true + } + return line[i : j+end+3], true + } + } + } + return "", false +} + +// findLink finds any link syntax: an inline link or image ("](" after a bracketed +// text), a full or collapsed reference link ("][" after a bracketed text), a +// link-reference definition line, an autolink "<scheme:…>", or an HTML anchor. +// A shortcut "[text]" alone is not flagged: it is a link only when a definition +// exists, and a definition is itself flagged. +func findLink(line, plain string) (string, bool) { + // Definition: up to three spaces, "[label]:". + indent := 0 + for indent < len(plain) && plain[indent] == ' ' { + indent++ + } + if indent <= 3 && indent < len(plain) && plain[indent] == '[' { + if c := indexOf(plain[indent:], "]"); c > 1 && indent+c+1 < len(plain) && plain[indent+c+1] == ':' { + return trimRight(line), true + } + } + for i := 0; i < len(plain); i++ { + switch plain[i] { + case '[': + c := indexOf(plain[i+1:], "]") + if c < 0 { + continue + } + after := i + 1 + c + 1 + if after < len(plain) && (plain[after] == '(' || plain[after] == '[') { + start := i + if start > 0 && plain[start-1] == '!' { + start-- + } + return line[start : after+1], true + } + case '<': + if text, ok := autolinkAt(line, plain, i); ok { + return text, true + } + if i+2 < len(plain) && lower(plain[i+1]) == 'a' && (plain[i+2] == ' ' || plain[i+2] == '\t' || plain[i+2] == '>') { + return line[i : i+2], true + } + } + } + return "", false +} + +// autolinkAt matches "<scheme:rest>" at i: a letter, then 1–31 letters, digits, +// '+', '.', or '-', a colon, and no space, '<', or '>' before the closing '>'. +func autolinkAt(line, plain string, i int) (string, bool) { + j := i + 1 + if j >= len(plain) || !isLetter(plain[j]) { + return "", false + } + k := j + 1 + for k < len(plain) && (isLetter(plain[k]) || isDigit(plain[k]) || plain[k] == '+' || plain[k] == '.' || plain[k] == '-') { + k++ + } + if n := k - j; n < 2 || n > 32 || k >= len(plain) || plain[k] != ':' { + return "", false + } + for m := k + 1; m < len(plain); m++ { + switch plain[m] { + case '>': + return line[i : m+1], true + case ' ', '\t', '<': + return "", false + } + } + return "", false +} + +// numberAt reads the digits at i and reports where they end, or ok=false when +// none start there. +func numberAt(s string, i int) (id, end int, ok bool) { + end = i + for end < len(s) && isDigit(s[end]) && end-i < 9 { + id = id*10 + int(s[end]-'0') + end++ + } + if end == i || (end < len(s) && isDigit(s[end])) { + return 0, end, false + } + return id, end, true +} + +// wholeNumber reports the number ending at end is not followed by a word +// character or a dot that continues into a word (a filename extension). +func wholeNumber(s string, end int) bool { + if end >= len(s) { + return true + } + if isWord(s[end]) { + return false + } + return !(s[end] == '.' && end+1 < len(s) && (isLetter(s[end+1]) || isDigit(s[end+1]))) +} + +// findChangeRef finds a change-reference form whose number is a known change: +// the word "change"/"changes" with a number (or, for the plural, a list), or a +// zero-padded four-digit id standing as its own word. ADR numbers, "PR #N", bare +// "#N", paths, and filenames are never forms. +func findChangeRef(line, plain string, known func(int) bool) (string, bool) { + if text, ok := findWordRef(line, plain, known); ok { + return text, true + } + return findPaddedRef(line, plain, known) +} + +func findWordRef(line, plain string, known func(int) bool) (string, bool) { + for i := 0; i+6 <= len(plain); i++ { + if !hasFoldAt(plain, i, "change") || (i > 0 && isWord(plain[i-1])) { + continue + } + j := i + 6 + plural := j < len(plain) && lower(plain[j]) == 's' + if plural { + j++ + } + if j < len(plain) && isWord(plain[j]) { + continue + } + ws := j + for j < len(plain) && (plain[j] == ' ' || plain[j] == '\t') { + j++ + } + if j == ws { + continue + } + if j < len(plain) && plain[j] == '#' { + j++ + } + id, end, ok := numberAt(plain, j) + if !ok || !wholeNumber(plain, end) { + continue + } + hit := known(id) + for plural { + k, sep := end, false + for k < len(plain) && plain[k] == ' ' { + k++ + } + if k < len(plain) && plain[k] == ',' { + sep = true + k++ + for k < len(plain) && plain[k] == ' ' { + k++ + } + } + if hasFoldAt(plain, k, "and ") { + sep = true + k += 4 + for k < len(plain) && plain[k] == ' ' { + k++ + } + } + if !sep { + break + } + if k < len(plain) && plain[k] == '#' { + k++ + } + next, nend, ok := numberAt(plain, k) + if !ok || !wholeNumber(plain, nend) { + break + } + hit = hit || known(next) + end = nend + } + if hit { + return line[i:end], true + } + } + return "", false +} + +func findPaddedRef(line, plain string, known func(int) bool) (string, bool) { + for i := 0; i+4 <= len(plain); i++ { + if plain[i] != '0' || (i > 0 && isDigit(plain[i-1])) { + continue + } + id, end, ok := numberAt(plain, i) + if !ok || end-i != 4 { + continue + } + start := i + if start > 0 && plain[start-1] == '#' { + start-- + } + if start > 0 { + p := plain[start-1] + if isWord(p) || p == '/' || p == '.' || p == '#' || p == '-' { + continue + } + } + if end < len(plain) { + c := plain[end] + if isWord(c) || c == '/' || c == '-' { + continue + } + if c == '.' && end+1 < len(plain) && (isLetter(plain[end+1]) || isDigit(plain[end+1])) { + continue + } + } + if afterADR(plain, start) || afterPR(plain, start) { + continue + } + if known(id) { + return line[start:end], true + } + } + return "", false +} + +// afterADR reports "ADR " or "ADR-" (any case, whole word) right before at. +func afterADR(s string, at int) bool { + i := at - 4 + return i >= 0 && hasFoldAt(s, i, "adr") && (s[at-1] == ' ' || s[at-1] == '-') && (i == 0 || !isWord(s[i-1])) +} + +// afterPR reports "PR " (whole word) right before at. +func afterPR(s string, at int) bool { + i := at - 3 + return i >= 0 && s[i:at] == "PR " && (i == 0 || !isWord(s[i-1])) +} + +// isStamp reports a grooming change stamp: "Change N, groomed YYYY-MM-DD…", +// "Change N. Groomed YYYY-MM-DD…", a line that is only "Change N.", or a line +// opening with a bold "**Change:** N" field. +func isStamp(plain string) bool { + s := trimRight(plain) + if hasPrefix(s, "**Change:** ") { + k := len("**Change:** ") + if k < len(s) && s[k] == '#' { + k++ + } + _, _, ok := numberAt(s, k) + return ok + } + if !hasPrefix(s, "Change ") { + return false + } + k := len("Change ") + if k < len(s) && s[k] == '#' { + k++ + } + _, end, ok := numberAt(s, k) + if !ok || end >= len(s) || (s[end] != ',' && s[end] != '.') { + return false + } + rest := s[end+1:] + if rest == "" { + return s[end] == '.' + } + if !hasPrefix(rest, " groomed ") && !hasPrefix(rest, " Groomed ") { + return false + } + date := rest[len(" groomed "):] + return len(date) >= 10 && isDate(date[:10]) +} + +func hasPrefix(s, p string) bool { return len(s) >= len(p) && s[:len(p)] == p } + +func isDate(s string) bool { + for i := 0; i < len(s); i++ { + if i == 4 || i == 7 { + if s[i] != '-' { + return false + } + } else if !isDigit(s[i]) { + return false + } + } + return true +} + +// headingLevel returns the level of an ATX heading line (up to three spaces of +// indent, one to six '#', then a space, a tab, or the end), or 0. +func headingLevel(line string) (int, bool) { + i := 0 + for i < len(line) && i < 4 && line[i] == ' ' { + i++ + } + if i > 3 { + return 0, false + } + n := 0 + for i+n < len(line) && line[i+n] == '#' { + n++ + } + if n < 1 || n > 6 { + return 0, false + } + if i+n < len(line) && line[i+n] != ' ' && line[i+n] != '\t' { + return 0, false + } + return n, true +} + +// headingLeftovers applies the heading rules outside code: exactly one H1, the +// H1 is the first heading, and no level is skipped going deeper. With no H1 at +// all, the first heading (or line 1, with no heading) is reported. +func headingLeftovers(lines []string, code []bool) []Leftover { + var out []Leftover + report := func(i int) { + out = append(out, Leftover{Line: i + 1, Text: trimRight(lines[i]), Rule: RuleHeading}) + } + h1s, first, prev := 0, -1, 0 + for i, line := range lines { + if code[i] { + continue + } + level, ok := headingLevel(line) + if !ok { + continue + } + switch { + case level == 1: + h1s++ + if h1s > 1 || first >= 0 { + report(i) + } + case prev > 0 && level > prev+1: + report(i) + } + if first < 0 { + first = i + } + prev = level + } + if h1s == 0 { + if first >= 0 { + report(first) + } else if len(lines) > 0 { + report(0) + } + } + return out +} + +// mergeByLine merges two line-ordered leftover lists into one, keeping a's +// entries first on a shared line. +func mergeByLine(a, b []Leftover) []Leftover { + out := make([]Leftover, 0, len(a)+len(b)) + i, j := 0, 0 + for i < len(a) || j < len(b) { + if j >= len(b) || (i < len(a) && a[i].Line <= b[j].Line) { + out = append(out, a[i]) + i++ + } else { + out = append(out, b[j]) + j++ + } + } + return out +} diff --git a/internal/exportcheck/check_test.go b/internal/exportcheck/check_test.go new file mode 100644 index 000000000..8c77b1378 --- /dev/null +++ b/internal/exportcheck/check_test.go @@ -0,0 +1,168 @@ +package exportcheck + +import ( + "reflect" + "strings" + "testing" +) + +// knownIDs reports the ids the crafted inputs treat as real changes. +func knownIDs(ids ...int) func(int) bool { + set := map[int]bool{} + for _, id := range ids { + set[id] = true + } + return func(id int) bool { return set[id] } +} + +var known = knownIDs(559, 113, 120, 547, 88, 282) + +type lineRule struct { + Line int + Rule string +} + +func lineRules(r Report) []lineRule { + var out []lineRule + for _, l := range r.Leftovers { + out = append(out, lineRule{l.Line, l.Rule}) + } + return out +} + +func TestCheckFindsEachLeftoverKind(t *testing.T) { + cases := []struct { + name string + md string + want []lineRule + }{ + {"marker docket", "# T\n\n<!-- docket:artifacts:start -->\n", []lineRule{{3, RuleMarker}}}, + {"marker dckt", "# T\n\ntext <!-- dckt:backlink:end --> more\n", []lineRule{{3, RuleMarker}}}, + {"frontmatter", "---\nid: 1\n---\n# T\n", []lineRule{{1, RuleFrontmatter}}}, + {"banner", "# T\n\n> ↩ **Back**\n", []lineRule{{3, RuleBanner}}}, + {"inline link", "# T\n\nsee [docs](https://x)\n", []lineRule{{3, RuleLink}}}, + {"image", "# T\n\n![alt](p.png)\n", []lineRule{{3, RuleLink}}}, + {"autolink", "# T\n\nsee <https://go.dev/x>\n", []lineRule{{3, RuleLink}}}, + {"reference link", "# T\n\nsee [text][ref]\n", []lineRule{{3, RuleLink}}}, + {"collapsed reference link", "# T\n\nsee [text][]\n", []lineRule{{3, RuleLink}}}, + {"link definition", "# T\n\n[ref]: https://x\n", []lineRule{{3, RuleLink}}}, + {"html anchor", "# T\n\nsee <a href=\"x\">t</a>\n", []lineRule{{3, RuleLink}}}, + {"word form", "# T\n\nfrom change 559 on\n", []lineRule{{3, RuleChangeRef}}}, + {"word form hash", "# T\n\nChange #547 holds\n", []lineRule{{3, RuleChangeRef}}}, + {"word form list", "# T\n\nchanges 9999, 4444 and 0120\n", []lineRule{{3, RuleChangeRef}}}, + {"padded hash", "# T\n\nsee #0559 now\n", []lineRule{{3, RuleChangeRef}}}, + {"padded paren", "# T\n\nfields (0113)\n", []lineRule{{3, RuleChangeRef}}}, + {"padded bare", "# T\n\nmirroring 0088\n", []lineRule{{3, RuleChangeRef}}}, + {"padded possessive", "# T\n\n0282's rule.\n", []lineRule{{3, RuleChangeRef}}}, + {"padded sentence end", "# T\n\nas in 0559.\n", []lineRule{{3, RuleChangeRef}}}, + {"stamp groomed", "# T\n\nChange #561, groomed 2026-10-20.\n", []lineRule{{3, RuleStamp}}}, + {"stamp groomed dot", "# T\n\nChange 9373. Groomed 2026-09-02 (interactive). Rest\n", []lineRule{{3, RuleStamp}}}, + {"stamp change only", "# T\n\nChange 9561.\n", []lineRule{{3, RuleStamp}}}, + {"stamp bold", "# T\n\n**Change:** 9003 · **Type:** feat\n", []lineRule{{3, RuleStamp}}}, + {"heading", "# T\n\n## A\n\n#### B\n", []lineRule{{5, RuleHeading}}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got := lineRules(Check([]byte(tc.md), known)) + if !reflect.DeepEqual(got, tc.want) { + t.Fatalf("Check(%q) leftovers = %v, want %v", tc.md, got, tc.want) + } + }) + } +} + +func TestCheckLeftoverCarriesText(t *testing.T) { + r := Check([]byte("# T\n\nsee [docs](https://x) here\n"), known) + if len(r.Leftovers) != 1 || !strings.Contains(r.Leftovers[0].Text, "[docs](") { + t.Fatalf("leftover text = %+v, want the matched link text", r.Leftovers) + } +} + +func TestCheckKeepsWhatTheExportKeeps(t *testing.T) { + md := strings.Join([]string{ + "# Title", + "", + "Bare #559 and PR #12 and PR #0559 stay.", + "ADR-0147, ADR 0559, and ADR-0065's rule stay.", + "An unknown change 9999 and changes 9998 and 9997 stay.", + "A bare https://go.dev/x URL stays, and a 0559-export.md file, docs/0559, 0559.md too.", + "A converted \"Close a change to done without a PR\" title stays.", + "Code: `<!-- docket:x:start -->`, `[a](b)`, `change 559`, ``a ` [x](y) ``, `#0559`, `↩`.", + "", + "## Section", + "", + "```md", + "---", + "<!-- dckt:backlink:start -->", + "> ↩ back", + "[a](b) ![c](d) <https://x> [r]: u <a href=\"x\">t</a>", + "change 559, #0559, (0113), mirroring 0088", + "# H1 in code", + "#### skipped in code", + "```", + "", + "~~~~", + "Change #561, groomed 2026-10-20.", + "```", + "still code", + "~~~~", + "", + "Tail.", + }, "\n") + "\n" + r := Check([]byte(md), known) + if len(r.Leftovers) != 0 { + t.Fatalf("Check flagged what the export keeps on purpose: %+v", r.Leftovers) + } +} + +func TestCheckStampOnlyBeforeFirstH2(t *testing.T) { + r := Check([]byte("# T\n\n## Why\n\nChange 9561.\n"), known) + if len(r.Leftovers) != 0 { + t.Fatalf("a stamp shape after the first H2 is prose: %+v", r.Leftovers) + } +} + +func TestCheckFrontmatterOnlyOnFirstLine(t *testing.T) { + r := Check([]byte("# T\n\n---\n\ntext\n"), known) + if len(r.Leftovers) != 0 { + t.Fatalf("a thematic break below the top is not frontmatter: %+v", r.Leftovers) + } +} + +func TestCheckMentions(t *testing.T) { + md := "# T\n" + + "docket keeps this\n" + + "\n" + + "```\n" + + "run DCKT now\n" + + "```\n" + + "Docketed is not the word\n" + got := Check([]byte(md), known).Mentions + want := Mentions{Count: 2, Lines: []int{2, 5}} + if !reflect.DeepEqual(got, want) { + t.Fatalf("Mentions = %+v, want %+v", got, want) + } +} + +func TestCheckHeadingRules(t *testing.T) { + cases := []struct { + name string + md string + want []lineRule + }{ + {"two H1s", "# A\n\ntext\n\n# B\n", []lineRule{{5, RuleHeading}}}, + {"H2 before the H1", "## Pre\n\n# A\n", []lineRule{{3, RuleHeading}}}, + {"skipped level", "# A\n\n## B\n\n#### C\n", []lineRule{{5, RuleHeading}}}, + {"no H1", "## A\n\ntext\n", []lineRule{{1, RuleHeading}}}, + {"no heading at all", "text\n", []lineRule{{1, RuleHeading}}}, + {"clean", "# A\n\n## B\n\n### C\n\n## D\n", nil}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got := lineRules(Check([]byte(tc.md), known)) + if !reflect.DeepEqual(got, tc.want) { + t.Fatalf("Check(%q) = %v, want %v", tc.md, got, tc.want) + } + }) + } +} diff --git a/internal/exportcheck/independence_test.go b/internal/exportcheck/independence_test.go new file mode 100644 index 000000000..b11966cf5 --- /dev/null +++ b/internal/exportcheck/independence_test.go @@ -0,0 +1,46 @@ +package exportcheck + +import ( + "os/exec" + "strings" + "testing" +) + +const ( + exportPkg = "github.com/danielhanold/docket/internal/export" + exportcheckPkg = "github.com/danielhanold/docket/internal/exportcheck" + documentPkg = "github.com/danielhanold/docket/internal/document" +) + +// deps lists the import paths pkg depends on, itself excluded. +func deps(t *testing.T, pkg string) map[string]bool { + t.Helper() + out, err := exec.Command("go", "list", "-deps", "-f", "{{.ImportPath}}", pkg).CombinedOutput() + if err != nil { + t.Fatalf("go list -deps %s: %v\n%s", pkg, err, out) + } + set := map[string]bool{} + for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") { + if line != "" && line != pkg { + set[line] = true + } + } + return set +} + +// TestDetectorSharesNothingWithTransform keeps the self-check independent of the +// transform it checks: sharing code or patterns would make the two agree by +// construction, so the detector could never find anything. +func TestDetectorSharesNothingWithTransform(t *testing.T) { + checkDeps := deps(t, exportcheckPkg) + exportDeps := deps(t, exportPkg) + if checkDeps[exportPkg] { + t.Errorf("%s depends on %s", exportcheckPkg, exportPkg) + } + if exportDeps[exportcheckPkg] { + t.Errorf("%s depends on %s", exportPkg, exportcheckPkg) + } + if checkDeps[documentPkg] { + t.Errorf("%s depends on %s, whose fence and marker scanning the transform uses", exportcheckPkg, documentPkg) + } +} From 03ad0c35260e1b2771a0aad92e2df4db5dd209a6 Mon Sep 17 00:00:00 2001 From: Daniel Hanold <danny@danielhanold.com> Date: Tue, 20 Oct 2026 09:56:41 -0400 Subject: [PATCH 07/12] test(export): frozen real-artifact corpus exports clean, and every transform step is load-bearing --- internal/export/corpus_test.go | 441 ++++++++++++++++++ internal/export/testdata/corpus/PROVENANCE.md | 50 ++ ...dual-review-findings-from-0193-and-0201.md | 72 +++ .../2026-06-02-0001-results-artifact.md | 64 +++ ...agent-v2-orchestration-through-docket-i.md | 63 +++ ...cked-child-s-branches-once-its-code-rea.md | 76 +++ .../testdata/corpus/constructed/code.md | 29 ++ .../corpus/constructed/frontmatter.md | 8 + ...klink-finding-codes-in-the-docket-statu.md | 182 ++++++++ ...de-and-cursor-tested-opencode-s-results.md | 49 ++ ...t-change-groom-clear-stacked-on-results.md | 37 ++ ...-06-04-migration-tool-pwd-target-design.md | 53 +++ ...2026-07-10-docket-skill-slimming-design.md | 157 +++++++ ...26-cursor-agent-wrapper-contract-design.md | 319 +++++++++++++ ...7-28-board-checks-exit-swallowed-design.md | 197 ++++++++ ...st-isolation-under-parallel-load-design.md | 77 +++ ...-unrelated-maintenance-preflight-design.md | 62 +++ ...he-ttl-cut-implement-next-s-cost-design.md | 98 ++++ internal/export/testdata/corpus/titles.tsv | 154 ++++++ 19 files changed, 2188 insertions(+) create mode 100644 internal/export/corpus_test.go create mode 100644 internal/export/testdata/corpus/PROVENANCE.md create mode 100644 internal/export/testdata/corpus/changes/0257-clear-the-residual-review-findings-from-0193-and-0201.md create mode 100644 internal/export/testdata/corpus/changes/2026-06-02-0001-results-artifact.md create mode 100644 internal/export/testdata/corpus/changes/2026-09-14-0423-certify-native-multi-agent-v2-orchestration-through-docket-i.md create mode 100644 internal/export/testdata/corpus/changes/2026-10-19-0567-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea.md create mode 100644 internal/export/testdata/corpus/constructed/code.md create mode 100644 internal/export/testdata/corpus/constructed/frontmatter.md create mode 100644 internal/export/testdata/corpus/plans/2026-10-16-list-the-artifact-backlink-finding-codes-in-the-docket-statu.md create mode 100644 internal/export/testdata/corpus/results/2026-10-08-release-v1-0-0-rc-1-claude-code-and-cursor-tested-opencode-s-results.md create mode 100644 internal/export/testdata/corpus/results/2026-10-17-let-change-groom-clear-stacked-on-results.md create mode 100644 internal/export/testdata/corpus/specs/2026-06-04-migration-tool-pwd-target-design.md create mode 100644 internal/export/testdata/corpus/specs/2026-07-10-docket-skill-slimming-design.md create mode 100644 internal/export/testdata/corpus/specs/2026-07-26-cursor-agent-wrapper-contract-design.md create mode 100644 internal/export/testdata/corpus/specs/2026-07-28-board-checks-exit-swallowed-design.md create mode 100644 internal/export/testdata/corpus/specs/2026-09-02-harden-integration-race-test-isolation-under-parallel-load-design.md create mode 100644 internal/export/testdata/corpus/specs/2026-09-23-named-implement-next-skips-unrelated-maintenance-preflight-design.md create mode 100644 internal/export/testdata/corpus/specs/2026-10-19-measure-whether-the-1h-cache-ttl-cut-implement-next-s-cost-design.md create mode 100644 internal/export/testdata/corpus/titles.tsv diff --git a/internal/export/corpus_test.go b/internal/export/corpus_test.go new file mode 100644 index 000000000..8fa71a0c0 --- /dev/null +++ b/internal/export/corpus_test.go @@ -0,0 +1,441 @@ +package export + +import ( + "bufio" + "bytes" + "fmt" + "os" + "path/filepath" + "regexp" + "sort" + "strconv" + "strings" + "testing" + + "github.com/danielhanold/docket/internal/document" + "github.com/danielhanold/docket/internal/exportcheck" +) + +// The frozen corpus is real artifacts copied verbatim from the metadata branch, +// plus a few constructed files; testdata/corpus/PROVENANCE.md lists what each one +// exercises. A leftover found here is fixed in the transform, never in the files. +const corpusDir = "testdata/corpus" + +// corpusKinds maps a corpus folder to the kind its files export as. +var corpusKinds = map[string]Kind{ + "changes": KindIssue, + "specs": KindSpec, + "plans": KindPlan, + "results": KindResults, + "constructed": KindPlan, +} + +type corpusFile struct { + rel string + kind Kind + src []byte + in Input +} + +// loadCorpus reads titles.tsv and every corpus file, in a stable order. +func loadCorpus(t *testing.T) []corpusFile { + t.Helper() + titles := loadTitles(t) + var files []corpusFile + for dir, kind := range corpusKinds { + paths, err := filepath.Glob(filepath.Join(corpusDir, dir, "*.md")) + if err != nil { + t.Fatal(err) + } + if len(paths) == 0 { + t.Fatalf("corpus folder %s holds no files", dir) + } + for _, p := range paths { + src, err := os.ReadFile(p) + if err != nil { + t.Fatal(err) + } + in := Input{Kind: kind, Source: src, Titles: titles} + if kind == KindIssue { + in.Title = frontmatterTitle(t, p, src) + } + files = append(files, corpusFile{rel: filepath.ToSlash(strings.TrimPrefix(p, corpusDir+string(filepath.Separator))), kind: kind, src: src, in: in}) + } + } + sort.Slice(files, func(i, j int) bool { return files[i].rel < files[j].rel }) + return files +} + +// loadTitles reads titles.tsv: "<id>\t<raw title>" per line. +func loadTitles(t *testing.T) Titles { + t.Helper() + data, err := os.ReadFile(filepath.Join(corpusDir, "titles.tsv")) + if err != nil { + t.Fatal(err) + } + titles := Titles{} + sc := bufio.NewScanner(bytes.NewReader(data)) + for n := 1; sc.Scan(); n++ { + id, title, ok := strings.Cut(sc.Text(), "\t") + num, err := strconv.Atoi(id) + if !ok || err != nil || title == "" { + t.Fatalf("titles.tsv line %d is not <id>\\t<title>: %q", n, sc.Text()) + } + titles[num] = title + } + if len(titles) == 0 { + t.Fatal("titles.tsv is empty") + } + return titles +} + +// frontmatterTitle reads the title: field of a change record's leading +// frontmatter, unquoting a YAML single- or double-quoted scalar. +func frontmatterTitle(t *testing.T, path string, src []byte) string { + t.Helper() + lines := strings.Split(string(src), "\n") + if len(lines) == 0 || lines[0] != "---" { + t.Fatalf("%s: change record has no frontmatter", path) + } + for _, l := range lines[1:] { + if l == "---" { + break + } + v, ok := strings.CutPrefix(l, "title:") + if !ok { + continue + } + v = strings.TrimSpace(v) + switch { + case len(v) >= 2 && v[0] == '\'' && v[len(v)-1] == '\'': + return strings.ReplaceAll(v[1:len(v)-1], "''", "'") + case len(v) >= 2 && v[0] == '"' && v[len(v)-1] == '"': + return v[1 : len(v)-1] + } + return v + } + t.Fatalf("%s: change record has no title", path) + return "" +} + +// codeSpans returns the inline code spans of one line, CommonMark style: a run of +// N backticks opens a span and the next run of exactly N closes it; an escaped +// backtick opens nothing. rest is the line with every span removed. +func codeSpans(line string) (spans []string, rest string) { + var b strings.Builder + for i := 0; i < len(line); { + if line[i] == '\\' && i+1 < len(line) { + b.WriteString(line[i : i+2]) + i += 2 + continue + } + if line[i] != '`' { + b.WriteByte(line[i]) + i++ + continue + } + n := 0 + for i+n < len(line) && line[i+n] == '`' { + n++ + } + end := -1 + for j := i + n; j < len(line); { + if line[j] != '`' { + j++ + continue + } + m := 0 + for j+m < len(line) && line[j+m] == '`' { + m++ + } + if m == n { + end = j + m + break + } + j += m + } + if end < 0 { + b.WriteString(line[i : i+n]) + i += n + continue + } + spans = append(spans, line[i:end]) + b.WriteByte(' ') + i = end + } + return spans, b.String() +} + +// mdLine is one line of Markdown with its fence class and its text outside code. +type mdLine struct { + text string + fenced bool + kind document.LineKind + name string + plain string // text with code spans removed ("" for a fenced line) + spans []string + heading int // ATX heading level outside fences, 0 otherwise +} + +var testHeadingRE = regexp.MustCompile(`^ {0,3}(#{1,6})(?:[ \t]|$)`) + +func readLines(md []byte) []mdLine { + s := string(md) + texts := strings.Split(s, "\n") + if strings.HasSuffix(s, "\n") { + texts = texts[:len(texts)-1] + } + info := document.ClassifyLines(md) + out := make([]mdLine, len(texts)) + for i, t := range texts { + l := mdLine{text: t} + if i < len(info) { + l.kind, l.name = info[i].Kind, info[i].Name + } + l.fenced = l.kind == document.LineFence + if !l.fenced { + l.spans, l.plain = codeSpans(t) + if m := testHeadingRE.FindStringSubmatch(t); m != nil { + l.heading = len(m[1]) + } + } + out[i] = l + } + return out +} + +var ( + // testStampRE is a grooming stamp shape in a spec's preamble: a line opening + // "Change N." / "Change #N,", or a "groomed <date>" sentence anywhere on it + // (which still shows once step 6 has turned the "Change N" into a title). + testStampRE = regexp.MustCompile(`(?i)^change #?\d+[.,]|\bgroomed \d{4}-\d{2}-\d{2}\b`) + issueH2 = map[string]bool{"## Why": true, "## What changes": true, "## Out of scope": true, "## Open questions": true} +) + +// corpusProblems checks one export: the independent detector finds no leftover, +// and each removal is also asserted directly, so the test does not rest on the +// detector alone. It returns one message per failure. +func corpusProblems(kind Kind, src, out []byte, titles Titles) []string { + var probs []string + add := func(format string, a ...any) { probs = append(probs, fmt.Sprintf(format, a...)) } + + report := exportcheck.Check(out, func(id int) bool { _, ok := titles[id]; return ok }) + for _, l := range report.Leftovers { + add("self-check %s leftover on line %d: %q", l.Rule, l.Line, l.Text) + } + + lines := readLines(out) + if len(lines) > 0 && lines[0].text == "---" { + add("line 1 is a frontmatter fence") + } + seenH2 := false + for i, l := range lines { + n := i + 1 + if l.fenced { + continue + } + if strings.Contains(l.plain, "<!-- docket:") || strings.Contains(l.plain, "<!-- dckt:") { + add("line %d: marker outside code: %q", n, l.text) + } + if strings.Contains(l.plain, "](") || strings.Contains(l.plain, "<http") { + add("line %d: link outside code: %q", n, l.text) + } + if l.heading == 2 { + seenH2 = true + if kind == KindIssue && !issueH2[strings.TrimRight(l.text, " \t")] { + add("line %d: issue keeps a non-allowlisted section: %q", n, l.text) + } + } + if kind == KindSpec && !seenH2 && (testStampRE.MatchString(l.text) || strings.Contains(l.plain, "**Change:**")) { + add("line %d: spec stamp before the first H2: %q", n, l.text) + } + if strings.TrimSpace(l.text) == "" && i > 0 && !lines[i-1].fenced && strings.TrimSpace(lines[i-1].text) == "" { + add("line %d: two consecutive blank lines", n) + } + if l.heading > 0 { + for j := i + 1; j < len(lines); j++ { + if !lines[j].fenced && strings.TrimSpace(lines[j].text) == "" { + continue + } + if !lines[j].fenced && lines[j].heading > 0 && lines[j].heading <= l.heading { + add("line %d: heading %q has an empty section", n, l.text) + } + break + } + } + } + + if missing := missingCodeRegions(kind, src, out); missing != "" { + add("code region not carried byte-identical, in order: %q", missing) + } + return probs +} + +// codeRegions returns, in order, every fenced block (its lines joined, each with +// its newline) and every inline code span of the given lines. +func codeRegions(lines []mdLine) []string { + var regions []string + var block strings.Builder + for _, l := range lines { + if l.fenced { + block.WriteString(l.text + "\n") + continue + } + if block.Len() > 0 { + regions = append(regions, block.String()) + block.Reset() + } + regions = append(regions, l.spans...) + } + if block.Len() > 0 { + regions = append(regions, block.String()) + } + return regions +} + +// exportScope is the part of src whose content an export keeps: never the +// frontmatter or a marker-delimited generated block, and for an issue only the +// allowlisted sections. +func exportScope(kind Kind, src []byte) []mdLine { + var scope []mdLine + inBlock, keepSection := "", kind != KindIssue + for _, l := range readLines(src) { + switch { + case l.kind == document.LineFrontmatter: + continue + case l.kind == document.LineMarkerStart: + inBlock = l.name + continue + case l.kind == document.LineMarkerEnd: + if l.name == inBlock { + inBlock = "" + } + continue + case inBlock != "": + continue + } + if kind == KindIssue && l.heading == 2 { + keepSection = issueH2[strings.TrimRight(l.text, " \t")] + } + if keepSection { + scope = append(scope, l) + } + } + return scope +} + +// missingCodeRegions returns the first code region of src's export scope that +// does not appear byte-identical, in order, in out; "" when all do. +func missingCodeRegions(kind Kind, src, out []byte) string { + text := string(out) + cursor := 0 + for _, r := range codeRegions(exportScope(kind, src)) { + at := strings.Index(text[cursor:], r) + if at < 0 { + return r + } + cursor += at + len(r) + } + return "" +} + +func TestCorpusExportsClean(t *testing.T) { + for _, f := range loadCorpus(t) { + t.Run(f.rel, func(t *testing.T) { + out := Transform(f.in) + for _, s := range out.Stray { + t.Errorf("stray marker on source line %d: %q", s.SourceLine, s.Text) + } + for _, p := range corpusProblems(f.kind, f.src, out.Markdown, f.in.Titles) { + t.Error(p) + } + if t.Failed() { + t.Logf("export:\n%s", out.Markdown) + } + }) + } +} + +// constructedCode is the hand-built file whose code regions and kept reference +// shapes are asserted directly. +const constructedCode = "constructed/code.md" + +func findCorpusFile(t *testing.T, rel string) corpusFile { + t.Helper() + for _, f := range loadCorpus(t) { + if f.rel == rel { + return f + } + } + t.Fatalf("corpus file %s is missing", rel) + return corpusFile{} +} + +func TestCorpusCodeRegionsUntouched(t *testing.T) { + f := findCorpusFile(t, constructedCode) + out := string(Transform(f.in).Markdown) + regions := codeRegions(readLines(f.src)) + var fences, spans int + for _, r := range regions { + if strings.HasSuffix(r, "\n") { + fences++ + } else { + spans++ + } + } + if fences < 2 || spans < 5 { + t.Fatalf("%s should hold at least 2 fenced blocks and 5 code spans, found %d and %d", constructedCode, fences, spans) + } + cursor := 0 + for _, r := range regions { + at := strings.Index(out[cursor:], r) + if at < 0 { + t.Fatalf("code region not carried byte-identical, in order: %q\nexport:\n%s", r, out) + } + cursor += at + len(r) + } +} + +func TestCorpusConstructedSurvivors(t *testing.T) { + f := findCorpusFile(t, constructedCode) + if _, ok := f.in.Titles[998]; ok { + t.Fatal("titles.tsv must not claim 998: the fixture uses it as the unknown id") + } + if _, ok := f.in.Titles[559]; !ok { + t.Fatal("titles.tsv must claim 559, so the bare #559 is a known id that still stays") + } + out := string(Transform(f.in).Markdown) + for _, keep := range []string{ + "a bare URL https://go.dev/doc/toolchain,", + "a bare #559,", + "PR #433,", + "ADR-0012,", + "the unknown 0998.", + "names change 0998, which", + } { + if !strings.Contains(out, keep) { + t.Errorf("export lost %q:\n%s", keep, out) + } + } +} + +// TestEveryStepIsLoadBearing disables one transform step at a time and requires +// the corpus checks to notice. A step that stays green means the corpus lacks the +// case it handles: add a file that exercises it, never weaken this guard. +func TestEveryStepIsLoadBearing(t *testing.T) { + files := loadCorpus(t) + for _, s := range allSteps { + var red []string + for _, f := range files { + out := transform(f.in, map[step]bool{s: true}) + if len(corpusProblems(f.kind, f.src, out.Markdown, f.in.Titles)) > 0 { + red = append(red, f.rel) + } + } + if len(red) == 0 { + t.Errorf("disabling step %d leaves every corpus file clean", s) + continue + } + t.Logf("disabling step %d reddens %d file(s): %s", s, len(red), strings.Join(red, ", ")) + } +} diff --git a/internal/export/testdata/corpus/PROVENANCE.md b/internal/export/testdata/corpus/PROVENANCE.md new file mode 100644 index 000000000..ba9a0f4f1 --- /dev/null +++ b/internal/export/testdata/corpus/PROVENANCE.md @@ -0,0 +1,50 @@ +# Export corpus provenance + +Frozen inputs for `corpus_test.go`. Every file under `changes/`, `specs/`, `plans/`, and +`results/` is a verbatim copy from this repository's `docket` metadata branch at commit +`a6c555422f1fdb17577ef472309f0b3859f519ec`, copied on 2026-10-20. Never edit them: a leftover +found here is fixed in the transform. The files under `constructed/` are hand-built. + +The folder sets the export kind: `changes/` exports as an issue, `specs/` as a spec, `plans/` +and `constructed/` as a plan, `results/` as results. + +## titles.tsv + +`<id>\t<raw title>` for every number in any corpus file that is a real change id, read from +that record's frontmatter `title:` on the same commit. No id is claimed by two records there. +`998` is deliberately absent: `constructed/code.md` uses it as the unknown id. + +## Files and what they exercise + +| File | Source path on the metadata branch | Exercises | +|---|---|---| +| `changes/2026-06-02-0001-results-artifact.md` | `docs/changes/archive/` | Older archived record: frontmatter with unquoted scalars, an artifacts block with no `## Artifacts` heading, `blob/main` docket links inside the block, a `## Reconcile log` dropped by the section allowlist, a word-form reference (`change #0004`) in kept prose. That reference names another repository's change, yet it converts to this repository's change 4 title: the export cannot tell repositories apart. | +| `changes/2026-09-14-0423-certify-native-multi-agent-v2-orchestration-through-docket-i.md` | `docs/changes/archive/` | Shared-repo absolute metadata-branch link (`blob/docket/...`), removed with its `## Reconcile log`; unpadded bare numbers (`425 and 424`) that are not reference forms. | +| `changes/2026-10-19-0567-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea.md` | `docs/changes/archive/` | Record with bookkeeping sections: `## Artifacts` block (heading left empty), `## Reconcile log`, `## Build evidence` with its `build-evidence` block; bare `#562` kept. | +| `changes/0257-clear-the-residual-review-findings-from-0193-and-0201.md` | `docs/changes/active/` | Active, deferred record: a title holding padded ids (title cleaning to "another issue"), dense padded and `#0ddd` references, `PR #152` kept, `## Why deferred` dropped, `## Open questions` kept. | +| `specs/2026-09-02-harden-integration-race-test-isolation-under-parallel-load-design.md` | `docs/superpowers/specs/` | Stamp `Change N. Groomed <date> (interactive). Priority …` (rest of the line kept); backlink block; references-only parenthesis `(0371, 0397)`. | +| `specs/2026-07-28-board-checks-exit-swallowed-design.md` | `docs/superpowers/specs/` | Stamp line that is only `Change N.`; empty headings left by removals. | +| `specs/2026-06-04-migration-tool-pwd-target-design.md` | `docs/superpowers/specs/` | `**Change:** N` stamp line; `change 0002` word form; `ADR-0002` kept. | +| `specs/2026-07-10-docket-skill-slimming-design.md` | `docs/superpowers/specs/` | Autolinks `<https://…>`; a `·`-separated `**Key:** value` run holding `**Change:**`; word-form references. | +| `specs/2026-09-23-named-implement-next-skips-unrelated-maintenance-preflight-design.md` | `docs/superpowers/specs/` | H1 `# Change N — <its own title>` (the remainder equals the record title), own-title dash removed; dense padded references in prose and in an arrow list. | +| `specs/2026-10-19-measure-whether-the-1h-cache-ttl-cut-implement-next-s-cost-design.md` | `docs/superpowers/specs/` | Recent `Change #N, groomed <date>.` stamp. | +| `specs/2026-07-26-cursor-agent-wrapper-contract-design.md` | `docs/superpowers/specs/` | External inline link `[text](https://cursor.com/…)` reduced to its text. | +| `plans/2026-10-16-list-the-artifact-backlink-finding-codes-in-the-docket-statu.md` | `docs/superpowers/plans/` | Code fences holding reference-shaped text (`change 0539` in Go comments, commit messages); code spans holding `(change 0539)` and `## Artifacts`; backlink block. | +| `results/2026-10-17-let-change-groom-clear-stacked-on-results.md` | `docs/results/` | Results dense with references: a padded list in a heading, a references-only parenthesis of seven ids removed whole, `0007-shaped` (not a form), bare `#565` kept. | +| `results/2026-10-08-release-v1-0-0-rc-1-claude-code-and-cursor-tested-opencode-s-results.md` | `docs/results/` | A bare URL ending a sentence, kept as written; backlink block. | +| `constructed/code.md` | hand-built | Reference-, link-, and marker-shaped text inside a backtick fence, a tilde fence, single- and double-backtick code spans; a bare URL, `#559` (a known id), `PR #433`, `ADR-0012`, and the unknown padded id `0998` in prose. | +| `constructed/frontmatter.md` | hand-built | A non-issue artifact with leading frontmatter. No spec, plan, or results file on the metadata branch has one, and an issue's frontmatter is also dropped by the section allowlist, so without this file disabling step 1 would leave the corpus green. | + +## What the corpus does not contain + +Checked by scanning every corpus file outside fences and code spans: + +| Category | Covered instead by | +|---|---| +| Images (`![alt](p)`) | `TestStripLinks` | +| Reference-style links and link-reference definitions (`[t][r]`, `[r]: u`) | `TestStripLinks`, `TestIsLinkDefinition` | +| HTML `<a href>` links | `TestStripLinks` | +| Inline code spans that cross a line break (a known limitation: such a span is treated as plain text) | none; no corpus line outside a fence holds an unmatched backtick run | +| Damaged markers and an unclosed frontmatter opener | `TestTransformDamagedSourceKeepsContent` | +| CRLF line endings | `TestTransformNormalizesCRLF` | +| An id two records claim | the app-layer export tests | diff --git a/internal/export/testdata/corpus/changes/0257-clear-the-residual-review-findings-from-0193-and-0201.md b/internal/export/testdata/corpus/changes/0257-clear-the-residual-review-findings-from-0193-and-0201.md new file mode 100644 index 000000000..9eff62044 --- /dev/null +++ b/internal/export/testdata/corpus/changes/0257-clear-the-residual-review-findings-from-0193-and-0201.md @@ -0,0 +1,72 @@ +--- +id: 257 +slug: clear-the-residual-review-findings-from-0193-and-0201 +title: 'Clear the residual review findings from 0193 and 0201' +status: 'deferred' +priority: low +type: chore +created: 2026-08-07 +updated: '2026-09-07' +depends_on: [] +related: [253, 260] +discovered_from: [197, 204] +adrs: [] +spec: docs/superpowers/specs/2026-08-07-clear-the-residual-review-findings-from-0193-and-0201-design.md +plan: +results: +trivial: false +auto_groomable: true +branch: +pr: +blocked_by: +reconciled: false +--- + +## Artifacts + +<!-- docket:artifacts:start (generated — do not hand-edit) --> +| Artifact | Link | +|---|---| +| Spec | [2026-08-07-clear-the-residual-review-findings-from-0193-and-0201-design.md](../../superpowers/specs/2026-08-07-clear-the-residual-review-findings-from-0193-and-0201-design.md) | +<!-- docket:artifacts:end --> + +## Why + +Consolidates #0197 and #0204 (2026-08-07 triage): the two surviving small "clear the residue" changes of the review-finding-clearance class (their siblings 0200 and 0196 are larger and stay separate). + +Verified 2026-08-07 — #0197's five findings from 0193's merge (PR #152), all present: + +1. `README.md:653` and `:655` still label `docket-build`/`docket-review` "opt-in", contradicted by `README.md:759` ("Change 0193 ended that: … shipped cross-harness defaults"). +2. `skills/docket-convention/SKILL.md:44` — the config sketch comment still says "unset key = the superpowers default shown", stale for build/review. +3. `tests/test_docket_review.sh:785` — an absence assert with no live non-vacuity companion through the same `awk` extractor. +4. `tests/test_docket_config.sh:461,463` — two `!=` asserts entailed by the `=` asserts directly above them (:458-459). Default disposition: remove. +5. `tests/test_docket_build.sh:694-695` — the README/SDD opt-back-in guard is a whole-file unanchored substring. + +#0204's surviving items (item 2 — the auto-capture mint-site consequence — was already restored by 0226 into `skills/docket-convention/SKILL.md:276-278`; drop it): + +1. The finalize explicit-id override kept its rule but lost the anti-deadlock rationale: `skills/docket-finalize-change/SKILL.md:164` has a different rationale, and `references/gate-failure.md`'s `## Finalize blocked` section (:26-31) has no occurrence of "deadlock"/"never be finalized". Restore the one-sentence why. +2. (absorbed 0214) `AGENTS.md:25-40`'s frontmatter-edit bullets omit the whitespace-class half — no `[[:blank:]]*`-not-`\s*` guidance, no read-back-after-write instruction. Add it (own bullet or a clause on the anchoring bullet — editorial default: a clause). +3. Sweep the other 0201-compressed files for the same rationale-loss class while there (bounded: the four files 0201 touched). + +## What changes + +Settled by the linked design spec (groomed 2026-08-07, critic-gated), eight edits E1–E8: two README roster cells ("opt-in" → "shipped default"), the convention sketch comment ("superpowers default" → "shipped default", live surface only), a non-vacuity companion assert through a factored shared extractor in the review test, removal of the two strictly-entailed `!=` asserts in the config test, the opt-back-in guard anchored to the `### docket-build` README section (0253-compatible shape), the anti-deadlock override rationale restated with its rule in `references/gate-failure.md`, a whitespace-class + read-back clause on AGENTS.md's anchoring bullet, and the bounded rationale-loss sweep of the four 0201-compressed SKILL.mds. + +Coupling: `related: [253]` — 0253 rewrites prose-anchored guards in the same two test files and its build-time site re-derivation would sweep the guard E5 anchors; no ordering constraint, whichever lands second reconciles. 0249/0224/0172 collisions on the same files are plain append/textual adjacency, left in prose (mirroring 0249's own spec). + +## Out of scope + +- 0200's board-checks bundle (separate, larger, re-scoped). +- Any new guard machinery beyond the anchoring fixes named; helper hoisting (0252); guard-pattern policy (0253); producer-pipe hygiene (0172). + +## Open questions + +- **Backlog review 2026-09-02 (Bash→Go migration)** — still valid for Docket Go; needs regrooming against the Go tree. Narrow to E2 (convention `unset key = the superpowers default shown`), E6 (gate-failure deadlock clause), E7 (AGENTS.md whitespace-class/read-back rule), E8 (bounded rationale-loss sweep). E1 is already fixed; E3/E4/E5 targeted deleted Bash tests. + +## Why deferred + +2026-09-07 — Deferred at the user's request following review of the groomed backlog against the current Go source. The near-term priorities are Go beta acceptance and observed workflow reliability. + +The original eight-edit bundle no longer describes eight live repairs. E1's README problem has been addressed; E3, E4, and E5 target deleted Bash tests. The surviving work is the convention's stale default comment, rationale restoration, ad hoc shell-edit guidance, and another documentation audit. The current finalize reference already states the named-id override and clearing behavior; the residual E6 request is its explanatory rationale, not a missing retry mechanism. + +Revival criterion: consolidate the still-valid corrections into a current documentation pass, potentially retained change 0154, and explicitly account for each surviving item. Do not run the original eight-edit spec as a standalone implementation, revive deleted tests, or silently declare remaining rationale/guidance work completed. diff --git a/internal/export/testdata/corpus/changes/2026-06-02-0001-results-artifact.md b/internal/export/testdata/corpus/changes/2026-06-02-0001-results-artifact.md new file mode 100644 index 000000000..fc9919d9d --- /dev/null +++ b/internal/export/testdata/corpus/changes/2026-06-02-0001-results-artifact.md @@ -0,0 +1,64 @@ +--- +id: 1 +slug: results-artifact +title: Change results artifact — linked, optional close-out file +status: done +priority: medium +created: 2026-06-02 +updated: 2026-06-02 +depends_on: [] +related: [] +adrs: [] +spec: docs/superpowers/specs/2026-06-02-results-artifact-design.md +plan: docs/superpowers/plans/2026-06-02-results-artifact.md +results: docs/results/2026-06-02-results-artifact-results.md +trivial: false +branch: feat/results-artifact +pr: https://github.com/danielhanold/docket/pull/2 +blocked_by: +reconciled: true +--- +<!-- docket:artifacts:start (generated — do not hand-edit) --> +| Artifact | Link | +|---|---| +| Spec | [2026-06-02-results-artifact-design.md](../../superpowers/specs/2026-06-02-results-artifact-design.md) | +| Plan | [2026-06-02-results-artifact.md](https://github.com/danielhanold/docket/blob/main/docs/superpowers/plans/2026-06-02-results-artifact.md) | +| Results | [2026-06-02-results-artifact-results.md](https://github.com/danielhanold/docket/blob/main/docs/results/2026-06-02-results-artifact-results.md) | +<!-- docket:artifacts:end --> + +## Why + +Implementing a change sometimes produces a close-out document — what the human must hand-verify at the merge gate, what the build discovered, what follow-ups it spawned. docket has no concept of such a file, so when Markhaus change #0004 (onboarding) produced one it landed orphaned at `markhaus/docs/2026-05-31-onboarding-results.md`: linked to nothing, and loose in top-level `docs/` where such files accumulate (markhaus already has several from the pre-docket era). The original design only addressed this obliquely — "fold results into the body" (2026-05-30 spec, line 401) — which conflicts with the rule that a change body is a PM-altitude proposal, not a home for build evidence or QA checklists. + +## What changes + +Introduce the **results artifact**: an optional close-out file modelled as a true twin of the plan — a feature-branch build artifact linked from the change by a new `results:` frontmatter field. + +- New `results:` manifest field (single path), slotted after `plan:` with a parallel comment. +- New `results_dir` knob in `.docket.yml` (default `docs/results`), matching how `changes_dir`/`adrs_dir` are exposed; the file lives at `docs/results/<YYYY-MM-DD>-<slug>-results.md`. +- **Optional, written only when warranted** — a concrete trigger (human verification steps, findings, or follow-ups). Otherwise skipped; the PR + green CI are the receipt. Keeps the document count low. +- Authored in the feature worktree (like the plan), merges with the PR; the `results:` field is set in the main tree on `metadata_branch`. Never archived; linked by path; resolves on `main` after merge (same as `plan:`). +- A lean three-section template (`Verify (human)` / `Findings` / `Follow-ups`), shipped as `results-template.md`. + +Touch-points: the synced convention block (manifest + layout + `.docket.yml` + branch-model line), `docket-implement-next` (conditional close-out step), `docket-finalize-change` (post-merge append note), `docket-status` (tolerate unresolved `results:` on `implemented`), the 2026-05-30 design spec (reconcile line 401), README, and the new template. Full detail in the linked spec. + +## Out of scope + +- Retrofitting other repos — migrating Markhaus's existing orphaned `*-results.md` files into `docs/results/` is a separate markhaus-side cleanup. +- Directory-per-change restructuring (rejected) and folding-results-into-the-body (superseded). +- Multi-file `results:` lists — forward-compatible but not implemented. + +## Open questions + +None outstanding — naming, cardinality, home, and the optional/triggered model are resolved in the spec. + +## Reconcile log + +**2026-06-02:** Reconciled at claim time — spec and change were authored the same day and `origin/main` has not advanced since, so this is a currency check, not a rewrite. Verified every spec §8 touch-point anchor against the live files: +- `docket-status` broken-link health check (its `plan:`-on-`implemented` tolerance) → extend the same tolerance to `results:`. +- Design-spec **line 401** ("results folded into the body") is a *historical description of the one-time Markhaus migration*, not a go-forward intent — so the reconcile action is to **add** a go-forward note + a §3 locked decision, not to rewrite the historical line. +- `docket-finalize-change` per-change steps → add a short post-merge "append interactive outcomes / late findings to the results file on `main`" note. +- README config block (`changes_dir`/`adrs_dir`) → add `results_dir`; mention the results artifact where artifacts are enumerated. +- Added **`change-template.md`** (add the `results:` field) to scope explicitly, alongside the new `results-template.md`. + +Scope otherwise unchanged; no work shipped elsewhere to drop. Build approach: encode the requirements as content/sync **assertions** (TDD-style for a docs+invariant change) — a real "convention blocks are in sync" check and a "`results:`/`results_dir` present across all five skills" check — then edit the canonical convention block, run `sync-convention.sh` to propagate, and add the template. diff --git a/internal/export/testdata/corpus/changes/2026-09-14-0423-certify-native-multi-agent-v2-orchestration-through-docket-i.md b/internal/export/testdata/corpus/changes/2026-09-14-0423-certify-native-multi-agent-v2-orchestration-through-docket-i.md new file mode 100644 index 000000000..2c5c3c720 --- /dev/null +++ b/internal/export/testdata/corpus/changes/2026-09-14-0423-certify-native-multi-agent-v2-orchestration-through-docket-i.md @@ -0,0 +1,63 @@ +--- +id: 423 +slug: 'certify-native-multi-agent-v2-orchestration-through-docket-i' +title: 'Certify native Multi-Agent V2 orchestration through Docket ImplementNext' +status: 'done' +priority: 'critical' +type: 'chore' +created: '2026-09-11' +updated: '2026-09-14' +depends_on: [] +stacked_on: +related: [323, 384, 393, 412, 424, 425, 426] +discovered_from: [323, 412] +adrs: [59, 60, 94, 114] +spec: 'docs/superpowers/specs/2026-09-13-certify-native-multi-agent-v2-orchestration-through-docket-i-design.md' +plan: +results: +trivial: false +auto_groomable: +branch_prefix: +branch: 'chore/certify-native-multi-agent-v2-orchestration-through-docket-i' +pr: +blocked_by: +reconciled: false +claimed_at: +--- + +## Artifacts + +<!-- docket:artifacts:start (generated — do not hand-edit) --> +| Artifact | Link | +|---|---| +| Spec | [2026-09-13-certify-native-multi-agent-v2-orchestration-through-docket-i-design.md](../../superpowers/specs/2026-09-13-certify-native-multi-agent-v2-orchestration-through-docket-i-design.md) | +| ADRs | [ADR-0059](../../adrs/0059-dispatch-capability-resolved-not-inferred-from-tool-name.md), [ADR-0060](../../adrs/0060-generated-wrapper-conforms-to-target-harness-contract.md), [ADR-0094](../../adrs/0094-plan-authoring-is-a-pinned-internal-composition-agent.md), [ADR-0114](../../adrs/0114-anchor-codex-feature-scoped-role-entry-to-the-owning-worktre.md) | +<!-- docket:artifacts:end --> + +## Why + +Docket adopted Codex app-server root entry after real ImplementNext runs could not launch docket-plan-writer as a nested child. Subsequent controlled tests found a more specific cause: the affected coordinator was pinned to a Multi-Agent V1 model, while an otherwise equivalent Multi-Agent V2 model received collaboration tools and successfully launched the same registered child. Before Docket reverses a large body of launch architecture, it needs durable, production-shaped evidence that the distinction is model capability rather than prompt wording, reasoning effort, role complexity, or an artifact of the earlier minimal probes. + +## What changes + +Deliver a repeatable manually operated native Codex POC that runs the actual ImplementNext coordinator, actual plan writer and corrected actual standard worker continuously from a fresh primary checkout. Under user-approved option 2, feature children validate their assigned worktree and explicitly target all feature operations there even when their startup cwd is primary. Carry complete planner and child-capability payloads, the unchanged outer gate context, real TDD/commit/acknowledgement, configured exact-commit gates, a results checkpoint and terminal bounded halt. Package setup, deterministic validation and sanitized evidence. No additional Luna control, production routing change or Docket build workflow is part of 423. + +## Out of scope + +Production dispatch or model-policy implementation (425 and 424), agent.enter calls, native startup-placement workarounds, hard isolation or parallel-safety claims, further Luna/control probes, review/PR/merge of the disposable candidate, and fabricated production merge/build evidence. Manual closure follows accepted POC evidence and an explicitly documented metadata exception. + +## Reconcile log + +### 2026-09-14 + +User-directed 2026-09-14 scope reconciliation: option2 replaces native startup equality, Luna/control retests end, continuous corrected positive path remains required, reusable POC package is delivered manually, and done requires explicit evidence acceptance plus truthful manual metadata close-out rather than Docket build/finalize fiction. Production work feeds425; historical evidence and accepted ADRs remain unchanged. + +Manual POC completion + +Accepted and manually completed on 2026-09-14 under the user instruction: “Continue with final evidence packaging and manual closeout.” This is the approved POC lifecycle exception; no production PR, merge or Docket build/finalize run is asserted. + +The continuous native ImplementNext → planner → standard worker run passed the agreed option 2 contract, including real TDD, the committed and locally published results checkpoint, the configured full suite at that checkpoint, and an unchanged primary audit. The fixture then halted deliberately under its typed boundary. Acceptance is `continuous-functional-passed`, with `evidence_audit_complete: false` and the documented observation limitations accepted. + +The [final report and reusable evidence package](https://github.com/danielhanold/docket/blob/docket/docs/codex/fixtures/native-implement-next/FINAL-RESULTS.md) preserve the evidence, independent review, Git history, reproducible fixture and checksums. This metadata-resident POC report is intentionally linked here rather than through a main-branch lifecycle results field. The original fixtures are retained; the historical branch label remains only as provenance, with the active claim and reconciliation bookkeeping cleared. + +Change 424 owns production model capability policy. Change 425 consumes this evidence for Codex-only native dispatch and explicit feature-worktree binding; it still depends on 424. This POC does not certify hard isolation, parallel safety or production readiness. diff --git a/internal/export/testdata/corpus/changes/2026-10-19-0567-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea.md b/internal/export/testdata/corpus/changes/2026-10-19-0567-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea.md new file mode 100644 index 000000000..6f841bb81 --- /dev/null +++ b/internal/export/testdata/corpus/changes/2026-10-19-0567-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea.md @@ -0,0 +1,76 @@ +--- +id: 567 +slug: 'cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea' +title: 'Clean up stacked children when their stack lands, and finalize a child after its parent' +status: 'done' +priority: 'high' +type: 'fix' +deliverable: 'pr' +created: '2026-10-17' +updated: '2026-10-19' +depends_on: [] +stacked_on: +related: [562] +discovered_from: [562] +adrs: [92, 35, 152] +spec: 'docs/superpowers/specs/2026-10-18-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea-design.md' +plan: 'docs/superpowers/plans/2026-10-18-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea.md' +results: 'docs/results/2026-10-19-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea-results.md' +trivial: false +auto_groomable: +branch_prefix: +branch: 'fix/cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea' +pr: 'https://github.com/danielhanold/docket/pull/433' +blocked_by: +reconciled: true +claimed_at: +--- + +## Artifacts + +<!-- docket:artifacts:start (generated — do not hand-edit) --> +| Artifact | Link | +|---|---| +| Spec | [2026-10-18-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea-design.md](../../superpowers/specs/2026-10-18-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea-design.md) | +| Spec (merged) | [2026-10-18-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea-design.md](https://github.com/danielhanold/docket/blob/main/docs/superpowers/specs/2026-10-18-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea-design.md) | +| Plan | [2026-10-18-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea.md](../../superpowers/plans/2026-10-18-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea.md) | +| Results | [2026-10-19-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea-results.md](../../results/2026-10-19-cleanup-deletes-a-stacked-child-s-branches-once-its-code-rea-results.md) | +| ADRs | [ADR-0092](../../adrs/0092-a-stacked-changes-base-is-its-parents-merge-destination.md), [ADR-0035](../../adrs/0035-cleanup-teardown-fail-closed.md), [ADR-0152](../../adrs/0152-a-finished-workspace-s-identity-excludes-the-base-it-was-cut.md) | +<!-- docket:artifacts:end --> + +## Why + +Docket users stack changes in their own repositories, and finishing a stack is broken in two ways. + +First, when a stack's root lands on main, none of its children get cleaned up: each child keeps its worktree folder, its local branch, and its remote branch forever. Finalize and the sweep clean up only the root. When cleanup does run for a child, it refuses, because the child's PR merged into its parent's branch rather than main. Even past that refusal, the child's folder looks like it belongs to someone else: docket compares the branch the folder was cut from (the parent's) with the base it now expects (main), and they no longer match. On top of that, the usual "is the merge on main" proof can't pass for a child, because docket's rebase merges put rewritten copies of the child's commits on main, not the same commits. + +Second, the same folder comparison likely stops docket from finalizing a child whose parent landed on main first, after finalize moved the child's PR to main. + +Found while grooming #562, which deliberately left stacked children alone. + +## What changes + +- A finished worktree folder is recognized as its change's own even when the branch it was cut from is no longer its base. A half-created folder (creation interrupted) still has to match. +- Cleanup proves a stacked child's work reached main through its stack, using the same check closeout already runs before marking the child done (shared, not copied). Then it removes the child's folder and both branches under the usual safety checks. If the proof fails, it keeps everything and says so, with no "delete it by hand" advice. +- Finalize and the sweep clean up each child the root carried right after the root itself. +- The sweep treats a stacked child's leftover branch like any other leftover, so leftovers already in users' repositories are cleaned on the first full sweep after upgrade. +- A child whose parent landed first can be finalized normally. + +## Out of scope + +How stacked children merge or become done, and the rule that a child's branches are kept until its root lands. Ordinary (unstacked) cleanup, including removing a clean folder when the branch is kept. Killed changes' branches and worktrees. The killed-parent policy. + +## Reconcile log + +### 2026-10-18 + +Reconciled against main at f42692b6d. The code the spec names is still present unchanged in shape: `ownsManifest` (internal/workspace/prepare.go), `proveCarry` (internal/domain/stackcloseout.go), `closeoutIntegrationDestination` and `finalizeCleanupDone` (internal/app), `sweepRunCloseout` and `sweepMaybeCarriedDescendant` (internal/app). The recently landed #568 (refuse killing a parent with built stacked children) touches the kill path only and does not overlap this change's cleanup, closeout, or workspace-identity work. #562 is done. Scope unchanged. + +## Build evidence + +<!-- docket:build-evidence:start --> +command: go run ./cmd/docket development test +result: green +head_sha: e1358d8501b1e3422bb6054daf79f7c63097d9e5 +ran_at: 2026-10-19T01:25:16Z +<!-- docket:build-evidence:end --> diff --git a/internal/export/testdata/corpus/constructed/code.md b/internal/export/testdata/corpus/constructed/code.md new file mode 100644 index 000000000..1227d2453 --- /dev/null +++ b/internal/export/testdata/corpus/constructed/code.md @@ -0,0 +1,29 @@ +# Code samples stay exactly as written + +Plain prose keeps a bare URL https://go.dev/doc/toolchain, a bare #559, PR #433, ADR-0012, and the unknown 0998. + +Inline code keeps `change 0559`, `[a link](https://x.example/y)`, `<!-- docket:artifacts:start -->`, `<https://go.dev/x>`, and `#0563`. + +A double-backtick span keeps ``a `change 0567` b`` too. + +```text +<!-- docket:backlink:start (generated — do not hand-edit) --> +> ↩ **[Change 0563 — a title](../changes/archive/x.md)** +<!-- docket:backlink:end --> +Fixed in change 0567 (0563, 0559). See <https://go.dev/x> and [the docs](https://go.dev/doc). + + +Two blank lines above stay inside the fence. +``` + +~~~markdown +## Reconcile log +--- +title: not frontmatter +--- +[ref]: https://example.com/ref +Change #547, groomed 2026-10-19. +<!-- dckt:artifacts:start --> +~~~ + +Closing prose names change 0998, which no record claims, so it stays. diff --git a/internal/export/testdata/corpus/constructed/frontmatter.md b/internal/export/testdata/corpus/constructed/frontmatter.md new file mode 100644 index 000000000..524041fe4 --- /dev/null +++ b/internal/export/testdata/corpus/constructed/frontmatter.md @@ -0,0 +1,8 @@ +--- +title: A plan saved with a YAML block on top +date: 2026-10-20 +--- + +# A plan saved with a YAML block on top + +Some plan writers open the file with a YAML block. The export drops it and keeps the rest. diff --git a/internal/export/testdata/corpus/plans/2026-10-16-list-the-artifact-backlink-finding-codes-in-the-docket-statu.md b/internal/export/testdata/corpus/plans/2026-10-16-list-the-artifact-backlink-finding-codes-in-the-docket-statu.md new file mode 100644 index 000000000..4ba8738a4 --- /dev/null +++ b/internal/export/testdata/corpus/plans/2026-10-16-list-the-artifact-backlink-finding-codes-in-the-docket-statu.md @@ -0,0 +1,182 @@ +<!-- docket:backlink:start (generated — do not hand-edit) --> +> ↩ **[Change 0539 — Describe repository-check drift findings by family in the docket-status skill](../../changes/archive/2026-10-16-0539-list-the-artifact-backlink-finding-codes-in-the-docket-statu.md)** +<!-- docket:backlink:end --> + +# Describe repository-check drift findings by family in the docket-status skill — Implementation Plan + +> **For agentic workers:** this plan is executed by `docket-build` (one `docket-build-task` worker per task, one whole-suite gate at the end). Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the docket-status skill's incomplete, partly wrong derived-view drift sentence with one that names the finding family and defers to each finding's own remedy, and make the glossary's `repository check` example cover backlinks too. + +**Architecture:** Two prose edits (one shipped skill body, one reference doc), each pinned by a row in the existing `alignmentContracts` table (`internal/repoguard/prose_contracts_test.go`) that asserts the retired wording is gone and the new claim is present. The skill edit grows the file, so its exact-count word ceiling in `internal/repoguard/budgets_test.go` is re-baselined in the same diff, and the embedded asset tree is regenerated. + +**Tech Stack:** Markdown; Go tests (`internal/repoguard`, `internal/assets`); `go generate`. + +**Spec:** none — trivial change. The change record's `## What changes` is the authority: `docs/changes/active/0539-list-the-artifact-backlink-finding-codes-in-the-docket-statu.md` on the `docket` branch. + +## Global Constraints + +- Name the family, never the codes: no finding code list is added anywhere in the skills (the `schema` operation owns codes and shapes; each finding owns its remedy). +- Do not change any finding, its detection, its remedy text, or repair behavior. No Go code outside `internal/repoguard/*_test.go` and the generated `internal/assets/embedded/` tree changes. +- Leave the bash-upgrade guide's findings table alone (deliberate Bash-repository subset). +- Docs describe only current behavior: no change or PR numbers in the skill or glossary prose (they belong only in test comments). +- Spell it "backlink" (one word, no hyphen) — the spelling the glossary heading and `skills/docket-status/SKILL.md` line 46 already use. +- The skill body ships into other repositories: the new sentence must be true in any repository, not only this one. +- Commit subjects follow the repo style: `docs(<area>): <summary> (change 0539)`. +- After any edit under `skills/`, run `go generate ./internal/assets/` and commit the regenerated `internal/assets/embedded/` tree in the same commit. + +## Review Focus + +- A future drift code (say a new `-malformed` or `-shared` form) is added: the new sentence must still be true with no edit — it states a family and a remedy split, not a list. The Task 1 guard asserts the code-list wording stays gone. +- A reader runs `repository.repair` on a `-malformed` or `artifact-backlink-shared` finding expecting it to clear: the skill and glossary must no longer say repair fixes everything. Task 1 asserts "repaired through `repository.repair`" is absent; Task 2 changes the repair comment to say it re-renders only the stale ones. +- The *Sweep posture* line (line 116: a stale `## Artifacts` block surfaces later as an `artifact-links-stale` finding that `repository.repair` re-renders) stays accurate — `artifact-links-stale` is repairable in `internal/reposetup/derived.go`. Leave it unchanged; Task 1 asserts it is still present so the edit cannot drop it by accident. +- A rewrap of the Findings paragraph must not redden the guard: `TestAlignmentContracts` already whitespace-collapses both the file and the phrases, so no extra work — but do not hand-roll a line-anchored grep instead. +- The word-budget ceiling is an exact count: re-baseline it to the measured `wc -w` value, never a rounded-up number with slack. + +--- + +### Task 1: docket-status *Findings* sentence names the drift family and defers to each finding's remedy + +**Files:** +- Modify: `skills/docket-status/SKILL.md:124` (the *Findings* paragraph — one long line) +- Modify: `internal/repoguard/prose_contracts_test.go` (append a row to `alignmentContracts`, just before its closing `}` at ~line 1224) +- Modify: `internal/repoguard/budgets_test.go:215` (the `docket-status/SKILL.md` row of `skillBudgets`) +- Regenerate: `internal/assets/embedded/tree/skills/docket-status/SKILL.md` (and the manifest) via `go generate ./internal/assets/` + +**Interfaces:** +- Consumes: the existing `alignmentContracts` row shape `{sentinel, file, present []string, absent []string}` and the `skillBudgets` row shape `{rel, maxLines, maxWords}`. +- Produces: sentinel name `change_0539_drift_family`, which Task 2 reuses for its glossary row. + +- [ ] **Step 1: Write the failing guard row** + +Append to `alignmentContracts` in `internal/repoguard/prose_contracts_test.go`: + +```go + // change 0539 — the docket-status Findings paragraph names the derived-view + // drift family and defers to each finding's own remedy; it no longer lists + // codes (the list drifted) or claims repair clears every drift finding + // (-malformed and artifact-backlink-shared need a hand edit first). The + // Sweep posture's artifact-links-stale line stays: that code is repairable. + {sentinel: "change_0539_drift_family", file: "skills/docket-status/SKILL.md", + present: []string{ + "is reported by the `repository.check` operation. Each finding carries its own remedy", + "Relay the finding's remedy rather than telling the human to just run repair", + "surfaces later as an `artifact-links-stale` finding that the authorized `repository.repair` operation re-renders", + }, + absent: []string{ + "and their `-malformed` forms", + "and repaired through `repository.repair`", + }}, +``` + +- [ ] **Step 2: Run it to verify it fails** + +Run: `go test ./internal/repoguard -run TestAlignmentContracts -count=1` +Expected: FAIL, with `[change_0539_drift_family]` messages for the two missing `present` phrases and the two forbidden `absent` phrases (the third `present` phrase already holds). + +- [ ] **Step 3: Replace the drift sentence in `skills/docket-status/SKILL.md`** + +In the *Findings* paragraph (line 124), replace exactly this sentence: + +> Derived-view drift (`board-stale`, `adr-index-stale`, `artifact-links-stale`, and their `-malformed` forms) is reported by the `repository.check` operation and repaired through `repository.repair`. + +with this text (keep it on the same single line; do not touch the rest of the paragraph or the *Sweep posture* line): + +> Derived-view drift — the board, the ADR index, a change's `## Artifacts` block, or the backlink at the top of a spec, plan, or results file being out of date or broken — is reported by the `repository.check` operation. Each finding carries its own remedy: most clear with `repository.repair`; a broken marker, or a file linked from more than one change, needs a hand edit first. Relay the finding's remedy rather than telling the human to just run repair. + +- [ ] **Step 4: Run the guard to verify it passes** + +Run: `go test ./internal/repoguard -run TestAlignmentContracts -count=1` +Expected: PASS. + +- [ ] **Step 5: Mutation-check the guard** + +Restore the old sentence in a scratch copy only: `cp skills/docket-status/SKILL.md /tmp/0539-skill.bak`, put the old sentence back in the working file, run `go test ./internal/repoguard -run TestAlignmentContracts -count=1` and confirm FAIL naming `change_0539_drift_family`; then `cp /tmp/0539-skill.bak skills/docket-status/SKILL.md` (never `git checkout --`, which would discard the uncommitted edit) and re-run to confirm PASS. + +- [ ] **Step 6: Re-baseline the word budget at the exact new count** + +Run: `wc -lw skills/docket-status/SKILL.md` (was `126 2923`; lines should stay 126, words grow by roughly 50). +Run: `go test ./internal/repoguard -run TestSkillSizeBudgets -count=1` — Expected: FAIL, `docket-status/SKILL.md is <N> words, over its 2923-word budget`. +Edit the `docket-status/SKILL.md` row in `skillBudgets` to `{"docket-status/SKILL.md", 126, <N>}` with `<N>` the measured count, and prepend to that row's trailing comment: `0539: derived-view drift is named by family and each finding's own remedy is relayed instead of a code list (126/2923 -> 126/<N>); `. +Re-run: `go test ./internal/repoguard -run TestSkillSizeBudgets -count=1` — Expected: PASS. + +- [ ] **Step 7: Regenerate embedded assets and check the drift guard** + +Run: `go generate ./internal/assets/` +Run: `go test ./internal/assets -count=1` +Expected: PASS (`TestEmbeddedMatchesAuthored` confirms the embedded copy matches `skills/`). `git status` shows `internal/assets/embedded/tree/skills/docket-status/SKILL.md` (and the manifest if it hashes content) modified. + +- [ ] **Step 8: Commit** + +```bash +git add skills/docket-status/SKILL.md internal/repoguard/prose_contracts_test.go internal/repoguard/budgets_test.go internal/assets/embedded +git commit -m "docs(docket-status): describe derived-view drift by family and relay each finding's remedy (change 0539)" +``` + +--- + +### Task 2: glossary `repository check` / `repair` example covers backlinks and the remedy split + +**Files:** +- Modify: `docs/reference/glossary.md:300-301` (the `sh` example under *Derived view / generated block / backlink*) +- Modify: `internal/repoguard/prose_contracts_test.go` (append one more row after Task 1's) + +**Interfaces:** +- Consumes: sentinel `change_0539_drift_family` from Task 1. +- Produces: nothing later tasks use. + +- [ ] **Step 1: Write the failing guard row** + +Append after Task 1's row: + +```go + {sentinel: "change_0539_drift_family", file: "docs/reference/glossary.md", + present: []string{ + "# reports links blocks and backlinks that are stale or broken", + "# re-renders the stale ones in one metadata commit", + }, + absent: []string{"stale or absolute"}}, +``` + +- [ ] **Step 2: Run it to verify it fails** + +Run: `go test ./internal/repoguard -run TestAlignmentContracts -count=1` +Expected: FAIL with `[change_0539_drift_family]` messages for `docs/reference/glossary.md` (two missing, one forbidden). + +- [ ] **Step 3: Edit the example block** + +Replace the two lines: + +```sh +docket repository check # reports records whose links are stale or absolute +docket repository repair # re-renders them in one metadata commit +``` + +with (keep the comment column aligned): + +```sh +docket repository check # reports links blocks and backlinks that are stale or broken +docket repository repair # re-renders the stale ones in one metadata commit +``` + +The repair comment changes because a broken (malformed or shared) backlink needs a hand edit before repair can re-render it; "re-renders them" would now claim otherwise. + +- [ ] **Step 4: Run the guard to verify it passes** + +Run: `go test ./internal/repoguard -run TestAlignmentContracts -count=1` +Expected: PASS. + +- [ ] **Step 5: Commit** + +```bash +git add docs/reference/glossary.md internal/repoguard/prose_contracts_test.go +git commit -m "docs(glossary): repository check covers backlinks; repair re-renders only stale views (change 0539)" +``` + +--- + +### Final verification (whole suite) + +- [ ] Run: `go run ./cmd/docket development test` + Expected: exit 0. (`docs/` is not embedded, so Task 2 needs no regeneration; `go test ./internal/assets -count=1` was already green after Task 1.) +- [ ] Confirm the diff touches only: `skills/docket-status/SKILL.md`, `docs/reference/glossary.md`, `internal/repoguard/prose_contracts_test.go`, `internal/repoguard/budgets_test.go`, and `internal/assets/embedded/**`. diff --git a/internal/export/testdata/corpus/results/2026-10-08-release-v1-0-0-rc-1-claude-code-and-cursor-tested-opencode-s-results.md b/internal/export/testdata/corpus/results/2026-10-08-release-v1-0-0-rc-1-claude-code-and-cursor-tested-opencode-s-results.md new file mode 100644 index 000000000..ed4f59cde --- /dev/null +++ b/internal/export/testdata/corpus/results/2026-10-08-release-v1-0-0-rc-1-claude-code-and-cursor-tested-opencode-s-results.md @@ -0,0 +1,49 @@ +<!-- docket:backlink:start (generated — do not hand-edit) --> +> ↩ **[Change 0544 — Release v1.0.0-rc.1: Claude Code and Cursor tested, OpenCode shipped untested](../changes/archive/2026-10-08-0544-release-v1-0-0-rc-1-claude-code-and-cursor-tested-opencode-s.md)** +<!-- docket:backlink:end --> + +# v1.0.0-rc.1 release candidate publication — Results + +**Human action:** None needed to merge. `v1.0.0-rc.1` is already tagged and published as the "Latest" full release; this PR adds the evidence bundle and the install-doc updates. Optionally, delete the local test folders listed below. + +## Outcome + +Docket `v1.0.0-rc.1` is public as a full release and is now "Latest", replacing `v0.9.3`: https://github.com/danielhanold/docket/releases/tag/v1.0.0-rc.1. + +- Cut from `main` at `d0f4712a53bd6a158fddada91cdf612f1755a531`, packaged once by release-candidate run 37844907335; `main` stayed at the candidate from the cut through publication. +- Six assets (four platform archives, `checksums.txt`, `install.sh`), each equal in name, size and SHA-256 to the read-only copy. +- No harness was re-tested by hand: Claude Code was proven in alpha.1 and Cursor in alpha.2, and the candidate's source is identical to alpha.2 (documentation-only diff). OpenCode is shipped untested; Codex is unsupported. +- A fresh install from the public release URL passed, with no quarantine attribute and a valid ad-hoc signature on the binary. +- The install docs now lead with the release downloader and state harness status. + +The evidence is in `docs/release/v1.0.0-rc.1/`; its `README.md` holds the candidate identity and the gate table. + +## Human actions and testing + +This was a human-attended release; Daniel attested no loops were running and gave the explicit "publish" after approving the notes. The gate table is the human-verify record: + +| Phase | Verdict | Record | +|---|---|---| +| 0 — Before the cut | pass | `decisions.md` | +| 1 — Cut and freeze | pass | `decisions.md` | +| 2 — Package once | pass, no STOP, no waiver | `candidate/run.txt` | +| 3 — Harness test | none by design; coverage statement recorded | `decisions.md` | +| 4 — Publish | pass, at Daniel's explicit "publish" | `publication.md` | +| 5 — Public install | pass | `public-install.md` | + +**Optional — clean up the test material.** Delete the local folders `~/docket-rc1-public-test` (the public-install test home), `~/docket-rc1-candidate` (the read-only bundle copy; `chmod -R u+w` first) and `~/docket-rc1-gate-run` (gate run logs). Nothing in the repository depends on them. + +## Verification performed + +- **Package:** run 37844907335 green on all seven jobs at the candidate. Source gate `SUITE files=86 passed=86 failed=0` on go1.26.8, including `test_go_integration_bashupgrade` `rc=0 ok=4`; ten `BUDGET WATCH` screening lines, no `SERIAL CONFIRMED OVER BUDGET`. +- **Candidate:** `evidence.json` names the candidate and `v1.0.0-rc.1`; its `checksums_txt` is byte-equal to `checksums.txt`. +- **Publication:** tag object `5df38f85…` peels to the candidate; the release is a full release and "Latest"; asset digests equal the read-only copy. +- **Public install:** `install.sh: OK` against the published `checksums.txt` before running it; `docket version` reported `v1.0.0-rc.1` at the candidate; `install check` clean for `[claude, cursor]`; `supported_target` true; `xattr` shows no `com.apple.quarantine`; `codesign -v` valid. +- **Build gate (this PR):** see the PR body for the gate result at the final head. +- **Review:** none. This change carries release evidence and install docs only, and is not built through implement-next. + +## Known issues and follow-ups + +- **Cursor's subagent model pins are unconfirmed.** Listed as a known gap in the release notes. Next action: Fits #545. +- **Cursor's documented "Allowlist (with Sandbox)" mode was not exercised.** Listed as a known gap in the release notes. Next action: none decided. +- **The binaries are not notarized.** A browser-downloaded archive is blocked by macOS Gatekeeper; the install docs and notes say to use the script. Next action: none decided; notarization is out of scope. diff --git a/internal/export/testdata/corpus/results/2026-10-17-let-change-groom-clear-stacked-on-results.md b/internal/export/testdata/corpus/results/2026-10-17-let-change-groom-clear-stacked-on-results.md new file mode 100644 index 000000000..5d9ca09d9 --- /dev/null +++ b/internal/export/testdata/corpus/results/2026-10-17-let-change-groom-clear-stacked-on-results.md @@ -0,0 +1,37 @@ +<!-- docket:backlink:start (generated — do not hand-edit) --> +> ↩ **[Change 0563 — change.groom: clear stacked_on, accept relationship-only revises, insert missing fields safely](../changes/archive/2026-10-18-0563-let-change-groom-clear-stacked-on.md)** +<!-- docket:backlink:end --> + +# change.groom: clear stacked_on, accept relationship-only revises, insert missing fields safely — Results + +**Human action:** No action is required to merge. Two follow-ups below are for backlog triage: three old deferred records still can't be revived or groomed, and there is no typed way to clear `branch:` on a proposed change. + +## Outcome + +`change.groom` can now un-stack a proposed change. Send `stacked_on: 0` and the record gets the empty `stacked_on:` key, so the change builds from the integration branch again. Omitting the field or sending `null` still leaves it unchanged. A negative value is refused with `invalid-stacked_on`. `deliverable: results-artifact` together with `stacked_on: 0` is accepted, which turns a stacked change into a results-artifact change in one step. + +Changing `stacked_on` on a change that already has a `branch:` is now refused with the new code `not-restackable`. That covers setting a first parent, re-parenting, and clearing. Sending the value the record already has still passes. The refusal says what actually lifts it: decide what to keep from the branch, then clear the record's `branch:` by hand, or kill the change and capture a new one. Deleting the git branch alone does not lift it. + +A revise that changes only relationship fields (`depends_on`, `related`, `discovered_from`, `adrs`, `stacked_on`) is no longer refused as `empty-revise`. + +Groom now writes every frontmatter field one at a time, adding the key when the record lacks it. Records missing `stacked_on:`, `discovered_from:`, `auto_groomable:` or `updated:` used to fail with a missing-target or `overlapping-edit` error. They now groom normally. + +The groom-next skill and the stacked-changes reference now describe the typed un-stack path. Both files had to be trimmed to stay within their size budgets, and a prose-contract sentinel now protects the new Stacking guidance. + +## Verification performed + +- Full suite (`go run ./cmd/docket development test`) passed at the final head. The first run failed only `TestSkillSizeBudgets`, because the new skill text went over budget. A repair commit trimmed both files without raising the ceilings. +- Budget screening reported `BUDGET WATCH` and `PARALLEL-SENSITIVE` lines for several integration test files under `-j11`, with no `SERIAL CONFIRMED OVER BUDGET` line. These come from parallel contention, and this change touched none of those tests. +- Workers mutation-tested the new tests. Routing two inserts back through one patch set, writing `0` as a parent id, making `stackedOnChanges` always return true, and dropping the finding-code registration each turned the relevant tests red. +- Whole-branch review (deep tier) returned 3 findings. 1 important and 1 minor were fixed in-branch. The other minor is reported as a follow-up below. The full table is in the PR body. +- Backlog check: the 24 proposed and deferred changes were checked by title and scope. + +## Known issues and follow-ups + +### Records 0007, 0009 and 0010 still can't be revived or groomed + +These three deferred records have no generated `## Artifacts` block. Revive and groom both rewrite that block, so both still fail with a missing-patch-target error on them. This is confirmed by code reading, not by running it. The other seven records the spec names (0008, 0195, 0248, 0257, 0263, 0273, 0302) do have the block and now groom correctly. The "0007-shaped" test fixture keeps an artifacts block, so it covers only the missing frontmatter keys. Workaround: run `repository.repair`, or add the block by hand before reviving. Suggested next action: insert the block on revive and groom when it's missing, or repair the three records. No existing change fits (checked 24). Capture a new change. + +### No typed way to clear `branch:` on a proposed change + +`not-restackable`'s remedy requires clearing `branch:` by hand, or killing the change and capturing a new one. Nothing else clears that field on a proposed record. This is confirmed. It only affects changes that were claimed and later deferred or reclaimed while they had a branch. Suggested next action: add an explicit typed operation if this comes up in practice. Related to #565 (killed-parent stacking, the main reason to un-stack). Capture a new change that links #565 under `related:`. diff --git a/internal/export/testdata/corpus/specs/2026-06-04-migration-tool-pwd-target-design.md b/internal/export/testdata/corpus/specs/2026-06-04-migration-tool-pwd-target-design.md new file mode 100644 index 000000000..effe3d820 --- /dev/null +++ b/internal/export/testdata/corpus/specs/2026-06-04-migration-tool-pwd-target-design.md @@ -0,0 +1,53 @@ +# Design: migrate-to-docket.sh targets the invoking repo ($PWD) + +**Status:** design (brainstormed 2026-06-04) +**Change:** 0003 +**Related:** change 0002 (introduced `migrate-to-docket.sh`); ADR-0002 (docket-mode default + refuse-and-migrate bootstrap) + +## 1. Context / problem + +`migrate-to-docket.sh` (shipped by change 0002) opens with `cd "$SCRIPT_DIR"`, so it migrates the repo it physically lives in — the **docket repo itself**. It is also not distributed to consuming repos (the *skills* are symlinked globally by `link-skills.sh`; the script is not). So migrating any **other** repo cannot use the script as-is. Real instance: `~/dev/obsidian-wiki` was migrated to docket-mode by **manual staged git steps**, and one step (the `.gitignore` `.docket/` entry — the script's step 5) was nearly missed and only caught in verification. See memory `docket-migration-tool-not-distributed`. + +## 2. Decision + +Retarget the script to operate on **the git repo containing the invocation directory (`$PWD`)**, not its own location. Reachability stays **minimal**: invoke docket's single copy by absolute path from within the target repo — + +``` +cd <target-repo> && bash ~/dev/docket/migrate-to-docket.sh +``` + +Because the script now acts on **whatever repo you are standing in** — and it does branch surgery + prune + push — guard it with a **confirmation prompt** (bypassable for automation). + +Rejected (out of scope, §5): global distribution (symlink / PATH install) and skill-ifying the migration. The script stays docket-repo-resident; only its **target resolution** and a **confirm guard** change. + +## 3. Design + +- **Target resolution.** Replace `SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"; cd "$SCRIPT_DIR"` with: + ```bash + REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" \ + || die "not inside a git repo — cd into the repo you want to migrate, then re-run." + cd "$REPO_ROOT" + ``` + `SCRIPT_DIR` / `BASH_SOURCE` are no longer used — the script's own location is irrelevant; it migrates `$PWD`'s repo. +- **Confirmation guard.** After the resolved-config banner, print `Target repo: <REPO_ROOT>` (plus the resolved `integration_branch` and `metadata_branch` target), then prompt `Migrate this repo to docket-mode? [y/N] ` reading from **`/dev/tty`** (so a piped or empty stdin cannot silently auto-confirm); abort unless the answer is `y`/`yes`. A **`--yes`/`-y`** flag, parsed at startup, skips the prompt for non-interactive use. +- **Unchanged:** all preconditions (clean tree; `require_ref` on the integration ref; abort-if-`origin/docket`-exists) and the seed → prune → `.gitignore` → idempotency logic. They already operate relative to the resolved repo root + config, so they work as-is once `cd "$REPO_ROOT"` points at the right repo. + +## 4. What changes (touch-points) + +- **`migrate-to-docket.sh`** — target resolution (§3); `--yes`/`-y` flag parse; confirmation prompt; update the header-comment usage block to `cd <target-repo> && bash /path/to/docket/migrate-to-docket.sh`. +- **`tests/test_docket_metadata_branch.sh`** — add assertions: resolves the target via `git rev-parse --show-toplevel`; no longer contains `cd "$SCRIPT_DIR"`; a `--yes`/`-y` bypass exists. The existing `migrate-to-docket.sh` assertions (exists, executable, creates orphan, prunes) stay green. +- **`README.md`** — migration section: the new invocation (run from *within* the target repo) + the confirm/`--yes` note; drop any wording implying the script only migrates the docket repo. + +## 5. Out of scope + +- **Distributing** the script (symlink/PATH install) or making migration a **skill** — declined; reachability stays "invoke by absolute path." Revisit as a separate change if it becomes painful in practice. +- **Auto-running** migration from the bootstrap guard — the guard still STOPs and points to the script; "refuse, never auto-migrate" (ADR-0002) stands. +- The **migration's behavior** (seed/prune sets, idempotency split, `ls-tree` probes) — unchanged. + +## 6. Testing + +TDD-for-docs/script: extend `tests/test_docket_metadata_branch.sh` with the §4 assertions; `bash -n migrate-to-docket.sh` clean; at build time, a real exercise — run it from a **subdirectory** of a throwaway repo to confirm `$PWD`→`--show-toplevel` resolution, the confirmation prompt, and the `--yes` bypass. + +## 7. Open questions + +None. An env-var alias for the bypass (e.g. `DOCKET_MIGRATE_YES=1`) is a build-time nicety, not a design decision. diff --git a/internal/export/testdata/corpus/specs/2026-07-10-docket-skill-slimming-design.md b/internal/export/testdata/corpus/specs/2026-07-10-docket-skill-slimming-design.md new file mode 100644 index 000000000..b4c82e77b --- /dev/null +++ b/internal/export/testdata/corpus/specs/2026-07-10-docket-skill-slimming-design.md @@ -0,0 +1,157 @@ +# Design: slim docket-convention + docket-status via progressive disclosure + +**Date:** 2026-07-10 · **Change:** 0053 · **Depends on:** 0051 (feat/global-agents-middle-layer, PR #60) + +## Problem + +The docket skill bodies have grown past the point where their size costs more than it buys. +`docket-convention` — loaded as blocking Step 0 by **every** docket skill on **every** run — is +349 lines / ~5,500 words on `main` and grows to **380 lines / ~6,000 words (~8k+ tokens)** once +change 0051 merges. `docket-status` (185 lines / ~2,820 words) runs on every implement cycle +(step-0 dispatch) at a small pinned model. Every token in these two bodies is paid on nearly +every docket operation, competing with the actual work's context. + +## Research findings (2026-07-10) + +Authoritative guidance, with sources: + +- **"Keep SKILL.md body under 500 lines for optimal performance."** Stated three times in + Anthropic's skill-authoring best practices + (<https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices>). All docket + skills pass this — but the agentskills.io spec (<https://agentskills.io/specification>) adds + **"Instructions (< 5000 tokens recommended)"**, which docket-convention exceeds ~1.7×. +- **"Concise is key. The context window is a public good."** And: **"Default assumption: Claude is + already very smart. Only add context Claude doesn't already have."** (Anthropic best practices.) +- **Frequently-loaded skills should be far smaller than the 500-line ceiling** — superpowers' + writing-skills targets **< 200 words** for skills loaded often (<https://github.com/obra/superpowers>). +- **The official recipe for a shared-contract skill** is progressive disclosure: invariants and a + routing table inline; per-domain detail in **one-level-deep** reference files. "If certain + contexts are mutually exclusive or rarely used together, keeping the paths separate will reduce + the token usage" (<https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills>). +- **"Prefer scripts for deterministic operations."** (Anthropic best practices.) docket already + does this well — 13 helper scripts with co-located `.md` contracts (ADR-0012 boundary). The + remaining prose is coordination and judgment, which is correct to keep in-model. +- **Named risks of splitting:** links must be loud and explicit or Claude skips them; reference + chains deeper than one level get partially read (`head -100`); reference files > 100 lines need + a leading TOC; cuts a frontier model tolerates can degrade a smaller model — "test with all + models you plan to use." `docket-status`'s wrapper pins a small model, so its imperative steps + must stay explicit. +- **Degradation mechanism** is attention dilution and instruction-count limits ("frontier thinking + LLMs can follow ~150-200 instructions with reasonable consistency", + <https://www.humanlayer.dev/blog/writing-a-good-claude-md>) — trimming redundancy and narration + raises compliance on what remains. + +## Decisions (brainstormed 2026-07-10, human-approved) + +1. **Scope:** one change (0053) concretely optimizes `docket-convention` + `docket-status`; the + spec carries the strategy + a categorization of all eight skills; follow-up stubs are minted + for the rest (0054, 0055). +2. **Provenance narration is cut, not relocated.** Change-number archaeology and + rejected-alternative asides ("change 0043's tiers were rejected", "retired by change 0024", + "the #0035 footgun") are deleted from skill prose. Where a rule genuinely needs a *why*, a bare + `(ADR-NNNN)` pointer remains. History stays fully recoverable in ADRs, the change archive, and + git blame. +3. **Structure: core + reference split** (not trim-in-place, not aggressive-minimal-core). + Behavior-neutral: every rule either stays inline, moves to a one-level-deep reference file + behind a loud blocking pointer, or already lives in a script contract. **No contract semantics + change.** + +## Design + +### 1. docket-convention — core + references + +Target: **~380 → ~190 lines, ~6,000 → ~2,400 words.** + +**Stays inline** (needed on virtually every run): the `.docket.yml` block + config-layer +resolution summary, the `DOCKET_SCRIPTS_DIR` mechanism, script-contract pointer rule, directory +layout, change manifest, change body sections, ADR format, lifecycle (diagram + table + rules), +build-readiness & selection, autonomous grooming, learnings ledger (compressed), bootstrap verdict +handling, branch model (compressed), and the skill-layer roles table + `auto`/missing-skill rule +(compressed to the table + ~4 bullets). + +**Moves to references** (one level deep, loud pointers): + +- **`references/agent-layer.md`** — the full Agent-layer deep-dive: harness-first `agents:` + resolution, `agent_harnesses` scoping (user-level vs per-repo passes), harness-portable model + IDs, always-full-set generation, the Cursor dispatch rule, `sync-agents.sh` mechanics and + `--check` legs. SKILL.md keeps ~10 lines: wrappers exist (five skills wrapped, eight wrappers, + three wrap no skill), the composition/dispatch contract (foreground, git-state-not-in-context + return, abort-and-report), and the pointer: *"Read `references/agent-layer.md` now (blocking) + before configuring `agents:`/`agent_harnesses:` or running/debugging `sync-agents.sh`."* No + runtime skill needs this section; only humans (or agents) configuring the agent layer do — + the textbook mutually-exclusive context. +- **`references/terminal-close-out.md`** — **new single source** for the shared per-change + close-out sequence: archive (`archive-change.sh`) → re-render `## Artifacts` + (`render-change-links.sh`, follow-on commit, push **before** publish) → terminal-publish + (`terminal-publish.sh`) → cleanup (`cleanup-feature-branch.sh`) → board refresh — plus a + per-caller **failure-posture table** (finalize: abort-and-report; status sweep: + log-and-continue with the failed-re-render-skips-publish guard; producer kill and + implementer reconcile-kill), the archive-first ordering rationale, the UTC-date rule, and the + `main`-mode degradation. Today this sequence is restated in four skills, each carrying + "identical — must not diverge" warnings; the duplication *is* the drift risk it warns about. +- **`github-board-mirror.md`** stays as is (already correct progressive disclosure). + +**Guardrails:** + +- Other skills cite convention sections by name ("per the convention's *Branch model*", + "*Learnings ledger*", "*Skill layer*", "*GitHub board mirror*"). Every kept section heading + stays byte-stable; a grep sweep across `skills/` and `agents/` verifies no dangling anchor. +- Any reference file > 100 lines opens with a table of contents. +- References are one level deep from SKILL.md; reference files may point at script contracts + (`scripts/*.md`) since those are terminal reads. + +### 2. docket-status — delegate to executable sources + +Target: **~185 → ~100 lines, ~2,820 → ~1,500 words.** + +- **Delete the board Structure section + abbreviated rendered example (~55 lines).** + `render-board.sh` is the executable source of the structure (its contract + `scripts/render-board.md` documents the output). The skill keeps: the invocation, the commit + discipline, the regenerate-never-3-way-merge conflict rule, and the readiness-cell semantics + that health checks share (the dependency-resolution pass section, already compact, stays). +- **Sweep steps c–e collapse** to a pointer into `references/terminal-close-out.md` + ~6 lines of + sweep-specific posture: per-change log-and-continue, the failed-re-render-skips-publish guard, + the determinism invariant one-liner. +- Cut the retired-drift-check historical footnote and other narration. +- Compress the Step-0 preamble (see §3). +- **Small-model constraint:** status's wrapper pins a small model; every remaining step stays an + explicit numbered imperative. Cuts remove duplication and narration — never step explicitness. + +### 3. Cross-cutting — the Step-0 preamble becomes convention-owned + +The preamble (load convention → `docket-config.sh --export` → act on `BOOTSTRAP` → metadata-tree +ensure/sync + `main`-mode degradation) appears near-verbatim in all seven operating skills +(~15–20 lines each). The convention gains one named section — **"Step-0 preamble"** — as its +single source; each skill's copy compresses to ~3 lines ("Run the convention's *Step-0 preamble*; +this skill's writes land on <X>"). 0053 applies this to `docket-status` (and the convention side); +0054/0055 propagate it to the remaining skills. + +### 4. Categorization of the remaining skills + +| Skill | Post-0051 size | Optimization potential | Risk of losing intelligence | Verdict | +|---|---|---|---|---| +| docket-finalize-change | 234 L / 3.5k w | **High** — rewire archive/publish prose to `terminal-close-out.md`; compress gate + selection prose | **Medium-high** — the merge gate is docket's highest-blast-radius path; gate flow, sign-off rule, and abort-and-report set must survive verbatim in meaning | Stub **0054** | +| docket-implement-next | 137 L / 2.9k w | **Medium** — the `render-change-links.sh` litany is restated 4×; Step-0/mode boilerplate; reconcile-kill rewires to close-out ref | **Medium** — its repetition is partly deliberate reinforcement for an autonomous agent; dedupe conservatively, keep the branch/metadata discipline section | Stub **0055** | +| docket-new-change | 70 L / 1.4k w | Low-medium — proposed-kill sub-path → close-out ref; Step-0 compression | Low | Fold into 0055 | +| docket-groom-next | 77 L / 1.5k w | Low — Step-0 compression only | Low | Fold into 0055 | +| docket-adr | 88 L / 1.3k w | Low — Step-0 compression only | Low | Fold into 0055 | +| docket-auto-groom | 64 L / 1.2k w | Low — already lean | Low | Fold into 0055 | + +### 5. Verification (build-time acceptance) + +1. **Anchor grep-gate:** no skill, agent wrapper, or script contract references a convention + section heading that no longer exists. +2. **Behavior-neutrality review:** a diff-level check that every deleted sentence is (a) narration, + (b) restated elsewhere inline, (c) moved to a reference file, or (d) covered by a script + contract. No invariant simply vanishes. +3. **Smoke run:** post-refactor `docket-status` end-to-end (board + sweep + health checks) on this + repo; `link-skills.sh` / `sync-agents.sh` untouched by construction. +4. **Size targets asserted** in the PR description: convention ≤ ~200 lines / ≤ 2,500 words; + status ≤ ~110 lines / ≤ 1,600 words; every reference file ≤ ~150 lines with TOC if > 100. + +## Out of scope + +- Any semantic change to the convention, config resolution, lifecycle, or close-out behavior. +- Editing docket-finalize-change / docket-implement-next / the four small skills (stubs 0054/0055). +- New scripts or changes to existing script contracts. +- Frontmatter `description:` rewrites (triggering is unaffected by this change). diff --git a/internal/export/testdata/corpus/specs/2026-07-26-cursor-agent-wrapper-contract-design.md b/internal/export/testdata/corpus/specs/2026-07-26-cursor-agent-wrapper-contract-design.md new file mode 100644 index 000000000..816e3623f --- /dev/null +++ b/internal/export/testdata/corpus/specs/2026-07-26-cursor-agent-wrapper-contract-design.md @@ -0,0 +1,319 @@ +<!-- docket:backlink:start (generated — do not hand-edit) --> +> ↩ **[Change 0135 — Generated Cursor wrappers violate Cursor's subagent contract, disabling skills and model effort](../../changes/archive/2026-07-28-0135-cursor-agent-wrapper-contract.md)** +<!-- docket:backlink:end --> + +# Cursor agent wrapper contract — design + +Change: #0135 · Type: fix · Groomed: 2026-07-26 + +## Problem + +Docket generates Cursor subagent wrappers through the **generic Claude-shaped emitter**. In +`sync-agents.sh`, `emit_for_harness()` routes `codex` to its own emitter and passes *everything +else* — including `cursor` — through `emit()`, which preserves the source wrapper's Claude +frontmatter verbatim: + +```yaml +model: claude-opus-4-8 +effort: xhigh +skills: [docket-implement-next, docket-convention] +``` + +Cursor's [subagent contract](https://cursor.com/docs/subagents) documents exactly five frontmatter +fields — `name`, `description`, `model`, `readonly`, `is_background` — and encodes reasoning effort +*inside* the model value (`claude-opus-5[effort=high]`). Neither a standalone `effort:` field nor a +`skills:` preload exists. Docket therefore emits two fields Cursor ignores and one pin Cursor cannot +read, while reporting all three as honored. + +The observed consequence: a live `docket-implement-next` run under Cursor produced a plausible PR in +which `plan`, `build`, `review`, and `finish` had all silently degraded to their inline `auto` +fallbacks. The child had no docket instructions and no reason to load them, so +`superpowers:subagent-driven-development`'s fresh per-task implementers, TDD gates, and independent +review never ran. This is the third instance of the `skill-fallback-degrades-discipline` learning +(#0066, re-hit #0136): complete-looking artifacts concealing an unrun discipline. + +## What this change is really for + +ADR-0059 (from change #0137) decided the harness-neutral rule: dispatch capability is **resolved, +never inferred from a tool name**, and unavailability is **tiered** — with `skills.build` and +`skills.review` on the strictest tier, **authorized-or-halt** (an explicitly configured `auto` is the +human's authorization to run inline; any other configured value that cannot dispatch is +abort-and-report). + +That rule currently **cannot reach a Cursor child at all**, because docket delivers the convention +through `skills:` — the one field Cursor ignores. #0137 fixed the Claude Code twin and delivered its +fix as docket-convention prose, through the very channel Cursor is broken on. **Repairing wrapper +delivery here is the prerequisite for any convention-level rule reaching Cursor.** The two changes +share the ADR, not the mechanism, and stay `related:` rather than `depends_on:` — neither gates the +other. + +## Grooming findings that changed the stub's premises + +Two of the stub's open questions were answered from Cursor's live documentation and from +`superpowers:subagent-driven-development`'s own flowchart, and one of them **invalidates a stated +fear**. Both are recorded here because the design depends on them. + +### Finding 1 — the nesting fear was unfounded + +The stub asked: *"What is Cursor's actual Task nesting limit? Docket's tree runs three deep (wrapper +→ SDD implementer → task reviewer). If the limit is below three, SDD genuinely cannot run on +Cursor."* + +Cursor documents a limit of **two**: *"The main agent and its direct subagents can launch subagents, +but a subagent launched by another subagent can't launch further ones."* + +But docket's tree does **not** run three deep. `superpowers:subagent-driven-development`'s topology +is **flat**: the orchestrator dispatches implementers, task reviewers, fix subagents, *and* the final +whole-branch reviewer. The implementer never dispatches — it implements, tests, commits, +self-reviews, and returns a status, after which the *orchestrator* writes the diff file and +dispatches the task reviewer. So the real tree is: + +``` +main chat → docket-implement-next wrapper → SDD implementer / task reviewer / fix / final reviewer + (depth 0) (depth 1, a direct subagent) (depth 2, siblings — none of them dispatch) +``` + +Depth 2 is exactly what Cursor permits. **SDD is genuinely reachable on Cursor**; no halt posture is +required for nesting. The residual risks are tool-policy denial and mode restrictions ("Nested +launches also need Task tool access in the current mode, and hooks or tool policies can block +spawning"), which ADR-0059's resolve-then-attempt rule and Tier C already govern. + +*Evidence scope: cursor.com/docs/subagents as of 2026-07-26, and superpowers 6.1.1's +`subagent-driven-development/SKILL.md`. Re-check both if either moves.* + +### Finding 2 — skills are discoverable; only the preload field is fake + +Cursor auto-discovers skills from `.cursor/skills/` and `~/.cursor/skills/` (among others), and +`link-skills.sh` **already symlinks every docket skill into `~/.cursor/skills/`**. Cursor documents no +frontmatter for attaching skills to an agent, but the skills are present and invocable. + +So `skills: [...]` is not failing because the skills are absent. It is failing because it is an +ignored field with **no body instruction behind it** — the child is never told to load anything. +This is what makes the fix cheap: an instruction, not an installation. + +## Design + +### 1 — `emit_cursor_md()`: a named Cursor emitter + +A new emitter in `sync-agents.sh`, structurally parallel to the existing `emit_codex_toml()` (same +extraction of `name` / `description` / `model` / `effort` / `skills` / body from the source wrapper, +same preamble-before-body assembly). + +**Frontmatter.** Only Cursor's documented fields, and only three of the five: + +```yaml +name: docket-implement-next +description: <verbatim from the source wrapper> +model: claude-opus-4-8[effort=xhigh] +``` + +`readonly` and `is_background` are **not emitted**. Their defaults are already correct for every +docket agent: the agents commit and push (so not readonly), and every docket dispatch is foreground +(so not background). Emitting them would assert a policy docket does not have. + +**Model/effort encoding — verbatim passthrough, no validation.** Per ADR-0015 (harness-portable model +IDs are opaque passthrough) and ADR-0059's rejection of per-harness name tables as a class: + +| resolved model | resolved effort | emitted | +|---|---|---| +| `claude-opus-4-8` | `xhigh` | `model: claude-opus-4-8[effort=xhigh]` | +| `claude-opus-4-8` | unset or `auto` | `model: claude-opus-4-8` | +| unset or `inherit` | unset or `auto` | *(no `model:` line)* | +| unset or `inherit` | `xhigh` | *(no `model:` line)* **+ generation-time WARN** | + +Docket keeps **no allowlist of Cursor model IDs and no allowlist of effort tokens**. Cursor's own +documented compatible-model fallback handles anything it does not recognize. A committed table of a +vendor's internals is the exact artifact ADR-0059 rejected: it goes stale silently, and a stale entry +produces a *false negative* that reads as a successful degrade. + +**The `inherit` + effort edge case is deliberately loud.** Effort has nowhere to attach without a +model, so the pin is dropped — and a dropped pin must never be silent, since silently-dropped pins +are the defect this whole change exists to fix. `sync-agents.sh` logs: + +``` +WARN cursor/docket-<name>: effort '<e>' dropped — Cursor encodes effort inside the model value, + and the resolved model is 'inherit'. Set an explicit model to pin effort on Cursor. +``` + +**Body.** The skills preamble, then the source wrapper's body verbatim. Preamble emitted only when +the source has a non-empty `skills:` list, mirroring `emit_codex_toml`'s conditional: + +``` +Before acting, load these docket skills from your Cursor skills directory: +docket-implement-next, docket-convention. +``` + +Rejected alternative: inlining the full skill text into each wrapper. It makes wrappers thousands of +lines, drifts against the skill sources on every edit, and duplicates what `link-skills.sh` already +installs. + +### 2 — `emit_for_harness()` gains named branches + +```sh +case "$2" in + codex) emit_codex_toml "$1" "$3" "$4";; + cursor) emit_cursor_md "$1" "$3" "$4";; + claude) emit "$1" "$3" "$4";; + *) emit "$1" "$3" "$4";; # generic Claude-shaped wrapper — see note +esac +``` + +The `*)` branch keeps working exactly as today, but is documented in a comment as *"the Claude-shaped +generic wrapper. A harness reaching this branch has no verified contract mapping — its wrapper is a +best guess, not a supported shape."* That converts today's silent inheritance (which is how Cursor +got here) into a stated gap the next harness rollout has to confront. + +### 3 — Dispatch rule rewording + +`cursor-rules/dispatch.head.md` and the nine `cursor-rules/dispatch/docket-*.md` fragments currently +instruct `Launch a **Task** with subagent_type: ...` and show `Task(subagent_type: ..., ...)` call +snippets. + +Reword the **instruction** to capability language — "dispatch to the subagent `docket-<name>`, +foreground, using this mode's subagent-launch mechanism; do not run it inline" — while keeping the +concrete call snippet as a clearly-labelled *illustration*. ADR-0059 §2 permits a tool name to appear +as an observed internal or in a diagnostic; it forbids one as a **decision input**. These fragments +tell a parent chat how to act, and are Cursor-scoped, so they were correctly left alone by #0137's +narrower prose fix — but standardizing them on capability language removes the last place a reader +could infer that docket depends on the name. + +### 4 — `runners/cursor.sh`: a Cursor runner adapter + +Mirrors `scripts/runners/codex.sh` (change 0079's framework), registered as +`REGISTERED_RUNNERS="codex cursor"`: + +- Prompt assembled from `agents/docket-<name>.md` (skills list + body), as codex.sh does. +- Executes `cursor-agent -p --output-format text --workspace "$DOCKET_REPO_ROOT"`, foreground, and + relays the final message on stdout. +- `--model` passed verbatim (ADR-0015). `--effort`, having no `cursor-agent` flag, rides inside the + model value using the same `<model>[effort=<e>]` encoding as the wrapper emitter; when no model is + resolved the effort is dropped with the same WARN. +- Mock seam `CURSOR_BIN`, matching `CODEX_BIN`. Contract doc at `scripts/runners/cursor.md`. +- Config block `runners.cursor` for sandbox/force flags, matching `runners.codex`. + +The existing rule that `runner:` is reserved for a **claude parent** is unchanged and correct: the +runner names the *child* harness, so a `cursor` runner is a Claude wrapper delegating to +`cursor-agent`. + +**Recorded risk.** `cursor-agent` is known (from prior hands-on testing) to be **unreliable and to lag +the Cursor IDE in features**. This adapter therefore rests on a shakier foundation than +`runners/codex.sh`. Its failure posture is pinned accordingly: a `cursor-agent` failure, timeout, or +missing-feature error is a **loud abort-and-report**, never a silent fall-back to running the agent +inline in the parent. The adapter must not become a new silent-degradation path — which would +reproduce this change's own root cause in a new location. + +**Separable scope.** This item is the one piece of the change that is a *new capability* rather than +a repair of the wrapper-contract defect. If the PR proves unreviewable at full scope, this is the +clean carve-out point: items 1, 2, 3, 5, 6 form a coherent standalone fix, and the runner adapter can +be spun into its own change without weakening any of them. + +### 5 — Documentation and ADR + +- **`skills/docket-convention/references/agent-layer.md`** gains a per-harness wrapper-shape table, so + the reference stops implying one uniform shape: + + | harness | file | model | effort | skills | + |---|---|---|---|---| + | claude | `.md` | `model:` | `effort:` | `skills:` frontmatter | + | cursor | `.md` | `model: <id>[effort=<e>]` | *(inside model)* | body preamble | + | codex | `.toml` | `model =` | `model_reasoning_effort =` | `developer_instructions` preamble | + +- Any config/README prose asserting a uniform wrapper shape is corrected alongside it. + +- **A new ADR** records the general rule this change generalizes: *a generated wrapper conforms to + its target harness's own documented contract; the generic emitter is Claude's shape, not a default + other harnesses may silently inherit, and a harness without a dedicated emitter is a known gap + rather than a supported mapping.* `relates_to: [8, 15, 17, 59]`, `supersedes: []`, `reverses: []` — + it **refines** ADR-0008 and ADR-0015's harness mappings without superseding either, and cites + ADR-0059 as the governing decision for the dispatch/tiering question it does not re-open. + +- **`adrs:` on this change** becomes `[8, 15, 24, 59, <new>]`. (Note: #0137's scope included adding + 59 to this change's `adrs:`; that had not landed as of grooming, so it is folded in here.) + +## Verification — three tiers, with asymmetric weight on the CLI + +### Tier 1 — hermetic contract tests (gating) + +`tests/test_sync_agents.sh` currently asserts Cursor wrappers are byte-identical to Claude wrappers +and carry a standalone `effort:` field. Those assertions **encode the defect** and are replaced with +contract tests: + +- a generated Cursor wrapper emits **no `effort:`** key; +- a generated Cursor wrapper emits **no `skills:`** key; +- the `model:` line uses bracket encoding when an effort is resolved, and bare when it is not; +- no `model:` line is emitted when the resolved model is `inherit`/empty; +- the `inherit` + effort case emits the WARN; +- the body preamble names **every** skill from the source wrapper's `skills:` list; +- Codex and Claude wrapper generation are unchanged (regression guard on the emitter split). + +These gate the suite. They prove **shape**, and nothing else — which is precisely why Tiers 2 and 3 +exist. + +### Tier 2 — `cursor-agent -p` spike (best-effort, **non-gating**) + +A scripted probe via `cursor-agent -p --output-format json` that dispatches a docket agent and reports +the effective model, whether the docket skills loaded, and whether a nested dispatch succeeds. +Findings recorded verbatim in the results file with the `cursor-agent` version. + +**Evidence rule — this is the load-bearing part of Tier 2, not a caveat.** The CLI is known to be +unreliable and to lack features the IDE has. Therefore: + +> **A negative or absent result from `cursor-agent` is never evidence that the wrapper contract is +> wrong.** It is recorded as a CLI limitation observation and nothing more. Only a *positive* result +> carries weight, and it proves only that the contract works on the CLI surface. + +Treating an unreliable probe's silence as capability absence is the exact false-negative shape +ADR-0059 exists to prevent — an absence observed in the wrong surface, promoted to a verdict. This +rule is stated in the spec, in the test file, and in the results file so that a future implementer +cannot quietly re-promote this spike to a gate. + +### Tier 3 — Cursor IDE validation checklist (human-executed, **required before merge**) + +Modelled on change #0078's Codex CLI validation runbook, which is this repo's house pattern: a phased +checklist Daniel executes interactively, findings recorded verbatim in the results file, every gap +becoming a follow-up stub. + +Phases, each with a definitive observable outcome: + +1. **Generated artifacts** — run `./sync-agents.sh`; assert `.cursor/agents/docket-*.md` contain no + `effort:`/`skills:` keys, carry bracket-encoded models, and carry the skills preamble. +2. **Agent visible** — the docket agents are listed and selectable in the Cursor IDE. +3. **Dispatch honored** — asking for a docket agent dispatches to the subagent rather than running + the skill inline in the parent chat. +4. **Pin honored** — the child reports the pinned model *and* the pinned reasoning effort. +5. **Skills loaded** — the child confirms `docket-convention` and its own docket skill loaded, and can + state a convention rule it could only know from having loaded them. +6. **SDD reachable at depth 2** — a real dispatch from inside the child succeeds, confirming Finding + 1 live rather than from documentation. + +**Passes** when phases 1–3 and 5 are green and phases 4 and 6 have definitive observed answers. + +### The merge-gate obligation + +Tier 3 necessarily runs *after* the PR opens. So the change carries an explicit obligation: **the PR +body must state that Cursor IDE validation is pending**, naming the checklist, so the human merge +gate is not cleared on a green hermetic suite alone. + +Without this, the change would become the fourth instance of `skill-fallback-degrades-discipline` — +green artifacts concealing an unrun verification — inside the very change written to end that +pattern. + +## Out of scope + +- Changing the Superpowers SDD or TDD skills themselves. +- Retrofitting or reopening the consuming `cet-devops` change 6 implementation or its PR. +- Completing change #0044's broader configurable per-role build-model design, beyond keeping its + eventual configuration compatible with the corrected Cursor emitter. +- Redesigning Claude Code or Codex wrapper generation beyond the emitter split needed to name them. +- Re-deciding ADR-0059's capability-resolution rule or its tiered unavailability posture. This change + **implements and delivers** that decision for Cursor; it does not reopen it. +- Other unvalidated harness tokens (`kiro`, `windsurf`) — they remain on the documented `*)` gap. + +## Risks + +- **Cursor's contract may move again.** The mitigation is structural, not a version pin: docket holds + no table of Cursor internals, so a contract move breaks at most the emitter's field mapping, which + Tier 1 tests localize, and Tier 3 re-detects on demand. +- **The CLI/IDE gap could mislead the build.** Addressed by the Tier 2 evidence rule and by making + Tier 3 the certifying tier. +- **Scope.** Six items in one change. The runner adapter is the pre-agreed carve-out point. diff --git a/internal/export/testdata/corpus/specs/2026-07-28-board-checks-exit-swallowed-design.md b/internal/export/testdata/corpus/specs/2026-07-28-board-checks-exit-swallowed-design.md new file mode 100644 index 000000000..ccfede411 --- /dev/null +++ b/internal/export/testdata/corpus/specs/2026-07-28-board-checks-exit-swallowed-design.md @@ -0,0 +1,197 @@ +<!-- docket:backlink:start (generated — do not hand-edit) --> +> ↩ **[Change 0144 — A board-checks.sh non-zero exit silently voids the entire health pass](../../changes/archive/2026-07-28-0144-a-board-checks-sh-non-zero-exit-silently-voids-the-entire-he.md)** +<!-- docket:backlink:end --> + +# A board-checks.sh non-zero exit silently voids the entire health pass — design + +Change 0144. + +## Problem + +`health_checks()` in `scripts/docket-status.sh` pipes `board-checks.sh` into a +`while IFS=$'\t' read` loop and never reads the producer's exit status. `board-checks.sh` +accumulates findings into `$FINDINGS` and prints once at the end, so every validation failure +(`exit 2`) emits **zero** TSV lines: the loop body never runs, `health_checks` returns 0, and the +report is byte-indistinguishable from a clean tree. + +Change 0117 hit a live instance (a missing `adrs_dir` made `board-checks.sh` exit 2 and dropped +every check) and fixed that trigger — the `[ -d "$mw/$ADRS_DIR" ]` guard now in `health_checks`. The +swallowing itself remains, and 0117's regression test cannot see it: its mock `board-checks.sh` +exits 0 regardless of arguments, so the "still emits check lines" assert passes against both the +fixed and the unfixed code (`green-suite-untested-branch`). + +## Decision + +**Keep the warn-only posture; make the failure loud.** Capture the checker's output and exit +status, then consume the captured text, and emit one new report line when the checker failed. + +``` +local out rc=0 check_id change_id message +out="$("$DOCKET_BASH_PATH" "$SCRIPTS_DIR"/board-checks.sh \ + --changes-dir "$cd_dir" --metadata-branch "$metadata_branch" \ + --integration-branch "origin/$INTEGRATION_BRANCH" \ + --lease-ttl-hours "${RECLAIM_LEASE_TTL:-72}" \ + ${adr_args[@]+"${adr_args[@]}"} 2>&2)" || rc=$? +while IFS=$'\t' read -r check_id change_id message; do + [ -n "$check_id" ] || continue + echo "check $check_id $change_id $message" +done <<<"$out" +[ "$rc" -eq 0 ] || printf 'health checks failed %s\n' "$rc" +return 0 +``` + +Verified against the running code: + +- `scripts/docket-status.sh`'s prologue is `set -uo pipefail` — **no `-e`** — so `|| rc=$?` is safe and + does not abort the pass. +- An empty `$out` yields one blank line from `<<<`, already swallowed by the existing + `[ -n "$check_id" ] || continue` guard. +- The loop no longer runs in a pipeline subshell, so `check_id`/`change_id`/`message` must be + declared `local` (they were previously subshell-scoped). +- Capture-then-consume is this file's own idiom: `reclaim_pass` captures then greps a here-string, + citing change 0067's no-`pipefail`-SIGPIPE rule. + +**The diagnostic is a new non-`check` report line, `health checks failed <exit>`.** The +`check <check-id>` vocabulary is closed — `BOARD_CHECK_IDS` in `scripts/lib/docket-frontmatter.sh` +(13 ids post-0117) is pinned in both directions — count and set — by `tests/test_board_checks.sh`, +and "the checker itself broke" is not a finding about a change. + +The token deliberately sits **outside the `board ` family**. `skills/docket-status/SKILL.md` is the +one place callers are told to key on report lines, and it teaches `board *-failed` / "no `board …` +line" as meaning **the board step** failed. Naming a health-pass diagnostic `board-checks failed` +would land inside that taught contract and force a disclaimer in a file the misled reader is not +reading. `health checks failed <exit>` names its own pass, matching the existing +`learnings index failed` shape (pass name + `failed`). + +Safe against every existing line-consuming matcher, verified: + +- `reclaim_pass`'s `RECLAIMABLE_LINE_RE` anchors on `^check stale-in-progress …`. +- `board_classify` matches `case "$line" in "board "*)`. +- SKILL.md's `board *-failed` gloss. + +None matches a line beginning `health checks `. + +**The exit code alone is the payload; the cause stays on stderr.** `board-checks.sh` already prints +its reason there (`board-checks: adrs dir not found: …`) and `health_checks` passes stderr through +untouched. This matches `board inline failed`, which likewise carries no reason on stdout: the +report line is a *signal that a step failed*, the diagnostic is the stderr text. + +**Not retryable; `board_classify` untouched.** The reason is **capture scope**, not flag +exclusivity: `board_pass_must_land` classifies only its own `board_out="$(board_pass)"`, captured +before `health_checks` ever runs. (A bare `--must-land` *does* run the full path — the arg parser +excludes `--must-land` only against `--digest-only` — so the scoping argument must rest on call +ordering, which is why it gets its own test below.) + +## Scope + +### `scripts/docket-status.sh` + +The `health_checks()` rewrite above, plus the stale comment on the function itself +("a clean tree (or a board-checks failure) prints nothing extra"). + +### `scripts/docket-status.md` + +Locate each site by its text, not by line number — the anchors drift: + +1. **§7 "Health checks"** — the sentence "a clean tree, or a `board-checks.sh` failure, produces no + extra output and never aborts the pass" is now false and must be corrected. This is the real + site. +2. **The `## Output contract` table** — add the `health checks failed <exit>` row, stating it is a + **health-pass** line. +3. The two *warn-only* restatements (the *Failure postures* health-check bullet and its echo in + *Invariants*) carry **no** stale claim — warn-only is still exactly right and both stay + byte-untouched. Editing only *Failure postures*, the obvious target, would miss the real site + entirely. + +### `tests/test_docket_status.sh` + +**Must fail against the unfixed `health_checks`** (the mutation mandate applies to these three): + +- mock exits 2, no output → exactly one `health checks failed 2`; the run still reaches `pass ok` + and exits 0. +- mock exits 1, no output → `health checks failed 1`. +- mock prints one well-formed TSV finding **then** exits 2 → the `check` line **and** + `health checks failed 2`. Pins "additive, not replacement"; a naive + `if rc; then diagnostic; else findings; fi` fails it. **Not hypothetical**: `board-checks.sh`'s + `--strict` path already prints `$FINDINGS` and *then* exits 1. `health_checks` never passes + `--strict` today, so the shape is unreachable from this caller — but it is one flag away, not a + speculative future. + +**Non-regression pins, expected to pass both ways — do NOT apply the mutation mandate:** + +- mock exits 0 with findings → unchanged output, no `health checks failed` line (the + no-false-positive direction; `correspondence-guard-runs-one-way`). +- mock emits `stale-in-progress … [reclaimable]` and exits 2 → the reclaim remedy line still + prints. + +**Two structural guards:** + +- The capture-scope argument rests on call ordering inside `main()` that a future edit could + silently break: full path with `--must-land`, board-checks mock exits 2, board mock clean → the + run still exits 0 and reaches `pass ok`. +- A doc guard that the **stale sentence is gone**, not merely that the new line is documented. The + existing `assert "status contract documents …"` family pins presence only. + +## Out of scope + +- `board-checks.sh`'s own exit-2-on-bad-argument rule, which is correct for a hand-run caller. +- Change 0117's specific trigger, already fixed and merged (PR #129). +- The check-id vocabulary and its four pinned surfaces (0111's guard); no id is added. +- `skills/docket-status/SKILL.md`. Renaming the token out of the `board ` family removes the reason + to touch it — the file's `board *-failed` gloss stays true. Change **0145** owns that file and is + `in-progress`; leaving it alone keeps the two changes collision-free. + +## No ADR + +A failure-posture refinement inside one function, expressed through the existing output contract. +No new decision a future reader would need the "why" for beyond this spec. + +## Assumptions + +1. **Warn-only, not fatal.** *Chosen:* a checker failure reports and the pass continues. + *Rejected:* exit non-zero — a checker bug must not abort a pass whose real work (board, sweep, + digest) succeeded. `scripts/docket-status.md`'s *Failure postures* already ships "health checks + warn-only" as an invariant, so escalating would be a shipped-contract break. + +2. **New line, not a `check` line.** *Chosen:* `health checks failed <exit>`. *Rejected:* + a `check checker-failed …` finding — that would add a 14th id to the closed `BOARD_CHECK_IDS` + vocabulary pinned across four surfaces, for something that is not a finding about a change. + *Rejected:* stderr only — invisible to every caller that keys on report lines, which is the + whole defect. + +3. **Capture-then-loop, not `PIPESTATUS`.** *Chosen:* command substitution + here-string. + *Rejected:* reading `${PIPESTATUS[0]}` after the pipeline — correct but keeps the loop in a + subshell and diverges from `reclaim_pass`'s established idiom in the same file. *Rejected:* + `set -e` + trap — far too broad a blast radius for one function. + +4. **Sequencing against change 0117 — resolved.** The prior abstain parked on this. PR #129 is + **merged** and 0117 is archived, so the collision is gone: the `adr_args` block and the + `[ -d "$mw/$ADRS_DIR" ]` guard are on `main` and are the code this design was re-verified + against. `depends_on` is therefore cleared on the change file. + + **0145 is the live overlap, and it is resolved by the rename, not by scope avoidance.** 0145 is + now `in-progress` on `feat/docket-status-skill-md-restates-a-stale-check-count-and-list`, and its + reconcile log explicitly predicts this collision: a `board-checks failed <exit>` diagnostic would + have forced 0144 to edit `## Read the report` in the same `skills/docket-status/SKILL.md` 0145 is + rewriting. Naming the line `health checks failed` leaves SKILL.md's `board *-failed` gloss + correct, so 0144 has no reason to open the file at all. `related: [145]` stays as subject + overlap; there is no file collision left. + +5. **A new non-`check` report line is an acceptable addition to the output contract.** *Chosen:* + yes. The contract is a documented table that already grew for `board inline failed` and + `learnings index failed`; adding a row in the same family and same commit as the doc update is + the established pattern, and every existing consumer's matcher was verified above not to catch + it. + +6. **The emit-then-fail test is worth writing despite being unreachable from this caller.** + *Chosen:* keep it. It is the one case that distinguishes "additive" from "replacement", it costs + three lines, and the implementation it excludes is the one a reasonable person would otherwise + write. *Rejected:* drop as speculative — `board-checks.sh --strict` already ships the + print-then-exit-1 shape, so the only thing standing between it and this caller is one flag. + +7. **The report line carries the exit code, not the reason.** *Chosen:* exit code only; the cause + stays on stderr, where `board-checks.sh` already writes it and `health_checks` already passes it + through. *Rejected:* interpolating the checker's stderr into the stdout line — it would make an + unbounded, multi-line, model-unfriendly report line out of a fixed-shape contract, and it + diverges from `board inline failed`, which sets the precedent that a failure line signals *which + step*, not *why*. diff --git a/internal/export/testdata/corpus/specs/2026-09-02-harden-integration-race-test-isolation-under-parallel-load-design.md b/internal/export/testdata/corpus/specs/2026-09-02-harden-integration-race-test-isolation-under-parallel-load-design.md new file mode 100644 index 000000000..7407072ad --- /dev/null +++ b/internal/export/testdata/corpus/specs/2026-09-02-harden-integration-race-test-isolation-under-parallel-load-design.md @@ -0,0 +1,77 @@ +<!-- docket:backlink:start (generated — do not hand-edit) --> +> ↩ **[Change 0373 — Harden integration/race test isolation under parallel load](../../changes/archive/2026-09-02-0373-harden-integration-race-test-isolation-under-parallel-load.md)** +<!-- docket:backlink:end --> + +# Harden integration/race test isolation under parallel load — design + +Change 0373. Groomed 2026-09-02 (interactive). Priority high: unrelated reds at the full-suite gate are halting otherwise-green implement-next and finalize runs, so other changes are blocked on this one. + +## Problem + +Four full-suite gate runs across two builds (0371, 0397) each reddened on a test the change under review did not touch, and every one was green when re-run serially: + +1. a process-group liveness check in `internal/process` (`TestObserveRunningThenTerminal`, 30 s ceiling under `-race`; also stub 381), +2. the `internal/app` package hitting Go's per-package timeout, +3. `t.TempDir()` teardown failing with `directory not empty` in `internal/gitcli`, +4. the same teardown failure in `internal/repository/transaction` (`TestKeyedCommitCarriesFiveTrailers/keyed`, assertions passed, only cleanup failed, under `-j11`). + +A fifth sighting (results file for change 0396, 2026-09-02) records concurrent gate-drive supervisors under `$TMPDIR` polluting `internal/process`'s recover-scan. + +## Root cause — two structural mechanisms, not four gaps + +The sightings span three packages, so a per-test fix is whack-a-mole. Two shared mechanisms explain all of them: + +**A. Oversubscription.** `internal/suiterunner` launches every `tests/test_*.sh` target in parallel at `-j = NumCPU` (11 on the reference machine). Thirty-four of those targets are Go wrappers, each running its own `go test`, and three of them (`test_go_toolchain.sh`, `test_go_race.sh`, `test_go_finalize_e2e.sh`) run `go test ./...` over the whole module, which itself runs packages in parallel at `-p = NumCPU` with `-parallel = GOMAXPROCS` inside each package. Nothing bounds the product: the gate can schedule on the order of `-j × NumCPU` concurrent Go test packages, each with real git and supervisor subprocesses. That is the mechanism behind the wall-clock sightings (1, 2, and the `-race` ceiling in 381). + +**B. Post-test writers into `t.TempDir()`.** Go's `t.TempDir()` cleanup is one `os.RemoveAll` with no retry; a process that is still writing into the directory when cleanup runs (a `Setsid` supervisor from `internal/process`, or a git child such as detached auto-gc / auto-maintenance) produces `directory not empty`. Under load (A) the window between the last assertion and the detached writer's exit widens. `internal/process` already carries a one-test workaround (`quiesceRun` in `launch_test.go`), which is evidence the gap is structural. This is the mechanism behind sightings 3, 4, and 5. + +Both causes are hypotheses inferred from the code and the sightings; the build's reconcile pass verifies each against the tree before scoping the fix (learning: *groomed-root-cause-is-a-hypothesis*). + +## Design + +### 1. Bound total load at the runner + +- The runner exports one concurrency cap into every target's sandbox environment (`internal/suiterunner/sandbox.go`, alongside the existing `HOME`/`TMPDIR`/git overrides) as a `DOCKET_`-namespaced variable derived from its own `-j` and `runtime.NumCPU()`. Name and derivation are settled at plan time; the contract is that a target can read *how much of the machine it may use*. +- The Go wrappers honor it: the shared `tests/lib/go-integration-shard.sh` helper and the three whole-module wrappers translate the cap into `go test -p <n>` and `GOMAXPROCS=<n>` for their child. When the variable is absent (a solo `bash tests/test_X.sh` or a bare `go test` run outside the runner) Go's defaults apply unchanged. +- Invariant the spec pins: the total number of concurrently running Go test packages across the whole gate stays at or under a small multiple of the CPU count, instead of `-j × NumCPU`. The multiplier is **measured during the build**, not chosen here: the plan sweeps candidate values on the reference machine, records wall clock per candidate, and picks the smallest multiplier that keeps every Go budget row under its ceiling. +- Every affected row in `tests/runtime-budgets.tsv` is re-seeded from post-fix measurements per the table's own rounding rule; no ceiling is raised without a written reason, and no row exceeds 60 s. + +### 2. Shared real-process test fixture + +A new internal test-support package (name settled at plan time; it lives under `internal/` and is imported only from `_test.go` files) replaces bare `t.TempDir()` in every package whose tests spawn real git or supervisor processes. The twelve packages today: `internal/app`, `internal/gitcli`, `internal/repository/transaction`, `internal/process`, `internal/workspace`, `internal/install`, `internal/gatedrive`, `internal/cli`, `internal/suiterunner`, `internal/repository`, `internal/repoguard`, `internal/release` (derived from a whole-repo grep for `exec.Command` / `"git"` in test files; the plan re-derives the list, never hand-copies it). + +The fixture provides: + +- **A temp dir with a draining cleanup.** Cleanup first drains the test's own detached children (the existing `quiesceRun` logic from `internal/process/launch_test.go` becomes the fixture's drain primitive rather than a one-test workaround), then retries `os.RemoveAll` over a bounded window (order of seconds, constant recorded with its measurement per learning *tolerance-constant-calibrated-on-one-machine*) before failing. A writer that outlives the window fails the test with a diagnostic naming the surviving paths, so a genuine leak surfaces as a finding rather than an opaque teardown crash. +- **Git background work off.** The fixture writes a per-fixture git config (via `GIT_CONFIG_GLOBAL` for the processes it spawns, or directly into each repository it initializes) that disables `gc.auto`, `gc.autoDetach`, `maintenance.auto`, and `core.fsmonitor`, so no git child survives the command that spawned it. The same four knobs are added to the runner sandbox's synthetic global gitconfig (`gitIdentityConfig` in `sandbox.go`) so gate runs and solo runs agree. +- **Process-registry isolation.** Tests that launch supervisors get a registry root under the fixture's own temp dir, never the shared `$TMPDIR`, closing sighting 5. + +### 3. Fail-closed guard; no serial pins + +- A `repoguard` test proves that no `_test.go` file in a real-process package calls bare `t.TempDir()` outside the fixture. The package list is derived by the same grep as section 2 at test time, not hand-listed. Mutation-tested: restoring one bare call reddens it. +- No wrapper receives a `serial` pin in `tests/runtime-budgets.tsv`. Serial pinning lengthens every gate and hides the isolation gap; the fix is structural or it is not done. +- Stub **381** is folded in: its test is covered by sections 1 and 2. The implementer's reconcile pass kills 381 as a duplicate once 373 is claimed. + +### 4. Evidence and acceptance + +The results file records: + +- five consecutive full gate runs (`go run ./cmd/docket development test`) at the same head with zero unrelated reds; +- the measured multiplier from section 1 and the per-candidate wall-clock table; +- the re-seeded budget rows with before/after seconds; +- the four named offenders plus sighting 5 as explicit regression cases, each run serially and under the gate. + +## Out of scope + +- Any product behavior change; this is test infrastructure only. +- The budget registry mechanism itself (`tests/runtime-budgets.tsv` format, screen-then-confirm regime) beyond re-seeding the rows this change affects. +- Sharding over-budget files (changes 280, 296). +- Changing what any test asserts. A fixture adoption is a substitution, not a rewrite. +- The 0371 and 0397 changes themselves (merged). + +## Related + +- 381 — same class, one test; folded in. +- 333 — partitioned `internal/app` behind the `integration` tag; produced today's 34-wrapper topology. +- 280, 296 — budget-driven sharding of other files; independent. +- Learnings: *groomed-root-cause-is-a-hypothesis*, *tolerance-constant-calibrated-on-one-machine*, *transient-resource-lifecycle*, *shared-resource-keeps-first-owner-assumptions*. diff --git a/internal/export/testdata/corpus/specs/2026-09-23-named-implement-next-skips-unrelated-maintenance-preflight-design.md b/internal/export/testdata/corpus/specs/2026-09-23-named-implement-next-skips-unrelated-maintenance-preflight-design.md new file mode 100644 index 000000000..f0ddf72d2 --- /dev/null +++ b/internal/export/testdata/corpus/specs/2026-09-23-named-implement-next-skips-unrelated-maintenance-preflight-design.md @@ -0,0 +1,62 @@ +<!-- docket:backlink:start (generated — do not hand-edit) --> +> ↩ **[Change 0448 — Named implement-next skips unrelated maintenance preflight](../../changes/archive/2026-09-24-0448-named-implement-next-skips-unrelated-maintenance-preflight.md)** +<!-- docket:backlink:end --> + +# Change 0448 — Named implement-next skips unrelated maintenance preflight + +## Origin and ordering + +Split out of change 0446 on 2026-09-23 (its former §7 and acceptance test 9). 0446 keeps the gate-history and run-bookkeeping fix. This change removes the incidental maintenance sweep from a named implementation start. Change 0449, which depends on this one, scopes metadata validation and board rendering. The three are built in succession (0446 → 0448 → 0449), which `depends_on` enforces. There is no code dependency on 0446. The ordering is the maintainer's build sequence. + +## Required outcome + +An explicitly named change B must be able to start, retry, and resume implementation even when another change A has a failing closeout, cleanup, or reclaim. A's maintenance problems stay visible to anyone who deliberately runs maintenance, but they cannot halt B before B's own claim/gate. The ID is preserved throughout; a named request never falls back to selecting another change. + +Shared repository/configuration/transport failures, defects in B, B's real unmet dependencies, and genuine ownership conflicts remain valid refusals. A defect attributed only to independent A does not. + +## Grounding + +Inspected main `442770e11bd05baf6200bec53e9c4757622811a6` on 2026-09-23 (read-only). + +- **#0389 / ADR-0101 and #0397 / ADR-0106:** historical done/stacked-merged cleanup is already deferred out of implementation startup (`sweepWorklist` skips it when `scope == SweepScopeImplementation`). But `sweepWorklist` still enqueues merged-implemented closeouts and expired-claim reclaims at both scopes, and `sweepRunCloseout` always appends the cleanup suffix after an applied or no-op closeout. When `reclaim.auto` is false a reclaim becomes `skipped`, which is not a problem disposition. +- `preflightVerdict` (`maintenance_preflight.go`) makes any entry in `problemDispositions` (blocked, failed, unknown, contended) a `problem`, and so is a whole-sweep result that is neither applied nor no-op. +- `skills/docket-implement-next/SKILL.md` Step 0 says: "before selection, run the implementation preflight … On `preflight: problem` … halt before claiming". It has no explicit-ID exemption. The `agents/docket-implement-next.md` wrapper only preloads the skill. Other named-entry callers must be derived by search. +- Changing gate admission (0446) cannot fix this earlier refusal. Relaxing the metadata gate (0449) cannot fix it either: the sweep's closeouts run through the same strict transaction gate, so an invalid A still yields blocked/failed entries and a halt. +- **Dependency semantics:** `EvaluateDependencies` (`internal/domain/graph.go`) treats a dependency as satisfied only when it is `done`; an `implemented` dependency yields `needs-merge`. `EvaluateReadiness` reports `waiting-dependency` before anything else. + +Relevant learnings: verify the hypothesis against code; test the producer/consumer path and its negative counterpart; printed remedies must work in the state that produced them. + +## Design + +### 1. Named start goes straight to B + +After the existing repository preparation/configuration checks, an implement-next request naming B goes directly to the existing authoritative `context.implementation --id B` and named claim/resume path. Do not invoke `maintenance.preflight`, a status sweep, or another maintenance child first. Do not depend on the global `status.ready` queue to certify a named resume. Keep readiness, entity-version, dependency, effective-base, claim eligibility, gate context, and resume/cancellation checks for B. A malformed, absent, not-ready, or improperly resumed B returns its existing local refusal; it never silently becomes a request for another change. + +This is a workflow change at the existing explicit-ID branch, not a new preflight command, scope flag, or verdict policy. Update the maintained implement-next instructions and every executable named-entry wrapper that currently imposes the sweep; derive those callers by search. Initial named calls, attributed retries, and named resumes must all take this path. Gate arming and attribution remain unchanged. + +### 2. Deliberate maintenance keeps its honest outcomes + +The existing no-ID implementation preflight, explicit `maintenance.preflight`, and `maintenance.sweep` keep their current outcomes. A user deliberately running maintenance still sees A's failures. `maintenance sweep --scope full` and the existing targeted closeout/cleanup/reclaim operations remain the places to recover that work. Add no deferred queue, background job, or implicit cleanup after B. Named finalize likewise must not acquire a new unrelated maintenance prerequisite. + +### 3. B's own merged dependencies + +Skipping the sweep never declares B's dependency satisfied. It does create a behavior change that must be handled. Today, when B `depends_on` an A whose PR has merged but which has not been closed out, the preflight sweep's merged-recovery closeout moves A to `done` and B proceeds. Without the sweep, B would refuse with `waiting-dependency`/`needs-merge`. + +Preferred handling: the named path runs the existing targeted closeout for **B's own** unmet `depends_on`/stack ancestors that are in `needs-merge` state with a merged PR, and nothing else. A failure there is a failure of B's real dependency and refuses B locally with A's locator. A failure in any other change's closeout cannot reach B. + +Fallback, if implementation cannot bound that closeout to B's dependency set through existing operations: a local refusal whose printed remedy names A and the existing finalize/closeout operation that settles it. Never silently wait or select another change. Record the chosen behavior in the ADR (below). + +## Acceptance tests + +1. **Named startup:** with A's merged-but-unclosed record and failing closeout/cleanup/reclaim seams, invoke implementation explicitly for B. Prove no maintenance operation is invoked and B reaches its own claim/gate. Repeat for attributed retries and named resume. +2. **Local refusals still hold:** missing/invalid B, unmet actual dependencies, active same-worktree owners, and unsupported shared configuration still refuse; no fallback selection. +3. **B's merged dependency:** B depending on a merged-but-not-closed-out A either proceeds after the bounded closeout of its own dependency, or refuses locally with a working remedy naming A (whichever §3 behavior is implemented). An unrelated change's failing closeout is never attempted. A failing closeout of B's own dependency refuses B with A's locator. +4. **Unchanged behavior:** regression coverage for no-ID implementation preflight, explicit `maintenance.preflight`, and `maintenance.sweep` outcomes. +5. **Mutation checks:** restore mandatory maintenance on a named request, or let the bounded dependency closeout touch a non-dependency; the corresponding test must fail. +6. **Build gate:** run the whole suite via the source Go runner using resolved `build.test_command`, and inspect budget findings. Use existing fixtures and seams; no new test framework. + +## Architecture and scope limits + +Through the ADR workflow, narrow ADR-0101/ADR-0106's mandatory startup-preflight clauses for explicit IDs, and record the §3 dependency-closeout choice. Accepted ADR text is not rewritten in place. + +No new commands, force flags, preflight scope flags, verdict policies, background cleanup, or deferred queues. Automatic (no-ID) selection, automatic finalize candidate ordering, and driver stop/continue behavior are out of scope. Gate admission and run bookkeeping belong to 0446. Metadata validation and board rendering belong to 0449. diff --git a/internal/export/testdata/corpus/specs/2026-10-19-measure-whether-the-1h-cache-ttl-cut-implement-next-s-cost-design.md b/internal/export/testdata/corpus/specs/2026-10-19-measure-whether-the-1h-cache-ttl-cut-implement-next-s-cost-design.md new file mode 100644 index 000000000..737774262 --- /dev/null +++ b/internal/export/testdata/corpus/specs/2026-10-19-measure-whether-the-1h-cache-ttl-cut-implement-next-s-cost-design.md @@ -0,0 +1,98 @@ +<!-- docket:backlink:start (generated — do not hand-edit) --> +> ↩ **[Change 0547 — Measure whether the 1h cache TTL cut implement-next's cost](../../changes/archive/2026-10-19-0547-measure-whether-the-1h-cache-ttl-cut-implement-next-s-cost.md)** +<!-- docket:backlink:end --> + +# Measure whether the 1h cache TTL cut implement-next's cost — design + +Change #547, groomed 2026-10-18. + +## Goal + +Confirm from this machine's subagent transcripts whether the 1-hour prompt-cache TTL that #546 pins on `docket-implement-next` really halves that agent's cost per run, and that the pin did not leak to any other agent. The change ends in its results file (`deliverable: results-artifact`): no code, no branch work, no PR. + +A first measurement on 2026-10-17 (13 runs) found the saving held: 100% 1h writes, cost per run $5.35 → $2.71. This run re-measures over every implement-next run made since then, and replaces that results file with the larger sample. It is also the first change to go through the results-artifact flow end to end. + +## Method + +1. Save the script below to a scratch location outside the repository (never commit it) and run it read-only. Nothing in the repository or the docket configuration changes. +2. **Window.** Start at `2026-10-12`: #546 merged and was installed on 2026-10-11, and the one run that day that predates the install is excluded by starting the next day. End at this run's own start time (its UTC claim stamp, `claimed_at:`), passed as the third argument, so the measuring run's own half-written transcript is not counted. +3. Run it for `docket-implement-next`, then for the guard agents `docket-build-standard`, `docket-build-premium`, and `docket-plan-writer`, all over the same window. +4. **Model.** The prices in the script are Opus 5.5's. Before trusting a cost figure, confirm the agent's pin in `~/.config/docket/config.yml` (the Claude `implement-next` pin was `claude-opus-5-5` when this was groomed). If an agent ran on another model in the window, say so in the results and price it with that model's rates. +5. Compare against the baseline table below, then write the results file. + +### Measurement script + +```python +# usage: python3 cache_ttl_check.py [agentType] [since-ISO] [until-ISO] +import json, glob, os, sys, collections +root = os.path.expanduser('~/.claude/projects/-Users-homer-dev-docket') +agent = sys.argv[1] if len(sys.argv) > 1 else 'docket-implement-next' +since = sys.argv[2] if len(sys.argv) > 2 else '' +until = sys.argv[3] if len(sys.argv) > 3 else '9999' +P = dict(inp=4, w5=5, w1=8, rd=0.20, out=20) # Opus 5.5 $/M; edit for another model +t = collections.Counter() +for meta in glob.glob(root + '/*/subagents/*.meta.json'): + if json.load(open(meta)).get('agentType') != agent: continue + seen, rows, first = set(), [], None + for line in open(meta.replace('.meta.json', '.jsonl')): + d = json.loads(line); m = d.get('message') or {} + first = first or d.get('timestamp', '') + u = m.get('usage') if isinstance(m, dict) else None + if not u or m.get('id') in seen: continue + seen.add(m.get('id')); rows.append(u) + if not rows or first < since or first >= until: continue + t['runs'] += 1 + for u in rows: + cc = u.get('cache_creation') or {} + cw, cr = u.get('cache_creation_input_tokens', 0), u.get('cache_read_input_tokens', 0) + t['turns'] += 1; t['cw'] += cw; t['cr'] += cr + t['w1'] += cc.get('ephemeral_1h_input_tokens', 0); t['w5'] += cc.get('ephemeral_5m_input_tokens', 0) + t['in'] += u.get('input_tokens', 0); t['out'] += u.get('output_tokens', 0) + if cw > 50000 and cr < cw: t['rewrites'] += 1; t['rewrite_tok'] += cw +n = max(t['runs'], 1) +cost = (t['in']*P['inp'] + t['w5']*P['w5'] + t['w1']*P['w1'] + t['cr']*P['rd'] + t['out']*P['out']) / 1e6 +print(f"{agent}: runs={t['runs']} turns/run={t['turns']/n:.0f}") +print(f"1h share of cache writes: {100*t['w1']/max(t['cw'],1):.0f}%") +print(f"expiry rewrites/run: {t['rewrites']/n:.1f} ({100*t['rewrite_tok']/max(t['cw'],1):.0f}% of write tokens)") +print(f"cache write/run: {t['cw']/n/1e3:.0f}k cache read/run: {t['cr']/n/1e6:.2f}M") +print(f"cost/run: ${cost/n:.2f} cost/turn: ${cost/max(t['turns'],1):.3f}") +``` + +The script counts a run's first turn as a "rewrite" (its initial ~80k write has no cache to read from). Count only rewrites after a turn other than the first as expiry rewrites, and check the time gap before each: a wait of more than an hour is an expected rewrite, not a failure. + +## Baseline and expected values + +Baseline: 95 Opus 5.5 implement-next runs, measured 2026-10-09, before #546. + +| Metric | Baseline | Expected after | First measurement (13 runs, 2026-10-17) | +|---|---|---|---| +| 1h share of cache-write tokens | 0% | ~100% | 100% | +| Expiry rewrites per run | ~4.9 | near 0 | 0 | +| Cache-write tokens per run | ~696k | ~100k | 156k | +| Cost per run (1h writes at $8/M) | $5.35 | ~$2.60 | $2.71 | +| Cost per turn | ~$0.08 | ~$0.04 | $0.047 | +| Cache-read tokens per run (should stay flat) | ~8.2M | ~8.2M | 7.17M | + +Guard baselines (cost per run, 0% 1h writes): `docket-build-standard` $0.96, `docket-build-premium` $2.23, `docket-plan-writer` $3.96. + +## Reading the result + +- Check the 1h share first. If it is 0%, nothing else moves, and the rest of the table is not worth reading. +- Run size varies (about 30–115 turns), so judge on the multi-run average and on cost per turn, never one run. +- If cache reads per run moved a lot, the runs themselves changed and the comparison isn't clean. Say so. +- Mixed 5-minute and 1-hour writes across runs mean the plan was drawing on usage credits at the time; name those runs. +- The logged output tokens undercount (usage is recorded mid-stream). That is the same on both sides of the comparison. +- Any 1h writes for a guard agent mean the setting leaked to it. A guard's cost moving with no change in cache bucket reflects a different mix of runs, not the pin. +- Also confirm implement-next's turns per run and its `run.verdict` outcomes look the same as before. The run tracker's verdicts for the window are enough; no new tooling. + +## Outcome rules + +- **Saving confirmed** (1h share ~100%, cost per run near $2.60–$2.80, guards at 0%): the results say so, and the `**Human action:**` line is `None`. +- **Writes back in the 5-minute bucket** (for all or most runs): record it as a Claude Code-side limitation, name when it started, and set the human action to deciding whether to try the broader `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` control, noting that it makes the build workers 10–23% more expensive. +- **A guard agent shows 1h writes**: the pin leaked. Record which agent and since when, and make that the human action. + +## The results file + +Write the results with `change.attach-results`, replacing the 2026-10-17 file. Use the standard results shape: the `**Human action:**` line, `## Outcome` with the measured table set against the baseline and the first measurement, the guard-check table, and `## Known issues and follow-ups` only if something real came up. State the window (start date, end time, run counts) and the exact commands run. Then close the change with `change.complete`. + +Follow-ups go in the results for a human to capture. Never mint a change, ADR, or learning from this run. #546's own follow-ups (measuring `docket-finalize-change`, the Sonnet 5.5 trials) are not part of this change. diff --git a/internal/export/testdata/corpus/titles.tsv b/internal/export/testdata/corpus/titles.tsv new file mode 100644 index 000000000..6540ec748 --- /dev/null +++ b/internal/export/testdata/corpus/titles.tsv @@ -0,0 +1,154 @@ +1 Change results artifact — linked, optional close-out file +2 docket metadata branch — separate planning state from code history +3 migrate-to-docket.sh targets the invoking repo ($PWD) — usable for consuming repos +4 BOARD.md goes stale during a build — refresh it on status transitions (claim / implemented), not only at Step 0 +5 Extract the shared convention into a docket-convention skill — reference-loaded, not embedded +6 Learnings ledger — an append-only per-repo memory that builds feed and future builds read +7 Recurring change templates — scheduled maintenance work that spawns proposed instances +8 Parallel backlog drain — fan out concurrent implement-next runs over independent build-ready changes +9 Human escalation loop — structured questions-for-you in the change file, answered asynchronously in git +10 Board analytics — throughput and cycle-time stats derived from git history, rendered on BOARD.md +11 GitHub board mirror — selectable board surfaces, one-way Issues + Projects mirror +12 Groom-next skill — pick the next needs-brainstorm stub and groom it to build-ready +13 Groom-next recap — introduce the selected stub before the brainstorm starts +14 docket-auto-groom — autonomous grooming drain over auto-groomable stubs +15 finalize — rebase onto base + re-run tests before merge +16 docket skills as model/effort-pinned subagents — foundation +17 docket subagent composition — nested status/adr/critic dispatch +18 Record the pure-bash YAML/frontmatter parsing stance as an ADR +19 Finalize ci/both gate — functional test against real GitHub CI (poll/retry) +20 Split the docket-convention skill via progressive disclosure — extract the GitHub board mirror first +23 Decide and apply scripting vs model-driven for the merge sweep and health checks +24 Retire or downgrade the inline board/source-drift health check once rendering is deterministic +25 Extract the shared terminal-transition close-out mechanics into deterministic scripts +26 Extract config resolution + bootstrap guard into a deterministic script +28 Wire the close-out call sites to the extracted scripts +30 Script docket-adr's deterministic passes — index render, ledger checks, ADR-only publish +31 ADR status-consistency check — match the supersede/reverse verb, not just the target id +34 Helper scripts unreachable in consuming repos — skills call repo-relative `scripts/…` that exists only in the docket source repo +35 Artifact links — a generated link block at the top of every change +38 Test suite — drop over-escaped dashes in test_docket_metadata_branch.sh grep (silences "stray \ before -") +40 terminal-publish leaves the integration-branch ADR index stale — regenerate it when an ADR is published +43 Model-tier indirection for agent model selection + config-driven advisories +44 Configurable SDD build models for docket-implement-next +46 Per-harness model overrides for docket agents +47 Make the agent-config refresh workflow discoverable in the README +50 Global config layer — full-schema ~/.config/docket/config.yml with a coordination-key fence +51 Machine-local config layer (.docket.local.yml) + all-local agent generation +53 Slim docket-convention + docket-status via progressive disclosure +54 Slim docket-finalize-change — rewire close-out to the shared reference +55 Slim docket-implement-next + propagate Step-0 preamble to the small skills +59 board-refresh honors board_surfaces — gate BOARD.md regeneration on the resolved surface set +60 board-refresh.sh must not write an empty BOARD.md — non-empty guard on the atomic write +64 Optional terminal-publish — per-repo opt-out to keep metadata on docket +66 Auto-groom's critic re-check must be foreground — a forked skill that yields returns a half-done run to its caller +67 Give the learnings ledger a promotion destination — it has no way to shrink +70 Harden the BOARD.md write guard — REDIRECT_RE misses real redirect forms +71 Encode the disabled board positively — an empty surfaces value is a wiring bug, not a configuration +72 Rewire the operating skills and Step-0 to the facade — retire the eval preamble +77 Codex harness — TOML agent generation + AGENTS.md dispatch block +78 Codex CLI live-validation runbook — prove docket works end-to-end under Codex +79 Cross-harness runner delegation framework (first runner — OpenAI Codex) +80 link-skills.sh creates a missing skills subdir when the harness is present +85 Second-round skill slimming — re-slim regrown skills + regrowth guard +86 Attended finalize has no merge path under auto_approve — scope the --admin ban to autonomous runs +88 Loop continuation — implement-next chains into the next ready change instead of stopping +91 Auto-create discovered stubs — a config flag that turns mid-run findings into proposed changes +92 Orphan detection script — cross-reference change ids in merged commits against archive state +94 Selection-order backlog digest — implement-next selects from a digest instead of walking active/ +95 Retire the auto-approve workflow — document the classifier and the single-maintainer branch-protection solution +96 An autonomous run can be halted by a sub-skill's interactive hand-off — pre-specify the outcome at every autonomous call site +100 Force-push-with-lease denied by the auto-mode classifier — unblock finalize's merge gate +101 .docket.yml.example — the canonical all-comprehensive config reference +106 Pin the finalize.test_command auto sentinel's cross-layer masking with a two-layer fixture +110 Concurrent agents collide on the shared .docket worktree's dirty-tree window +111 Guard the board-checks check-id enumerations against drift +114 Decide the repo's posture on line-number comment anchors +115 Extend the board-row-dropped invariant to archive/ files +116 Single-source the remaining duplicated board vocabularies +117 Deferred ADR-publish visibility — detect an unpublished ADR with a computed board-checks finding +124 Backlog triage pass — kill, defer, or arm each needs-brainstorm stub +126 Apply the poison-value prelude uniformly to every resolver eval in the config suite +129 Fix the pipefail-unsafe plain-format config assertion +135 Generated Cursor wrappers violate Cursor's subagent contract, disabling skills and model effort +136 Artifact back-links — a generated link at the top of every artifact pointing to the change +137 Claude Code dispatch-capability detection: name-based probing silently drops SDD build and review discipline +144 A board-checks.sh non-zero exit silently voids the entire health pass +145 docket-status SKILL.md restates a stale check count and list the 0111 guard does not pin +150 Pin or report the resolved shell toolchain across the test suite +152 Consolidate the two surviving hand-rolled GNU Bash 4+ validator copies +154 Remove stale Bash instructions and duplicated runtime contracts from Docket skills +156 render-board.sh exits 0 on malformed input and commits a corrupt board +158 Batch mode for docket-implement-next — build several coupled changes on one branch +164 Retune agent model/effort defaults for all three supported harnesses +172 Normalize the banned producer-pipe shape across tests and helpers +185 Test-suite profilers — per-assertion and per-command timing +190 Close the build-evidence value gap: a post-gate results commit always defeats finalize's suite skip +193 Default the build and review roles to docket-build and docket-review +195 Retune the opencode shipped model defaults for cost +196 Shared AGENTS.md dispatch block — restate and test the single-owner assumptions +197 Clear the unfixed review findings from change 0193 +200 Board-checks hardening — sanitize LF escape, capture-shape mutation, minor-finding clearance +201 Skill compression round three — targeted progressive disclosure on the Big 4 + regrowth-guard ratchet +204 Restore dropped doc rationale (compression losses) and complete AGENTS.md's frontmatter-edit rule +214 AGENTS.md's promoted frontmatter rule omits the whitespace-class half that corrupted two field writes +215 Escape newlines in board-checks sanitize now that -z can deliver a raw LF +224 The build gate contract never says green/red is the exit code, so an output-shape match passes as a gate +226 Reframe auto-capture as capability discovery with strict admission gates +234 Split gate-execution.md: probe evidence should not sit on a blocking-read surface +248 Role self-description: enforce the positive half and harden the guard +249 Build-worker contract: gate-execution pointer and staging discipline +252 Harden test fixtures and hermeticity into tests-lib +253 Settle and enforce the prose-anchored guard house pattern +256 Config-reader consolidation: one extractor or a recorded ADR +257 Clear the residual review findings from 0193 and 0201 +260 Tier finalize's in-context dispatches and name the push-denial posture +263 Guard the remaining AGENTS.md Shell rules across scripts, tests, and agent-executed markdown +273 Put runtime budgets on a host-relative basis and re-seed the table +276 Dummy mode — persona-calibrated human-facing language simplification +278 test_docket_example_yml's fidelity fixture goes intermittently red under parallel contention +280 Shard or re-budget the test files the suite runner reports OVER BUDGET +296 Shard tests/test_docket_status.sh — its runtime row is at the table's hard 60s ceiling +300 Close the single-backslash word-boundary gap: convert the 56 sites and make the census gating +301 The convention doc's lifecycle cardinalities are hardcoded prose with no guard +302 mint-stub dedup misses a general-form parent of a specific discovery +323 docket uninstall and version-tree collection for the Go installer +333 Partition slow Go integration tests and retire the race gate's 300s ceiling exemption +349 Make the finalize rebase-resolver dispatch cap configurable +371 Cut generated agent invocation over to native host dispatch +373 Harden integration/race test isolation under parallel load +380 Add a descendant-receipt negative fixture pinning the root-anchored trailer read +381 Stabilize internal/process TestObserveRunningThenTerminal parallel-load -race flake +384 Launch compositional Docket agents in coordinator-capable harness contexts +389 Speed up implement-next status sweeps and retire completed status children +393 Enter compositional Docket roles as coordinator-capable Codex root threads +396 finalize async gate WAITING has no CLI re-entry that resumes the same drive +397 Run the implementation preflight as one deterministic operation instead of a docket-status dispatch, and drop status --json's corpus records by default +400 Rewrite the README as a goal-first landing page and relocate its technical body to docs/ +401 Add a source-available license: PolyForm Noncommercial plus an individual commercial exemption +412 Forked implement-next/build agent still backgrounds the gate driver and yields (recurring suite-gate yield-wedge) +423 Certify native Multi-Agent V2 orchestration through Docket ImplementNext +424 Validate Codex coordinator models against a versioned capability registry +425 Restore native Codex dispatch for Multi-Agent V2 Docket coordinators +426 Constrain agent.enter to explicit legacy and feature-worktree use +433 Pilot top-level Codex coordinators with one-level native dispatch +446 Orphaned halted gate drive blocks every new worktree's first gate admission +448 Named implement-next skips unrelated maintenance preflight +449 Unrelated invalid change records must not block a named change's metadata writes or board +458 Attach refuses a same-path same-day re-attach with verify-delta invalid-state +459 Worker's gate.drive.acknowledge is refused scope-closed after the parent claims its WAITING drive +461 Allow editing an existing change's title +463 Resume gate-armed line is ambiguous when no epoch exists — dispatch context gets passed as --run-epoch +500 committed-ignore-invalid remedies print the paste-ready managed block +531 Keep the metadata branch on a local remote with neutral naming +539 Describe repository-check drift findings by family in the docket-status skill +544 Release v1.0.0-rc.1: Claude Code and Cursor tested, OpenCode shipped untested +545 Confirm in a sandbox whether Cursor runs docket subagents at their pinned models +546 Per-agent prompt-cache TTL pin, shipped 1h for implement-next +547 Measure whether the 1h cache TTL cut implement-next's cost +559 Let a change deliver a results artifact instead of a PR +562 Sweep retries deleting a leftover local branch +563 change.groom: clear stacked_on, accept relationship-only revises, insert missing fields safely +565 Refuse a stack-parent kill that would strand built children +567 Clean up stacked children when their stack lands, and finalize a child after its parent +568 Stop deferring a change that is already being built From 952a318398f83ca51e709fd1b1ea74094736fa72 Mon Sep 17 00:00:00 2001 From: Daniel Hanold <danny@danielhanold.com> Date: Tue, 20 Oct 2026 10:01:50 -0400 Subject: [PATCH 08/12] feat(open): --export writes a clean Markdown copy, reports leftovers and mentions, and opens it --- internal/app/open.go | 58 ++++- internal/app/open_export.go | 249 ++++++++++++++++++++ internal/app/open_export_test.go | 377 +++++++++++++++++++++++++++++++ internal/app/open_test.go | 13 ++ internal/cli/presenter.go | 6 + internal/cli/presenter_test.go | 27 +++ 6 files changed, 718 insertions(+), 12 deletions(-) create mode 100644 internal/app/open_export.go create mode 100644 internal/app/open_export_test.go diff --git a/internal/app/open.go b/internal/app/open.go index 80211d2ad..445495b04 100644 --- a/internal/app/open.go +++ b/internal/app/open.go @@ -55,6 +55,9 @@ const ( ReasonOpenFileMissing = "file-missing" ReasonOpenNoOpener = "no-opener" ReasonOpenOpenerFailed = "opener-failed" + ReasonOpenInvalidOption = "invalid-option" // an export flag used where it does not apply + ReasonOpenOutputPathInvalid = "output-path-invalid" // the export destination cannot be written + ReasonOpenExportFailed = "export-failed" // reading the source or writing the copy failed ) // openNoteNotGitHub is the note attached when a GitHub page was wanted but the @@ -73,6 +76,11 @@ type OpenOptions struct { What string ID int // 0 = infer from the checked-out branch Print bool + + // Export writes a clean Markdown copy of the artifact and opens the copy. + Export bool + OutputPath string // "" = the default destination + Warnings string // "" = WarningsAll } // OpenDeps is what Open reads and runs, injected so tests start no real git @@ -82,6 +90,11 @@ type OpenDeps struct { Checkout func(ctx context.Context, dir string) (gitcli.CheckoutState, error) Prepare func(ctx context.Context, repoDir string) RepositoryPrepareResult Opener Opener + + // The export destination's seams; production sets all three. + HomeDir func() (string, error) + Getwd func() (string, error) + GOOS string } // OpenResult is the document `docket open` emits for every outcome. ChangeID is @@ -96,6 +109,12 @@ type OpenResult struct { Notes []string `json:"notes"` Reason string `json:"reason,omitempty"` Message string `json:"message,omitempty"` + + // Export fields, set only by --export; Leftovers and Mentions follow --warnings. + ExportedPath string `json:"exported_path,omitempty"` + Replaced bool `json:"replaced,omitempty"` + Leftovers []ExportLeftover `json:"leftovers,omitempty"` + Mentions *ExportMentions `json:"mentions,omitempty"` } // HumanText renders the result for a terminal: the target alone on success @@ -158,7 +177,9 @@ func ParseOpenArgs(args []string) (string, int, error) { // records when the id is 0) to a target and opens it. A private repository, // open.artifacts: local, or a non-GitHub origin opens the file from the // metadata checkout after preparing it; otherwise the GitHub blob page opens. -// A change's PR always opens its URL. With Print set nothing is launched. +// A change's PR always opens its URL. With Export set the local file is always +// read and its clean copy (openExport) is what opens. With Print set nothing is +// launched. func Open(ctx context.Context, deps OpenDeps, o OpenOptions) OpenResult { res := OpenResult{What: o.What, ChangeID: o.ID, Notes: []string{}} fail := func(f openFailure) OpenResult { @@ -174,6 +195,9 @@ func Open(ctx context.Context, deps OpenDeps, o OpenOptions) OpenResult { _, _, err := ParseOpenArgs(args) return fail(openFailure{ResultInvalidInput, ReasonOpenInvalidTarget, err.Error()}) } + if err := ValidateOpenExport(o); err != nil { + return fail(openFailure{ResultInvalidInput, ReasonOpenInvalidOption, err.Error()}) + } if o.RepoDir == "" { return fail(openFailure{ResultInvalidInput, ReasonOpenInvalidTarget, "a repository directory is required"}) } @@ -197,14 +221,19 @@ func Open(ctx context.Context, deps OpenDeps, o OpenOptions) OpenResult { return fail(openFailure{result, reason, err.Error()}) } eff := pin.Config.Effective - var rel string + var ( + rel string + c domain.Change + snap domain.Snapshot + ) if o.What == "board" { if !slices.Contains(eff.BoardSurfaces.Value, boardSurfaceInline) { return fail(openFailure{ResultInvalidState, ReasonOpenBoardDisabled, "this repository has no board (board_surfaces has no inline surface)"}) } rel = boardCorpusPath(eff) } else { - c, f := resolveOpenChange(ctx, deps.Reader, pin, o.ID, branch) + var f *openFailure + c, snap, f = resolveOpenChange(ctx, deps.Reader, pin, o.ID, branch) if f != nil { return fail(*f) } @@ -226,6 +255,9 @@ func Open(ctx context.Context, deps OpenDeps, o OpenOptions) OpenResult { if !filepath.IsLocal(filepath.FromSlash(rel)) { return fail(openFailure{ResultInvalidState, ReasonOpenPathInvalid, fmt.Sprintf("%s path %q is not a path inside the repository", o.What, rel)}) } + if o.Export { + return openExport(ctx, deps, o, dir, pin, c, snap, rel, res) + } if pin.Layout.Mode != layout.Private && eff.Open.Artifacts.Value != "local" { if u := linkContextOf(pin).BlobURL(rel); u != "" { res.Target, res.TargetKind = u, OpenTargetKindURL @@ -273,30 +305,32 @@ func localArtifact(ctx context.Context, deps OpenDeps, dir string, pin StatusPin } // resolveOpenChange reads the pinned corpus and returns change id, or, when id -// is 0, the change whose recorded branch is branch. -func resolveOpenChange(ctx context.Context, reader StatusReader, pin StatusPin, id int, branch string) (domain.Change, *openFailure) { +// is 0, the change whose recorded branch is branch, plus the snapshot it built. +func resolveOpenChange(ctx context.Context, reader StatusReader, pin StatusPin, id int, branch string) (domain.Change, domain.Snapshot, *openFailure) { blobs, err := reader.ReadCorpus(ctx, pin) if err != nil { result, reason := classifyStatusError(ctx, err) - return domain.Change{}, &openFailure{result, reason, err.Error()} + return domain.Change{}, domain.Snapshot{}, &openFailure{result, reason, err.Error()} } inputs, _ := parseCorpus(blobs) build, err := repository.BuildSnapshot(repository.BuildInput{Config: pin.Config.Effective, Documents: inputs}) if err != nil { - return domain.Change{}, &openFailure{ResultInternalError, ReasonStatusInternalError, err.Error()} + return domain.Change{}, domain.Snapshot{}, &openFailure{ResultInternalError, ReasonStatusInternalError, err.Error()} } + snap := build.Snapshot if id == 0 { - return inferChangeFromBranch(build.Snapshot, branch) + c, f := inferChangeFromBranch(snap, branch) + return c, snap, f } - c, out := build.Snapshot.Change(domain.ChangeID(id)) + c, out := snap.Change(domain.ChangeID(id)) switch out { case domain.LookupFound: - return c, nil + return c, snap, nil case domain.LookupAmbiguous: - return domain.Change{}, &openFailure{ResultInvalidState, ReasonOpenAmbiguousChange, + return domain.Change{}, snap, &openFailure{ResultInvalidState, ReasonOpenAmbiguousChange, fmt.Sprintf("more than one record claims change %d — refusing to choose", id)} } - return domain.Change{}, &openFailure{ResultInvalidInput, ReasonOpenUnknownChange, fmt.Sprintf("no change %d", id)} + return domain.Change{}, snap, &openFailure{ResultInvalidInput, ReasonOpenUnknownChange, fmt.Sprintf("no change %d", id)} } // changeArtifactPath returns the repository-relative path what names for c: the diff --git a/internal/app/open_export.go b/internal/app/open_export.go new file mode 100644 index 000000000..7ed89e1f5 --- /dev/null +++ b/internal/app/open_export.go @@ -0,0 +1,249 @@ +package app + +// open_export.go holds the --export branch of `docket open`: its usage check, +// the destination rule, the atomic write of the clean copy, and the warnings +// the self-check reports, filtered by --warnings. + +import ( + "context" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "strconv" + "strings" + + "github.com/danielhanold/docket/internal/domain" + "github.com/danielhanold/docket/internal/export" + "github.com/danielhanold/docket/internal/exportcheck" +) + +// The --warnings values: which warning lists an export reports. +const ( + WarningsAll = "all" + WarningsLeftovers = "leftovers" + WarningsMentions = "mentions" +) + +// ExportRuleStrayMarker is the leftover rule of an unpaired or malformed marker +// line the transform removed from the source; its Line is a source line. +const ExportRuleStrayMarker = "stray-marker" + +// ExportLeftover is one piece of docket machinery the self-check found in the +// exported copy, or a damaged marker the transform removed from the source. +type ExportLeftover struct { + Line int `json:"line"` + Text string `json:"text"` + Rule string `json:"rule"` +} + +// ExportMentions lists the exported lines, code included, that name docket. +type ExportMentions struct { + Count int `json:"count"` + Lines []int `json:"lines"` +} + +// ValidateOpenExport is the one usage check of the export flags, shared by the +// CLI and Open: --export takes no board or pr, --output-path and --warnings +// need --export, and --warnings takes all, leftovers, or mentions. +func ValidateOpenExport(o OpenOptions) error { + if !o.Export { + switch { + case o.OutputPath != "": + return errors.New("--output-path needs --export") + case o.Warnings != "": + return errors.New("--warnings needs --export") + } + return nil + } + if o.What == "board" || o.What == "pr" { + return fmt.Errorf("--export works on change, spec, plan, or results, not %s", o.What) + } + switch o.Warnings { + case "", WarningsAll, WarningsLeftovers, WarningsMentions: + return nil + } + return fmt.Errorf("invalid --warnings value %q — choose all, leftovers, or mentions", o.Warnings) +} + +// HumanWarnings returns the warning lines a human renderer writes after the +// notes: one per leftover, then one for the docket mentions when there are any. +func (r OpenResult) HumanWarnings() []string { + out := []string{} + for _, l := range r.Leftovers { + if l.Rule == ExportRuleStrayMarker { + out = append(out, fmt.Sprintf("damaged marker removed at source line %d: %s — the source has an unpaired marker; the exported file is clean", l.Line, l.Text)) + continue + } + out = append(out, fmt.Sprintf("leftover line %d (%s): %s — docket machinery the export did not remove; edit it out before sharing", l.Line, l.Rule, l.Text)) + } + if m := r.Mentions; m != nil && m.Count > 0 { + nums := make([]string, len(m.Lines)) + for i, n := range m.Lines { + nums[i] = strconv.Itoa(n) + } + if m.Count == 1 { + out = append(out, fmt.Sprintf("1 mention of docket on line %s — kept as written; review it before sharing", strings.Join(nums, ", "))) + } else { + out = append(out, fmt.Sprintf("%d mentions of docket on lines %s — kept as written; review them before sharing", m.Count, strings.Join(nums, ", "))) + } + } + return out +} + +// exportKinds maps an exportable target to its export kind. +var exportKinds = map[string]export.Kind{ + "change": export.KindIssue, "spec": export.KindSpec, "plan": export.KindPlan, "results": export.KindResults, +} + +// openExport reads rel from the local metadata checkout (whatever the +// repository's open routing), writes its clean copy to the destination, runs +// the self-check, and opens or prints the copy. Warnings never block. +func openExport(ctx context.Context, deps OpenDeps, o OpenOptions, dir string, pin StatusPin, c domain.Change, snap domain.Snapshot, rel string, res OpenResult) OpenResult { + fail := func(f openFailure) OpenResult { + res.Envelope = NewEnvelope(OperationOpen, f.result) + res.Reason, res.Message = f.reason, f.message + return res + } + if deps.HomeDir == nil || deps.Getwd == nil || deps.GOOS == "" { + return fail(openFailure{ResultInternalError, ReasonOpenExportFailed, "export is not wired: home directory, working directory, and platform are required"}) + } + src, notes, f := localArtifact(ctx, deps, dir, pin, rel) + res.Notes = append(res.Notes, notes...) + if f != nil { + return fail(*f) + } + body, err := os.ReadFile(src) + if err != nil { + return fail(openFailure{ResultExternalFailed, ReasonOpenExportFailed, fmt.Sprintf("could not read %s: %v", src, err)}) + } + + kind := exportKinds[o.What] + created := "" + if cr := c.Created(); cr.State == domain.FieldPresent { + created = cr.Value.Format("2006-01-02") + } + dest, f := exportDestination(deps, o.OutputPath, export.FileName(kind, rel, created, c.Slug())) + if f != nil { + return fail(*f) + } + + titles := exportTitles(snap) + out := export.Transform(export.Input{Kind: kind, Source: body, Title: c.Title(), Titles: titles}) + report := exportcheck.Check(out.Markdown, func(id int) bool { _, ok := titles[id]; return ok }) + + replaced, err := writeExport(dest, out.Markdown) + if err != nil { + return fail(openFailure{ResultExternalFailed, ReasonOpenExportFailed, fmt.Sprintf("could not write %s: %v", dest, err)}) + } + if replaced { + res.Notes = append(res.Notes, "replaced "+dest) + } + res.ExportedPath, res.Replaced = dest, replaced + + warnings := o.Warnings + if warnings == "" { + warnings = WarningsAll + } + if warnings != WarningsMentions { + for _, s := range out.Stray { + res.Leftovers = append(res.Leftovers, ExportLeftover{Line: s.SourceLine, Text: s.Text, Rule: ExportRuleStrayMarker}) + } + for _, l := range report.Leftovers { + res.Leftovers = append(res.Leftovers, ExportLeftover{Line: l.Line, Text: l.Text, Rule: l.Rule}) + } + } + if warnings != WarningsLeftovers { + res.Mentions = &ExportMentions{Count: report.Mentions.Count, Lines: append([]int{}, report.Mentions.Lines...)} + } + res.Target, res.TargetKind = dest, OpenTargetKindFile + return finishOpen(ctx, deps, o, res) +} + +// exportTitles maps every change id exactly one record claims to its title; an +// ambiguous id is left out, so the export treats it as unknown. +func exportTitles(snap domain.Snapshot) export.Titles { + count := map[int]int{} + for _, c := range snap.Changes() { + count[int(c.ID())]++ + } + titles := export.Titles{} + for _, c := range snap.Changes() { + if id := int(c.ID()); count[id] == 1 { + titles[id] = c.Title() + } + } + return titles +} + +// exportDestination resolves where the copy named name is written. With no +// output path it goes to ~/Downloads on darwin (refused when missing) and the +// home directory elsewhere. An existing directory takes the copy under name; +// any other output path is the exact file, relative to the working directory, +// and its parent directory must exist. +func exportDestination(deps OpenDeps, outputPath, name string) (string, *openFailure) { + invalid := func(msg string) (string, *openFailure) { + return "", &openFailure{ResultInvalidState, ReasonOpenOutputPathInvalid, msg} + } + if outputPath == "" { + home, err := deps.HomeDir() + if err != nil || home == "" { + return invalid(fmt.Sprintf("cannot find the home directory (%v) — pass --output-path", err)) + } + dir := home + if deps.GOOS == "darwin" { + dir = filepath.Join(home, "Downloads") + if info, err := os.Stat(dir); err != nil || !info.IsDir() { + return invalid(fmt.Sprintf("%s does not exist — pass --output-path to choose where the export goes", dir)) + } + } + return filepath.Join(dir, name), nil + } + path := outputPath + if !filepath.IsAbs(path) { + wd, err := deps.Getwd() + if err != nil { + return invalid(fmt.Sprintf("cannot resolve %s: %v", outputPath, err)) + } + path = filepath.Join(wd, path) + } + if info, err := os.Stat(path); err == nil && info.IsDir() { + return filepath.Join(path, name), nil + } + parent := filepath.Dir(path) + if info, err := os.Stat(parent); err != nil || !info.IsDir() { + return invalid(fmt.Sprintf("%s is not an existing directory — create it or choose another --output-path", parent)) + } + return path, nil +} + +// writeExport writes data to dest atomically (a temp file beside it, mode 0644, +// then a rename) and reports whether dest existed before. +func writeExport(dest string, data []byte) (bool, error) { + _, statErr := os.Lstat(dest) + replaced := statErr == nil + if statErr != nil && !errors.Is(statErr, fs.ErrNotExist) { + return false, statErr + } + tmp, err := os.CreateTemp(filepath.Dir(dest), "."+filepath.Base(dest)+".*.tmp") + if err != nil { + return false, err + } + name := tmp.Name() + defer func() { _ = os.Remove(name) }() // a no-op once renamed + if _, err := tmp.Write(data); err != nil { + _ = tmp.Close() + return false, err + } + if err := tmp.Close(); err != nil { + return false, err + } + if err := os.Chmod(name, 0o644); err != nil { + return false, err + } + if err := os.Rename(name, dest); err != nil { + return false, err + } + return replaced, nil +} diff --git a/internal/app/open_export_test.go b/internal/app/open_export_test.go new file mode 100644 index 000000000..5e19c6e52 --- /dev/null +++ b/internal/app/open_export_test.go @@ -0,0 +1,377 @@ +package app + +import ( + "context" + "encoding/json" + "errors" + "os" + "path/filepath" + "reflect" + "regexp" + "strings" + "testing" + + "github.com/danielhanold/docket/internal/testsupport" +) + +// retitle gives a fixture record a real title in place of openChange's +// "Change N", which title cleaning would itself treat as a change reference. +func retitle(b StatusBlob, title string) StatusBlob { + b.Data = regexp.MustCompile(`(?m)^title: .*$`).ReplaceAll(b.Data, []byte("title: "+title)) + return b +} + +// exportCorpus is openCorpus with change 3 and change 7 carrying real titles. +func exportCorpus() []StatusBlob { + blobs := openCorpus() + for i, b := range blobs { + switch { + case strings.Contains(b.Path, "0003-old"): + blobs[i] = retitle(b, "Old gadget") + case strings.Contains(b.Path, "0007-widget"): + blobs[i] = retitle(b, "Widget export") + } + } + return blobs +} + +const exportSpecBody = "<!-- docket:backlink:start (generated — do not hand-edit) -->\n" + + "> ↩ **[Change 0007 — Widget export](../../changes/active/0007-widget.md)**\n" + + "<!-- docket:backlink:end -->\n\n" + + "# Widget design\n\nBuilt after change 0003, see [the notes](https://example.test/n).\n" + +const exportSpecClean = "# Widget design\n\nBuilt after \"Old gadget\", see the notes.\n" + +// exportDeps is the fixture's deps plus the export seams: home is the home +// directory, GOOS the platform, and the working directory is cwd. +func (f *openFixture) exportDeps(home, goos, cwd string) OpenDeps { + d := f.deps() + d.HomeDir = func() (string, error) { return home, nil } + d.GOOS = goos + d.Getwd = func() (string, error) { return cwd, nil } + return d +} + +func (f *openFixture) export(t *testing.T, deps OpenDeps, what string, id int, mut func(*OpenOptions)) OpenResult { + t.Helper() + o := OpenOptions{RepoDir: f.repoDir, What: what, ID: id, Export: true} + if mut != nil { + mut(&o) + } + return Open(context.Background(), deps, o) +} + +func readExport(t *testing.T, path string) string { + t.Helper() + b, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + return string(b) +} + +func TestOpenExportWritesCleanCopy(t *testing.T) { + f := newOpenFixture(t, "", false, openWeb, exportCorpus()...) + f.writeBody(t, widgetSpec, exportSpecBody) + out := testsupport.TempDir(t) + res := f.export(t, f.exportDeps(testsupport.TempDir(t), "linux", "/nowhere"), "spec", 7, func(o *OpenOptions) { + o.Print, o.OutputPath = true, out + }) + want := filepath.Join(out, "2026-01-02-spec-widget.md") + if res.Result != ResultApplied || res.Launched || res.ExportedPath != want || res.Target != want || + res.TargetKind != OpenTargetKindFile || len(f.opener.targets) != 0 { + t.Fatalf("Open = (%s, launched %v, exported %q, target %q, %s, %q)", res.Result, res.Launched, res.ExportedPath, res.Target, res.TargetKind, res.Message) + } + if got := readExport(t, want); got != exportSpecClean { + t.Errorf("exported bytes = %q, want %q", got, exportSpecClean) + } + info, err := os.Stat(want) + if err != nil || info.Mode().Perm() != 0o644 { + t.Errorf("mode = %v (%v), want 0644", info, err) + } + if res.Replaced || len(res.Leftovers) != 0 || res.Mentions == nil || res.Mentions.Count != 0 { + t.Errorf("replaced %v leftovers %v mentions %+v", res.Replaced, res.Leftovers, res.Mentions) + } + entries, _ := os.ReadDir(out) + if len(entries) != 1 { + t.Errorf("destination holds %d entries, want only the export (no temp file left)", len(entries)) + } +} + +func TestOpenExportOpensTheCopy(t *testing.T) { + f := newOpenFixture(t, "", false, openWeb, exportCorpus()...) + f.writeBody(t, widgetSpec, exportSpecBody) + out := testsupport.TempDir(t) + res := f.export(t, f.exportDeps(testsupport.TempDir(t), "linux", "/nowhere"), "spec", 7, func(o *OpenOptions) { o.OutputPath = out }) + want := filepath.Join(out, "2026-01-02-spec-widget.md") + if res.Result != ResultApplied || !res.Launched || !reflect.DeepEqual(f.opener.targets, []string{want}) { + t.Errorf("(%s, launched %v, opener %v), want the exported copy opened", res.Result, res.Launched, f.opener.targets) + } +} + +// TestOpenExportIgnoresGitHubRouting: a shared repository with a GitHub origin +// and the default open.artifacts still exports the local metadata-checkout file. +func TestOpenExportIgnoresGitHubRouting(t *testing.T) { + f := newOpenFixture(t, "", false, openWeb, exportCorpus()...) + f.writeBody(t, widgetSpec, exportSpecBody) + out := testsupport.TempDir(t) + res := f.export(t, f.exportDeps(testsupport.TempDir(t), "linux", "/nowhere"), "spec", 7, func(o *OpenOptions) { o.OutputPath, o.Print = out, true }) + if res.Result != ResultApplied || res.TargetKind != OpenTargetKindFile || !strings.HasPrefix(res.Target, out) || len(f.prepared) != 1 { + t.Errorf("(%s, %s, %q) prepared %v", res.Result, res.TargetKind, res.Target, f.prepared) + } + if !reflect.DeepEqual(res.Notes, []string{}) { + t.Errorf("notes %q, want none (no not-GitHub note on the export path)", res.Notes) + } +} + +func TestOpenExportKeepsStalenessNote(t *testing.T) { + f := newOpenFixture(t, "", false, openWeb, exportCorpus()...) + f.refusePrepare("metadata-worktree-dirty") + f.writeBody(t, widgetSpec, exportSpecBody) + out := testsupport.TempDir(t) + res := f.export(t, f.exportDeps(testsupport.TempDir(t), "linux", "/nowhere"), "spec", 7, func(o *OpenOptions) { o.OutputPath, o.Print = out, true }) + if res.Result != ResultApplied || !reflect.DeepEqual(res.Notes, []string{openNoteStale("metadata-worktree-dirty")}) { + t.Errorf("(%s, %q)", res.Result, res.Notes) + } +} + +func TestOpenExportDefaultDestination(t *testing.T) { + name := "2026-01-02-spec-widget.md" + newF := func() *openFixture { + f := newOpenFixture(t, "", false, openWeb, exportCorpus()...) + f.writeBody(t, widgetSpec, exportSpecBody) + return f + } + print := func(o *OpenOptions) { o.Print = true } + + home := testsupport.TempDir(t) + if err := os.Mkdir(filepath.Join(home, "Downloads"), 0o755); err != nil { + t.Fatal(err) + } + f := newF() + if res := f.export(t, f.exportDeps(home, "darwin", "/nowhere"), "spec", 7, print); res.Result != ResultApplied || + res.ExportedPath != filepath.Join(home, "Downloads", name) { + t.Errorf("darwin: (%s, %q, %q)", res.Result, res.ExportedPath, res.Message) + } + + bare := testsupport.TempDir(t) + f = newF() + res := f.export(t, f.exportDeps(bare, "darwin", "/nowhere"), "spec", 7, print) + if res.Result != ResultInvalidState || res.Reason != ReasonOpenOutputPathInvalid || !strings.Contains(res.Message, "--output-path") || + strings.Contains(res.Message, "\n") || res.ExportedPath != "" { + t.Errorf("darwin without Downloads: (%s, %s, %q)", res.Result, res.Reason, res.Message) + } + if entries, _ := os.ReadDir(bare); len(entries) != 0 { + t.Errorf("refusal wrote %d entries into home", len(entries)) + } + + linux := testsupport.TempDir(t) + f = newF() + if res := f.export(t, f.exportDeps(linux, "linux", "/nowhere"), "spec", 7, print); res.Result != ResultApplied || + res.ExportedPath != filepath.Join(linux, name) { + t.Errorf("linux: (%s, %q, %q)", res.Result, res.ExportedPath, res.Message) + } + + f = newF() + d := f.exportDeps(linux, "linux", "/nowhere") + d.HomeDir = func() (string, error) { return "", errors.New("no home") } + if res := f.export(t, d, "spec", 7, print); res.Result == ResultApplied || res.ExportedPath != "" { + t.Errorf("home error: (%s, %s, %q)", res.Result, res.Reason, res.Message) + } +} + +func TestOpenExportOutputPath(t *testing.T) { + newF := func() *openFixture { + f := newOpenFixture(t, "", false, openWeb, exportCorpus()...) + f.writeBody(t, widgetSpec, exportSpecBody) + return f + } + home := testsupport.TempDir(t) + dir := testsupport.TempDir(t) + at := func(p string) func(*OpenOptions) { return func(o *OpenOptions) { o.OutputPath, o.Print = p, true } } + + f := newF() + if res := f.export(t, f.exportDeps(home, "linux", "/nowhere"), "spec", 7, at(dir)); res.ExportedPath != filepath.Join(dir, "2026-01-02-spec-widget.md") { + t.Errorf("dir: (%s, %q, %q)", res.Result, res.ExportedPath, res.Message) + } + + exact := filepath.Join(dir, "shared.md") + f = newF() + if res := f.export(t, f.exportDeps(home, "linux", "/nowhere"), "spec", 7, at(exact)); res.ExportedPath != exact || readExport(t, exact) != exportSpecClean { + t.Errorf("file: (%s, %q, %q)", res.Result, res.ExportedPath, res.Message) + } + + cwd := testsupport.TempDir(t) + f = newF() + if res := f.export(t, f.exportDeps(home, "linux", cwd), "spec", 7, at("out.md")); res.ExportedPath != filepath.Join(cwd, "out.md") { + t.Errorf("relative: (%s, %q, %q)", res.Result, res.ExportedPath, res.Message) + } + + missing := filepath.Join(dir, "no-such-dir", "x.md") + f = newF() + res := f.export(t, f.exportDeps(home, "linux", "/nowhere"), "spec", 7, at(missing)) + if res.Result != ResultInvalidState || res.Reason != ReasonOpenOutputPathInvalid || strings.Contains(res.Message, "\n") { + t.Errorf("missing parent: (%s, %s, %q)", res.Result, res.Reason, res.Message) + } + if _, err := os.Stat(filepath.Dir(missing)); !errors.Is(err, os.ErrNotExist) { + t.Errorf("missing parent was created: %v", err) + } + + again := testsupport.TempDir(t) + f = newF() + first := f.export(t, f.exportDeps(home, "linux", "/nowhere"), "spec", 7, at(again)) + second := f.export(t, f.exportDeps(home, "linux", "/nowhere"), "spec", 7, at(again)) + if first.Replaced || !second.Replaced || second.Result != ResultApplied || + !reflect.DeepEqual(second.Notes, []string{"replaced " + second.ExportedPath}) { + t.Errorf("re-export: first replaced %v, second (%s, %v, %q)", first.Replaced, second.Result, second.Replaced, second.Notes) + } +} + +func TestOpenExportIssueNameAndH1(t *testing.T) { + f := newOpenFixture(t, "", false, openWeb, exportCorpus()...) + f.writeBody(t, "docs/changes/active/0007-widget.md", + "---\nid: 7\ntitle: Widget export\n---\n\n# Widget export\n\n## Why\n\nBecause change 0003 broke.\n\n## Reconcile log\n\nnoise\n") + out := testsupport.TempDir(t) + res := f.export(t, f.exportDeps(testsupport.TempDir(t), "linux", "/nowhere"), "change", 7, func(o *OpenOptions) { o.OutputPath, o.Print = out, true }) + want := filepath.Join(out, "2026-01-02-issue-widget.md") + if res.Result != ResultApplied || res.ExportedPath != want { + t.Fatalf("(%s, %q, %q)", res.Result, res.ExportedPath, res.Message) + } + if got, w := readExport(t, want), "# Widget export\n\n## Why\n\nBecause \"Old gadget\" broke.\n"; got != w { + t.Errorf("issue = %q, want %q", got, w) + } +} + +func TestOpenExportWarningsFilter(t *testing.T) { + body := "# Widget design\n\n<!-- docket:artifacts:start -->\nTalk about docket here.\n" + for _, tc := range []struct { + warnings string + leftovers, mentions bool + }{{"", true, true}, {WarningsAll, true, true}, {WarningsLeftovers, true, false}, {WarningsMentions, false, true}} { + f := newOpenFixture(t, "", false, openWeb, exportCorpus()...) + f.writeBody(t, widgetSpec, body) + out := testsupport.TempDir(t) + res := f.export(t, f.exportDeps(testsupport.TempDir(t), "linux", "/nowhere"), "spec", 7, func(o *OpenOptions) { + o.OutputPath, o.Print, o.Warnings = out, true, tc.warnings + }) + if res.Result != ResultApplied || res.ExportedPath == "" { + t.Errorf("%q: (%s, %q)", tc.warnings, res.Result, res.Message) + continue + } + wantLeft := []ExportLeftover{{Line: 3, Text: "<!-- docket:artifacts:start -->", Rule: ExportRuleStrayMarker}} + if !tc.leftovers { + wantLeft = nil + } + if !reflect.DeepEqual(res.Leftovers, wantLeft) { + t.Errorf("%q: leftovers %+v, want %+v", tc.warnings, res.Leftovers, wantLeft) + } + var wantMent *ExportMentions + if tc.mentions { + wantMent = &ExportMentions{Count: 1, Lines: []int{3}} + } + if !reflect.DeepEqual(res.Mentions, wantMent) { + t.Errorf("%q: mentions %+v, want %+v", tc.warnings, res.Mentions, wantMent) + } + wantHuman := []string{} + if tc.leftovers { + wantHuman = append(wantHuman, "damaged marker removed at source line 3: <!-- docket:artifacts:start --> — the source has an unpaired marker; the exported file is clean") + } + if tc.mentions { + wantHuman = append(wantHuman, "1 mention of docket on line 3 — kept as written; review it before sharing") + } + if got := res.HumanWarnings(); !reflect.DeepEqual(got, wantHuman) { + t.Errorf("%q: human warnings %q, want %q", tc.warnings, got, wantHuman) + } + } +} + +func TestOpenResultHumanWarningsWording(t *testing.T) { + r := OpenResult{ + Leftovers: []ExportLeftover{{Line: 12, Text: "[x](y)", Rule: "link"}}, + Mentions: &ExportMentions{Count: 3, Lines: []int{2, 5, 9}}, + } + want := []string{ + "leftover line 12 (link): [x](y) — docket machinery the export did not remove; edit it out before sharing", + "3 mentions of docket on lines 2, 5, 9 — kept as written; review them before sharing", + } + if got := r.HumanWarnings(); !reflect.DeepEqual(got, want) { + t.Errorf("HumanWarnings = %q, want %q", got, want) + } + if got := (OpenResult{Mentions: &ExportMentions{Lines: []int{}}}).HumanWarnings(); len(got) != 0 { + t.Errorf("zero mentions render %q, want nothing", got) + } +} + +// TestOpenExportAmbiguousIDLeftAsWritten (Review Focus 4): an id two records +// claim is unknown to the export, never given either record's title. +func TestOpenExportAmbiguousIDLeftAsWritten(t *testing.T) { + blobs := append(exportCorpus(), retitle(openChange(3, "old-copy", false, "branch: feat/old-copy\n"), "Copy gadget")) + f := newOpenFixture(t, "", false, openWeb, blobs...) + f.writeBody(t, widgetSpec, exportSpecBody) + out := testsupport.TempDir(t) + res := f.export(t, f.exportDeps(testsupport.TempDir(t), "linux", "/nowhere"), "spec", 7, func(o *OpenOptions) { o.OutputPath, o.Print = out, true }) + if res.Result != ResultApplied { + t.Fatalf("(%s, %q)", res.Result, res.Message) + } + if got := readExport(t, res.ExportedPath); !strings.Contains(got, "Built after change 0003, see the notes.") { + t.Errorf("ambiguous id converted: %q", got) + } +} + +func TestValidateOpenExport(t *testing.T) { + bad := []OpenOptions{ + {What: "board", Export: true}, {What: "pr", ID: 7, Export: true}, + {What: "spec", OutputPath: "x.md"}, {What: "spec", Warnings: WarningsAll}, + {What: "spec", Export: true, Warnings: "bogus"}, + } + for _, o := range bad { + if err := ValidateOpenExport(o); err == nil || strings.Contains(err.Error(), "\n") { + t.Errorf("ValidateOpenExport(%+v) = %v, want a one-line error", o, err) + } + } + good := []OpenOptions{ + {What: "spec"}, {What: "board"}, {What: "pr", ID: 7}, + {What: "spec", Export: true}, {What: "change", Export: true, OutputPath: "x", Warnings: WarningsLeftovers}, + {What: "plan", Export: true, Warnings: WarningsMentions}, {What: "results", Export: true, Warnings: WarningsAll}, + } + for _, o := range good { + if err := ValidateOpenExport(o); err != nil { + t.Errorf("ValidateOpenExport(%+v) = %v, want nil", o, err) + } + } + // Open refuses the same way, writing nothing and opening nothing. + f := newOpenFixture(t, "", false, openWeb, exportCorpus()...) + res := Open(context.Background(), f.deps(), OpenOptions{RepoDir: f.repoDir, What: "pr", ID: 7, Export: true}) + if res.Result != ResultInvalidInput || res.Reason != ReasonOpenInvalidOption || len(f.opener.targets) != 0 || f.reader.pinCount != 0 { + t.Errorf("Open pr --export: (%s, %s, %q) opener %v", res.Result, res.Reason, res.Message, f.opener.targets) + } + res = Open(context.Background(), f.deps(), OpenOptions{RepoDir: f.repoDir, What: "spec", ID: 7, OutputPath: "x.md"}) + if res.Result != ResultInvalidInput || res.Reason != ReasonOpenInvalidOption { + t.Errorf("Open spec --output-path without --export: (%s, %s, %q)", res.Result, res.Reason, res.Message) + } +} + +func TestOpenResultExportJSON(t *testing.T) { + raw, _ := json.Marshal(OpenResult{What: "spec", Notes: []string{}, ExportedPath: "/d/x.md", Replaced: true, + Leftovers: []ExportLeftover{{Line: 2, Text: "t", Rule: "link"}}, Mentions: &ExportMentions{Count: 1, Lines: []int{4}}}) + var doc map[string]any + if err := json.Unmarshal(raw, &doc); err != nil { + t.Fatal(err) + } + want := map[string]any{ + "exported_path": "/d/x.md", "replaced": true, + "leftovers": []any{map[string]any{"line": float64(2), "text": "t", "rule": "link"}}, + "mentions": map[string]any{"count": float64(1), "lines": []any{float64(4)}}, + } + for k, w := range want { + if !reflect.DeepEqual(doc[k], w) { + t.Errorf("%s = %#v, want %#v (doc %s)", k, doc[k], w, raw) + } + } + plain, _ := json.Marshal(OpenResult{What: "spec", Notes: []string{}}) + for k := range want { + if strings.Contains(string(plain), `"`+k+`"`) { + t.Errorf("non-export document carries %s: %s", k, plain) + } + } +} diff --git a/internal/app/open_test.go b/internal/app/open_test.go index 252d7248a..babcb62f7 100644 --- a/internal/app/open_test.go +++ b/internal/app/open_test.go @@ -185,6 +185,19 @@ func (f *openFixture) writeFile(t *testing.T, rel string) string { return p } +// writeBody writes body at rel inside the metadata checkout and returns its path. +func (f *openFixture) writeBody(t *testing.T, rel, body string) string { + t.Helper() + p := filepath.Join(f.root, filepath.FromSlash(rel)) + if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(p, []byte(body), 0o644); err != nil { + t.Fatal(err) + } + return p +} + func (f *openFixture) refusePrepare(code string) { f.prepare = RepositoryPrepareResult{Envelope: NewEnvelope(OperationRepositoryPrepare, ResultInvalidState), Disposition: PrepareDispositionRefused, Findings: []reposetup.Finding{{Code: code}}} diff --git a/internal/cli/presenter.go b/internal/cli/presenter.go index 477593867..119d6ed0a 100644 --- a/internal/cli/presenter.go +++ b/internal/cli/presenter.go @@ -40,6 +40,12 @@ func (p Presenter) Present(r app.OperationResult) int { fmt.Fprintf(p.Stderr, "note: %s\n", note) } } + // Warnings (an export's leftovers and mentions) follow the notes on stderr. + if w, ok := r.(interface{ HumanWarnings() []string }); ok { + for _, line := range w.HumanWarnings() { + fmt.Fprintf(p.Stderr, "warning: %s\n", line) + } + } return app.ExitCode(r.Env().Result) } diff --git a/internal/cli/presenter_test.go b/internal/cli/presenter_test.go index 3c48a83b0..d42a40148 100644 --- a/internal/cli/presenter_test.go +++ b/internal/cli/presenter_test.go @@ -92,3 +92,30 @@ func TestPresentHumanNotesGoToStderr(t *testing.T) { t.Errorf("JSON mode wrote stderr %q", errBuf.String()) } } + +// TestPresenterWritesWarningsToStderr pins the export output: stdout is +// exactly the exported path, stderr carries the notes and then one "warning:" +// line each, and JSON mode writes nothing to stderr. +func TestPresenterWritesWarningsToStderr(t *testing.T) { + r := app.OpenResult{ + Envelope: app.NewEnvelope(app.OperationOpen, app.ResultApplied), What: "spec", + Target: "/d/2026-01-02-spec-widget.md", ExportedPath: "/d/2026-01-02-spec-widget.md", + Notes: []string{"replaced /d/2026-01-02-spec-widget.md"}, + Leftovers: []app.ExportLeftover{{Line: 4, Text: "[a](b)", Rule: "link"}}, + Mentions: &app.ExportMentions{Count: 2, Lines: []int{1, 7}}, + } + var out, errBuf bytes.Buffer + Presenter{Stdout: &out, Stderr: &errBuf}.Present(r) + wantErr := "note: replaced /d/2026-01-02-spec-widget.md\n" + for _, w := range r.HumanWarnings() { + wantErr += "warning: " + w + "\n" + } + if out.String() != "/d/2026-01-02-spec-widget.md\n" || errBuf.String() != wantErr || len(r.HumanWarnings()) != 2 { + t.Errorf("stdout %q stderr %q, want stderr %q", out.String(), errBuf.String(), wantErr) + } + out.Reset() + errBuf.Reset() + if (Presenter{Stdout: &out, Stderr: &errBuf, JSON: true}).Present(r); errBuf.Len() != 0 { + t.Errorf("JSON mode wrote stderr %q", errBuf.String()) + } +} From 7d359c78ada77eec05560790a24a0c4903da4994 Mon Sep 17 00:00:00 2001 From: Daniel Hanold <danny@danielhanold.com> Date: Tue, 20 Oct 2026 10:03:55 -0400 Subject: [PATCH 09/12] feat(cli): docket open --export, --output-path, and --warnings --- docs/reference/cli.md | 4 +- internal/cli/capability_production_test.go | 2 +- internal/cli/open.go | 65 +++++++++++++++++++--- internal/cli/open_test.go | 49 ++++++++++++++++ 4 files changed, 111 insertions(+), 9 deletions(-) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 54072843a..9e347f3b3 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -46,7 +46,9 @@ Each line is a pointer: the command, what its verbs govern, and where to read th expired claims in one pass (`docket status` stays read-only). Verbs: `docket maintenance --help`. - **`docket open`** — open the board, or a change's record, spec, plan, results, or pull request, as a GitHub page or from the local metadata checkout. Without an id it opens the change whose - branch is checked out. Details: `docket open --help`. + branch is checked out. With `--export` it writes a clean Markdown copy of a change, spec, plan, + or results file, free of docket's links and generated blocks, and opens that copy. Details: + `docket open --help`. - **`docket pr`** — publish the ready-for-review pull request for an in-progress change's tested head. Verbs: `docket pr --help`. - **`docket repository`** — initialize, migrate, check, and repair the docket repository diff --git a/internal/cli/capability_production_test.go b/internal/cli/capability_production_test.go index 9573fbc48..5f7e5e530 100644 --- a/internal/cli/capability_production_test.go +++ b/internal/cli/capability_production_test.go @@ -349,7 +349,7 @@ func TestRepresentativeSignatures(t *testing.T) { "workspace.prepare": "--id <id> --revision <revision> [--repo-dir <dir>]", "workspace.checkout": "--id <id> [--head <ref>] [--repo-dir <dir>] [--revision <revision>]", // positional target and optional id lead, the optional flags trail sorted. - "open": "<what> [<id>] [--print] [--repo-dir <dir>]", + "open": "<what> [<id>] [--export] [--output-path <path>] [--print] [--repo-dir <dir>] [--warnings <which>=all]", } for id, wantSig := range want { e, ok := entryByID(entries, id) diff --git a/internal/cli/open.go b/internal/cli/open.go index b359e8246..691ce3fb1 100644 --- a/internal/cli/open.go +++ b/internal/cli/open.go @@ -2,6 +2,8 @@ package cli import ( "context" + "errors" + "os" "os/exec" "runtime" @@ -30,7 +32,10 @@ var ( Prepare: func(ctx context.Context, dir string) app.RepositoryPrepareResult { return app.RunRepositoryPrepare(ctx, app.SetupDeps{Git: client, RepoDir: dir}, app.PrepareOptions{}) }, - Opener: app.NewSystemOpener(runtime.GOOS, exec.LookPath, app.RunOpenerProcess), + Opener: app.NewSystemOpener(runtime.GOOS, exec.LookPath, app.RunOpenerProcess), + HomeDir: os.UserHomeDir, + Getwd: os.Getwd, + GOOS: runtime.GOOS, }, nil } ) @@ -44,10 +49,30 @@ func newOpenCommand(setResult func(app.OperationResult)) *cobra.Command { Short: "Open the board, or a change's record, spec, plan, results, or pull request", Long: `Without an id, opens the change whose recorded branch is checked out. Shared repositories open GitHub pages unless open.artifacts is local; private ones open -the metadata checkout's file; pr opens the pull request.`, - Args: func(_ *cobra.Command, args []string) error { - _, _, err := app.ParseOpenArgs(args) - return err +the metadata checkout's file; pr opens the pull request. + +--export writes a clean Markdown copy of a change, spec, plan, or results file +and opens that copy (--print prints its path). It always reads the local +metadata checkout. The copy drops the frontmatter, docket's generated blocks +and markers, every link (keeping its text), and docket-only sections; explicit +change references become quoted titles. Fenced code and inline code stay +exactly as written. + +The copy is named <date>-<type>-<name>.md, type one of issue, spec, plan, or +results, and lands in ~/Downloads on macOS or the home directory on Linux. +--output-path names a directory to write into or the exact file to write; an +existing file is replaced. Leftover docket machinery and mentions of docket are +reported as warnings on stderr; --warnings picks which. Warnings never block.`, + Args: func(c *cobra.Command, args []string) error { + what, id, err := app.ParseOpenArgs(args) + if err != nil { + return err + } + o, err := openOptionsFromFlags(c, what, id) + if err != nil { + return err + } + return app.ValidateOpenExport(o) }, Annotations: capability("open", EffectRead, EffectLocalWrite, EffectProcessControl), RunE: func(c *cobra.Command, args []string) error { @@ -59,16 +84,42 @@ the metadata checkout's file; pr opens the pull request.`, if err != nil { return err } - printOnly, _ := c.Flags().GetBool("print") + o, err := openOptionsFromFlags(c, what, id) + if err != nil { + return err + } + o.RepoDir = repoDir deps, err := openDepsFor() if err != nil { return err } - setResult(openRunner(c.Context(), deps, app.OpenOptions{RepoDir: repoDir, What: what, ID: id, Print: printOnly})) + setResult(openRunner(c.Context(), deps, o)) return nil }, } + cmd.Flags().Bool("export", false, "write a clean Markdown copy of the artifact and open that copy") + cmd.Flags().String("output-path", "", "directory or exact file `path` for the --export copy (default: ~/Downloads on macOS, the home directory on Linux)") + cmd.Flags().String("warnings", app.WarningsAll, "`which` --export warnings to report: all, leftovers, or mentions") cmd.Flags().Bool("print", false, "print the URL or path without opening it") cmd.Flags().String("repo-dir", "", "repository `dir` to operate on (default: current directory)") return cmd } + +// openOptionsFromFlags builds the open options from the parsed target and the +// command's flags. Warnings is set only when --warnings was given, so the +// export check sees an explicit value and never the flag's default; an +// explicitly empty --output-path is refused. +func openOptionsFromFlags(c *cobra.Command, what string, id int) (app.OpenOptions, error) { + f := c.Flags() + o := app.OpenOptions{What: what, ID: id} + o.Print, _ = f.GetBool("print") + o.Export, _ = f.GetBool("export") + o.OutputPath, _ = f.GetString("output-path") + if f.Changed("output-path") && o.OutputPath == "" { + return o, errors.New("--output-path needs a path") + } + if f.Changed("warnings") { + o.Warnings, _ = f.GetString("warnings") + } + return o, nil +} diff --git a/internal/cli/open_test.go b/internal/cli/open_test.go index ede96b8cd..a079f1bd1 100644 --- a/internal/cli/open_test.go +++ b/internal/cli/open_test.go @@ -2,6 +2,7 @@ package cli import ( "context" + "runtime" "strings" "testing" @@ -76,3 +77,51 @@ func TestOpenCLIUsageErrors(t *testing.T) { t.Errorf("usage errors reached the operation: %+v", *got) } } + +func TestOpenCLIExportOptions(t *testing.T) { + got := stubOpen(t, openOK("/tmp/x/2026-01-02-spec-widget.md")) + if _, errS, code := runCLI(t, "open", "spec", "541", "--export", "--output-path", "/tmp/x", "--warnings", "leftovers", "--print", "--repo-dir", "/tmp/repo"); code != 0 { + t.Fatalf("code %d stderr %q", code, errS) + } + if _, errS, code := runCLI(t, "open", "spec", "541", "--export", "--repo-dir", "/tmp/repo"); code != 0 { + t.Fatalf("default-warnings code %d stderr %q", code, errS) + } + want := []app.OpenOptions{ + {RepoDir: "/tmp/repo", What: "spec", ID: 541, Print: true, Export: true, OutputPath: "/tmp/x", Warnings: "leftovers"}, + {RepoDir: "/tmp/repo", What: "spec", ID: 541, Export: true}, + } + if len(*got) != 2 || (*got)[0] != want[0] || (*got)[1] != want[1] { + t.Fatalf("options = %+v, want %+v", *got, want) + } +} + +func TestOpenCLIExportUsageErrors(t *testing.T) { + got := stubOpen(t, openOK("x")) + for _, args := range [][]string{ + {"open", "board", "--export"}, + {"open", "pr", "5", "--export"}, + {"open", "spec", "5", "--output-path", "x"}, + {"open", "spec", "5", "--warnings", "all"}, + {"open", "spec", "5", "--export", "--warnings", "bogus"}, + {"open", "spec", "5", "--export", "--output-path", ""}, + } { + if _, errS, code := runCLI(t, args...); code != 2 || errS == "" || strings.Contains(strings.TrimRight(errS, "\n"), "\n") { + t.Errorf("%q: code %d stderr %q, want exit 2 and one line", args, code, errS) + } + } + if len(*got) != 0 { + t.Errorf("usage errors reached the operation: %+v", *got) + } +} + +// TestOpenCLIExportDepsWiring pins the production wiring the export needs: +// the app layer refuses an export when any of these is unset. +func TestOpenCLIExportDepsWiring(t *testing.T) { + d, err := openDepsFor() + if err != nil { + t.Skipf("git unavailable: %v", err) + } + if d.GOOS != runtime.GOOS || d.HomeDir == nil || d.Getwd == nil { + t.Fatalf("GOOS %q (want %q), HomeDir set %v, Getwd set %v", d.GOOS, runtime.GOOS, d.HomeDir != nil, d.Getwd != nil) + } +} From 30eea1e42f47ff7506f8bdd2d7c83c5b24549934 Mon Sep 17 00:00:00 2001 From: Daniel Hanold <danny@danielhanold.com> Date: Tue, 20 Oct 2026 10:59:23 -0400 Subject: [PATCH 10/12] fix(export): match spec stamps by shape, so older stamp spellings never ship as a converted title MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review finding: removeStamps and the self-check's isStamp listed stamp spellings, so 83 of 240 real stamped specs kept a stamp (`Change: #N · slug …`, `**Change:** N — title`, `Change N. Spec date …`, linked `**Change:** [#N](…)`), which step 6 then shipped as `**Change:** "<title>"` unnoticed. The transform now matches a stamp by shape on the link-stripped line: a line opening `Change`, `Change:`, or `**Change:**` with the id (or a later `· **Change:**` field). The head and its metadata go; an author sentence after it stays. The detector recognizes the label and converted-title shapes without needing a digit, still sharing no code with the transform. Two older real specs (a plain-label `·` run and a linked stamp) join the frozen corpus. --- internal/export/corpus_test.go | 7 +- internal/export/export.go | 119 +++++++++--- internal/export/export_test.go | 43 +++++ internal/export/testdata/corpus/PROVENANCE.md | 2 + ...0-frontmatter-field-domain-guard-design.md | 179 ++++++++++++++++++ ...07-20-readme-snippet-drift-guard-design.md | 100 ++++++++++ internal/export/testdata/corpus/titles.tsv | 8 + internal/exportcheck/check.go | 73 ++++--- internal/exportcheck/check_test.go | 9 + 9 files changed, 485 insertions(+), 55 deletions(-) create mode 100644 internal/export/testdata/corpus/specs/2026-07-20-frontmatter-field-domain-guard-design.md create mode 100644 internal/export/testdata/corpus/specs/2026-07-20-readme-snippet-drift-guard-design.md diff --git a/internal/export/corpus_test.go b/internal/export/corpus_test.go index 8fa71a0c0..31d2d3cdc 100644 --- a/internal/export/corpus_test.go +++ b/internal/export/corpus_test.go @@ -206,9 +206,10 @@ func readLines(md []byte) []mdLine { var ( // testStampRE is a grooming stamp shape in a spec's preamble: a line opening - // "Change N." / "Change #N,", or a "groomed <date>" sentence anywhere on it - // (which still shows once step 6 has turned the "Change N" into a title). - testStampRE = regexp.MustCompile(`(?i)^change #?\d+[.,]|\bgroomed \d{4}-\d{2}-\d{2}\b`) + // "Change N." / "Change #N,", a "Change:" label, a "Change" followed by a + // converted title, or a "groomed <date>" sentence anywhere on it (which still + // shows once step 6 has turned the "Change N" into a title). + testStampRE = regexp.MustCompile(`(?i)^change #?\d+[.,]|^change:|^change "|\bgroomed \d{4}-\d{2}-\d{2}\b`) issueH2 = map[string]bool{"## Why": true, "## What changes": true, "## Out of scope": true, "## Open questions": true} ) diff --git a/internal/export/export.go b/internal/export/export.go index 5ce168b25..243b93ce7 100644 --- a/internal/export/export.go +++ b/internal/export/export.go @@ -194,15 +194,20 @@ func keepIssueSections(lines []line, title string) []line { } var ( - // stampSentenceRE is a grooming stamp sentence at the start of a line. - stampSentenceRE = regexp.MustCompile(`^Change #?\d+[,.] [Gg]roomed \d{4}-\d{2}-\d{2}(?: \([^)]*\))?\.`) - changeOnlyRE = regexp.MustCompile(`^Change #?\d+\.$`) - boldChangeRE = regexp.MustCompile(`^\*\*Change:\*\* #?\d+$`) - boldPairRE = regexp.MustCompile(`^\*\*[^*]+:\*\* \S.*$`) + // stampLabelRE is a labelled stamp head: "Change:" or "**Change:**", then the + // change id, which older specs also spell with its slug or as a record path. + stampLabelRE = regexp.MustCompile(`^(?:\*\*Change:\*\*|Change:)[ \t]+(?:#?\d+(?:-[\w.-]+)?|[\w./-]*\d[\w./-]*)`) + // stampSentenceRE is a sentence stamp head: "Change", then the change id. + stampSentenceRE = regexp.MustCompile(`^Change[ \t]+#?\d+`) + isoDateRE = regexp.MustCompile(`\b\d{4}-\d{2}-\d{2}\b`) + boldLabelRE = regexp.MustCompile(`^\*\*[^*]+:\*\*`) ) -// removeStamps is step 4: before the first H2 of a spec, every shape of the -// grooming change stamp goes, and the rest of a stamp sentence's line stays. +// removeStamps is step 4: before the first H2 of a spec, the grooming change +// stamp goes. A stamp is known by its shape, not by a list of spellings, and is +// matched on the line with its links stripped, so a linked id is a stamp too. +// Only the stamp and the metadata after it go; an author sentence that follows +// stays and continues to step 6. func removeStamps(lines []line) []line { var out []line for i, l := range lines { @@ -213,35 +218,99 @@ func removeStamps(lines []line) []line { out = append(out, l) continue } - if loc := stampSentenceRE.FindStringIndex(l.text); loc != nil { - l.text = strings.TrimLeft(l.text[loc[1]:], " \t") - } - if changeOnlyRE.MatchString(l.text) || boldChangeRE.MatchString(l.text) || isBoldChangeRun(l.text) { - continue + masked, restore := maskCode(l.text) + if rest, ok := stripStamp(restore(stripLinks(masked, nil))); ok { + if rest == "" { + continue + } + l.text = rest } out = append(out, l) } return out } -// isBoldChangeRun reports a "·"-separated run of **Key:** value pairs that -// includes **Change:**. -func isBoldChangeRun(text string) bool { +// stripStamp reports whether text opens with a change stamp and returns what +// stays of the line once it goes: the stamp head and an id-trailing parenthetical +// or code span always go; a "·" metadata run (including one whose change field +// comes later) or a " — title" after the id takes the whole line; after a "." +// or "," the complete sentences that carry a date or open with a bold "**Key:**" +// label go, and the first other sentence and everything after it stay. A +// sentence the line does not finish stays, since its continuation sits on the +// next line. +func stripStamp(text string) (string, bool) { + var rest string + if loc := stampLabelRE.FindStringIndex(text); loc != nil { + rest = text[loc[1]:] + } else if loc := stampSentenceRE.FindStringIndex(text); loc != nil && stampFollows(text[loc[1]:]) { + rest = text[loc[1]:] + } else if isChangeFieldRun(text) { + return "", true + } else { + return text, false + } + rest = skipEnclosed(strings.TrimLeft(rest, " \t"), "(", ")") + rest = skipEnclosed(rest, "`", "`") + switch { + case rest == "" || strings.HasPrefix(rest, "·") || strings.HasPrefix(rest, "—") || strings.HasPrefix(rest, "–"): + return "", true + case strings.IndexByte(".,;:", rest[0]) >= 0: + return dropMetadataSentences(rest[1:]), true + } + return rest, true +} + +// isChangeFieldRun reports a "·"-separated metadata run whose later field is the +// change label ("**Date:** … · **Change:** N · …"). +func isChangeFieldRun(text string) bool { parts := strings.Split(text, "·") - if len(parts) < 2 { - return false + for _, p := range parts[1:] { + if stampLabelRE.MatchString(strings.TrimLeft(p, " \t")) { + return true + } } - hasChange := false - for _, p := range parts { - p = strings.TrimSpace(p) - if !boldPairRE.MatchString(p) { - return false + return false +} + +// stampFollows reports that what follows a sentence head's id ends the stamp +// ("Change 12." / "Change 12 · …"), rather than continuing a sentence that only +// opens with a change reference ("Change 12 is …"), which step 6 converts. +func stampFollows(s string) bool { + if s == "" || strings.IndexByte(".,;:", s[0]) >= 0 { + return true + } + t := strings.TrimLeft(s, " \t") + return len(t) < len(s) && (t == "" || strings.HasPrefix(t, "(") || strings.HasPrefix(t, "·") || + strings.HasPrefix(t, "—") || strings.HasPrefix(t, "–")) +} + +// skipEnclosed drops a leading open…close run closed on the same line. +func skipEnclosed(s, open, close string) string { + if !strings.HasPrefix(s, open) { + return s + } + if i := strings.Index(s[len(open):], close); i >= 0 { + return strings.TrimLeft(s[len(open)+i+len(close):], " \t") + } + return s +} + +// dropMetadataSentences drops leading complete sentences that carry a date or +// open with a bold "**Key:**" label, and returns the rest. +func dropMetadataSentences(s string) string { + for { + s = strings.TrimLeft(s, " \t") + sentence, next := s, "" + if i := strings.Index(s, ". "); i >= 0 { + sentence, next = s[:i+1], s[i+2:] + } else if !strings.HasSuffix(s, ".") { + return s } - if strings.HasPrefix(p, "**Change:**") { - hasChange = true + if !isoDateRE.MatchString(sentence) && !boldLabelRE.MatchString(sentence) { + return s } + s = next } - return hasChange } // inlineSteps runs steps 5 and 6 on every line outside fences: link-reference diff --git a/internal/export/export_test.go b/internal/export/export_test.go index 91ebca64d..232b44f2b 100644 --- a/internal/export/export_test.go +++ b/internal/export/export_test.go @@ -72,6 +72,49 @@ func TestTransformSpecStampKeepsRest(t *testing.T) { "\"Twelve\".\n") } +// TestTransformSpecStampShapes covers the stamp shapes older specs carry. A stamp +// is matched by its shape (a line opening "Change", "Change:", or "**Change:**" +// and the change id), never by a list of spellings, and on link-stripped text. +func TestTransformSpecStampShapes(t *testing.T) { + titles := Titles{36: "Thirty-six", 31: "Thirty-one", 51: "Fifty-one", 205: "Two oh five", + 462: "Four six two", 398: "Three nine eight", 257: "Two five seven", 282: "Two eight two", + 104: "One oh four", 234: "Two three four", 474: "Four seven four", 237: "Two three seven", + 236: "Two three six", 401: "Four oh one", 74: "Seventy-four", 72: "Seventy-two", 554: "Five five four"} + cases := []struct{ name, line, want string }{ + {"colon dot-run", "Change: #0036 · slug `s` · spec drafted 2026-06-21 (autonomous groom)", ""}, + {"bold dash title", "**Change:** 0031 — match the supersede verb", ""}, + {"bold paren slug", "**Change:** 0051 (`global-agents-middle-layer`)", ""}, + {"spec date", "Change 0205. Spec date 2026-08-04.", ""}, + {"paren then groomed", "Change 0462 (discovered from 0398). Groomed 2026-09-27.", ""}, + {"plain dot-run", "Change 0257 · groomed 2026-08-07 (auto-groom) · consolidates the surviving items", ""}, + {"colon auto-groomed", "Change: 0282. Auto-groomed 2026-08-09 (critic-gated).", ""}, + {"bold linked", "**Change:** [#0104](../../changes/active/0104-x.md)", ""}, + {"linked sentence", "Change [#0234](../../changes/active/0234-x.md).", ""}, + {"colon slug", "Change: 0074-bootstrap-facade-verb", ""}, + {"colon record path", "Change: docs/changes/active/0258-guard-x.md", ""}, + {"bold code slug", "**Change:** #0072 `facade-skill-rewiring`", ""}, + {"bold dot-separated fields", "**Change:** 0401. **Type:** docs. **Path:** bounded (files added).", ""}, + {"later change field", "**Date:** 2026-07-10 · **Change:** 0053 · **Depends on:** 0051", ""}, + {"author sentence stays", "Change 0237. Supersedes and absorbs change 0236 (killed into this one).", + "Supersedes and absorbs \"Two three six\" (killed into this one)."}, + {"groomed then author sentence", "Change #554, groomed 2026-10-16. Revised the same day.", "Revised the same day."}, + {"unfinished sentence stays", "Change: 0261. Discovered in review (merged 2026-08-08), which introduced the", + "Discovered in review (merged 2026-08-08), which introduced the"}, + {"unclosed parenthesis stays", "Change: 0247 (consolidates two killed stubs and", "(consolidates two killed stubs and"}, + {"prose opening with a reference", "Change 0474 is the last family change.", "\"Four seven four\" is the last family change."}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got := Transform(Input{Kind: KindSpec, Source: []byte("# T\n\n" + tc.line + "\n\n## Body\n\nx\n"), Titles: titles}) + want := "# T\n\n## Body\n\nx\n" + if tc.want != "" { + want = "# T\n\n" + tc.want + "\n\n## Body\n\nx\n" + } + assertMarkdown(t, got, want) + }) + } +} + func TestTransformSpecStampOnlyBeforeFirstH2(t *testing.T) { // A non-spec artifact never loses a stamp-shaped line; it converts instead. src := "# T\n\nChange 12.\n" diff --git a/internal/export/testdata/corpus/PROVENANCE.md b/internal/export/testdata/corpus/PROVENANCE.md index ba9a0f4f1..25002999b 100644 --- a/internal/export/testdata/corpus/PROVENANCE.md +++ b/internal/export/testdata/corpus/PROVENANCE.md @@ -28,6 +28,8 @@ that record's frontmatter `title:` on the same commit. No id is claimed by two r | `specs/2026-07-10-docket-skill-slimming-design.md` | `docs/superpowers/specs/` | Autolinks `<https://…>`; a `·`-separated `**Key:** value` run holding `**Change:**`; word-form references. | | `specs/2026-09-23-named-implement-next-skips-unrelated-maintenance-preflight-design.md` | `docs/superpowers/specs/` | H1 `# Change N — <its own title>` (the remainder equals the record title), own-title dash removed; dense padded references in prose and in an arrow list. | | `specs/2026-10-19-measure-whether-the-1h-cache-ttl-cut-implement-next-s-cost-design.md` | `docs/superpowers/specs/` | Recent `Change #N, groomed <date>.` stamp. | +| `specs/2026-07-20-readme-snippet-drift-guard-design.md` | `docs/superpowers/specs/` | Older plain-label stamp `Change: N · Date: … · Status: …` (a `·` metadata run with no bold); `Change 0101` word form in prose. | +| `specs/2026-07-20-frontmatter-field-domain-guard-design.md` | `docs/superpowers/specs/` | Linked stamp `**Change:** [#N](../../changes/…)`, matched only once its link is stripped; the following `**Date:**` line is not a stamp and stays. | | `specs/2026-07-26-cursor-agent-wrapper-contract-design.md` | `docs/superpowers/specs/` | External inline link `[text](https://cursor.com/…)` reduced to its text. | | `plans/2026-10-16-list-the-artifact-backlink-finding-codes-in-the-docket-statu.md` | `docs/superpowers/plans/` | Code fences holding reference-shaped text (`change 0539` in Go comments, commit messages); code spans holding `(change 0539)` and `## Artifacts`; backlink block. | | `results/2026-10-17-let-change-groom-clear-stacked-on-results.md` | `docs/results/` | Results dense with references: a padded list in a heading, a references-only parenthesis of seven ids removed whole, `0007-shaped` (not a form), bare `#565` kept. | diff --git a/internal/export/testdata/corpus/specs/2026-07-20-frontmatter-field-domain-guard-design.md b/internal/export/testdata/corpus/specs/2026-07-20-frontmatter-field-domain-guard-design.md new file mode 100644 index 000000000..1daca5408 --- /dev/null +++ b/internal/export/testdata/corpus/specs/2026-07-20-frontmatter-field-domain-guard-design.md @@ -0,0 +1,179 @@ +# Frontmatter field-domain guard — design + +**Change:** [#0104](../../changes/active/0104-guard-frontmatter-field-domain-violations-that-silently-drop.md) +**Date:** 2026-07-20 + +## Problem + +A frontmatter value that is well-formed *text* but outside its field's *domain* silently deletes the +change from every board surface. No diagnostic fires on any channel. + +`render-board.sh` buckets on the raw read (`SECTION["$st"]`) and both renderers iterate a fixed +seven-name list, so an unrecognized bucket is never emitted. The file is still counted in `total` +(`render-board.sh:86`), so the board's count line and its tables silently disagree — a three-change +fixture with one poisoned `status:` renders `**3 changes** — 🟡 2 proposed` above two rows. + +Since change 0094 the digest's `ready` line is the machine-parsed selection channel for +`docket-implement-next`. A stray inline comment can therefore remove a change from the autonomous +build queue while the board still reports a healthy count. + +Settled before this spec, and not re-litigated here: the guard site is `scripts/board-checks.sh` +(the existing warn-only frontmatter-validation channel), the posture is warn-only, and two guard +sites were rejected — changing `field()` (66 call sites across 13 scripts inherit the contract) and +renderer-stderr warnings (outside the closed report-line vocabulary callers key on). + +## Design + +Four parts. Parts 1 and 2 are the guard; part 3 fixes a hole in the channel the guard reports +through; part 4 single-sources the vocabulary both the guard and the renderer depend on. + +### 1 — `field-domain`: a new check-id in `board-checks.sh` + +Emitted from the existing `FILES` walk (active + archive), warn-only, git-only. One finding per +violated field. The domains are chosen by what the renderers actually consume — not by a general +schema ambition (see *Out of scope*). + +| field | domain | failure today | +|---|---|---| +| `status` | one of `DOCKET_STATUSES`; **empty also fails** | row dropped from every board surface | +| `slug` | `^[a-z0-9-]+$` — `slugify`'s own alphabet (`mint-stub.sh:88-91`); empty fails | leaks raw into the digest's space-joined `change` line | +| `priority` | one of `low\|medium\|high\|critical`; **empty is legal** | silently sorts as `medium` in the `ready` line, renders raw in the Priority cell | +| `title` | contains no `\|` | injects columns into the `BOARD.md` table row | + +`priority`'s empty case is legal because the convention documents `medium` as the default and +`render-board.sh`'s sort already implements it. `status` and `slug` have no documented default — +empty is a violation. + +`id` is deliberately **not** covered here. The existing `malformed-id` check already detects it; a +second overlapping check would double-report the same file. + +The slug check is frontmatter-only. The original stub anticipated a filename-derived fallback, but +`render-board.sh:135` reads `field "$f" slug` bare — no fallback exists in the board path. +(`reclaim-claims.sh:71,101` and `archive-change.sh:88-89` do derive a slug from the basename, but +they are not board consumers and are out of scope.) + +### 2 — `board-row-dropped`: a suppressed backstop + +An active file counted in `total` but rendered in no section is itself a detectable invariant +violation. It is emitted **only when no `field-domain` or `malformed-id` finding exists for that +same change id** — both accumulate into `FINDINGS` keyed by id, so suppression is a lookup. + +The suppression is what makes the backstop mean something. A backstop that fires alongside every +domain finding trains the reader to ignore it; suppressed, it says exactly one thing: *a row +vanished and nothing enumerated explains why.* With part 4 in place its remaining trigger is a +future renderer-added drop path — which is what a backstop is for. + +### 3 — Sanitize the findings channel + +`emit malformed-id "$raw" …` places an **untrusted frontmatter value in the TAB-separated change-id +column**, and `docket-status.sh:627` reads findings back with +`IFS=$'\t' read -r check_id change_id message`. An `id: 4<TAB>EVIL` shifts the message into the +wrong field. `field()` truncates at the first newline and strips trailing whitespace, but an +interior TAB survives. + +Two fixes, both in `board-checks.sh`: + +- `emit` escapes TAB and CR to visible `\t` / `\r` in every embedded value. +- The change-id column never carries a raw frontmatter value. It uses the filename-derived padded + id, falling back to `?` when the filename yields none. + +This closes the existing `malformed-id` hole and pre-empts the same hole in `field-domain`, whose +messages quote the offending value by design. The message column is the last field of the +`read -r`, so a TAB there is harmless — only the change-id column is at risk. + +### 4 — Single-source the status vocabulary + +The seven-name list is currently written out at four sites in `render-board.sh` in two shapes: the +full seven at `:123` and `:193`, the active five at `:137` and `:290`. + +Move it into `lib/docket-frontmatter.sh`, authored as its two semantic groups with the seven +derived: + +```bash +DOCKET_STATUSES_ACTIVE=(in-progress proposed blocked deferred implemented) +DOCKET_STATUSES_TERMINAL=(done killed) +DOCKET_STATUSES=("${DOCKET_STATUSES_ACTIVE[@]}" "${DOCKET_STATUSES_TERMINAL[@]}") +``` + +Every name appears exactly once. The split is not arbitrary — it is the convention's +terminal/non-terminal distinction, the same one the directory layout encodes (`active/` holds every +non-terminal status; `archive/` holds the two terminal outcomes). The concatenation reproduces the +existing order byte-for-byte, so `:123`/`:193` take `DOCKET_STATUSES` and `:137`/`:290` take +`DOCKET_STATUSES_ACTIVE`. + +**Why this is load-bearing rather than tidying.** Duplicating the list makes `field-domain` and the +renderer drift in two directions, and only one of them is caught: + +- New status added to `render-board.sh` but not `board-checks.sh` → `field-domain` fires a **false** + finding on every file carrying it, and `board-row-dropped` is suppressed because a domain finding + "explained" it. The guard becomes the noise source. The backstop is blind to this. +- New status added to `board-checks.sh` but not `render-board.sh` → the row is silently dropped and + `board-row-dropped` fires correctly. + +The duplication that gives the backstop its only realistic trigger is the same duplication that +manufactures the false-positive direction. Sharing the array eliminates both. + +It also makes the test meaningful. Without the shared array, a test that "the two lists agree" must +hard-code the seven names a third time — asserting a duplicate against a duplicate, which passes +while both copies drift together. + +**Residual: the case-statement mappings.** The list iterations are not the only place the vocabulary +is written down. `render-board.sh` also carries `emoji_for` (seven arms, no catch-all) and +`label_for_title` (five arms, no catch-all); an unknown status yields empty output from either. +`label_for` has a `*` catch-all and is total. These are a parallel representation the array cannot +unify, and they fail by printing *nothing* — the same silent-emptiness class this change exists to +kill, one layer down. Do **not** restructure them into the array; a case statement is the right +shape for a mapping. Pin them with a test instead (see *Testing*). + +## Autonomy posture + +`docket-implement-next` **reports, never gates.** Findings are surfaced in the run report and PR +body; selection and building proceed normally. + +The argument for gating is real — a poisoned `status:` on a `critical` change does not make the +implementer fail, it makes it silently build the wrong change, and the dropped change's absence is +indistinguishable from it never being ready. It loses anyway: a warn-only channel that halts +autonomy converts one malformed file into a total backlog stall, which is the posture this change +exists to avoid. A precise "gate only on selection-affecting findings" variant was considered and +rejected — it needs the checker to know whether the poisoned file *would* have been `proposed`, +which is exactly unknowable when the poisoned field **is** `status`. + +At reconcile, check whether `docket-implement-next` already echoes step-0 `check` lines generically +before planning an edit to it. The `docket-status.sh:623-630` passthrough auto-discovers new +check-ids with zero wiring; the report path may too. + +## Registration points + +A new check-id must be registered in three places beyond the emitting code: + +- `scripts/board-checks.sh`'s header block at `:11-12` — currently **stale**, it omits the existing + `malformed-id`. Add both. +- `scripts/board-checks.md` — the script contract. +- `scripts/docket-status.md` — the closed check-id enumeration in the `check <check-id>` report-line + row. + +## Testing + +- One fixture per domain in `tests/test_board_checks.sh`: poisoned `status` (inline comment), bad + `slug` (TAB and space), unrecognized `priority`, `title` with a pipe. Assert the exact + `<check-id>\t<change-id>\t<message>` line. +- `priority:` empty asserts **no** finding (the documented default), guarding against an + over-eager domain check. +- `board-row-dropped` suppression: a poisoned-`status` fixture asserts exactly one finding, not two. +- A TAB-in-`id` fixture asserting all three findings columns survive intact through + `docket-status.sh`'s `IFS=$'\t' read`. +- The existing golden byte-compare and idempotence assertions (`tests/test_render_board.sh:227`, + `:232`) must still pass unchanged after part 4 — order is the only hazard in the substitution and + the golden catches an order slip on the first run. +- New: assert `render-board.sh`'s buckets are exactly the lib's array. +- New: every name in `DOCKET_STATUSES` yields a non-empty `emoji_for`, and every name in + `DOCKET_STATUSES_ACTIVE` yields a non-empty `label_for_title` — the residual guard from part 4. +- Mutation-check: stripping each guard reddens at least one assertion. + +## Out of scope + +- Rejecting or rewriting the offending change files. This change makes the failure **visible**; it + does not decide what a malformed file's canonical value should be. +- Broader frontmatter schema validation beyond what board rendering actually consumes. +- Restructuring `emoji_for` / `label_for_title` into data. They are pinned by test, not unified. +- The non-board slug derivations in `reclaim-claims.sh` and `archive-change.sh`. diff --git a/internal/export/testdata/corpus/specs/2026-07-20-readme-snippet-drift-guard-design.md b/internal/export/testdata/corpus/specs/2026-07-20-readme-snippet-drift-guard-design.md new file mode 100644 index 000000000..1f1fb0adc --- /dev/null +++ b/internal/export/testdata/corpus/specs/2026-07-20-readme-snippet-drift-guard-design.md @@ -0,0 +1,100 @@ +# Guard the README config snippet against `.docket.yml.example` drift — design + +Change: 0107 · Date: 2026-07-20 · Status: settled + +## Problem + +Change 0101 made `.docket.yml.example` the single canonical config reference and deleted the other +all-keys surfaces. Mid-review it found a fourth one still standing: the README carried a full +commented `.docket.yml` sample, already drifted (no `learnings:` block, no `auto` sentinel). It was +cut down to a five-key illustrative snippet plus a pointer to the example — the right shape, but +nothing tests it. The snippet's values can silently diverge from the canonical file's, and the +pointer can rot if the example moves. 0101's results file records this as an accepted, unguarded +residual; this change closes it. + +## Decision + +Add one new numbered section — **`(8) README SNIPPET CORRESPONDENCE`** — to +`tests/test_docket_yml_example.sh`, placed after the existing `(7) README + dogfooding`. + +**Why that file, not a README doc-test of its own** (open question 1): it already owns every +example-mirroring invariant, which is what ADR-0048's must-update rule points at. A second file +guarding the same artifact from the other side is a coordination surface with no payoff; the +existing `(7)` already asserts README facts, so the precedent is set. + +## The guard + +Extract the fenced YAML block under the README's `### `.docket.yml` — per-repo settings` heading, +flatten it to dotted key paths with values, and for each extracted key assert: + +1. the key path exists in `.docket.yml.example`, and +2. the value shown in the README equals the value on the example's corresponding line. + +Plus a pointer assert: the README's link target for the canonical reference resolves to a file that +actually exists at that path (guards the rename/relocate case). + +### Nesting is handled generically + +The snippet already nests (`finalize:` → `gate: local`), and more nested keys are expected over +time, so extraction parses indentation into dotted paths (`finalize.gate`) rather than hardcoding +the one known nested key. Both sides — snippet and example — go through the same flattener, so the +comparison is path-to-path. A shared helper is fine; it need only cover the block-mapping subset +YAML that both files actually use (two levels, scalar and inline-list values). It is a test helper, +not a general YAML parser — do not grow it beyond what the two files contain. + +### Direction: forward only, deliberately + +The guard iterates the **snippet's** keys (`S ⊆ E` plus value agreement). It does **not** iterate +the example's keys. + +This is a conscious departure from the `correspondence-guard-runs-one-way` learning harvested from +0101, which says: name the direction you iterate, then write the other one. Here the reverse loop +*is* a completeness assert — "every key in the example appears in the README" — and that is exactly +the fourth all-keys surface 0101 deleted. The snippet is a deliberate proper subset: a small taste, +not a mirror. Writing the reverse direction would undo the change that motivated this one. + +The orphan direction that actually bit 0101 — a documented key that no real surface carries — is +already covered by the forward loop here: a snippet key absent from the example fails assert (1). +The asymmetry is safe *because* the two artifacts stand in a subset relation rather than a +correspondence, which was not true of 0101's export-keys-vs-example guards. + +**This reasoning must be written into the test as a comment.** A future reader who has internalized +the learning will otherwise "fix" the missing reverse loop and reintroduce the drift surface. The +comment states: the reverse loop is intentionally absent, and why. + +### Non-vacuity floor + +The forward loop's real failure mode is iterating an empty set: rename the fence, retitle the +heading, or move the section, and the extractor finds zero keys — the loop runs zero times and the +test passes while proving nothing. `(1)` already carries this defense for its fidelity fixture +(lines 48–55), for the same reason. + +So assert the extracted key count **equals the number the snippet actually shows** (currently 5: +`metadata_branch`, `integration_branch`, `board_surfaces`, `finalize`, `finalize.gate` — settle the +exact count against the flattener's output when implementing), not `>= 1`. An exact count is the +right bar: it also catches a snippet that quietly grows toward being a mirror again. + +## Completion bar + +Mutation-prove each assert before calling it done: + +- change a value in the README snippet → the value assert reddens; +- add a key to the snippet that is not in the example → the existence assert reddens; +- break the heading or the fence so extraction yields nothing → the non-vacuity assert reddens; +- point the README's canonical-reference link at a nonexistent path → the pointer assert reddens; +- add a nested key two levels deep to both files consistently → everything stays green (proves the + flattener is generic, not accidentally passing on the one hardcoded path). + +## Out of scope + +- Regenerating the snippet from the example. Codegen was rejected for the example itself in + ADR-0048; the same hand-maintained-mirror trade-off applies, and a five-key taste is not worth a + generator. +- Auditing the README's other prose claims against the code — broader than this snippet and not + grep-able (see the `verify-the-claim` finding). +- Any reverse/completeness direction, per the reasoning above. + +## No ADR + +The direction-of-truth call is a test-design decision scoped to one guard, and it is recorded here +plus in the test's own comment. ADR-0048 already owns the standing rule this sits under. diff --git a/internal/export/testdata/corpus/titles.tsv b/internal/export/testdata/corpus/titles.tsv index 6540ec748..5be6cd554 100644 --- a/internal/export/testdata/corpus/titles.tsv +++ b/internal/export/testdata/corpus/titles.tsv @@ -33,6 +33,7 @@ 44 Configurable SDD build models for docket-implement-next 46 Per-harness model overrides for docket agents 47 Make the agent-config refresh workflow discoverable in the README +48 Generate Cursor dispatch rules; always write the full agent set per harness 50 Global config layer — full-schema ~/.config/docket/config.yml with a coordination-key fence 51 Machine-local config layer (.docket.local.yml) + all-local agent generation 53 Slim docket-convention + docket-status via progressive disclosure @@ -53,6 +54,7 @@ 85 Second-round skill slimming — re-slim regrown skills + regrowth guard 86 Attended finalize has no merge path under auto_approve — scope the --admin ban to autonomous runs 88 Loop continuation — implement-next chains into the next ready change instead of stopping +89 Claim leases + reclaim script — expired in-progress claims self-heal back to proposed 91 Auto-create discovered stubs — a config flag that turns mid-run findings into proposed changes 92 Orphan detection script — cross-reference change ids in merged commits against archive state 94 Selection-order backlog digest — implement-next selects from a digest instead of walking active/ @@ -60,13 +62,16 @@ 96 An autonomous run can be halted by a sub-skill's interactive hand-off — pre-specify the outcome at every autonomous call site 100 Force-push-with-lease denied by the auto-mode classifier — unblock finalize's merge gate 101 .docket.yml.example — the canonical all-comprehensive config reference +104 Guard frontmatter field-domain violations that silently drop board rows 106 Pin the finalize.test_command auto sentinel's cross-layer masking with a two-layer fixture +107 Guard the README config snippet against .docket.yml.example drift 110 Concurrent agents collide on the shared .docket worktree's dirty-tree window 111 Guard the board-checks check-id enumerations against drift 114 Decide the repo's posture on line-number comment anchors 115 Extend the board-row-dropped invariant to archive/ files 116 Single-source the remaining duplicated board vocabularies 117 Deferred ADR-publish visibility — detect an unpublished ADR with a computed board-checks finding +123 Machine-check the docket-config.md export list order against the resolver 124 Backlog triage pass — kill, defer, or arm each needs-brainstorm stub 126 Apply the poison-value prelude uniformly to every resolver eval in the config suite 129 Fix the pipefail-unsafe plain-format config assertion @@ -95,6 +100,8 @@ 215 Escape newlines in board-checks sanitize now that -z can deliver a raw LF 224 The build gate contract never says green/red is the exit code, so an output-shape match passes as a gate 226 Reframe auto-capture as capability discovery with strict admission gates +227 Parallel test-suite runner — 4x+ wall-clock speedup +232 The gate execution posture never reaches the build workers that also run the full suite 234 Split gate-execution.md: probe evidence should not sit on a blocking-read surface 248 Role self-description: enforce the positive half and harden the guard 249 Build-worker contract: gate-execution pointer and staging discipline @@ -108,6 +115,7 @@ 276 Dummy mode — persona-calibrated human-facing language simplification 278 test_docket_example_yml's fidelity fixture goes intermittently red under parallel contention 280 Shard or re-budget the test files the suite runner reports OVER BUDGET +290 run-tests.sh --timings truncates a test file passed as its target 296 Shard tests/test_docket_status.sh — its runtime row is at the table's hard 60s ceiling 300 Close the single-backslash word-boundary gap: convert the 56 sites and make the census gating 301 The convention doc's lifecycle cardinalities are hardcoded prose with no guard diff --git a/internal/exportcheck/check.go b/internal/exportcheck/check.go index d6b4b0c75..b1030df50 100644 --- a/internal/exportcheck/check.go +++ b/internal/exportcheck/check.go @@ -496,56 +496,75 @@ func afterPR(s string, at int) bool { return i >= 0 && s[i:at] == "PR " && (i == 0 || !isWord(s[i-1])) } -// isStamp reports a grooming change stamp: "Change N, groomed YYYY-MM-DD…", -// "Change N. Groomed YYYY-MM-DD…", a line that is only "Change N.", or a line -// opening with a bold "**Change:** N" field. +// isStamp reports a grooming change stamp by its shape, not by a list of +// spellings: a "Change:" or "**Change:**" label whatever follows it, opening +// the line or a "·"-separated field of it; or a line opening with "Change" and +// a quoted converted title, or with "Change", an optional "[" and "#", and a +// number that ends the stamp: end of line, one of ".,;:]", or a space and then +// "(", "·", or a dash. func isStamp(plain string) bool { s := trimRight(plain) - if hasPrefix(s, "**Change:** ") { - k := len("**Change:** ") - if k < len(s) && s[k] == '#' { - k++ + if changeLabel(s) { + return true + } + for t := s; ; { + i := indexOf(t, "·") + if i < 0 { + break + } + t = t[i+len("·"):] + for hasPrefix(t, " ") { + t = t[1:] } - _, _, ok := numberAt(s, k) - return ok + if changeLabel(t) { + return true + } + } + if hasPrefix(s, "Change \"") { + return true } if !hasPrefix(s, "Change ") { return false } k := len("Change ") + if k < len(s) && s[k] == '[' { + k++ + } if k < len(s) && s[k] == '#' { k++ } _, end, ok := numberAt(s, k) - if !ok || end >= len(s) || (s[end] != ',' && s[end] != '.') { + if !ok { return false } - rest := s[end+1:] - if rest == "" { - return s[end] == '.' + rest := s[end:] + if rest == "" || indexOf(".,;:]", rest[:1]) >= 0 { + return true } - if !hasPrefix(rest, " groomed ") && !hasPrefix(rest, " Groomed ") { + if rest[0] != ' ' { return false } - date := rest[len(" groomed "):] - return len(date) >= 10 && isDate(date[:10]) + rest = rest[1:] + for _, p := range []string{"(", "·", "—", "–"} { + if hasPrefix(rest, p) { + return true + } + } + return false } -func hasPrefix(s, p string) bool { return len(s) >= len(p) && s[:len(p)] == p } - -func isDate(s string) bool { - for i := 0; i < len(s); i++ { - if i == 4 || i == 7 { - if s[i] != '-' { - return false - } - } else if !isDigit(s[i]) { - return false +// changeLabel reports s opening with a "Change:" or "**Change:**" label. +func changeLabel(s string) bool { + for _, label := range []string{"**Change:**", "Change:"} { + if hasPrefix(s, label) && (len(s) == len(label) || s[len(label)] == ' ' || s[len(label)] == '\t') { + return true } } - return true + return false } +func hasPrefix(s, p string) bool { return len(s) >= len(p) && s[:len(p)] == p } + // headingLevel returns the level of an ATX heading line (up to three spaces of // indent, one to six '#', then a space, a tab, or the end), or 0. func headingLevel(line string) (int, bool) { diff --git a/internal/exportcheck/check_test.go b/internal/exportcheck/check_test.go index 8c77b1378..19338b708 100644 --- a/internal/exportcheck/check_test.go +++ b/internal/exportcheck/check_test.go @@ -59,6 +59,14 @@ func TestCheckFindsEachLeftoverKind(t *testing.T) { {"stamp groomed dot", "# T\n\nChange 9373. Groomed 2026-09-02 (interactive). Rest\n", []lineRule{{3, RuleStamp}}}, {"stamp change only", "# T\n\nChange 9561.\n", []lineRule{{3, RuleStamp}}}, {"stamp bold", "# T\n\n**Change:** 9003 · **Type:** feat\n", []lineRule{{3, RuleStamp}}}, + {"stamp bold converted title", "# T\n\n**Change:** \"Some title\" — x\n", []lineRule{{3, RuleStamp}}}, + {"stamp colon converted title", "# T\n\nChange: \"Some title\" · slug\n", []lineRule{{3, RuleStamp}}}, + {"stamp converted title", "# T\n\nChange \"Some title\".\n", []lineRule{{3, RuleStamp}}}, + {"stamp colon record path", "# T\n\nChange: docs/changes/active/0258-x.md\n", []lineRule{{3, RuleStamp}}}, + {"stamp dot-run", "# T\n\nChange #9036 · slug\n", []lineRule{{3, RuleStamp}}}, + {"stamp parenthesis", "# T\n\nChange 9462 (discovered). Groomed\n", []lineRule{{3, RuleStamp}}}, + {"stamp later field", "# T\n\n**Date:** 2026-07-10 · **Change:** \"Some title\" · **Type:** x\n", []lineRule{{3, RuleStamp}}}, + {"stamp dot then author sentence", "# T\n\nChange 9237. Supersedes it.\n", []lineRule{{3, RuleStamp}}}, {"heading", "# T\n\n## A\n\n#### B\n", []lineRule{{5, RuleHeading}}}, } for _, tc := range cases { @@ -87,6 +95,7 @@ func TestCheckKeepsWhatTheExportKeeps(t *testing.T) { "An unknown change 9999 and changes 9998 and 9997 stay.", "A bare https://go.dev/x URL stays, and a 0559-export.md file, docs/0559, 0559.md too.", "A converted \"Close a change to done without a PR\" title stays.", + "Change management is prose, and so is Changes: none.", "Code: `<!-- docket:x:start -->`, `[a](b)`, `change 559`, ``a ` [x](y) ``, `#0559`, `↩`.", "", "## Section", From c1b86fa0eb783d23b40edfb6b8b15d235aec792d Mon Sep 17 00:00:00 2001 From: Daniel Hanold <danny@danielhanold.com> Date: Tue, 20 Oct 2026 11:01:39 -0400 Subject: [PATCH 11/12] fix(exportcheck): stop flagging author prose as export leftovers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The self-check reported a ↩ anywhere outside code, any <a>/<A> placeholder, and any [x][y] pair as docket machinery the export did not remove, though the transform keeps all three on purpose. The banner rule now matches only the banner's '> ↩' line shape, an anchor needs an attribute assignment or a closing </a> on the line, and a reference link is flagged only when its label has a definition in the document. --- internal/exportcheck/check.go | 155 +++++++++++++++++++++++++---- internal/exportcheck/check_test.go | 35 ++++++- 2 files changed, 170 insertions(+), 20 deletions(-) diff --git a/internal/exportcheck/check.go b/internal/exportcheck/check.go index b1030df50..475127fbf 100644 --- a/internal/exportcheck/check.go +++ b/internal/exportcheck/check.go @@ -45,6 +45,7 @@ type Report struct { func Check(md []byte, known func(id int) bool) Report { lines := splitLines(string(md)) code := fencedLines(lines) + defs := definitionLabels(lines, code) var r Report for i, line := range lines { @@ -74,10 +75,10 @@ func Check(md []byte, known func(id int) bool) Report { if i == 0 && trimRight(line) == "---" { add(RuleFrontmatter, "---") } - if idx := indexOf(plain, "↩"); idx >= 0 { + if isBanner(plain) { add(RuleBanner, trimRight(line)) } - if text, ok := findLink(line, plain); ok { + if text, ok := findLink(line, plain, defs); ok { add(RuleLink, text) } if text, ok := findChangeRef(line, plain, known); ok { @@ -274,22 +275,83 @@ func findMarker(line, plain string) (string, bool) { return "", false } -// findLink finds any link syntax: an inline link or image ("](" after a bracketed -// text), a full or collapsed reference link ("][" after a bracketed text), a -// link-reference definition line, an autolink "<scheme:…>", or an HTML anchor. -// A shortcut "[text]" alone is not flagged: it is a link only when a definition -// exists, and a definition is itself flagged. -func findLink(line, plain string) (string, bool) { - // Definition: up to three spaces, "[label]:". +// isBanner reports the backlink banner's shape: up to three spaces, a ">" +// blockquote mark, optional blanks, then "↩". A "↩" anywhere else is prose. +func isBanner(plain string) bool { + i := 0 + for i < len(plain) && i < 4 && plain[i] == ' ' { + i++ + } + if i > 3 || i >= len(plain) || plain[i] != '>' { + return false + } + i++ + for i < len(plain) && (plain[i] == ' ' || plain[i] == '\t') { + i++ + } + return hasPrefix(plain[i:], "↩") +} + +// definitionLabel reports a link-reference definition line, up to three spaces +// then "[label]:", and returns its label folded for matching. +func definitionLabel(plain string) (string, bool) { indent := 0 for indent < len(plain) && plain[indent] == ' ' { indent++ } - if indent <= 3 && indent < len(plain) && plain[indent] == '[' { - if c := indexOf(plain[indent:], "]"); c > 1 && indent+c+1 < len(plain) && plain[indent+c+1] == ':' { - return trimRight(line), true + if indent > 3 || indent >= len(plain) || plain[indent] != '[' { + return "", false + } + c := indexOf(plain[indent:], "]") + if c <= 1 || indent+c+1 >= len(plain) || plain[indent+c+1] != ':' { + return "", false + } + return foldLabel(plain[indent+1 : indent+c]), true +} + +// foldLabel folds a reference label for matching: ASCII case ignored, outer +// blanks trimmed, inner blank runs collapsed to one space. +func foldLabel(s string) string { + var b []byte + blank := false + for i := 0; i < len(s); i++ { + c := s[i] + if c == ' ' || c == '\t' { + blank = len(b) > 0 + continue + } + if blank { + b = append(b, ' ') + blank = false + } + b = append(b, lower(c)) + } + return string(b) +} + +// definitionLabels collects the labels of every definition outside code. +func definitionLabels(lines []string, code []bool) map[string]bool { + defs := map[string]bool{} + for i, line := range lines { + if code[i] { + continue + } + if label, ok := definitionLabel(maskSpans(line)); ok { + defs[label] = true } } + return defs +} + +// findLink finds any link syntax: an inline link or image ("](" after a bracketed +// text), a full or collapsed reference link whose label has a definition in the +// document, a link-reference definition line, an autolink "<scheme:…>", or an +// HTML anchor element. A "[x][y]" with no definition behind it renders as +// literal text, as does a shortcut "[text]"; a definition is itself flagged. +func findLink(line, plain string, defs map[string]bool) (string, bool) { + if _, ok := definitionLabel(plain); ok { + return trimRight(line), true + } for i := 0; i < len(plain); i++ { switch plain[i] { case '[': @@ -298,25 +360,82 @@ func findLink(line, plain string) (string, bool) { continue } after := i + 1 + c + 1 - if after < len(plain) && (plain[after] == '(' || plain[after] == '[') { - start := i - if start > 0 && plain[start-1] == '!' { - start-- - } + if after >= len(plain) { + continue + } + start := i + if start > 0 && plain[start-1] == '!' { + start-- + } + if plain[after] == '(' { return line[start : after+1], true } + if plain[after] == '[' { + r := indexOf(plain[after+1:], "]") + if r < 0 { + continue + } + label := plain[after+1 : after+1+r] + if r == 0 { + label = plain[i+1 : i+1+c] + } + if defs[foldLabel(label)] { + return line[start : after+1+r+1], true + } + } case '<': if text, ok := autolinkAt(line, plain, i); ok { return text, true } - if i+2 < len(plain) && lower(plain[i+1]) == 'a' && (plain[i+2] == ' ' || plain[i+2] == '\t' || plain[i+2] == '>') { + if text, ok := anchorAt(line, plain, i); ok { + return text, true + } + } + } + return "", false +} + +// anchorAt matches an HTML anchor element at i, ignoring case: "<a" then blanks +// and an attribute name followed by "=", or a "<a"/"<a>" on a line that also +// closes one with "</a>". A bare "<a>" placeholder in prose is not an anchor. +func anchorAt(line, plain string, i int) (string, bool) { + if !hasFoldAt(plain, i, "<a") { + return "", false + } + j := i + 2 + if j < len(plain) && (plain[j] == ' ' || plain[j] == '\t') { + for j < len(plain) && (plain[j] == ' ' || plain[j] == '\t') { + j++ + } + k := j + for k < len(plain) && (isWord(plain[k]) || plain[k] == '-' || plain[k] == ':') { + k++ + } + if k > j { + for k < len(plain) && (plain[k] == ' ' || plain[k] == '\t') { + k++ + } + if k < len(plain) && plain[k] == '=' { return line[i : i+2], true } } } + if j < len(plain) && (plain[j] == '>' || plain[j] == ' ' || plain[j] == '\t') && hasFoldIn(plain[i:], "</a>") { + return line[i : i+2], true + } return "", false } +// hasFoldIn reports word (lower case) anywhere in s, ignoring ASCII case. +func hasFoldIn(s, word string) bool { + for i := 0; i+len(word) <= len(s); i++ { + if hasFoldAt(s, i, word) { + return true + } + } + return false +} + // autolinkAt matches "<scheme:rest>" at i: a letter, then 1–31 letters, digits, // '+', '.', or '-', a colon, and no space, '<', or '>' before the closing '>'. func autolinkAt(line, plain string, i int) (string, bool) { diff --git a/internal/exportcheck/check_test.go b/internal/exportcheck/check_test.go index 19338b708..43b2d6859 100644 --- a/internal/exportcheck/check_test.go +++ b/internal/exportcheck/check_test.go @@ -43,10 +43,13 @@ func TestCheckFindsEachLeftoverKind(t *testing.T) { {"inline link", "# T\n\nsee [docs](https://x)\n", []lineRule{{3, RuleLink}}}, {"image", "# T\n\n![alt](p.png)\n", []lineRule{{3, RuleLink}}}, {"autolink", "# T\n\nsee <https://go.dev/x>\n", []lineRule{{3, RuleLink}}}, - {"reference link", "# T\n\nsee [text][ref]\n", []lineRule{{3, RuleLink}}}, - {"collapsed reference link", "# T\n\nsee [text][]\n", []lineRule{{3, RuleLink}}}, + {"banner indented", "# T\n\n >↩ Back\n", []lineRule{{3, RuleBanner}}}, + {"reference link", "# T\n\nsee [text][Ref]\n\n[ref]: https://x\n", []lineRule{{3, RuleLink}, {5, RuleLink}}}, + {"collapsed reference link", "# T\n\nsee [Text][]\n\n[text]: https://x\n", []lineRule{{3, RuleLink}, {5, RuleLink}}}, {"link definition", "# T\n\n[ref]: https://x\n", []lineRule{{3, RuleLink}}}, {"html anchor", "# T\n\nsee <a href=\"x\">t</a>\n", []lineRule{{3, RuleLink}}}, + {"html anchor upper", "# T\n\nsee <A\tNAME='x'>t\n", []lineRule{{3, RuleLink}}}, + {"html anchor bare with close", "# T\n\nsee <a>t</A>\n", []lineRule{{3, RuleLink}}}, {"word form", "# T\n\nfrom change 559 on\n", []lineRule{{3, RuleChangeRef}}}, {"word form hash", "# T\n\nChange #547 holds\n", []lineRule{{3, RuleChangeRef}}}, {"word form list", "# T\n\nchanges 9999, 4444 and 0120\n", []lineRule{{3, RuleChangeRef}}}, @@ -124,6 +127,34 @@ func TestCheckKeepsWhatTheExportKeeps(t *testing.T) { } } +// TestCheckKeepsProseThatOnlyResemblesMachinery covers author prose the transform +// leaves alone on purpose: a ↩ that is not the banner's "> ↩" line, an <a> +// placeholder that is not an anchor element, and a "[x][y]" with no definition +// behind it, which Markdown renders as literal text. +func TestCheckKeepsProseThatOnlyResemblesMachinery(t *testing.T) { + cases := []struct{ name, md string }{ + {"arrow in prose", "# T\n\nThe ↩ backlink banner goes.\n"}, + {"arrow later in a quote", "> a quote about the ↩ banner\n"}, + {"placeholder a", "# T\n\nThe main tree is at <a>, the dckt branch at <b>.\n"}, + {"placeholder A", "# T\n\nCompare <A> with <B>.\n"}, + {"a then words", "# T\n\nwrite <a and b> here\n"}, + {"index pair", "# T\n\nread x[i][j] twice\n"}, + {"undefined reference", "# T\n\nsee [t][r] here\n"}, + {"undefined collapsed reference", "# T\n\nsee [t][] here\n"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + md := tc.md + if !strings.HasPrefix(md, "# ") { + md = "# T\n\n" + md + } + if r := Check([]byte(md), known); len(r.Leftovers) != 0 { + t.Fatalf("Check(%q) flagged prose: %+v", md, r.Leftovers) + } + }) + } +} + func TestCheckStampOnlyBeforeFirstH2(t *testing.T) { r := Check([]byte("# T\n\n## Why\n\nChange 9561.\n"), known) if len(r.Leftovers) != 0 { From e707401323e302730029b7b177f501fa2ff1a38c Mon Sep 17 00:00:00 2001 From: Daniel Hanold <danny@danielhanold.com> Date: Tue, 20 Oct 2026 11:08:31 -0400 Subject: [PATCH 12/12] fix(export): clear five review findings on the export transform, self-check, and destination - Finding 3: the transform (maskParagraph) and the self-check (maskParagraphs), each written separately, now find inline code spans across a whole paragraph. A span that crosses a line break stays code on both of its lines. PROVENANCE.md no longer lists this as a limitation. - Finding 4: an inserted title respects the author's quotes. A fully convertible reference that is the whole quoted text takes those quotes ("change 0559" -> "<title>"). A quoted references-only parenthesis is replaced by its titles and never leaves "". Inside a longer quoted phrase, the title gets single quotes. - Finding 5: a stray-marker leftover reports its source line as source_line. line is left only for output lines, and the JSON test and human warning are updated. - Finding 6: --output-path is refused with output-path-protected when the resolved destination (cleaned, parent symlinks resolved) is the source artifact or lies inside the metadata checkout. - Finding 7: corpusProblems directly asserts that no known word-form or padded change id is left outside code, using a regex of its own. --- internal/app/open.go | 20 ++--- internal/app/open_export.go | 48 +++++++++-- internal/app/open_export_test.go | 60 +++++++++++++- internal/export/corpus_test.go | 52 ++++++++++++ internal/export/export.go | 29 ++++--- internal/export/inline.go | 79 +++++++++++++------ internal/export/inline_test.go | 22 ++++++ internal/export/refs.go | 48 ++++++++--- internal/export/refs_test.go | 12 +++ internal/export/testdata/corpus/PROVENANCE.md | 2 +- internal/exportcheck/check.go | 60 ++++++++++---- internal/exportcheck/check_test.go | 15 ++++ 12 files changed, 369 insertions(+), 78 deletions(-) diff --git a/internal/app/open.go b/internal/app/open.go index 445495b04..806bdd513 100644 --- a/internal/app/open.go +++ b/internal/app/open.go @@ -58,6 +58,9 @@ const ( ReasonOpenInvalidOption = "invalid-option" // an export flag used where it does not apply ReasonOpenOutputPathInvalid = "output-path-invalid" // the export destination cannot be written ReasonOpenExportFailed = "export-failed" // reading the source or writing the copy failed + // ReasonOpenOutputPathProtected refuses an export destination that is the + // source artifact itself or lies inside the metadata checkout. + ReasonOpenOutputPathProtected = "output-path-protected" ) // openNoteNotGitHub is the note attached when a GitHub page was wanted but the @@ -265,7 +268,7 @@ func Open(ctx context.Context, deps OpenDeps, o OpenOptions) OpenResult { } res.Notes = append(res.Notes, openNoteNotGitHub) } - path, notes, f := localArtifact(ctx, deps, dir, pin, rel) + path, _, notes, f := localArtifact(ctx, deps, dir, pin, rel) res.Notes = append(res.Notes, notes...) if f != nil { return fail(*f) @@ -275,13 +278,12 @@ func Open(ctx context.Context, deps OpenDeps, o OpenOptions) OpenResult { } // localArtifact prepares the metadata checkout and returns rel's path inside -// it. A prepare that does not succeed never blocks the open: it adds a -// staleness note, and the layout's metadata worktree stands in for prepare's -// own path. A file absent from the checkout is refused. -func localArtifact(ctx context.Context, deps OpenDeps, dir string, pin StatusPin, rel string) (string, []string, *openFailure) { +// it, and the checkout's root. A prepare that does not succeed never blocks +// the open: it adds a staleness note, and the layout's metadata worktree +// stands in for prepare's own path. A file absent from the checkout is refused. +func localArtifact(ctx context.Context, deps OpenDeps, dir string, pin StatusPin, rel string) (path, root string, notes []string, f *openFailure) { pr := deps.Prepare(ctx, dir) root, code := pin.Layout.MetadataWorktree, "" - var notes []string if pr.Disposition == PrepareDispositionApplied || pr.Disposition == PrepareDispositionNoOp { if pr.Context != nil && pr.Context.MetadataWorktreePath != "" { root = pr.Context.MetadataWorktreePath @@ -290,7 +292,7 @@ func localArtifact(ctx context.Context, deps OpenDeps, dir string, pin StatusPin code = prepareFindingCode(pr) notes = append(notes, openNoteStale(code)) } - path := filepath.Join(root, filepath.FromSlash(rel)) + path = filepath.Join(root, filepath.FromSlash(rel)) if _, err := os.Stat(path); err != nil { msg := fmt.Sprintf("%s is not in the metadata checkout", path) if !errors.Is(err, fs.ErrNotExist) { @@ -299,9 +301,9 @@ func localArtifact(ctx context.Context, deps OpenDeps, dir string, pin StatusPin if code != "" { msg += fmt.Sprintf(" (metadata checkout not synced: %s)", code) } - return "", notes, &openFailure{ResultInvalidState, ReasonOpenFileMissing, msg} + return "", root, notes, &openFailure{ResultInvalidState, ReasonOpenFileMissing, msg} } - return path, notes, nil + return path, root, notes, nil } // resolveOpenChange reads the pinned corpus and returns change id, or, when id diff --git a/internal/app/open_export.go b/internal/app/open_export.go index 7ed89e1f5..84f8ff7bd 100644 --- a/internal/app/open_export.go +++ b/internal/app/open_export.go @@ -27,15 +27,17 @@ const ( ) // ExportRuleStrayMarker is the leftover rule of an unpaired or malformed marker -// line the transform removed from the source; its Line is a source line. +// line the transform removed from the source; it carries a SourceLine, not a Line. const ExportRuleStrayMarker = "stray-marker" // ExportLeftover is one piece of docket machinery the self-check found in the -// exported copy, or a damaged marker the transform removed from the source. +// exported copy, located by its output Line, or a damaged marker the transform +// removed from the source, located by its SourceLine. Exactly one is set. type ExportLeftover struct { - Line int `json:"line"` - Text string `json:"text"` - Rule string `json:"rule"` + Line int `json:"line,omitempty"` + SourceLine int `json:"source_line,omitempty"` + Text string `json:"text"` + Rule string `json:"rule"` } // ExportMentions lists the exported lines, code included, that name docket. @@ -73,7 +75,7 @@ func (r OpenResult) HumanWarnings() []string { out := []string{} for _, l := range r.Leftovers { if l.Rule == ExportRuleStrayMarker { - out = append(out, fmt.Sprintf("damaged marker removed at source line %d: %s — the source has an unpaired marker; the exported file is clean", l.Line, l.Text)) + out = append(out, fmt.Sprintf("damaged marker removed at source line %d: %s — the source has an unpaired marker; the exported file is clean", l.SourceLine, l.Text)) continue } out = append(out, fmt.Sprintf("leftover line %d (%s): %s — docket machinery the export did not remove; edit it out before sharing", l.Line, l.Rule, l.Text)) @@ -109,7 +111,7 @@ func openExport(ctx context.Context, deps OpenDeps, o OpenOptions, dir string, p if deps.HomeDir == nil || deps.Getwd == nil || deps.GOOS == "" { return fail(openFailure{ResultInternalError, ReasonOpenExportFailed, "export is not wired: home directory, working directory, and platform are required"}) } - src, notes, f := localArtifact(ctx, deps, dir, pin, rel) + src, root, notes, f := localArtifact(ctx, deps, dir, pin, rel) res.Notes = append(res.Notes, notes...) if f != nil { return fail(*f) @@ -128,6 +130,9 @@ func openExport(ctx context.Context, deps OpenDeps, o OpenOptions, dir string, p if f != nil { return fail(*f) } + if f := protectedDestination(dest, src, root); f != nil { + return fail(*f) + } titles := exportTitles(snap) out := export.Transform(export.Input{Kind: kind, Source: body, Title: c.Title(), Titles: titles}) @@ -148,7 +153,7 @@ func openExport(ctx context.Context, deps OpenDeps, o OpenOptions, dir string, p } if warnings != WarningsMentions { for _, s := range out.Stray { - res.Leftovers = append(res.Leftovers, ExportLeftover{Line: s.SourceLine, Text: s.Text, Rule: ExportRuleStrayMarker}) + res.Leftovers = append(res.Leftovers, ExportLeftover{SourceLine: s.SourceLine, Text: s.Text, Rule: ExportRuleStrayMarker}) } for _, l := range report.Leftovers { res.Leftovers = append(res.Leftovers, ExportLeftover{Line: l.Line, Text: l.Text, Rule: l.Rule}) @@ -218,6 +223,33 @@ func exportDestination(deps OpenDeps, outputPath, name string) (string, *openFai return path, nil } +// protectedDestination refuses a destination that is the source artifact or +// lies inside the metadata checkout, compared after cleaning the path and +// resolving the symlinks of its parent directory (and of the source and the +// checkout root), so no spelling of the path slips past. +func protectedDestination(dest, src, root string) *openFailure { + refuse := func(msg string) *openFailure { + return &openFailure{ResultInvalidState, ReasonOpenOutputPathProtected, msg} + } + d := filepath.Join(resolveSymlinks(filepath.Dir(filepath.Clean(dest))), filepath.Base(dest)) + if d == resolveSymlinks(src) { + return refuse(fmt.Sprintf("%s is the source artifact — choose another --output-path", dest)) + } + if rel, err := filepath.Rel(resolveSymlinks(root), d); err == nil && rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator)) { + return refuse(fmt.Sprintf("%s is inside the metadata checkout — choose another --output-path", dest)) + } + return nil +} + +// resolveSymlinks returns p cleaned and with its symlinks resolved, or cleaned +// alone when it cannot be resolved. +func resolveSymlinks(p string) string { + if r, err := filepath.EvalSymlinks(p); err == nil { + return r + } + return filepath.Clean(p) +} + // writeExport writes data to dest atomically (a temp file beside it, mode 0644, // then a rename) and reports whether dest existed before. func writeExport(dest string, data []byte) (bool, error) { diff --git a/internal/app/open_export_test.go b/internal/app/open_export_test.go index 5e19c6e52..22628e028 100644 --- a/internal/app/open_export_test.go +++ b/internal/app/open_export_test.go @@ -227,6 +227,54 @@ func TestOpenExportOutputPath(t *testing.T) { } } +// TestOpenExportRefusesProtectedDestination: --output-path never overwrites the +// source artifact and never writes into the metadata checkout, however the path +// is spelled — exactly, relatively, as a directory, or through a symlinked +// parent. The refusal writes nothing and opens nothing. +func TestOpenExportRefusesProtectedDestination(t *testing.T) { + home := testsupport.TempDir(t) + cases := []struct { + name string + cwd func(src string) string + path func(src string) string + }{ + {"source file", nil, func(src string) string { return src }}, + {"source file, unclean", nil, func(src string) string { + return filepath.Join(filepath.Dir(src), "..", filepath.Base(filepath.Dir(src)), filepath.Base(src)) + }}, + {"source file, relative", func(src string) string { return filepath.Dir(src) }, func(src string) string { return filepath.Base(src) }}, + {"directory in the checkout", nil, func(src string) string { return filepath.Dir(src) }}, + {"new file in the checkout", nil, func(src string) string { return filepath.Join(filepath.Dir(src), "copy.md") }}, + {"symlinked parent into the checkout", nil, func(src string) string { + link := filepath.Join(testsupport.TempDir(t), "meta-link") + if err := os.Symlink(filepath.Dir(src), link); err != nil { + t.Fatal(err) + } + return filepath.Join(link, filepath.Base(src)) + }}, + } + for _, tc := range cases { + f := newOpenFixture(t, "", false, openWeb, exportCorpus()...) + src := f.writeBody(t, widgetSpec, exportSpecBody) + cwd := "/nowhere" + if tc.cwd != nil { + cwd = tc.cwd(src) + } + res := f.export(t, f.exportDeps(home, "linux", cwd), "spec", 7, func(o *OpenOptions) { o.OutputPath = tc.path(src) }) + if res.Result != ResultInvalidState || res.Reason != ReasonOpenOutputPathProtected || res.ExportedPath != "" || + strings.Contains(res.Message, "\n") || len(f.opener.targets) != 0 { + t.Errorf("%s: (%s, %s, %q, exported %q, opened %v)", tc.name, res.Result, res.Reason, res.Message, res.ExportedPath, f.opener.targets) + } + if got := readExport(t, src); got != exportSpecBody { + t.Errorf("%s: source artifact changed to %q", tc.name, got) + } + entries, _ := os.ReadDir(filepath.Dir(src)) + if len(entries) != 1 { + t.Errorf("%s: the checkout directory holds %d entries, want only the source", tc.name, len(entries)) + } + } +} + func TestOpenExportIssueNameAndH1(t *testing.T) { f := newOpenFixture(t, "", false, openWeb, exportCorpus()...) f.writeBody(t, "docs/changes/active/0007-widget.md", @@ -258,7 +306,7 @@ func TestOpenExportWarningsFilter(t *testing.T) { t.Errorf("%q: (%s, %q)", tc.warnings, res.Result, res.Message) continue } - wantLeft := []ExportLeftover{{Line: 3, Text: "<!-- docket:artifacts:start -->", Rule: ExportRuleStrayMarker}} + wantLeft := []ExportLeftover{{SourceLine: 3, Text: "<!-- docket:artifacts:start -->", Rule: ExportRuleStrayMarker}} if !tc.leftovers { wantLeft = nil } @@ -353,15 +401,19 @@ func TestValidateOpenExport(t *testing.T) { func TestOpenResultExportJSON(t *testing.T) { raw, _ := json.Marshal(OpenResult{What: "spec", Notes: []string{}, ExportedPath: "/d/x.md", Replaced: true, - Leftovers: []ExportLeftover{{Line: 2, Text: "t", Rule: "link"}}, Mentions: &ExportMentions{Count: 1, Lines: []int{4}}}) + Leftovers: []ExportLeftover{{SourceLine: 5, Text: "m", Rule: ExportRuleStrayMarker}, {Line: 2, Text: "t", Rule: "link"}}, + Mentions: &ExportMentions{Count: 1, Lines: []int{4}}}) var doc map[string]any if err := json.Unmarshal(raw, &doc); err != nil { t.Fatal(err) } want := map[string]any{ "exported_path": "/d/x.md", "replaced": true, - "leftovers": []any{map[string]any{"line": float64(2), "text": "t", "rule": "link"}}, - "mentions": map[string]any{"count": float64(1), "lines": []any{float64(4)}}, + "leftovers": []any{ + map[string]any{"source_line": float64(5), "text": "m", "rule": "stray-marker"}, + map[string]any{"line": float64(2), "text": "t", "rule": "link"}, + }, + "mentions": map[string]any{"count": float64(1), "lines": []any{float64(4)}}, } for k, w := range want { if !reflect.DeepEqual(doc[k], w) { diff --git a/internal/export/corpus_test.go b/internal/export/corpus_test.go index 31d2d3cdc..e3782218d 100644 --- a/internal/export/corpus_test.go +++ b/internal/export/corpus_test.go @@ -211,8 +211,57 @@ var ( // shows once step 6 has turned the "Change N" into a title). testStampRE = regexp.MustCompile(`(?i)^change #?\d+[.,]|^change:|^change "|\bgroomed \d{4}-\d{2}-\d{2}\b`) issueH2 = map[string]bool{"## Why": true, "## What changes": true, "## Out of scope": true, "## Open questions": true} + // testWordRefRE is a "change N" / "changes N" reference; testPaddedRE a + // zero-padded four-digit id, optionally after '#'. Both are written here, + // apart from the transform's own patterns. + testWordRefRE = regexp.MustCompile(`(?i)(?:^|[^A-Za-z0-9_])changes?[ \t]+#?(\d+)`) + testPaddedRE = regexp.MustCompile(`#?0[0-9]+`) ) +// knownRefsLeft returns the change references in plain (a line with its code +// spans removed) whose id is known: a word-form "change N", or a padded id that +// stands alone — not inside a path, filename, version, or longer number, and not +// an "ADR"/"PR" number. +func knownRefsLeft(plain string, titles Titles) []string { + var left []string + for _, m := range testWordRefRE.FindAllStringSubmatchIndex(plain, -1) { + end := m[3] + if end < len(plain) && (isAlnum(plain[end]) || plain[end] == '_') { + continue + } + if id, err := strconv.Atoi(plain[m[2]:m[3]]); err == nil { + if _, ok := titles[id]; ok { + left = append(left, plain[m[0]:m[1]]) + } + } + } + for _, m := range testPaddedRE.FindAllStringIndex(plain, -1) { + start, end := m[0], m[1] + digits := strings.TrimPrefix(plain[start:end], "#") + if len(digits) != 4 { + continue + } + if start > 0 && strings.ContainsRune("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_/.#-", rune(plain[start-1])) { + continue + } + if end < len(plain) { + c := plain[end] + if isAlnum(c) || c == '_' || c == '/' || c == '-' || (c == '.' && end+1 < len(plain) && isAlnum(plain[end+1])) { + continue + } + } + before := strings.ToUpper(plain[:start]) + if strings.HasSuffix(before, "ADR ") || strings.HasSuffix(before, "ADR-") || strings.HasSuffix(before, "PR ") { + continue + } + id, _ := strconv.Atoi(digits) + if _, ok := titles[id]; ok { + left = append(left, plain[start:end]) + } + } + return left +} + // corpusProblems checks one export: the independent detector finds no leftover, // and each removal is also asserted directly, so the test does not rest on the // detector alone. It returns one message per failure. @@ -250,6 +299,9 @@ func corpusProblems(kind Kind, src, out []byte, titles Titles) []string { if kind == KindSpec && !seenH2 && (testStampRE.MatchString(l.text) || strings.Contains(l.plain, "**Change:**")) { add("line %d: spec stamp before the first H2: %q", n, l.text) } + for _, ref := range knownRefsLeft(l.plain, titles) { + add("line %d: known change reference %q outside code: %q", n, ref, l.text) + } if strings.TrimSpace(l.text) == "" && i > 0 && !lines[i-1].fenced && strings.TrimSpace(lines[i-1].text) == "" { add("line %d: two consecutive blank lines", n) } diff --git a/internal/export/export.go b/internal/export/export.go index 243b93ce7..0067861af 100644 --- a/internal/export/export.go +++ b/internal/export/export.go @@ -315,7 +315,9 @@ func dropMetadataSentences(s string) string { // inlineSteps runs steps 5 and 6 on every line outside fences: link-reference // definitions go, then each line is code-masked, its links are stripped, and its -// change references are converted, before its code spans are restored. +// change references are converted, before its code spans are restored. Masking +// runs over a whole paragraph (consecutive non-blank lines outside fences), so a +// code span that crosses a line break is masked on both lines. func inlineSteps(lines []line, titles Titles, links, refs bool) []line { if !links && !refs { return lines @@ -330,18 +332,27 @@ func inlineSteps(lines []line, titles Titles, links, refs bool) []line { labels = linkLabels(texts, info) lines = filter(lines, func(l line) bool { return l.fenced() || !isLinkDefinition(l.text) }) } - for i, l := range lines { - if l.fenced() { + for i := 0; i < len(lines); { + if lines[i].fenced() || blank(lines[i]) { + i++ continue } - masked, restore := maskCode(l.text) - if links { - masked = stripLinks(masked, labels) + j := i + var texts []string + for ; j < len(lines) && !lines[j].fenced() && !blank(lines[j]); j++ { + texts = append(texts, lines[j].text) } - if refs { - masked = convertRefs(masked, titles) + masked, restore := maskParagraph(texts) + for k, m := range masked { + if links { + m = stripLinks(m, labels) + } + if refs { + m = convertRefs(m, titles) + } + lines[i+k].text = restore[k](m) } - lines[i].text = restore(masked) + i = j } return lines } diff --git a/internal/export/inline.go b/internal/export/inline.go index 714c99954..b4cb27ee3 100644 --- a/internal/export/inline.go +++ b/internal/export/inline.go @@ -25,42 +25,75 @@ const ( // of exactly N backticks closes it. A backslash-escaped backtick outside a span // opens nothing, and a run with no matching closer stays plain text. func maskCode(line string) (masked string, restore func(string) string) { - var spans []string - var b strings.Builder - i := 0 - for i < len(line) { - c := line[i] - if c == '\\' && i+1 < len(line) { - b.WriteString(line[i : i+2]) + m, r := maskParagraph([]string{line}) + return m[0], r[0] +} + +// maskParagraph is maskCode over the lines of one paragraph, where a code span +// may cross a line break: each line's part of such a span is masked on that +// line, and each line gets its own restore. +func maskParagraph(lines []string) (masked []string, restore []func(string) string) { + joined := strings.Join(lines, "\n") + ranges := codeSpanRanges(joined) + masked = make([]string, len(lines)) + restore = make([]func(string) string, len(lines)) + start := 0 + for i, l := range lines { + end := start + len(l) + var spans []string + var b strings.Builder + pos := start + for _, r := range ranges { + from, to := max(r[0], start), min(r[1], end) + if from >= to { + continue + } + b.WriteString(joined[pos:from]) + b.WriteString(placeholder(len(spans))) + spans = append(spans, joined[from:to]) + pos = to + } + if len(spans) == 0 { + masked[i], restore[i] = l, func(s string) string { return s } + } else { + b.WriteString(joined[pos:end]) + masked[i] = b.String() + restore[i] = func(s string) string { + for idx, span := range spans { + s = strings.ReplaceAll(s, placeholder(idx), span) + } + return s + } + } + start = end + 1 + } + return masked, restore +} + +// codeSpanRanges returns the byte range of every inline code span in s, +// backticks included, by the CommonMark rule maskCode describes. +func codeSpanRanges(s string) [][2]int { + var ranges [][2]int + for i := 0; i < len(s); { + c := s[i] + if c == '\\' && i+1 < len(s) { i += 2 continue } if c != '`' { - b.WriteByte(c) i++ continue } - n := backtickRun(line, i) - end := closingRun(line, i+n, n) + n := backtickRun(s, i) + end := closingRun(s, i+n, n) if end < 0 { - b.WriteString(line[i : i+n]) i += n continue } - b.WriteString(placeholder(len(spans))) - spans = append(spans, line[i:end]) + ranges = append(ranges, [2]int{i, end}) i = end } - if len(spans) == 0 { - return line, func(s string) string { return s } - } - restore = func(s string) string { - for idx, span := range spans { - s = strings.ReplaceAll(s, placeholder(idx), span) - } - return s - } - return b.String(), restore + return ranges } // backtickRun returns the length of the backtick run starting at i. diff --git a/internal/export/inline_test.go b/internal/export/inline_test.go index f64b62311..bcec7bd56 100644 --- a/internal/export/inline_test.go +++ b/internal/export/inline_test.go @@ -132,3 +132,25 @@ func TestLinkLabels(t *testing.T) { t.Errorf("linkLabels = %v, want only {ref one}", got) } } + +// A code span may cross a line break inside a paragraph: its parts on both lines +// stay as written, while text outside it still converts. A blank line ends the +// paragraph, so a backtick run before it never pairs with one after it. +func TestTransformMasksCodeSpansAcrossLines(t *testing.T) { + titles := Titles{559: "Close"} + cases := []struct{ in, want string }{ + { + "# T\n\n- Markers (`<!-- x [y](z) change 0559 do not\n hand-edit) -->` / `change 0559`); change 0559 and [a](b).\n", + "# T\n\n- Markers (`<!-- x [y](z) change 0559 do not\n hand-edit) -->` / `change 0559`); \"Close\" and a.\n", + }, + { + "# T\n\nopen ` change 0559\n\nchange 0559 ` close\n", + "# T\n\nopen ` \"Close\"\n\n\"Close\" ` close\n", + }, + } + for _, tc := range cases { + if got := string(Transform(Input{Kind: KindPlan, Source: []byte(tc.in), Titles: titles}).Markdown); got != tc.want { + t.Errorf("Transform(%q)\n got %q\nwant %q", tc.in, got, tc.want) + } + } +} diff --git a/internal/export/refs.go b/internal/export/refs.go index 39aebeb32..5ddc5cca8 100644 --- a/internal/export/refs.go +++ b/internal/export/refs.go @@ -179,9 +179,11 @@ func applyEdits(line string, edits []refEdit) string { // parenEdits applies the references-only parenthesis reading: a parenthesis whose // whole content is reference items, at least one of them a fully convertible // form, loses its convertible items; the rest re-join, and an emptied parenthesis -// goes with the one space before it. render gives a kept span's text. The spans -// it consumed are reported so no other reading touches them. -func parenEdits(line string, spans []refSpan, render func(refSpan) string) (edits []refEdit, consumed map[int]bool) { +// goes with the one space before it. render gives a kept span's text. When +// emptying it would leave an empty quote pair (`"(0559)"`), the quoted text is +// instead replaced by its spans rendered by whole. The spans it consumed are +// reported so no other reading touches them. +func parenEdits(line string, spans []refSpan, render, whole func(refSpan) string) (edits []refEdit, consumed map[int]bool) { consumed = map[int]bool{} for open := strings.IndexByte(line, '('); open >= 0; { closeRel := strings.IndexAny(line[open+1:], "()") @@ -193,7 +195,7 @@ func parenEdits(line string, spans []refSpan, render func(refSpan) string) (edit open = closeAt continue } - if e, used, ok := parenReading(line, open, closeAt, spans, render); ok { + if e, used, ok := parenReading(line, open, closeAt, spans, render, whole); ok { edits = append(edits, e) for _, i := range used { consumed[i] = true @@ -208,7 +210,7 @@ func parenEdits(line string, spans []refSpan, render func(refSpan) string) (edit return edits, consumed } -func parenReading(line string, open, closeAt int, spans []refSpan, render func(refSpan) string) (refEdit, []int, bool) { +func parenReading(line string, open, closeAt int, spans []refSpan, render, whole func(refSpan) string) (refEdit, []int, bool) { type token struct { text string drop bool @@ -267,6 +269,13 @@ func parenReading(line string, open, closeAt int, spans []refSpan, render func(r if start > 0 && line[start-1] == ' ' { start-- } + if start > 0 && line[start-1] == '"' && closeAt+1 < len(line) && line[closeAt+1] == '"' { + parts := make([]string, len(toks)) + for i, tk := range toks { + parts[i] = whole(spans[tk.spanIdx]) + } + return refEdit{start: start - 1, end: closeAt + 2, text: joinList(parts)}, used, true + } return refEdit{start: start, end: closeAt + 1}, used, true } lastAnd := toks[len(toks)-1].sepAnd @@ -288,14 +297,17 @@ func parenReading(line string, open, closeAt int, spans []refSpan, render func(r // convertRefs runs step 6 on one masked line: every recognized form whose number // is a known change id is removed (references-only parenthesis, own-title dash) -// or replaced by that change's cleaned title in double quotes. +// or replaced by that change's cleaned title in double quotes. The author's own +// quotes are respected: a fully convertible reference that is the whole of a +// double-quoted text takes those quotes as its own, and a title inserted inside a +// longer double-quoted phrase gets single quotes. func convertRefs(masked string, titles Titles) string { spans := findRefs(masked, titles) if len(spans) == 0 { return masked } - quoted := func(id int) string { return `"` + cleanTitle(titles[id], titles) + `"` } - render := func(s refSpan) string { + renderIn := func(s refSpan, q string) string { + quoted := func(id int) string { return q + cleanTitle(titles[id], titles) + q } if !s.anyKnown() { return masked[s.start:s.end] } @@ -317,11 +329,17 @@ func convertRefs(masked string, titles Titles) string { } return applyEdits(masked[s.start:s.end], edits) } - edits, consumed := parenEdits(masked, spans, render) + render := func(s refSpan) string { return renderIn(s, quoteAt(masked, s.start)) } + whole := func(s refSpan) string { return renderIn(s, `"`) } + edits, consumed := parenEdits(masked, spans, render, whole) for i, s := range spans { if consumed[i] || !s.anyKnown() { continue } + if s.allKnown() && s.start > 0 && s.end < len(masked) && masked[s.start-1] == '"' && masked[s.end] == '"' { + edits = append(edits, refEdit{start: s.start - 1, end: s.end + 1, text: whole(s)}) + continue + } if end, ok := ownTitleDash(masked, s, titles); ok { edits = append(edits, refEdit{start: s.start, end: end}) continue @@ -331,6 +349,16 @@ func convertRefs(masked string, titles Titles) string { return applyEdits(masked, edits) } +// quoteAt returns the quote an inserted title at offset at takes: a single quote +// inside an open double-quoted phrase (an odd number of '"' before it), else a +// double quote. +func quoteAt(line string, at int) string { + if strings.Count(line[:at], `"`)%2 == 1 { + return "'" + } + return `"` +} + // ownTitleDash reports a singular known reference followed by a spaced dash and // text that begins with that change's raw title, returning where the dash ends. func ownTitleDash(line string, s refSpan, titles Titles) (int, bool) { @@ -384,7 +412,7 @@ func cleanTitle(title string, titles Titles) string { } return applyEdits(masked[s.start:s.end], edits) } - edits, consumed := parenEdits(masked, spans, render) + edits, consumed := parenEdits(masked, spans, render, render) for i, s := range spans { if consumed[i] || !s.anyKnown() { continue diff --git a/internal/export/refs_test.go b/internal/export/refs_test.go index 2f799e666..d410753e7 100644 --- a/internal/export/refs_test.go +++ b/internal/export/refs_test.go @@ -49,6 +49,18 @@ func TestConvertRefs(t *testing.T) { {"mirroring 0088", `mirroring "Y"`}, {"#0559", `"Close a change to done without a PR"`}, {"done in 0559.", `done in "Close a change to done without a PR".`}, + // The author's own quotes around a reference: the whole quoted text is the + // reference, so the title takes those quotes; inside a longer quoted phrase + // the title takes single quotes; a quoted references-only parenthesis never + // leaves an empty quote pair. + {`the "change 0559" note`, `the "Close a change to done without a PR" note`}, + {`"#0559"`, `"Close a change to done without a PR"`}, + {`"changes 0113 and 0114"`, `"C" and "D"`}, + {`"changes 0113 and 9999"`, `"changes 'C' and 9999"`}, + {`as "(0559)" said`, `as "Close a change to done without a PR" said`}, + {`as "(0113, 0114)" said`, `as "C" and "D" said`}, + {`("groom 0559")`, `("groom 'Close a change to done without a PR'")`}, + {`said "see change 0559 now" and change 0113`, `said "see 'Close a change to done without a PR' now" and "C"`}, // Left exactly as written. {"#559", "#559"}, {"PR #559", "PR #559"}, diff --git a/internal/export/testdata/corpus/PROVENANCE.md b/internal/export/testdata/corpus/PROVENANCE.md index 25002999b..1d391ed33 100644 --- a/internal/export/testdata/corpus/PROVENANCE.md +++ b/internal/export/testdata/corpus/PROVENANCE.md @@ -46,7 +46,7 @@ Checked by scanning every corpus file outside fences and code spans: | Images (`![alt](p)`) | `TestStripLinks` | | Reference-style links and link-reference definitions (`[t][r]`, `[r]: u`) | `TestStripLinks`, `TestIsLinkDefinition` | | HTML `<a href>` links | `TestStripLinks` | -| Inline code spans that cross a line break (a known limitation: such a span is treated as plain text) | none; no corpus line outside a fence holds an unmatched backtick run | +| Inline code spans that cross a line break (both the transform and the self-check find spans across a whole paragraph, so such a span stays code on each of its lines) | `TestTransformMasksCodeSpansAcrossLines`, `TestCheckMasksCodeSpansAcrossLines` | | Damaged markers and an unclosed frontmatter opener | `TestTransformDamagedSourceKeepsContent` | | CRLF line endings | `TestTransformNormalizesCRLF` | | An id two records claim | the app-layer export tests | diff --git a/internal/exportcheck/check.go b/internal/exportcheck/check.go index 475127fbf..46c2b0a9c 100644 --- a/internal/exportcheck/check.go +++ b/internal/exportcheck/check.go @@ -45,7 +45,8 @@ type Report struct { func Check(md []byte, known func(id int) bool) Report { lines := splitLines(string(md)) code := fencedLines(lines) - defs := definitionLabels(lines, code) + plains := maskParagraphs(lines, code) + defs := definitionLabels(plains, code) var r Report for i, line := range lines { @@ -67,7 +68,7 @@ func Check(md []byte, known func(id int) bool) Report { if level, _ := headingLevel(line); level == 2 { seenH2 = true } - plain := maskSpans(line) + plain := plains[i] if text, ok := findMarker(line, plain); ok { add(RuleMarker, text) @@ -204,12 +205,41 @@ func fencedLines(lines []string) []bool { return code } -// maskSpans blanks every inline code span, backticks included, with NUL bytes of -// the same length, so offsets still index the original line. A backslash-escaped -// backtick does not open a span, and a backtick run with no closing run of the -// same length is literal text. -func maskSpans(line string) string { - b := []byte(line) +// maskParagraphs returns every line with its inline code spans blanked, +// backticks included, by NUL bytes of the same length, so offsets still index the +// original line. A span may cross a line break: spans are found across each +// paragraph, a run of non-blank lines outside fences, and a line break inside a +// span stays a line break. Code lines come back as they are. +func maskParagraphs(lines []string, code []bool) []string { + out := make([]string, len(lines)) + copy(out, lines) + inPara := func(i int) bool { return !code[i] && trimRight(lines[i]) != "" } + for i := 0; i < len(lines); { + if !inPara(i) { + i++ + continue + } + var para []byte + first := i + for ; i < len(lines) && inPara(i); i++ { + if i > first { + para = append(para, '\n') + } + para = append(para, lines[i]...) + } + blankSpans(para) + for k, at := first, 0; k < i; k++ { + out[k] = string(para[at : at+len(lines[k])]) + at += len(lines[k]) + 1 + } + } + return out +} + +// blankSpans overwrites every inline code span in b with NUL bytes, keeping +// line breaks. A backslash-escaped backtick does not open a span, and a backtick +// run with no closing run of the same length is literal text. +func blankSpans(b []byte) { for i := 0; i < len(b); { if b[i] == '\\' { i += 2 @@ -244,11 +274,12 @@ func maskSpans(line string) string { continue } for j := open; j < closeAt; j++ { - b[j] = 0 + if b[j] != '\n' { + b[j] = 0 + } } i = closeAt } - return string(b) } // findMarker finds managed-block marker text: an HTML comment that opens with a @@ -329,14 +360,15 @@ func foldLabel(s string) string { return string(b) } -// definitionLabels collects the labels of every definition outside code. -func definitionLabels(lines []string, code []bool) map[string]bool { +// definitionLabels collects the labels of every definition outside code, from +// the lines with their code spans masked. +func definitionLabels(plains []string, code []bool) map[string]bool { defs := map[string]bool{} - for i, line := range lines { + for i, plain := range plains { if code[i] { continue } - if label, ok := definitionLabel(maskSpans(line)); ok { + if label, ok := definitionLabel(plain); ok { defs[label] = true } } diff --git a/internal/exportcheck/check_test.go b/internal/exportcheck/check_test.go index 43b2d6859..1f177b580 100644 --- a/internal/exportcheck/check_test.go +++ b/internal/exportcheck/check_test.go @@ -206,3 +206,18 @@ func TestCheckHeadingRules(t *testing.T) { }) } } + +// TestCheckMasksCodeSpansAcrossLines: a code span may cross a line break inside +// a paragraph, so marker-, link-, and reference-shaped text on either of its +// lines is code. A blank line ends the paragraph: a backtick run before it never +// pairs with one after it. +func TestCheckMasksCodeSpansAcrossLines(t *testing.T) { + md := "# T\n\n- Markers (`<!-- docket:dispatch:start (managed by docket — do not\n" + + " hand-edit) -->` / `<!-- docket:dispatch:end -->`); see `x`.\n\n" + + "open ` [a](b)\n\nchange 0559 ` close\n" + got := lineRules(Check([]byte(md), known)) + want := []lineRule{{6, RuleLink}, {8, RuleChangeRef}} + if !reflect.DeepEqual(got, want) { + t.Errorf("leftovers = %v, want %v", got, want) + } +}