From d27c41dba5a6e77a875fa9ef5c78a0f52204049a Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 13:35:04 -0500 Subject: [PATCH 1/7] Add design spec: Add acceptance criteria to changes and rename export's issue kind to ticket --- ...hanges-and-rename-export-s-issue-design.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-09-add-acceptance-criteria-to-changes-and-rename-export-s-issue-design.md diff --git a/docs/superpowers/specs/2026-11-09-add-acceptance-criteria-to-changes-and-rename-export-s-issue-design.md b/docs/superpowers/specs/2026-11-09-add-acceptance-criteria-to-changes-and-rename-export-s-issue-design.md new file mode 100644 index 000000000..2be6c9253 --- /dev/null +++ b/docs/superpowers/specs/2026-11-09-add-acceptance-criteria-to-changes-and-rename-export-s-issue-design.md @@ -0,0 +1,107 @@ +# Acceptance criteria on changes, and export's `issue` kind renamed to `ticket` + +Change 0582 — Add acceptance criteria to changes and rename export's issue kind to ticket + +Change #582, groomed interactively on 2026-11-09. + +## Why + +The ticket integration (designed in change 581's spec) needs two small foundations before any ticket capability can be built: + +1. A ticket needs **acceptance criteria that belong to the change**. A change body has no place for them today. +2. The export that will become a ticket body is the change-record export, whose kind is named after GitHub issues: `docket open change --export` writes `-issue-.md`. The ticket work uses one term, "ticket", throughout, and no name should contradict its value. + +This change carries both. It builds without reading change 581: every decision it needs is restated here. + +## Settled decisions (fixed by change 581; not reopened) + +- `## Acceptance criteria` is a new, **optional** change-body section, placed **after `## What changes` and before `## Out of scope`**. +- It is settable at creation (`change.create`) and editable through `change.groom`'s owned sections (outcomes `spec` and `revise`), like the other proposal sections. +- It is **never a build gate**: build-readiness is unchanged, and a change without it is as complete as before. Changes that never become tickets need none. +- The convention's body-section list documents it. +- Export carries it: the change-record export's section allowlist gains `Acceptance criteria`. +- Export's `issue` kind becomes `ticket`, its internal identifiers renamed with it, and the exported change file becomes `-ticket-.md`. The rename is internal apart from that filename: no JSON field carries the kind (`open`'s `target_kind` is `file`, a different thing), and no skill or guide names the `-issue-` filename. +- **No compatibility alias** for the old kind or filename. + +## Decisions made at grooming + +- **Proposal sections keep a consistent order, also when added later.** The five proposal sections have one order: Why, What changes, Acceptance criteria, Out of scope, Open questions. `change.create` already writes them in that order. When an owned-section edit (`change.groom`, reconcile, or any other caller of the shared splicer) adds one of them to a record that lacks it, it is placed in that order instead of at end of file. This matters because the ticket path adds criteria to existing changes routinely — creating a ticket from a change runs a readiness check whose refinement writes missing criteria through `change.groom` — and export keeps source order, so end-of-file placement would put the criteria after the non-goals and open questions in the ticket body. Every other section added later (Reconcile log, Why on hold, Auto-groom blocked, Run halted, Build evidence, and the rest) is still appended at end of file: those are event records, where chronological order is right. +- **"another issue" stays.** `cleanTitle` in `internal/export/refs.go` rewrites a known change reference in an inserted title to "another issue" / "other issues". That outward wording is unchanged: "another ticket" would be wrong when the referenced change has no ticket, and "issue" reads naturally inside a ticket system. + +## Design + +### `change.create` + +- `ChangeCreateRequest` gains an optional `acceptance_criteria` string (`json:"acceptance_criteria,omitempty"`, not required). Its `schema` descriptor follows from the struct, as for the other fields. +- Omitted or blank (whitespace only) writes **no** section — the section is optional, so blank is absent, not an error. +- Non-blank: `render.NewChangeRecord` gains an `AcceptanceCriteria` body field, and `render.ChangeRecord` emits `## Acceptance criteria` between `## What changes` and `## Out of scope`. Section order of a new record becomes: Artifacts, Why, What changes, [Acceptance criteria], Out of scope, [Why on hold]. +- Validation (builder's call made at grooming): the body gets the same structural checks `hold_reason` gets — no column-zero `## ` heading outside fenced code and no unterminated fence (`render.ValidateSectionBody`), and the authored-input size bound (`boundAuthored`) — refusing with a new `invalid-acceptance_criteria` finding code registered beside the existing codes. A heading inside the body would otherwise split the section and escape the owned set. `holdReasonProblem`'s messages name `## Why on hold`, so the new field needs its own messages: generalise that helper over the heading name or add a sibling (the builder's call). +- **Digest compatibility:** `changeCreatePayload` gains `AcceptanceCriteria string \`json:"acceptance_criteria,omitempty"\``, populated with the blank-normalized value (blank digests as absent), so a request that does not use the field digests exactly as before and an older retry still replays — the same pattern `hold`/`hold_reason` used. + +### Ordered placement of proposal sections (`internal/render/section.go`) + +`render.ApplySectionEdits` gains ordered placement for the proposal sections; every other behavior of the splicer is unchanged. + +- The proposal order is one exported list in `internal/render`: `## Why`, `## What changes`, `## Acceptance criteria`, `## Out of scope`, `## Open questions`. +- A `replace` edit naming a proposal heading that is **absent** from the record is inserted: + 1. immediately after the section of the nearest **earlier** proposal heading (in the list) that is present — that is, at the start of the next top-level heading after that section, or at end of file when that section is last; + 2. otherwise, immediately before the nearest **later** proposal heading that is present; + 3. otherwise, at end of file (today's behavior). +- "Present" is judged against the record as edited by the same request, so several proposal sections added in one request land in proposal order relative to each other and to the sections already there. +- Layout matches the existing rules: the inserted section is preceded by exactly one blank line and followed by exactly one blank line before the next heading; at end of file it keeps the single trailing newline. All other bytes are unchanged. +- Absent non-proposal headings are appended at end of file exactly as today. A `replace` of a present section stays where it is. `remove` and `preserve` are unchanged. +- The rule keys on heading names, so callers whose owned set holds no proposal heading (the learnings operations) are unaffected. +- **No migration.** Existing records whose proposal sections are already out of order (for example an Open questions appended after a Reconcile log) are not reordered; only a section being added is placed. + +### Owned headings + +- `"## Acceptance criteria"` joins `render.ChangeOwnedHeadings`. Every operation that splices owned change sections picks it up: `change.groom` (`spec`, `revise`, and `re-enable` section edits), reconcile, and the lifecycle/kill/claim callers that pass the shared list. No per-operation code change is needed beyond the list itself; `change.groom`'s `invalid-section-heading` check already derives from the list. +- It is not a build-readiness input anywhere (`status` readiness, the selector, the board are untouched). + +### Export rename + +| Today | Becomes | +|---|---| +| `KindIssue Kind = "issue"` (`internal/export/export.go`) | `KindTicket Kind = "ticket"` | +| `issueSections` (allowlist: Why, What changes, Out of scope, Open questions) | `ticketSections`, also allowing `Acceptance criteria` | +| `stepIssueSections`, `keepIssueSections` | `stepTicketSections`, `keepTicketSections` | +| `FileName`'s `kind != KindIssue` branch and doc comment (`internal/export/filename.go`) | `KindTicket` | +| `"change": export.KindIssue` in `exportKinds` (`internal/app/open_export.go`) | `export.KindTicket` | +| tests: `issueFixture`, `issueWant`, `TestTransformIssue` (`export_test.go`); `issueH2` and its uses (`corpus_test.go`); the `issue-…` expectations (`filename_test.go`) | `ticket` equivalents; `ticketH2` includes `## Acceptance criteria` | + +Comments that call the change-record export "the issue" (for example `Title`'s "the issue H1") follow the rename. + +**Not renamed:** `cleanTitle`'s "another issue" / "other issues" wording (decided above); the `"issue"` key in `internal/reposetup/repair.go`, which is the legacy frontmatter field retired by change 583; the archived spec of change 561 that mentions `-issue-` (a point-in-time record). + +### Documentation + +- `skills/docket-convention/SKILL.md`, *Change body sections*: the opening sentence names `## Acceptance criteria` as optional at creation, and a new list entry after `## What changes` reads, in substance: "`## Acceptance criteria` — optional; verifiable conditions that belong to this change. Written by `change.create` (between What changes and Out of scope) when given; a later owned-section edit that adds it places it in proposal order. Never a build gate." The section also states the rule once: the proposal sections keep the order Why, What changes, Acceptance criteria, Out of scope, Open questions — an edit that adds one places it in that order — and every other section added later is appended at end of file. +- `skills/docket-new-change/SKILL.md` step 4: the request description names the optional `acceptance_criteria` body field beside `why`/`what_changes`/`out_of_scope`. +- Regenerate the embedded twins with `go generate ./internal/assets/`. +- Docs describe only current behavior: no change numbers or history in the convention or skill text. + +## Tests + +- **Renderer** (`internal/render`): `ChangeRecord` with criteria places `## Acceptance criteria` between What changes and Out of scope (and before Why on hold when both are set); without criteria the output is byte-identical to today. +- **`change.create`** (`internal/app`): criteria land in place; blank criteria write no section; a body carrying a column-zero `## ` heading or an unterminated fence refuses with `invalid-acceptance_criteria` and writes nothing; a request without the field produces the same digest as before the field existed (replay compatibility). +- **Splicer** (`internal/render`): an absent proposal section is inserted after its nearest present predecessor (Acceptance criteria after What changes, before Out of scope; Open questions after Out of scope, ahead of a later Why on hold or Reconcile log); before its nearest present successor when no predecessor is present; at end of file when no proposal section is present; two proposal sections added in one request land in order; an absent non-proposal section is still appended at end of file; a present section replaced in place does not move; CRLF and fenced-code headings behave as today; all other bytes are identical. +- **`change.groom`**: a `revise` adding `## Acceptance criteria` to a record that lacks it places it between What changes and Out of scope; a `revise` replacing an existing one keeps its position; a `spec` outcome carrying it as a section edit is accepted. +- **Export**: the transform under `KindTicket` keeps `## Acceptance criteria` and drops non-allowlisted sections as before; `FileName` yields `-ticket-.md`; the corpus test's allowlist includes the new heading. +- Guards are mutation-checked: removing the heading from `ChangeOwnedHeadings`, from the proposal order, or from `ticketSections`, or falling back to end-of-file placement, must redden a test. +- The whole suite runs at the build gate. + +## Acceptance criteria + +- A change created with acceptance criteria shows `## Acceptance criteria` between What changes and Out of scope. +- `change.groom` adds the section to an existing change between What changes and Out of scope, or replaces it where it already is; any proposal section added later lands in proposal order, while other added sections still go at end of file. +- `docket open change --export` writes `-ticket-.md` and keeps the section. +- A change without the section builds as before and exports the same sections as before, under the `ticket` filename. + +## Out of scope + +- Reviewers checking a build against acceptance criteria (a possible follow-up). +- The legacy `issue:` frontmatter field and repair's `"issue"` key (change 583). +- Reordering existing records whose sections are already out of order. +- Ordered placement for non-proposal sections. +- Renaming export's "another issue" reference wording. +- Any board change, and any ticket-system call. From 2aa4a44f7c6bb45829ee1d46776308c4351e5f93 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 13:41:44 -0500 Subject: [PATCH 2/7] feat(render): place added proposal sections in proposal order --- internal/app/change_groom_test.go | 55 ++++++++++++ internal/render/section.go | 81 ++++++++++++++++- internal/render/section_test.go | 140 ++++++++++++++++++++++++++++++ 3 files changed, 272 insertions(+), 4 deletions(-) diff --git a/internal/app/change_groom_test.go b/internal/app/change_groom_test.go index 15ecd08ce..65ad8e589 100644 --- a/internal/app/change_groom_test.go +++ b/internal/app/change_groom_test.go @@ -3190,3 +3190,58 @@ func TestChangeGroomHoldCodesAreRegistered(t *testing.T) { } } } + +// TestChangeGroomReviseAddsAcceptanceCriteriaInProposalOrder: a revise adding +// the absent ## Acceptance criteria section places it in proposal order, +// between ## What changes and ## Out of scope, not at EOF. +func TestChangeGroomReviseAddsAcceptanceCriteriaInProposalOrder(t *testing.T) { + req := validReviseRequest() + req.SpecMarkdown = "" + req.Sections = []SectionEditRequest{{Heading: "## Acceptance criteria", Intent: "replace", Markdown: "- It works.\n"}} + plan, opRes := groomPlanFor(t, reviseFixtureFiles(), baseGroomOp([]string{}, req)) + if opRes.Refused { + t.Fatalf("unexpected refusal: %v", opRes.Findings) + } + rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) + want := "## What changes\n\nOriginal what.\n\n## Acceptance criteria\n\n- It works.\n\n## Out of scope\n" + if !strings.Contains(rec, want) { + t.Errorf("acceptance criteria not placed in proposal order; want substring %q in:\n%s", want, rec) + } +} + +// TestChangeGroomReviseReplacesAcceptanceCriteriaInPlace: a revise replacing a +// present ## Acceptance criteria section rewrites it where it stands. +func TestChangeGroomReviseReplacesAcceptanceCriteriaInPlace(t *testing.T) { + files := reviseFixtureFiles() + p := groomPath(2, "add-a-widget") + files[p] = strings.Replace(files[p], "## Out of scope\n", "## Acceptance criteria\n\nOld.\n\n## Out of scope\n", 1) + req := validReviseRequest() + req.SpecMarkdown = "" + req.Sections = []SectionEditRequest{{Heading: "## Acceptance criteria", Intent: "replace", Markdown: "New.\n"}} + plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, req)) + if opRes.Refused { + t.Fatalf("unexpected refusal: %v", opRes.Findings) + } + rec := string(groomedRecordBytes(t, plan, p)) + want := "## What changes\n\nOriginal what.\n\n## Acceptance criteria\n\nNew.\n\n## Out of scope\n" + if !strings.Contains(rec, want) || strings.Contains(rec, "Old.") { + t.Errorf("acceptance criteria not replaced in place; want substring %q in:\n%s", want, rec) + } +} + +// TestChangeGroomSpecAcceptsAcceptanceCriteriaSection: a spec-outcome groom may +// write ## Acceptance criteria, which lands in proposal order. +func TestChangeGroomSpecAcceptsAcceptanceCriteriaSection(t *testing.T) { + req := validGroomSpecRequest() + req.Sections = append(req.Sections, SectionEditRequest{Heading: "## Acceptance criteria", Intent: "replace", Markdown: "- It works.\n"}) + files := map[string]string{groomPath(2, "add-a-widget"): groomableChange(2, "add-a-widget")} + plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, req)) + if opRes.Refused { + t.Fatalf("unexpected refusal: %v", opRes.Findings) + } + rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) + want := "## What changes\n\nOriginal what.\n\n## Acceptance criteria\n\n- It works.\n\n## Out of scope\n" + if !strings.Contains(rec, want) { + t.Errorf("acceptance criteria not placed in proposal order; want substring %q in:\n%s", want, rec) + } +} diff --git a/internal/render/section.go b/internal/render/section.go index eced89c7c..8cd558312 100644 --- a/internal/render/section.go +++ b/internal/render/section.go @@ -37,10 +37,19 @@ type SectionEdit struct { // Owned heading sets, exported for app operations. var ChangeOwnedHeadings = []string{ - "## Why", "## What changes", "## Out of scope", "## Open questions", + "## Why", "## What changes", "## Acceptance criteria", "## Out of scope", "## Open questions", "## Why deferred", "## Why killed", "## Auto-groom blocked", } +// ProposalHeadings is the proposal order of a change record's design sections. +// When ApplySectionEdits adds one of these headings to a record that lacks it, +// the section lands right after the nearest present earlier proposal section, +// else right before the nearest present later one, else at EOF. Sections +// already present are never moved. +var ProposalHeadings = []string{ + "## Why", "## What changes", "## Acceptance criteria", "## Out of scope", "## Open questions", +} + var LearningOwnedHeadings = []string{"## Apply", "## War story"} // h2Prefix is the CommonMark ATX H2 lead-in; a top-level section boundary is any @@ -186,8 +195,13 @@ func ValidateSectionBody(body []byte) error { // top-level "## " heading outside fences, or EOF. // - Every owned heading present in src must be unique; a duplicate refuses the // whole edit set. All edits are validated before any splice. -// - replace: substitute the section body (appended at EOF, preceded by exactly -// one blank line, when the section is absent). remove: delete heading and +// - replace: substitute the section body. When the section is absent, a +// heading in ProposalHeadings is placed in proposal order — right after the +// nearest present earlier proposal section, else right before the nearest +// present later one, else at EOF — judged against the record after this +// request's in-place splices and earlier insertions; every other absent +// heading is appended at EOF. A new section is preceded by exactly one blank +// line. remove: delete heading and // body (error when absent). preserve: assert untouched (no-op, valid whether // present or not). // - Splices apply from the last edit position toward the first, then the @@ -250,7 +264,8 @@ func ApplySectionEdits(src []byte, owned []string, edits []SectionEdit) ([]byte, le := detectLineEnding(src) // Split edits into in-place splices (replace-present, remove) applied against - // original offsets, and appends (replace-absent) applied after at EOF. + // original offsets, and additions (replace-absent) applied after, in request + // order: proposal headings at their proposal-order position, all others at EOF. type splice struct { start, end int repl []byte @@ -289,6 +304,10 @@ func ApplySectionEdits(src []byte, owned []string, edits []SectionEdit) ([]byte, out = next } for _, e := range appends { + if off, ok := proposalInsertOffset(out, e.Heading); ok { + out = insertSectionAt(out, off, e.Heading, e.Markdown, le) + continue + } out = appendSection(out, e.Heading, e.Markdown, le) } @@ -298,6 +317,60 @@ func ApplySectionEdits(src []byte, owned []string, edits []SectionEdit) ([]byte, return out, nil } +// proposalInsertOffset returns where an absent proposal heading belongs in src: +// the end of the nearest present earlier proposal section, else the start of +// the nearest present later one. ok is false when heading is not a proposal +// heading or no proposal neighbour is present (the caller appends at EOF). +// Presence is the first fence-aware occurrence, per scanH2Headings. +func proposalInsertOffset(src []byte, heading string) (int, bool) { + idx := -1 + for i, h := range ProposalHeadings { + if h == heading { + idx = i + break + } + } + if idx < 0 { + return 0, false + } + heads := scanH2Headings(src) + first := make(map[string]int, len(heads)) + for k, h := range heads { + if _, ok := first[h.heading]; !ok { + first[h.heading] = k + } + } + for i := idx - 1; i >= 0; i-- { + if k, ok := first[ProposalHeadings[i]]; ok { + return sectionEnd(heads, k, len(src)), true + } + } + for i := idx + 1; i < len(ProposalHeadings); i++ { + if k, ok := first[ProposalHeadings[i]]; ok { + return heads[k].start, true + } + } + return 0, false +} + +// insertSectionAt inserts a new section at off, a line start in src. At EOF it +// is appendSection; elsewhere it adds one line ending first when the preceding +// bytes do not already end in a blank line, then the section followed by a +// blank line. It never deletes an existing byte. +func insertSectionAt(src []byte, off int, heading, markdown, le string) []byte { + if off >= len(src) { + return appendSection(src, heading, markdown, le) + } + section := renderSection(heading, markdown, le, false) + out := make([]byte, 0, len(src)+len(section)+len(le)) + out = append(out, src[:off]...) + if off > 0 && !bytes.HasSuffix(src[:off], []byte(le+le)) { + out = append(out, le...) + } + out = append(out, section...) + return append(out, src[off:]...) +} + // sectionEnd returns the byte offset one past section k: the start of the next // top-level heading, or EOF. func sectionEnd(heads []h2Heading, k, srcLen int) int { diff --git a/internal/render/section_test.go b/internal/render/section_test.go index ffa707494..dfe84e258 100644 --- a/internal/render/section_test.go +++ b/internal/render/section_test.go @@ -312,3 +312,143 @@ func TestValidateSectionBodyErrorsCarryNoBodyContent(t *testing.T) { } } } + +// proposalBase is the shared fixture for the proposal-order placement tests: +// an unowned lead section, then Why, What changes, Out of scope in order. +const proposalBase = "---\nid: 7\n---\n\n## Artifacts\n\nA\n\n## Why\n\nW\n\n## What changes\n\nC\n\n## Out of scope\n\nO\n" + +// applyProposalEdits runs ApplySectionEdits over the change owned set and +// compares the full output against want byte for byte. +func applyProposalEdits(t *testing.T, src, want string, edits ...render.SectionEdit) { + t.Helper() + out, err := render.ApplySectionEdits([]byte(src), render.ChangeOwnedHeadings, edits) + if err != nil { + t.Fatal(err) + } + if !bytes.Equal(out, []byte(want)) { + t.Fatalf("placement produced:\n%q\nwant:\n%q", out, want) + } +} + +func replaceEdit(heading, markdown string) render.SectionEdit { + return render.SectionEdit{Heading: heading, Intent: render.SectionReplace, Markdown: markdown} +} + +// TestApplySectionEditsProposalInsertAfterPredecessor: an absent proposal +// section lands right after its nearest present earlier proposal section. +func TestApplySectionEditsProposalInsertAfterPredecessor(t *testing.T) { + want := "---\nid: 7\n---\n\n## Artifacts\n\nA\n\n## Why\n\nW\n\n## What changes\n\nC\n\n## Acceptance criteria\n\nAC\n\n## Out of scope\n\nO\n" + applyProposalEdits(t, proposalBase, want, replaceEdit("## Acceptance criteria", "AC\n")) +} + +// TestApplySectionEditsProposalInsertAfterPredecessorAheadOfEventSections: a +// proposal section added after the last proposal section still lands ahead of +// trailing non-proposal sections. +func TestApplySectionEditsProposalInsertAfterPredecessorAheadOfEventSections(t *testing.T) { + src := proposalBase + "\n## Reconcile log\n\nR\n\n## Why on hold\n\nH\n" + want := "---\nid: 7\n---\n\n## Artifacts\n\nA\n\n## Why\n\nW\n\n## What changes\n\nC\n\n## Out of scope\n\nO\n\n## Open questions\n\nQ\n\n## Reconcile log\n\nR\n\n## Why on hold\n\nH\n" + applyProposalEdits(t, src, want, replaceEdit("## Open questions", "Q\n")) +} + +// TestApplySectionEditsProposalInsertBeforeSuccessor: with no earlier proposal +// section present, the added one lands before the nearest present later one. +func TestApplySectionEditsProposalInsertBeforeSuccessor(t *testing.T) { + src := "---\nid: 7\n---\n\n## Artifacts\n\nA\n\n## Out of scope\n\nO\n" + want := "---\nid: 7\n---\n\n## Artifacts\n\nA\n\n## Why\n\nW\n\n## Out of scope\n\nO\n" + applyProposalEdits(t, src, want, replaceEdit("## Why", "W\n")) +} + +// TestApplySectionEditsProposalAppendsWhenNoProposalPresent: with no proposal +// neighbour present, the added proposal section is appended at EOF. +func TestApplySectionEditsProposalAppendsWhenNoProposalPresent(t *testing.T) { + src := "---\nid: 7\n---\n\n## Artifacts\n\nA\n\n## Reconcile log\n\nR\n" + want := "---\nid: 7\n---\n\n## Artifacts\n\nA\n\n## Reconcile log\n\nR\n\n## Why\n\nW\n" + applyProposalEdits(t, src, want, replaceEdit("## Why", "W\n")) +} + +// TestApplySectionEditsProposalTwoInOneRequestLandInOrder: an earlier +// insertion in the same request counts as present for the next one. +func TestApplySectionEditsProposalTwoInOneRequestLandInOrder(t *testing.T) { + src := "---\nid: 7\n---\n\n## Why\n\nW\n\n## Out of scope\n\nO\n\n## Reconcile log\n\nR\n" + want := "---\nid: 7\n---\n\n## Why\n\nW\n\n## Acceptance criteria\n\nAC\n\n## Out of scope\n\nO\n\n## Open questions\n\nQ\n\n## Reconcile log\n\nR\n" + applyProposalEdits(t, src, want, + replaceEdit("## Open questions", "Q\n"), + replaceEdit("## Acceptance criteria", "AC\n"), + ) +} + +// TestApplySectionEditsProposalAfterLastSectionKeepsEOFLayout: a predecessor +// that ends the file yields the ordinary EOF append layout. +func TestApplySectionEditsProposalAfterLastSectionKeepsEOFLayout(t *testing.T) { + want := proposalBase + "\n## Open questions\n\nQ\n" + applyProposalEdits(t, proposalBase, want, replaceEdit("## Open questions", "Q\n")) +} + +// TestApplySectionEditsProposalPresentReplaceStaysInPlace: replacing a present +// proposal section never moves it, even when it sits out of order. +func TestApplySectionEditsProposalPresentReplaceStaysInPlace(t *testing.T) { + src := "---\nid: 7\n---\n\n## Why\n\nW\n\n## Reconcile log\n\nR\n\n## Open questions\n\nold\n" + want := "---\nid: 7\n---\n\n## Why\n\nW\n\n## Reconcile log\n\nR\n\n## Open questions\n\nnew\n" + applyProposalEdits(t, src, want, replaceEdit("## Open questions", "new\n")) +} + +// TestApplySectionEditsNonProposalStillAppends: a non-proposal owned section is +// appended at EOF even when proposal sections are present. +func TestApplySectionEditsNonProposalStillAppends(t *testing.T) { + want := proposalBase + "\n## Why deferred\n\nD\n" + applyProposalEdits(t, proposalBase, want, replaceEdit("## Why deferred", "D\n")) +} + +// TestApplySectionEditsProposalInsertAddsMissingBlankLine: when the +// predecessor's body runs straight into the next heading, the insertion still +// sits behind exactly one blank line and deletes no existing byte. +func TestApplySectionEditsProposalInsertAddsMissingBlankLine(t *testing.T) { + src := "---\nid: 7\n---\n\n## What changes\n\nC\n## Out of scope\n\nO\n" + want := "---\nid: 7\n---\n\n## What changes\n\nC\n\n## Acceptance criteria\n\nAC\n\n## Out of scope\n\nO\n" + applyProposalEdits(t, src, want, replaceEdit("## Acceptance criteria", "AC\n")) +} + +// TestApplySectionEditsProposalJudgedAgainstEditedRecord: "present" is judged +// after the request's in-place splices, so a predecessor removed in the same +// request does not anchor the insertion. +func TestApplySectionEditsProposalJudgedAgainstEditedRecord(t *testing.T) { + want := "---\nid: 7\n---\n\n## Artifacts\n\nA\n\n## Why\n\nW\n\n## Acceptance criteria\n\nAC\n\n## Out of scope\n\nO\n" + applyProposalEdits(t, proposalBase, want, + render.SectionEdit{Heading: "## What changes", Intent: render.SectionRemove}, + replaceEdit("## Acceptance criteria", "AC\n"), + ) +} + +// TestApplySectionEditsProposalInsertCRLF: a CRLF record gets a CRLF section at +// the mid-file insertion point and keeps every surrounding byte. +func TestApplySectionEditsProposalInsertCRLF(t *testing.T) { + crlf := func(s string) string { return strings.ReplaceAll(s, "\n", "\r\n") } + want := "---\nid: 7\n---\n\n## Artifacts\n\nA\n\n## Why\n\nW\n\n## What changes\n\nC\n\n## Acceptance criteria\n\nAC\n\n## Out of scope\n\nO\n" + applyProposalEdits(t, crlf(proposalBase), crlf(want), replaceEdit("## Acceptance criteria", "AC\n")) +} + +// TestApplySectionEditsProposalIgnoresFencedHeading: a proposal heading inside +// a fenced code block is content, not a present section. +func TestApplySectionEditsProposalIgnoresFencedHeading(t *testing.T) { + src := "---\nid: 7\n---\n\n## Why\n\nW\n\n```text\n## What changes\n```\n\n## Out of scope\n\nO\n" + want := "---\nid: 7\n---\n\n## Why\n\nW\n\n```text\n## What changes\n```\n\n## Acceptance criteria\n\nAC\n\n## Out of scope\n\nO\n" + applyProposalEdits(t, src, want, replaceEdit("## Acceptance criteria", "AC\n")) +} + +// TestProposalHeadingsAreOwnedChangeHeadings: the proposal order is the five +// verbatim headings, and every one is an owned change heading. +func TestProposalHeadingsAreOwnedChangeHeadings(t *testing.T) { + want := []string{"## Why", "## What changes", "## Acceptance criteria", "## Out of scope", "## Open questions"} + if strings.Join(render.ProposalHeadings, "|") != strings.Join(want, "|") { + t.Fatalf("ProposalHeadings = %q, want %q", render.ProposalHeadings, want) + } + owned := make(map[string]bool, len(render.ChangeOwnedHeadings)) + for _, h := range render.ChangeOwnedHeadings { + owned[h] = true + } + for _, h := range render.ProposalHeadings { + if !owned[h] { + t.Errorf("proposal heading %q is not in ChangeOwnedHeadings", h) + } + } +} From 23549767a09eb965318345b17b1aab844407194a Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 13:42:23 -0500 Subject: [PATCH 3/7] feat(render): write optional acceptance criteria on a new change record --- internal/render/record.go | 12 +++++++-- internal/render/record_test.go | 45 ++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 2 deletions(-) diff --git a/internal/render/record.go b/internal/render/record.go index c7b2399ce..98acc2f45 100644 --- a/internal/render/record.go +++ b/internal/render/record.go @@ -34,7 +34,12 @@ type NewChangeRecord struct { Hold bool // true ⇒ hold: true; false ⇒ a valueless hold: Why string // markdown body, no heading line WhatChanges string // markdown body, no heading line - OutOfScope string // markdown body, no heading line + // AcceptanceCriteria is the optional acceptance criteria, a markdown body + // with no heading line; "" writes no section, otherwise + // "## Acceptance criteria" sits between "## What changes" and + // "## Out of scope". + AcceptanceCriteria string + OutOfScope string // markdown body, no heading line // WhyOnHold is the optional hold reason, a markdown body with no heading // line; "" writes no section, otherwise "## Why on hold" follows // "## Out of scope". @@ -78,8 +83,11 @@ func ChangeRecord(r NewChangeRecord) ([]byte, error) { section("## Artifacts", artifactsBlockBody), section("## Why", r.Why), section("## What changes", r.WhatChanges), - section("## Out of scope", r.OutOfScope), } + if r.AcceptanceCriteria != "" { + sections = append(sections, section("## Acceptance criteria", r.AcceptanceCriteria)) + } + sections = append(sections, section("## Out of scope", r.OutOfScope)) if r.WhyOnHold != "" { sections = append(sections, section("## Why on hold", r.WhyOnHold)) } diff --git a/internal/render/record_test.go b/internal/render/record_test.go index 409ec2a54..ac474586d 100644 --- a/internal/render/record_test.go +++ b/internal/render/record_test.go @@ -89,6 +89,51 @@ func TestChangeRecordHasNoTrivialKey(t *testing.T) { t.Fatalf("frontmatter never closed:\n%s", got) } +// TestChangeRecordAcceptanceCriteria proves the optional acceptance criteria +// land between "## What changes" and "## Out of scope", and that an empty +// value writes no section. +func TestChangeRecordAcceptanceCriteria(t *testing.T) { + base := func() render.NewChangeRecord { + return render.NewChangeRecord{ + ID: 1, Slug: "s", Title: "T", Type: "feat", Priority: "medium", Created: goldenDate, + Why: "w", WhatChanges: "c", OutOfScope: "oos", + } + } + render1 := func(r render.NewChangeRecord) []byte { + t.Helper() + got, err := render.ChangeRecord(r) + if err != nil { + t.Fatalf("ChangeRecord: %v", err) + } + if _, err := document.Parse(got); err != nil { + t.Fatalf("document.Parse: %v\n%s", err, got) + } + return got + } + + withAC := base() + withAC.AcceptanceCriteria = "- ac" + if got, want := string(render1(withAC)), "## What changes\n\nc\n\n## Acceptance criteria\n\n- ac\n\n## Out of scope\n\noos\n"; !strings.HasSuffix(got, want) { + t.Fatalf("criteria placement:\n%s", got) + } + + held := withAC + held.Hold, held.WhyOnHold = true, "h" + if got, want := string(render1(held)), "## Acceptance criteria\n\n- ac\n\n## Out of scope\n\noos\n\n## Why on hold\n\nh\n"; !strings.HasSuffix(got, want) { + t.Fatalf("criteria with hold:\n%s", got) + } + + without := render1(base()) + if bytes.Contains(without, []byte("## Acceptance criteria")) { + t.Fatalf("empty criteria wrote a section:\n%s", without) + } + explicitEmpty := base() + explicitEmpty.AcceptanceCriteria = "" + if !bytes.Equal(without, render1(explicitEmpty)) { + t.Fatal("empty criteria changed the rendered bytes") + } +} + // TestLearningRecordMatchesGolden pins the canonical learning shape. func TestLearningRecordMatchesGolden(t *testing.T) { got, err := render.LearningRecord(render.NewLearningRecord{ From f8e23fa75144a9d1531f534e921f9f39f2d209f3 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 13:44:13 -0500 Subject: [PATCH 4/7] feat(app): accept optional acceptance criteria on change.create --- internal/app/change_create.go | 50 ++++++++++- internal/app/change_create_test.go | 130 +++++++++++++++++++++++++++++ internal/app/finding_codes.go | 5 ++ internal/app/finding_codes_test.go | 2 + internal/app/schema_test.go | 5 +- 5 files changed, 188 insertions(+), 4 deletions(-) diff --git a/internal/app/change_create.go b/internal/app/change_create.go index 4d4bb0329..4f039e2f5 100644 --- a/internal/app/change_create.go +++ b/internal/app/change_create.go @@ -3,6 +3,7 @@ package app import ( "context" "encoding/json" + "errors" "fmt" "path" "sort" @@ -48,7 +49,10 @@ type ChangeCreateRequest struct { Why string `json:"why" docket:"required"` WhatChanges string `json:"what_changes" docket:"required"` - OutOfScope string `json:"out_of_scope" docket:"required"` + // AcceptanceCriteria is the optional "## Acceptance criteria" section body, + // written between What changes and Out of scope. Whitespace-only is absent. + AcceptanceCriteria string `json:"acceptance_criteria,omitempty"` + OutOfScope string `json:"out_of_scope" docket:"required"` DependsOn []int `json:"depends_on"` StackedOn *int `json:"stacked_on"` @@ -151,6 +155,9 @@ type changeCreatePayload struct { // older retry still replays. Hold bool `json:"hold,omitempty"` HoldReason string `json:"hold_reason,omitempty"` + // AcceptanceCriteria is omitempty and blank-normalized so a request without + // it digests exactly as before the field existed and an older retry replays. + AcceptanceCriteria string `json:"acceptance_criteria,omitempty"` } func changeCreateSemanticPayload(req ChangeCreateRequest) changeCreatePayload { @@ -171,7 +178,35 @@ func changeCreateSemanticPayload(req ChangeCreateRequest) changeCreatePayload { Deliverable: normalizedDeliverable(req), Hold: requestHeld(req), HoldReason: req.HoldReason, + + AcceptanceCriteria: normalizedAcceptanceCriteria(req), + } +} + +// normalizedAcceptanceCriteria is the stored, digested spelling of the +// request's acceptance criteria: whitespace-only digests and renders as absent. +func normalizedAcceptanceCriteria(req ChangeCreateRequest) string { + if strings.TrimSpace(req.AcceptanceCriteria) == "" { + return "" + } + return req.AcceptanceCriteria +} + +// acceptanceCriteriaHeading is the section an acceptance_criteria body becomes. +const acceptanceCriteriaHeading = "## Acceptance criteria" + +// acceptanceCriteriaProblem returns why a non-blank acceptance_criteria body is +// unusable as the "## Acceptance criteria" section, or "" when it is usable. +// The message never echoes the body. +func acceptanceCriteriaProblem(body string) string { + err := render.ValidateSectionBody([]byte(body)) + if err == nil { + return "" + } + if errors.Is(err, render.ErrSectionBodyUnterminatedFence) { + return "acceptance_criteria leaves a code fence unterminated; close the fence so the sections after \"" + acceptanceCriteriaHeading + "\" stay visible" } + return "acceptance_criteria carries a column-zero \"## \" heading outside fenced code; the operation owns the \"" + acceptanceCriteriaHeading + "\" heading — author body text, lists, or \"###\"-or-deeper subsections, and put heading examples inside closed code fences" } // requestHeld reports whether the request creates the change already on hold. @@ -378,6 +413,13 @@ func validateChangeCreateShape(req ChangeCreateRequest) []StatusFinding { } } boundAuthored(&findings, "hold_reason", req.HoldReason) + // acceptance_criteria becomes the "## Acceptance criteria" body; blank is absent. + if normalizedAcceptanceCriteria(req) != "" { + if msg := acceptanceCriteriaProblem(req.AcceptanceCriteria); msg != "" { + addShape(FCInvalidAcceptanceCriteria, msg) + } + } + boundAuthored(&findings, "acceptance_criteria", req.AcceptanceCriteria) return findings } @@ -588,8 +630,10 @@ func (o changeCreateOp) Plan(ctx context.Context, st transaction.AttemptState) ( Why: o.req.Why, WhatChanges: o.req.WhatChanges, OutOfScope: o.req.OutOfScope, - Hold: requestHeld(o.req), - WhyOnHold: o.req.HoldReason, + + AcceptanceCriteria: normalizedAcceptanceCriteria(o.req), + Hold: requestHeld(o.req), + WhyOnHold: o.req.HoldReason, }) if err != nil { return transaction.MutationPlan{}, transaction.OperationResult{}, fmt.Errorf("change create: serializing record: %w", err) diff --git a/internal/app/change_create_test.go b/internal/app/change_create_test.go index 66cddecac..d4b772100 100644 --- a/internal/app/change_create_test.go +++ b/internal/app/change_create_test.go @@ -914,3 +914,133 @@ func TestChangeCreateDigestUnchangedWithoutHold(t *testing.T) { t.Error("a hold_reason must change the digest") } } + +// TestChangeCreateAcceptanceCriteria: a non-blank acceptance_criteria writes the +// "## Acceptance criteria" section between What changes and Out of scope; a +// blank or omitted one writes no section. +func TestChangeCreateAcceptanceCriteria(t *testing.T) { + recPath := "docs/changes/active/0002-add-a-widget.md" + fenced := "### Core\n\n- a\n\n```md\n## Example\n```\n" + cases := []struct { + name string + criteria string + wantSection bool + wantText string + }{ + {"present", "- It works.\n", true, "## What changes\n\nAdds the widget.\n\n## Acceptance criteria\n\n- It works.\n\n## Out of scope\n"}, + {"blank", " \n\t ", false, ""}, + {"omitted", "", false, ""}, + {"subsection and fenced heading", fenced, true, "\n## Acceptance criteria\n\n" + fenced + "\n## Out of scope\n"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + op := baseOp([]string{}) + op.req.AcceptanceCriteria = c.criteria + plan, opRes := planFor(t, map[string]string{ + "docs/changes/active/0001-first.md": fixtureChange(1, "first"), + }, op) + if opRes.Refused { + t.Fatalf("unexpected refusal: %v", opRes.Findings) + } + rec := string(groomedRecordBytes(t, plan, recPath)) + if got := strings.Count(rec, "\n## Acceptance criteria\n"); got != map[bool]int{true: 1, false: 0}[c.wantSection] { + t.Errorf("acceptance criteria headings = %d, want present=%v:\n%s", got, c.wantSection, rec) + } + if c.wantText != "" && !strings.Contains(rec, c.wantText) { + t.Errorf("record missing %q:\n%s", c.wantText, rec) + } + }) + } +} + +// TestChangeCreateAcceptanceCriteriaRefusals: an unusable acceptance_criteria +// is refused before any engine call. +func TestChangeCreateAcceptanceCriteriaRefusals(t *testing.T) { + cases := []struct { + name string + criteria string + code string + }{ + {"column-zero heading", "text\n## Heading\n", "invalid-acceptance_criteria"}, + {"unterminated fence", "text\n```\ncode\n", "invalid-acceptance_criteria"}, + {"too large", strings.Repeat("a", maxAuthoredMarkdownBytes+1), string(FCAuthoredInputTooLarge)}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + req := validChangeCreateRequest() + req.AcceptanceCriteria = c.criteria + engine := &recordingEngine{} + reader := &fakeChangeReader{pin: mainModePin([]string{"inline"})} + deps := PlanningDeps{Engine: engine, Reader: reader, Clock: testClock()} + + res := ChangeCreate(context.Background(), deps, "", req) + + if res.Result != ResultInvalidInput { + t.Fatalf("result = %q, want invalid-input", res.Result) + } + if len(engine.calls) != 0 { + t.Errorf("engine called %d times on a refused acceptance_criteria, want 0", len(engine.calls)) + } + if !hasFindingCode(res.Findings, c.code) { + t.Errorf("missing finding %q; got %v", c.code, res.Findings) + } + }) + } +} + +// TestChangeCreateDigestUnchangedWithoutAcceptanceCriteria: a request without +// acceptance_criteria, or with a blank one, digests exactly as the payload did +// before the field existed, so an older retry still replays. +func TestChangeCreateDigestUnchangedWithoutAcceptanceCriteria(t *testing.T) { + // legacyPayload is changeCreatePayload as it stood before acceptance_criteria. + type legacyPayload struct { + Title string `json:"title"` + Type string `json:"type"` + Priority string `json:"priority"` + Why string `json:"why"` + WhatChanges string `json:"what_changes"` + OutOfScope string `json:"out_of_scope"` + DependsOn []int `json:"depends_on"` + StackedOn *int `json:"stacked_on"` + Related []int `json:"related"` + DiscoveredFrom []int `json:"discovered_from"` + ADRs []int `json:"adrs"` + AutoGroomable *bool `json:"auto_groomable,omitempty"` + BranchPrefix string `json:"branch_prefix,omitempty"` + Deliverable string `json:"deliverable,omitempty"` + Hold bool `json:"hold,omitempty"` + HoldReason string `json:"hold_reason,omitempty"` + } + req := validChangeCreateRequest() + req.Hold = boolPtr(true) + req.HoldReason = "Needs a sign-in." + legacy := legacyPayload{ + Title: req.Title, Type: req.Type, Priority: req.Priority, + Why: req.Why, WhatChanges: req.WhatChanges, OutOfScope: req.OutOfScope, + Hold: true, HoldReason: req.HoldReason, + } + want, err := canonicalDigest(OperationChangeCreate, legacy) + if err != nil { + t.Fatalf("canonicalDigest: %v", err) + } + for _, criteria := range []string{"", " \n\t "} { + r := req + r.AcceptanceCriteria = criteria + got, err := canonicalDigest(OperationChangeCreate, changeCreateSemanticPayload(r)) + if err != nil { + t.Fatalf("canonicalDigest: %v", err) + } + if got != want { + t.Errorf("acceptance_criteria %q digests %s, want the pre-field %s", criteria, got, want) + } + } + withCriteria := req + withCriteria.AcceptanceCriteria = "- x" + got, err := canonicalDigest(OperationChangeCreate, changeCreateSemanticPayload(withCriteria)) + if err != nil { + t.Fatalf("canonicalDigest: %v", err) + } + if got == want { + t.Error("a non-blank acceptance_criteria must change the digest") + } +} diff --git a/internal/app/finding_codes.go b/internal/app/finding_codes.go index cba32b101..5e9e88e54 100644 --- a/internal/app/finding_codes.go +++ b/internal/app/finding_codes.go @@ -175,6 +175,10 @@ const ( FCHoldReasonWithoutHold FindingCode = "hold-reason-without-hold" FCInvalidHoldReason FindingCode = "invalid-hold_reason" + // FCInvalidAcceptanceCriteria: change.create's acceptance_criteria is not + // usable as the "## Acceptance criteria" section body. + FCInvalidAcceptanceCriteria FindingCode = "invalid-acceptance_criteria" + // Install-maintenance findings. collection-pending is the reason an explicit // `install collect` reports and the warning code an automatic post-install // collection surfaces when a version tree could not be reclaimed; the primary @@ -297,6 +301,7 @@ var AllFindingCodes = []FindingCode{ FindingCode("illegal-source-status"), FindingCode(ReasonStatusInternalError), FindingCode(ReasonStatusInterrupted), + FCInvalidAcceptanceCriteria, FCInvalidADRs, FCInvalidAttempt, FCInvalidBlockedNote, diff --git a/internal/app/finding_codes_test.go b/internal/app/finding_codes_test.go index 1b5fab76c..d11b1b98d 100644 --- a/internal/app/finding_codes_test.go +++ b/internal/app/finding_codes_test.go @@ -225,6 +225,7 @@ func TestShapeValidatorCodesAreRegistered(t *testing.T) { emitted = append(emitted, validateChangeCreateShape(ChangeCreateRequest{StackedOn: &zero})...) emitted = append(emitted, validateChangeCreateShape(ChangeCreateRequest{BranchPrefix: "a/b"})...) emitted = append(emitted, validateChangeCreateShape(ChangeCreateRequest{Title: "a\nb"})...) + emitted = append(emitted, validateChangeCreateShape(ChangeCreateRequest{AcceptanceCriteria: "x\n## H\n"})...) emitted = append(emitted, validateADRRecordShape(adrContent)...) emitted = append(emitted, validateADRReplaceShape(ADRReplaceRequest{Target: ADRTarget{ID: 0}, Successor: adrContent})...) emitted = append(emitted, validateLearningRecordShape(LearningRecordRequest{Topics: []string{""}})...) @@ -272,6 +273,7 @@ func TestShapeValidatorCodesAreRegistered(t *testing.T) { FCEmptyBlockedNote, FCInvalidBlockedNote, FCInvalidSections, FCInvalidPRNumber, FCInvalidAttempt, FCEmptyHead, FCInvalidPriority, FCUnknownPriority, FCInvalidHold, FCHoldReasonWithoutHold, FCInvalidHoldReason, + FCInvalidAcceptanceCriteria, } for _, c := range floor { if !seen[string(c)] { diff --git a/internal/app/schema_test.go b/internal/app/schema_test.go index 2c027488e..d1b6ef31e 100644 --- a/internal/app/schema_test.go +++ b/internal/app/schema_test.go @@ -156,7 +156,7 @@ func TestReflectDescriptorChangeCreateRequest(t *testing.T) { keys := descriptorKeys(d) want := []string{ "request_id", "title", "type", "priority", "deliverable", - "why", "what_changes", "out_of_scope", + "why", "what_changes", "acceptance_criteria", "out_of_scope", "depends_on", "stacked_on", "related", "discovered_from", "adrs", "auto_groomable", "branch_prefix", "hold", "hold_reason", } @@ -190,6 +190,9 @@ func TestReflectDescriptorChangeCreateRequest(t *testing.T) { if f := fieldByKey(t, d, "hold_reason"); f.Required || f.Repeated || f.Type != "string" { t.Errorf("hold_reason = %+v, want optional string", f) } + if f := fieldByKey(t, d, "acceptance_criteria"); f.Required || f.Repeated || f.Type != "string" { + t.Errorf("acceptance_criteria = %+v, want optional non-repeated string", f) + } // Required set per Task 4's tags. wantRequired := map[string]bool{ From 466caafb642c1284be21c730226c7c9433bd60bd Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 13:45:30 -0500 Subject: [PATCH 5/7] refactor(export): rename the change export kind to ticket and keep acceptance criteria --- internal/app/open_export.go | 2 +- internal/app/open_export_test.go | 6 +-- internal/export/corpus_test.go | 18 +++---- internal/export/export.go | 31 ++++++------ internal/export/export_test.go | 48 +++++++++++++++---- internal/export/filename.go | 4 +- internal/export/filename_test.go | 6 +-- internal/export/testdata/corpus/PROVENANCE.md | 5 +- 8 files changed, 75 insertions(+), 45 deletions(-) diff --git a/internal/app/open_export.go b/internal/app/open_export.go index 84f8ff7bd..eae1dce45 100644 --- a/internal/app/open_export.go +++ b/internal/app/open_export.go @@ -96,7 +96,7 @@ func (r OpenResult) HumanWarnings() []string { // 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, + "change": export.KindTicket, "spec": export.KindSpec, "plan": export.KindPlan, "results": export.KindResults, } // openExport reads rel from the local metadata checkout (whatever the diff --git a/internal/app/open_export_test.go b/internal/app/open_export_test.go index 22628e028..59f3804f9 100644 --- a/internal/app/open_export_test.go +++ b/internal/app/open_export_test.go @@ -275,18 +275,18 @@ func TestOpenExportRefusesProtectedDestination(t *testing.T) { } } -func TestOpenExportIssueNameAndH1(t *testing.T) { +func TestOpenExportTicketNameAndH1(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") + want := filepath.Join(out, "2026-01-02-ticket-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) + t.Errorf("ticket = %q, want %q", got, w) } } diff --git a/internal/export/corpus_test.go b/internal/export/corpus_test.go index e3782218d..5eb07fbbe 100644 --- a/internal/export/corpus_test.go +++ b/internal/export/corpus_test.go @@ -23,7 +23,7 @@ const corpusDir = "testdata/corpus" // corpusKinds maps a corpus folder to the kind its files export as. var corpusKinds = map[string]Kind{ - "changes": KindIssue, + "changes": KindTicket, "specs": KindSpec, "plans": KindPlan, "results": KindResults, @@ -56,7 +56,7 @@ func loadCorpus(t *testing.T) []corpusFile { t.Fatal(err) } in := Input{Kind: kind, Source: src, Titles: titles} - if kind == KindIssue { + if kind == KindTicket { 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}) @@ -210,7 +210,7 @@ var ( // converted title, or a "groomed " 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} + ticketH2 = map[string]bool{"## Why": true, "## What changes": true, "## Acceptance criteria": 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. @@ -292,8 +292,8 @@ func corpusProblems(kind Kind, src, out []byte, titles Titles) []string { } 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 == KindTicket && !ticketH2[strings.TrimRight(l.text, " \t")] { + add("line %d: ticket keeps a non-allowlisted section: %q", n, l.text) } } if kind == KindSpec && !seenH2 && (testStampRE.MatchString(l.text) || strings.Contains(l.plain, "**Change:**")) { @@ -347,11 +347,11 @@ func codeRegions(lines []mdLine) []string { } // 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 +// frontmatter or a marker-delimited generated block, and for a ticket only the // allowlisted sections. func exportScope(kind Kind, src []byte) []mdLine { var scope []mdLine - inBlock, keepSection := "", kind != KindIssue + inBlock, keepSection := "", kind != KindTicket for _, l := range readLines(src) { switch { case l.kind == document.LineFrontmatter: @@ -367,8 +367,8 @@ func exportScope(kind Kind, src []byte) []mdLine { case inBlock != "": continue } - if kind == KindIssue && l.heading == 2 { - keepSection = issueH2[strings.TrimRight(l.text, " \t")] + if kind == KindTicket && l.heading == 2 { + keepSection = ticketH2[strings.TrimRight(l.text, " \t")] } if keepSection { scope = append(scope, l) diff --git a/internal/export/export.go b/internal/export/export.go index 0067861af..f1a3d1e7d 100644 --- a/internal/export/export.go +++ b/internal/export/export.go @@ -11,7 +11,7 @@ import ( type Kind string const ( - KindIssue Kind = "issue" + KindTicket Kind = "ticket" KindSpec Kind = "spec" KindPlan Kind = "plan" KindResults Kind = "results" @@ -21,7 +21,7 @@ const ( type Input struct { Kind Kind Source []byte // the artifact bytes from the metadata checkout - Title string // the change's raw title (the issue H1) + Title string // the change's raw title (the ticket H1) Titles Titles } @@ -45,21 +45,22 @@ type step int const ( stepFrontmatter step = iota + 1 stepBlocks - stepIssueSections + stepTicketSections stepStamps stepLinks stepRefs stepCleanup ) -var allSteps = []step{stepFrontmatter, stepBlocks, stepIssueSections, stepStamps, stepLinks, stepRefs, stepCleanup} +var allSteps = []step{stepFrontmatter, stepBlocks, stepTicketSections, 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, +// ticketSections is the allowlist of H2 sections a change record keeps. +var ticketSections = map[string]bool{ + "Why": true, + "What changes": true, + "Acceptance criteria": true, + "Out of scope": true, + "Open questions": true, } // line is one physical line moving through the pipeline. @@ -88,8 +89,8 @@ func transform(in Input, skip map[step]bool) Output { 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 == KindTicket && !skip[stepTicketSections] { + lines = keepTicketSections(lines, cleanTitle(in.Title, in.Titles)) } if in.Kind == KindSpec && !skip[stepStamps] { lines = removeStamps(lines) @@ -177,14 +178,14 @@ func blockEnd(lines []line, i int) int { func isH2(l line) bool { return !l.fenced() && strings.HasPrefix(l.text, "## ") } -// keepIssueSections is step 3: only the allowlisted H2 sections stay, in source +// keepTicketSections 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 { +func keepTicketSections(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("## "):])] + keep = ticketSections[strings.TrimSpace(l.text[len("## "):])] } if keep { out = append(out, l) diff --git a/internal/export/export_test.go b/internal/export/export_test.go index 232b44f2b..4a77bdeec 100644 --- a/internal/export/export_test.go +++ b/internal/export/export_test.go @@ -122,7 +122,7 @@ func TestTransformSpecStampOnlyBeforeFirstH2(t *testing.T) { assertMarkdown(t, got, "# T\n\n\"Twelve\".\n") } -const issueFixture = "---\n" + +const ticketFixture = "---\n" + "id: 7\n" + "title: Seven\n" + "---\n" + @@ -143,6 +143,10 @@ const issueFixture = "---\n" + "\n" + "Things.\n" + "\n" + + "## Acceptance criteria\n" + + "\n" + + "- Works.\n" + + "\n" + "## Reconcile log\n" + "\n" + "- log\n" + @@ -155,7 +159,7 @@ const issueFixture = "---\n" + "\n" + "None.\n" -const issueWant = "# Seven\n" + +const ticketWant = "# Seven\n" + "\n" + "## Why\n" + "\n" + @@ -165,29 +169,53 @@ const issueWant = "# Seven\n" + "\n" + "Things.\n" + "\n" + + "## Acceptance criteria\n" + + "\n" + + "- Works.\n" + + "\n" + "## Out of scope\n" + "\n" + "None.\n" -func TestTransformIssue(t *testing.T) { +func TestTransformTicket(t *testing.T) { got := Transform(Input{ - Kind: KindIssue, - Source: []byte(issueFixture), + Kind: KindTicket, + Source: []byte(ticketFixture), Title: "Seven (0008)", Titles: Titles{8: "Eight"}, }) - assertMarkdown(t, got, issueWant) + assertMarkdown(t, got, ticketWant) +} + +// TestTransformTicketWithoutAcceptanceCriteria pins that a change record with no +// "## Acceptance criteria" section exports the same sections it always did. +func TestTransformTicketWithoutAcceptanceCriteria(t *testing.T) { + src := strings.Replace(ticketFixture, "## Acceptance criteria\n\n- Works.\n\n", "", 1) + if src == ticketFixture { + t.Fatal("fixture no longer holds the acceptance criteria section") + } + want := strings.Replace(ticketWant, "## Acceptance criteria\n\n- Works.\n\n", "", 1) + got := Transform(Input{ + Kind: KindTicket, + Source: []byte(src), + Title: "Seven (0008)", + Titles: Titles{8: "Eight"}, + }) + assertMarkdown(t, got, want) + if strings.Contains(string(got.Markdown), "Acceptance criteria") { + t.Fatalf("criteria-less export grew a criteria section: %q", got.Markdown) + } } func TestTransformNormalizesCRLF(t *testing.T) { - crlf := strings.ReplaceAll(issueFixture, "\n", "\r\n") + crlf := strings.ReplaceAll(ticketFixture, "\n", "\r\n") got := Transform(Input{ - Kind: KindIssue, + Kind: KindTicket, Source: []byte(crlf), Title: "Seven (0008)", Titles: Titles{8: "Eight"}, }) - assertMarkdown(t, got, issueWant) + assertMarkdown(t, got, ticketWant) if strings.Contains(string(got.Markdown), "\r") { t.Fatalf("output still holds a carriage return: %q", got.Markdown) } @@ -249,7 +277,7 @@ func TestTransformFenceHeadingsAreContent(t *testing.T) { "\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"}}) + got := Transform(Input{Kind: KindTicket, Source: []byte(src), Title: "T", Titles: Titles{559: "Z"}}) assertMarkdown(t, got, "# T\n\n## Why\n\n"+fence+"\nMore.\n") } diff --git a/internal/export/filename.go b/internal/export/filename.go index 8defe6827..4a4171c62 100644 --- a/internal/export/filename.go +++ b/internal/export/filename.go @@ -11,7 +11,7 @@ var leadingDateRE = regexp.MustCompile(`^(\d{4}-\d{2}-\d{2})-(.+)$`) // FileName returns the exported file's name, --.md. // -// For a change record (KindIssue) the date is created and the name is slug. For a +// For a change record (KindTicket) 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 @@ -20,7 +20,7 @@ var leadingDateRE = regexp.MustCompile(`^(\d{4}-\d{2}-\d{2})-(.+)$`) // the type word. func FileName(kind Kind, sourcePath, created, slug string) string { date, name := created, slug - if kind != KindIssue { + if kind != KindTicket { base := filepath.Base(sourcePath) name = strings.TrimSuffix(base, filepath.Ext(base)) if m := leadingDateRE.FindStringSubmatch(name); m != nil { diff --git a/internal/export/filename_test.go b/internal/export/filename_test.go index 1fddd03da..5e7b39d5f 100644 --- a/internal/export/filename_test.go +++ b/internal/export/filename_test.go @@ -14,12 +14,12 @@ func TestFileName(t *testing.T) { "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"}, + {KindTicket, "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-ticket-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"}, + {KindTicket, "docs/changes/active/0559-x.md", "", "x", "ticket-x.md"}, } for _, tc := range cases { if got := FileName(tc.kind, tc.source, tc.created, tc.s); got != tc.want { diff --git a/internal/export/testdata/corpus/PROVENANCE.md b/internal/export/testdata/corpus/PROVENANCE.md index 1d391ed33..d1d2a129c 100644 --- a/internal/export/testdata/corpus/PROVENANCE.md +++ b/internal/export/testdata/corpus/PROVENANCE.md @@ -5,7 +5,7 @@ Frozen inputs for `corpus_test.go`. Every file under `changes/`, `specs/`, `plan `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/` +The folder sets the export kind: `changes/` exports as a ticket, `specs/` as a spec, `plans/` and `constructed/` as a plan, `results/` as results. ## titles.tsv @@ -35,7 +35,7 @@ that record's frontmatter `title:` on the same commit. No id is claimed by two r | `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. | +| `constructed/frontmatter.md` | hand-built | A non-ticket artifact with leading frontmatter. No spec, plan, or results file on the metadata branch has one, and a ticket'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 @@ -50,3 +50,4 @@ Checked by scanning every corpus file outside fences and code spans: | Damaged markers and an unclosed frontmatter opener | `TestTransformDamagedSourceKeepsContent` | | CRLF line endings | `TestTransformNormalizesCRLF` | | An id two records claim | the app-layer export tests | +| A `## Acceptance criteria` section | `TestTransformTicket` | From e0640ef293ccdc994ea0a1b93eb92f5fb6be4de5 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 13:46:22 -0500 Subject: [PATCH 6/7] docs: document the acceptance criteria section and proposal order --- internal/assets/embedded/manifest.json | 10 +++++----- .../embedded/tree/skills/docket-convention/SKILL.md | 5 ++++- .../embedded/tree/skills/docket-new-change/SKILL.md | 2 +- internal/repoguard/budgets_test.go | 4 ++-- skills/docket-convention/SKILL.md | 5 ++++- skills/docket-new-change/SKILL.md | 2 +- 6 files changed, 17 insertions(+), 11 deletions(-) diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index f8df0551b..5a34c6caa 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,7 +1,7 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:ed92c875853423025ab9e290850a0a559ce537417838caf8b3ebd718aa90d88e", + "asset_set_id": "sha256:65fed69e738a8fab40f222d7c34d6593082cda5d07b07ea8d6d715a751f306c6", "entries": [ { "path": ".docket.example.yml", @@ -322,8 +322,8 @@ "path": "skills/docket-convention/SKILL.md", "role": "skill", "mode": 420, - "size": 52586, - "sha256": "ba1892e869dff673e1f4e4248032213830d9a19fb57613cef33a3a1e9d2010f2" + "size": 53141, + "sha256": "e8e6a32628f729415a866a90406865427b5449aea7da28e1bb2cd48cefb8c23b" }, { "path": "skills/docket-convention/references/agent-layer.md", @@ -420,8 +420,8 @@ "path": "skills/docket-new-change/SKILL.md", "role": "skill", "mode": 420, - "size": 10669, - "sha256": "f95cab6bec123d39473d206be294f1d667a89bcb442a5f7beccaedb38db4757d" + "size": 10780, + "sha256": "ffc4f0d640b5399884987aa66fabe1ee36fbe05f81ec42c8e6b9005c47177842" }, { "path": "skills/docket-review/SKILL.md", diff --git a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md index abe793e4f..ef17a3634 100644 --- a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md @@ -209,11 +209,12 @@ change, never in the frozen artifact. ### Change body sections -`change.create` writes `## Artifacts`, `## Why`, `## What changes`, and `## Out of scope`; `## Open questions` and every later section are added by later operations. +`change.create` writes `## Artifacts`, `## Why`, `## What changes`, `## Out of scope`, and — when given — `## Acceptance criteria`; `## Open questions` and every later section are added by later operations. - `## Artifacts` — **first body section** (immediately after the frontmatter closing `---`, above `## Why`). Marker-bounded (`` / ``); rendered from frontmatter by the Go app-layer link-block renderer inside the owning metadata transaction; **never hand-edited** — the renderer is the sole writer. Seeded empty by `change.create`; regenerated after every frontmatter field write. Its **reciprocal** is the `docket:backlink` block (markers `` / ``) stamped at the TOP of each artifact (spec, plan, results, PR body) pointing home to the change on the metadata branch, from one shared renderer. Same-branch links (rows and file backlinks) are relative; the PR body's are absolute. `change.attach-plan`, `change.attach-results`, and `change.groom` write the file blocks, `pr.publish` the PR body's, which `finalize.closeout` (retried by `finalize.cleanup`, `maintenance.sweep`) or `repository.repair` with `--pr-backlinks` repoints at the archived record (ADRs excluded, back-referenced by `change:`). - `## Why` — the motivation, as detailed as warranted (no length limit). - `## What changes` — scope of the work. +- `## Acceptance criteria` — optional; verifiable conditions that belong to this change. Written by `change.create` (between What changes and Out of scope) when given; a later owned-section edit that adds it places it in proposal order. Never a build gate. - `## Out of scope` — explicit non-goals. - `## Open questions` — unknowns to resolve during reconcile/design. - `## Reconcile log` — dated entries appended by the implementer's reconcile pass. @@ -225,6 +226,8 @@ change, never in the frozen artifact. - `## Why deferred` / `## Why killed` — added when entering those states. - `## Why on hold` — the optional hold reason, written only by the `hold_reason` key; lifting the hold removes it. +The proposal sections keep the order `## Why`, `## What changes`, `## Acceptance criteria`, `## Out of scope`, `## Open questions` — an edit that adds one places it in that order; every other section added later is appended at the end of the file. + The change body is a **PM-altitude proposal** (intent + scope). Detailed design lives in the linked superpowers spec; the task breakdown in the linked superpowers plan. Different zoom levels, no duplication. ### ADR file (`/-.md`) diff --git a/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md b/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md index 948c2df05..c3b6501ec 100644 --- a/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md @@ -29,7 +29,7 @@ The default path for a new change. Five steps: 3. **Scan related context** — scan neighbouring changes (`active/` + recent `archive/`) and the ADR index to pre-fill `related`, `depends_on`, `adrs`, and — when the human names the change(s) whose work surfaced this one (or scan mode infers an origin) — `discovered_from` (informational, like `related:`; empty for deliberately planned work). In practice, do this quick read just *before* step 2 so the brainstorm is informed by neighbouring work; record the resulting `related`/`depends_on`/`adrs`/`discovered_from` after the design settles. -4. **Create the proposed change** — submit the record through one atomic transaction: the `change.create` operation (resolve argv from the capability catalog) with `--repo-dir --request `. Its closed JSON request carries `title`, `type` (one configured `change_type` — `create` refuses an unknown or empty type, so no created change is ever left `untyped`, and there is no template comment to replace), `priority` (default `medium`), `deliverable: results-artifact` when the work ends in findings, not code (omit it for the default `pr`), the PM-altitude `why`/`what_changes`/`out_of_scope` body distilled from the brainstorm (design detail lives in the linked spec, NOT here), the resolved `depends_on`/`related`/`adrs`/`discovered_from` from step 3, `stacked_on` when the work builds on another change's **unmerged** branch (set it and **read [stacked-changes.md](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how it is built, merged, and closed out), and the stable `request_id` from step 1. The transaction allocates the id, derives the slug, serializes the canonical `status: proposed` record (`created`/`updated` = the commit's UTC date), renders its `## Artifacts` block, and re-renders the inline board — one metadata commit under an exact-lease push, returning the new `id`/`slug`/`path`. +4. **Create the proposed change** — submit the record through one atomic transaction: the `change.create` operation (resolve argv from the capability catalog) with `--repo-dir --request `. Its closed JSON request carries `title`, `type` (one configured `change_type` — `create` refuses an unknown or empty type, so no created change is ever left `untyped`, and there is no template comment to replace), `priority` (default `medium`), `deliverable: results-artifact` when the work ends in findings, not code (omit it for the default `pr`), the PM-altitude `why`/`what_changes`/`out_of_scope` body distilled from the brainstorm, plus an optional `acceptance_criteria` body when the brainstorm settled verifiable conditions for this change (design detail lives in the linked spec, NOT here), the resolved `depends_on`/`related`/`adrs`/`discovered_from` from step 3, `stacked_on` when the work builds on another change's **unmerged** branch (set it and **read [stacked-changes.md](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how it is built, merged, and closed out), and the stable `request_id` from step 1. The transaction allocates the id, derives the slug, serializes the canonical `status: proposed` record (`created`/`updated` = the commit's UTC date), renders its `## Artifacts` block, and re-renders the inline board — one metadata commit under an exact-lease push, returning the new `id`/`slug`/`path`. **Two draft-time scalars ride in the same request** — `auto_groomable` and `branch_prefix`. When the human says the change may be designed without them, send `auto_groomable: true` (so `docket-auto-groom` carries it to build-ready; `false` opts it out). When they name a branch prefix ("use the `hotfix/` prefix"), send it as typed in `branch_prefix` — the operation normalizes it and refuses an unusable value with `invalid-branch_prefix` before anything is written: show the human that finding and ask for a new value. Omit `auto_groomable` to leave the change not auto-groomable; omit `branch_prefix` to use ``. When the design needs a step a person must carry out, suggest a hold; if the human agrees, send `hold: true` (and an optional `hold_reason`) here for a captured stub, or in the step-5 `change.groom` request. diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 554ad1ed7..e0bee6c74 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -199,7 +199,7 @@ var skillBudgets = []skillBudget{ {"docket-build/references/gate-driver.md", 138, 1552}, // 0502 review: the raw-verb section names finalize's repaired-head re-gate (137/1546 -> 138/1552); 0502: "loop" means /loop only (137/1550 -> 137/1546); 0502: finalize's repaired-head re-gate is a direct caller (136/1523 -> 137/1550); 0502: the gate-execution intro reference is deleted (138/1555 -> 136/1523); 0502: renamed from gate-caller-loop.md; 0497: +halted-gate tree-survives finding relay (134/1510 -> 138/1555); 0491: the run id is retired (134/1513 -> 134/1510); 0490: the admission section describes the supervisor-held worktree lock; launch-unconfirmed is no longer a refusal (136/1511 -> 134/1513); 0488 review fix: finalize reaches the driver only through finalize.rebase; task-era handoff clauses dropped (word ceiling 1504 -> 1511); 0488 review: start row carries --change-id (word ceiling 1491 -> 1504); 0488: worker-scope/takeover/acknowledge rows and the parent-takeover section removed; callers are the full-suite gates (175/1872 -> 136/1491); 0467: +prepare-scope --run-id and scope-inherited start run id (word ceiling 1826 -> 1872); 0375: +worktree-admission section (word ceiling 1750 -> 1826) {"docket-build/references/task-routing.md", 50, 500}, {"docket-build-task/SKILL.md", 173, 1695}, // 0532: the private-repository writing rule and visibility hand-off (168/1640 -> 173/1695); 0531: the metadata worktree and remote come from the repository.prepare context (168/1637 -> 168/1640); 0488: scoped drive protocol replaced by direct foreground tests under timeout; three outcomes (211/2235 -> 168/1637); 0467 review fix: +the repair re-run run-id exception (206/2183 -> 211/2235); 0467: +the run id rides on the scope, never the bundle (204/2151 -> 206/2183); 0459: +post-handoff continuation never acknowledges or reuses the transferred scope (188/1964 -> 204/2151); 0405: sequential-drive receipt and acknowledgement; 0420: shell-safe capture; 0375: worktree-busy-not-a-retry rule (179/1842 -> 188/1964) - {"docket-convention/SKILL.md", 353, 7259}, // 0578: docket-export joins the inline skills (353/7257 -> 353/7259); 0575: reclaim and the claim lease are retired (361/7377 -> 353/7257); 0360: claimed_at is stamped by claim, reconcile, and resume-halted; a halt no longer claims a refreshed lease (361/7381 -> 361/7377); 0573: trivial retired (362/7411 -> 361/7381); 0560: the hold manifest field, its selection rule, the ## Why on hold section, and the auto-groomer's hold write (360/7331 -> 362/7411); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) + {"docket-convention/SKILL.md", 356, 7352}, // acceptance criteria section and proposal order (353/7259 -> 356/7352); 0578: docket-export joins the inline skills (353/7257 -> 353/7259); 0575: reclaim and the claim lease are retired (361/7377 -> 353/7257); 0360: claimed_at is stamped by claim, reconcile, and resume-halted; a halt no longer claims a refreshed lease (361/7381 -> 361/7377); 0573: trivial retired (362/7411 -> 361/7381); 0560: the hold manifest field, its selection rule, the ## Why on hold section, and the auto-groomer's hold write (360/7331 -> 362/7411); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) // 0154: docket-convention/github-board-mirror.md removed — the GitHub mirror is // retired (unsupported, mutation-blocking); its budget row is deleted with it. {"docket-convention/references/agent-layer.md", 214, 1991}, // 0578: docket-export joins the inline skills (214/1989 -> 214/1991); 0552: the user-level settings.json also carries the finalize allow rules (212/1951 -> 214/1990); 0546: the per-agent cache_ttl pin, its shipped 1h default, and the machine-wide controls docket leaves unset (168/1593 -> 212/1951); 0538: init and repository.configure-harnesses set agent_harnesses; repository.check reports harnesses-unset (164/1553 -> 168/1593); 0535: a private repository's instructions file and its user-level triggers (148/1419 -> 164/1553); 0502: rewritten around user-level wrappers and global-only pins (202/2346 -> 148/1419); 0502: the legacy agents-file migration clause is deleted (202/2349 -> 202/2346) @@ -216,7 +216,7 @@ var skillBudgets = []skillBudget{ {"docket-implement-next/references/results-artifact.md", 76, 737}, // 0360: no claim refreshes; change.complete pins a locally looked-up revision (79/765 -> 76/737); 0573: trivial retired (79/775 -> 79/765); 0559: new — the results-artifact ending (no plan, build, or PR; review, complete, clean up) {"docket-implement-next/results-template.md", 70, 543}, // 0573: trivial retired (70/545 -> 70/543); 0502 rebase onto 0510: carried the backlog verdict and next action in the Known issues placeholder (68/506 -> 70/545); 0502: inline review replaces the custom review skill (68/511 -> 68/510); 0498: +whole-branch review summary line in Verification performed (64/446 -> 68/511); 0440: reader-first template — action statement + merged Known issues (see note above); 0502: drop change citations and Go v1 narration (68/510 -> 68/506) {"docket-review/SKILL.md", 127, 1054}, // 0573: trivial retired (127/1059 -> 127/1054); 0559: the results-artifact mode (114/966 -> 127/1049); 0559: Inputs and evidence sections defer to results-artifact mode (127/1049 -> 127/1059); 0531: the metadata worktree and remote come from the repository.prepare context (114/965 -> 114/966); 0502: the evidence rule keys on the payload's build.gate value; gate-off skipped records are expected (110/913 -> 114/965); 0410: +findings-return capture contract (see note above) - {"docket-new-change/SKILL.md", 48, 1538}, // 0573: trivial retired; the trivial path is deleted and the brainstorm is told the artifact is always a spec (53/1636 -> 48/1538); 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) + {"docket-new-change/SKILL.md", 48, 1552}, // optional acceptance_criteria body (48/1538 -> 48/1552); 0573: trivial retired; the trivial path is deleted and the brainstorm is told the artifact is always a spec (53/1636 -> 48/1538); 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) {"docket-status/SKILL.md", 125, 2956}, // 0575: reclaim and the claim lease are retired, the intentional-skip example names snapshot-retained and snapshot-no-work (126/2990 -> 125/2956); 0573: trivial retired (126/2993 -> 126/2990); 0560: a held change shows on hold (126/2983 -> 126/2993); 0539: derived-view drift is named by family and each finding's own remedy is relayed instead of a code list (126/2923 -> 126/2983); 0531: the metadata worktree and remote come from the repository.prepare context (126/2921 -> 126/2923); 0530: artifact-missing names where a plan or results file may live — the docket branch, or the integration branch for a record closed before the move (126/2904 -> 126/2921); 0529 review: full-scope cleanup retries also repoint stale merged-PR description backlinks; repair --pr-backlinks previews them (126/2880 -> 126/2904); 0502: one metadata layout — the docket branch and the .docket/ worktree (126/2876 -> 126/2880); 0502: findings named as the binary emits them (126/2852 -> 126/2876); 0502: deferred learnings and publication narration is deleted (127/2956 -> 126/2852); 0502: the dummy-mode pointer is deleted (129/2985 -> 127/2956); 0388: +sync-integration prose (see note above) } diff --git a/skills/docket-convention/SKILL.md b/skills/docket-convention/SKILL.md index abe793e4f..ef17a3634 100644 --- a/skills/docket-convention/SKILL.md +++ b/skills/docket-convention/SKILL.md @@ -209,11 +209,12 @@ change, never in the frozen artifact. ### Change body sections -`change.create` writes `## Artifacts`, `## Why`, `## What changes`, and `## Out of scope`; `## Open questions` and every later section are added by later operations. +`change.create` writes `## Artifacts`, `## Why`, `## What changes`, `## Out of scope`, and — when given — `## Acceptance criteria`; `## Open questions` and every later section are added by later operations. - `## Artifacts` — **first body section** (immediately after the frontmatter closing `---`, above `## Why`). Marker-bounded (`` / ``); rendered from frontmatter by the Go app-layer link-block renderer inside the owning metadata transaction; **never hand-edited** — the renderer is the sole writer. Seeded empty by `change.create`; regenerated after every frontmatter field write. Its **reciprocal** is the `docket:backlink` block (markers `` / ``) stamped at the TOP of each artifact (spec, plan, results, PR body) pointing home to the change on the metadata branch, from one shared renderer. Same-branch links (rows and file backlinks) are relative; the PR body's are absolute. `change.attach-plan`, `change.attach-results`, and `change.groom` write the file blocks, `pr.publish` the PR body's, which `finalize.closeout` (retried by `finalize.cleanup`, `maintenance.sweep`) or `repository.repair` with `--pr-backlinks` repoints at the archived record (ADRs excluded, back-referenced by `change:`). - `## Why` — the motivation, as detailed as warranted (no length limit). - `## What changes` — scope of the work. +- `## Acceptance criteria` — optional; verifiable conditions that belong to this change. Written by `change.create` (between What changes and Out of scope) when given; a later owned-section edit that adds it places it in proposal order. Never a build gate. - `## Out of scope` — explicit non-goals. - `## Open questions` — unknowns to resolve during reconcile/design. - `## Reconcile log` — dated entries appended by the implementer's reconcile pass. @@ -225,6 +226,8 @@ change, never in the frozen artifact. - `## Why deferred` / `## Why killed` — added when entering those states. - `## Why on hold` — the optional hold reason, written only by the `hold_reason` key; lifting the hold removes it. +The proposal sections keep the order `## Why`, `## What changes`, `## Acceptance criteria`, `## Out of scope`, `## Open questions` — an edit that adds one places it in that order; every other section added later is appended at the end of the file. + The change body is a **PM-altitude proposal** (intent + scope). Detailed design lives in the linked superpowers spec; the task breakdown in the linked superpowers plan. Different zoom levels, no duplication. ### ADR file (`/-.md`) diff --git a/skills/docket-new-change/SKILL.md b/skills/docket-new-change/SKILL.md index 948c2df05..c3b6501ec 100644 --- a/skills/docket-new-change/SKILL.md +++ b/skills/docket-new-change/SKILL.md @@ -29,7 +29,7 @@ The default path for a new change. Five steps: 3. **Scan related context** — scan neighbouring changes (`active/` + recent `archive/`) and the ADR index to pre-fill `related`, `depends_on`, `adrs`, and — when the human names the change(s) whose work surfaced this one (or scan mode infers an origin) — `discovered_from` (informational, like `related:`; empty for deliberately planned work). In practice, do this quick read just *before* step 2 so the brainstorm is informed by neighbouring work; record the resulting `related`/`depends_on`/`adrs`/`discovered_from` after the design settles. -4. **Create the proposed change** — submit the record through one atomic transaction: the `change.create` operation (resolve argv from the capability catalog) with `--repo-dir --request `. Its closed JSON request carries `title`, `type` (one configured `change_type` — `create` refuses an unknown or empty type, so no created change is ever left `untyped`, and there is no template comment to replace), `priority` (default `medium`), `deliverable: results-artifact` when the work ends in findings, not code (omit it for the default `pr`), the PM-altitude `why`/`what_changes`/`out_of_scope` body distilled from the brainstorm (design detail lives in the linked spec, NOT here), the resolved `depends_on`/`related`/`adrs`/`discovered_from` from step 3, `stacked_on` when the work builds on another change's **unmerged** branch (set it and **read [stacked-changes.md](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how it is built, merged, and closed out), and the stable `request_id` from step 1. The transaction allocates the id, derives the slug, serializes the canonical `status: proposed` record (`created`/`updated` = the commit's UTC date), renders its `## Artifacts` block, and re-renders the inline board — one metadata commit under an exact-lease push, returning the new `id`/`slug`/`path`. +4. **Create the proposed change** — submit the record through one atomic transaction: the `change.create` operation (resolve argv from the capability catalog) with `--repo-dir --request `. Its closed JSON request carries `title`, `type` (one configured `change_type` — `create` refuses an unknown or empty type, so no created change is ever left `untyped`, and there is no template comment to replace), `priority` (default `medium`), `deliverable: results-artifact` when the work ends in findings, not code (omit it for the default `pr`), the PM-altitude `why`/`what_changes`/`out_of_scope` body distilled from the brainstorm, plus an optional `acceptance_criteria` body when the brainstorm settled verifiable conditions for this change (design detail lives in the linked spec, NOT here), the resolved `depends_on`/`related`/`adrs`/`discovered_from` from step 3, `stacked_on` when the work builds on another change's **unmerged** branch (set it and **read [stacked-changes.md](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how it is built, merged, and closed out), and the stable `request_id` from step 1. The transaction allocates the id, derives the slug, serializes the canonical `status: proposed` record (`created`/`updated` = the commit's UTC date), renders its `## Artifacts` block, and re-renders the inline board — one metadata commit under an exact-lease push, returning the new `id`/`slug`/`path`. **Two draft-time scalars ride in the same request** — `auto_groomable` and `branch_prefix`. When the human says the change may be designed without them, send `auto_groomable: true` (so `docket-auto-groom` carries it to build-ready; `false` opts it out). When they name a branch prefix ("use the `hotfix/` prefix"), send it as typed in `branch_prefix` — the operation normalizes it and refuses an unusable value with `invalid-branch_prefix` before anything is written: show the human that finding and ask for a new value. Omit `auto_groomable` to leave the change not auto-groomable; omit `branch_prefix` to use ``. When the design needs a step a person must carry out, suggest a hold; if the human agrees, send `hold: true` (and an optional `hold_reason`) here for a captured stub, or in the step-5 `change.groom` request. From 07f5c869de244faca90da5aca324cd49b10ab954 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 13:56:17 -0500 Subject: [PATCH 7/7] docs: match acceptance-criteria wording to written order and budget idiom --- internal/assets/embedded/manifest.json | 8 ++++---- .../embedded/tree/skills/docket-convention/SKILL.md | 2 +- .../embedded/tree/skills/docket-new-change/SKILL.md | 2 +- internal/repoguard/budgets_test.go | 4 ++-- skills/docket-convention/SKILL.md | 2 +- skills/docket-new-change/SKILL.md | 2 +- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 5a34c6caa..9dd420b23 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,7 +1,7 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:65fed69e738a8fab40f222d7c34d6593082cda5d07b07ea8d6d715a751f306c6", + "asset_set_id": "sha256:d7f5d56a646a8b930ad3d8cd7d127a20a04b14caf23f2f33fb74f8d75863c53a", "entries": [ { "path": ".docket.example.yml", @@ -322,8 +322,8 @@ "path": "skills/docket-convention/SKILL.md", "role": "skill", "mode": 420, - "size": 53141, - "sha256": "e8e6a32628f729415a866a90406865427b5449aea7da28e1bb2cd48cefb8c23b" + "size": 53140, + "sha256": "b433182ecb64c7d8bea9d8566b01bd6189510acdbfbce2ef36ea05d9ac9192f5" }, { "path": "skills/docket-convention/references/agent-layer.md", @@ -421,7 +421,7 @@ "role": "skill", "mode": 420, "size": 10780, - "sha256": "ffc4f0d640b5399884987aa66fabe1ee36fbe05f81ec42c8e6b9005c47177842" + "sha256": "dc0b94574eb6057caef8dc7cff653c75acf4a794a531310cdd5cdbdcd4a2b1da" }, { "path": "skills/docket-review/SKILL.md", diff --git a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md index ef17a3634..a7c600349 100644 --- a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md @@ -209,7 +209,7 @@ change, never in the frozen artifact. ### Change body sections -`change.create` writes `## Artifacts`, `## Why`, `## What changes`, `## Out of scope`, and — when given — `## Acceptance criteria`; `## Open questions` and every later section are added by later operations. +`change.create` writes `## Artifacts`, `## Why`, `## What changes`, `## Acceptance criteria` (only when given), and `## Out of scope`; `## Open questions` and every later section are added by later operations. - `## Artifacts` — **first body section** (immediately after the frontmatter closing `---`, above `## Why`). Marker-bounded (`` / ``); rendered from frontmatter by the Go app-layer link-block renderer inside the owning metadata transaction; **never hand-edited** — the renderer is the sole writer. Seeded empty by `change.create`; regenerated after every frontmatter field write. Its **reciprocal** is the `docket:backlink` block (markers `` / ``) stamped at the TOP of each artifact (spec, plan, results, PR body) pointing home to the change on the metadata branch, from one shared renderer. Same-branch links (rows and file backlinks) are relative; the PR body's are absolute. `change.attach-plan`, `change.attach-results`, and `change.groom` write the file blocks, `pr.publish` the PR body's, which `finalize.closeout` (retried by `finalize.cleanup`, `maintenance.sweep`) or `repository.repair` with `--pr-backlinks` repoints at the archived record (ADRs excluded, back-referenced by `change:`). - `## Why` — the motivation, as detailed as warranted (no length limit). diff --git a/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md b/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md index c3b6501ec..d442aec1b 100644 --- a/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md @@ -29,7 +29,7 @@ The default path for a new change. Five steps: 3. **Scan related context** — scan neighbouring changes (`active/` + recent `archive/`) and the ADR index to pre-fill `related`, `depends_on`, `adrs`, and — when the human names the change(s) whose work surfaced this one (or scan mode infers an origin) — `discovered_from` (informational, like `related:`; empty for deliberately planned work). In practice, do this quick read just *before* step 2 so the brainstorm is informed by neighbouring work; record the resulting `related`/`depends_on`/`adrs`/`discovered_from` after the design settles. -4. **Create the proposed change** — submit the record through one atomic transaction: the `change.create` operation (resolve argv from the capability catalog) with `--repo-dir --request `. Its closed JSON request carries `title`, `type` (one configured `change_type` — `create` refuses an unknown or empty type, so no created change is ever left `untyped`, and there is no template comment to replace), `priority` (default `medium`), `deliverable: results-artifact` when the work ends in findings, not code (omit it for the default `pr`), the PM-altitude `why`/`what_changes`/`out_of_scope` body distilled from the brainstorm, plus an optional `acceptance_criteria` body when the brainstorm settled verifiable conditions for this change (design detail lives in the linked spec, NOT here), the resolved `depends_on`/`related`/`adrs`/`discovered_from` from step 3, `stacked_on` when the work builds on another change's **unmerged** branch (set it and **read [stacked-changes.md](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how it is built, merged, and closed out), and the stable `request_id` from step 1. The transaction allocates the id, derives the slug, serializes the canonical `status: proposed` record (`created`/`updated` = the commit's UTC date), renders its `## Artifacts` block, and re-renders the inline board — one metadata commit under an exact-lease push, returning the new `id`/`slug`/`path`. +4. **Create the proposed change** — submit the record through one atomic transaction: the `change.create` operation (resolve argv from the capability catalog) with `--repo-dir --request `. Its closed JSON request carries `title`, `type` (one configured `change_type` — `create` refuses an unknown or empty type, so no created change is ever left `untyped`, and there is no template comment to replace), `priority` (default `medium`), `deliverable: results-artifact` when the work ends in findings, not code (omit it for the default `pr`), the PM-altitude `why`/`what_changes`/`out_of_scope` body distilled from the brainstorm (design detail lives in the linked spec, NOT here), plus an optional `acceptance_criteria` body when the brainstorm settled verifiable conditions for this change, the resolved `depends_on`/`related`/`adrs`/`discovered_from` from step 3, `stacked_on` when the work builds on another change's **unmerged** branch (set it and **read [stacked-changes.md](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how it is built, merged, and closed out), and the stable `request_id` from step 1. The transaction allocates the id, derives the slug, serializes the canonical `status: proposed` record (`created`/`updated` = the commit's UTC date), renders its `## Artifacts` block, and re-renders the inline board — one metadata commit under an exact-lease push, returning the new `id`/`slug`/`path`. **Two draft-time scalars ride in the same request** — `auto_groomable` and `branch_prefix`. When the human says the change may be designed without them, send `auto_groomable: true` (so `docket-auto-groom` carries it to build-ready; `false` opts it out). When they name a branch prefix ("use the `hotfix/` prefix"), send it as typed in `branch_prefix` — the operation normalizes it and refuses an unusable value with `invalid-branch_prefix` before anything is written: show the human that finding and ask for a new value. Omit `auto_groomable` to leave the change not auto-groomable; omit `branch_prefix` to use ``. When the design needs a step a person must carry out, suggest a hold; if the human agrees, send `hold: true` (and an optional `hold_reason`) here for a captured stub, or in the step-5 `change.groom` request. diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index e0bee6c74..ed992bea6 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -199,7 +199,7 @@ var skillBudgets = []skillBudget{ {"docket-build/references/gate-driver.md", 138, 1552}, // 0502 review: the raw-verb section names finalize's repaired-head re-gate (137/1546 -> 138/1552); 0502: "loop" means /loop only (137/1550 -> 137/1546); 0502: finalize's repaired-head re-gate is a direct caller (136/1523 -> 137/1550); 0502: the gate-execution intro reference is deleted (138/1555 -> 136/1523); 0502: renamed from gate-caller-loop.md; 0497: +halted-gate tree-survives finding relay (134/1510 -> 138/1555); 0491: the run id is retired (134/1513 -> 134/1510); 0490: the admission section describes the supervisor-held worktree lock; launch-unconfirmed is no longer a refusal (136/1511 -> 134/1513); 0488 review fix: finalize reaches the driver only through finalize.rebase; task-era handoff clauses dropped (word ceiling 1504 -> 1511); 0488 review: start row carries --change-id (word ceiling 1491 -> 1504); 0488: worker-scope/takeover/acknowledge rows and the parent-takeover section removed; callers are the full-suite gates (175/1872 -> 136/1491); 0467: +prepare-scope --run-id and scope-inherited start run id (word ceiling 1826 -> 1872); 0375: +worktree-admission section (word ceiling 1750 -> 1826) {"docket-build/references/task-routing.md", 50, 500}, {"docket-build-task/SKILL.md", 173, 1695}, // 0532: the private-repository writing rule and visibility hand-off (168/1640 -> 173/1695); 0531: the metadata worktree and remote come from the repository.prepare context (168/1637 -> 168/1640); 0488: scoped drive protocol replaced by direct foreground tests under timeout; three outcomes (211/2235 -> 168/1637); 0467 review fix: +the repair re-run run-id exception (206/2183 -> 211/2235); 0467: +the run id rides on the scope, never the bundle (204/2151 -> 206/2183); 0459: +post-handoff continuation never acknowledges or reuses the transferred scope (188/1964 -> 204/2151); 0405: sequential-drive receipt and acknowledgement; 0420: shell-safe capture; 0375: worktree-busy-not-a-retry rule (179/1842 -> 188/1964) - {"docket-convention/SKILL.md", 356, 7352}, // acceptance criteria section and proposal order (353/7259 -> 356/7352); 0578: docket-export joins the inline skills (353/7257 -> 353/7259); 0575: reclaim and the claim lease are retired (361/7377 -> 353/7257); 0360: claimed_at is stamped by claim, reconcile, and resume-halted; a halt no longer claims a refreshed lease (361/7381 -> 361/7377); 0573: trivial retired (362/7411 -> 361/7381); 0560: the hold manifest field, its selection rule, the ## Why on hold section, and the auto-groomer's hold write (360/7331 -> 362/7411); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) + {"docket-convention/SKILL.md", 356, 7352}, // 0582: acceptance criteria section and proposal order (353/7259 -> 356/7352); 0578: docket-export joins the inline skills (353/7257 -> 353/7259); 0575: reclaim and the claim lease are retired (361/7377 -> 353/7257); 0360: claimed_at is stamped by claim, reconcile, and resume-halted; a halt no longer claims a refreshed lease (361/7381 -> 361/7377); 0573: trivial retired (362/7411 -> 361/7381); 0560: the hold manifest field, its selection rule, the ## Why on hold section, and the auto-groomer's hold write (360/7331 -> 362/7411); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) // 0154: docket-convention/github-board-mirror.md removed — the GitHub mirror is // retired (unsupported, mutation-blocking); its budget row is deleted with it. {"docket-convention/references/agent-layer.md", 214, 1991}, // 0578: docket-export joins the inline skills (214/1989 -> 214/1991); 0552: the user-level settings.json also carries the finalize allow rules (212/1951 -> 214/1990); 0546: the per-agent cache_ttl pin, its shipped 1h default, and the machine-wide controls docket leaves unset (168/1593 -> 212/1951); 0538: init and repository.configure-harnesses set agent_harnesses; repository.check reports harnesses-unset (164/1553 -> 168/1593); 0535: a private repository's instructions file and its user-level triggers (148/1419 -> 164/1553); 0502: rewritten around user-level wrappers and global-only pins (202/2346 -> 148/1419); 0502: the legacy agents-file migration clause is deleted (202/2349 -> 202/2346) @@ -216,7 +216,7 @@ var skillBudgets = []skillBudget{ {"docket-implement-next/references/results-artifact.md", 76, 737}, // 0360: no claim refreshes; change.complete pins a locally looked-up revision (79/765 -> 76/737); 0573: trivial retired (79/775 -> 79/765); 0559: new — the results-artifact ending (no plan, build, or PR; review, complete, clean up) {"docket-implement-next/results-template.md", 70, 543}, // 0573: trivial retired (70/545 -> 70/543); 0502 rebase onto 0510: carried the backlog verdict and next action in the Known issues placeholder (68/506 -> 70/545); 0502: inline review replaces the custom review skill (68/511 -> 68/510); 0498: +whole-branch review summary line in Verification performed (64/446 -> 68/511); 0440: reader-first template — action statement + merged Known issues (see note above); 0502: drop change citations and Go v1 narration (68/510 -> 68/506) {"docket-review/SKILL.md", 127, 1054}, // 0573: trivial retired (127/1059 -> 127/1054); 0559: the results-artifact mode (114/966 -> 127/1049); 0559: Inputs and evidence sections defer to results-artifact mode (127/1049 -> 127/1059); 0531: the metadata worktree and remote come from the repository.prepare context (114/965 -> 114/966); 0502: the evidence rule keys on the payload's build.gate value; gate-off skipped records are expected (110/913 -> 114/965); 0410: +findings-return capture contract (see note above) - {"docket-new-change/SKILL.md", 48, 1552}, // optional acceptance_criteria body (48/1538 -> 48/1552); 0573: trivial retired; the trivial path is deleted and the brainstorm is told the artifact is always a spec (53/1636 -> 48/1538); 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) + {"docket-new-change/SKILL.md", 48, 1552}, // 0582: optional acceptance_criteria body (48/1538 -> 48/1552); 0573: trivial retired; the trivial path is deleted and the brainstorm is told the artifact is always a spec (53/1636 -> 48/1538); 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) {"docket-status/SKILL.md", 125, 2956}, // 0575: reclaim and the claim lease are retired, the intentional-skip example names snapshot-retained and snapshot-no-work (126/2990 -> 125/2956); 0573: trivial retired (126/2993 -> 126/2990); 0560: a held change shows on hold (126/2983 -> 126/2993); 0539: derived-view drift is named by family and each finding's own remedy is relayed instead of a code list (126/2923 -> 126/2983); 0531: the metadata worktree and remote come from the repository.prepare context (126/2921 -> 126/2923); 0530: artifact-missing names where a plan or results file may live — the docket branch, or the integration branch for a record closed before the move (126/2904 -> 126/2921); 0529 review: full-scope cleanup retries also repoint stale merged-PR description backlinks; repair --pr-backlinks previews them (126/2880 -> 126/2904); 0502: one metadata layout — the docket branch and the .docket/ worktree (126/2876 -> 126/2880); 0502: findings named as the binary emits them (126/2852 -> 126/2876); 0502: deferred learnings and publication narration is deleted (127/2956 -> 126/2852); 0502: the dummy-mode pointer is deleted (129/2985 -> 127/2956); 0388: +sync-integration prose (see note above) } diff --git a/skills/docket-convention/SKILL.md b/skills/docket-convention/SKILL.md index ef17a3634..a7c600349 100644 --- a/skills/docket-convention/SKILL.md +++ b/skills/docket-convention/SKILL.md @@ -209,7 +209,7 @@ change, never in the frozen artifact. ### Change body sections -`change.create` writes `## Artifacts`, `## Why`, `## What changes`, `## Out of scope`, and — when given — `## Acceptance criteria`; `## Open questions` and every later section are added by later operations. +`change.create` writes `## Artifacts`, `## Why`, `## What changes`, `## Acceptance criteria` (only when given), and `## Out of scope`; `## Open questions` and every later section are added by later operations. - `## Artifacts` — **first body section** (immediately after the frontmatter closing `---`, above `## Why`). Marker-bounded (`` / ``); rendered from frontmatter by the Go app-layer link-block renderer inside the owning metadata transaction; **never hand-edited** — the renderer is the sole writer. Seeded empty by `change.create`; regenerated after every frontmatter field write. Its **reciprocal** is the `docket:backlink` block (markers `` / ``) stamped at the TOP of each artifact (spec, plan, results, PR body) pointing home to the change on the metadata branch, from one shared renderer. Same-branch links (rows and file backlinks) are relative; the PR body's are absolute. `change.attach-plan`, `change.attach-results`, and `change.groom` write the file blocks, `pr.publish` the PR body's, which `finalize.closeout` (retried by `finalize.cleanup`, `maintenance.sweep`) or `repository.repair` with `--pr-backlinks` repoints at the archived record (ADRs excluded, back-referenced by `change:`). - `## Why` — the motivation, as detailed as warranted (no length limit). diff --git a/skills/docket-new-change/SKILL.md b/skills/docket-new-change/SKILL.md index c3b6501ec..d442aec1b 100644 --- a/skills/docket-new-change/SKILL.md +++ b/skills/docket-new-change/SKILL.md @@ -29,7 +29,7 @@ The default path for a new change. Five steps: 3. **Scan related context** — scan neighbouring changes (`active/` + recent `archive/`) and the ADR index to pre-fill `related`, `depends_on`, `adrs`, and — when the human names the change(s) whose work surfaced this one (or scan mode infers an origin) — `discovered_from` (informational, like `related:`; empty for deliberately planned work). In practice, do this quick read just *before* step 2 so the brainstorm is informed by neighbouring work; record the resulting `related`/`depends_on`/`adrs`/`discovered_from` after the design settles. -4. **Create the proposed change** — submit the record through one atomic transaction: the `change.create` operation (resolve argv from the capability catalog) with `--repo-dir --request `. Its closed JSON request carries `title`, `type` (one configured `change_type` — `create` refuses an unknown or empty type, so no created change is ever left `untyped`, and there is no template comment to replace), `priority` (default `medium`), `deliverable: results-artifact` when the work ends in findings, not code (omit it for the default `pr`), the PM-altitude `why`/`what_changes`/`out_of_scope` body distilled from the brainstorm, plus an optional `acceptance_criteria` body when the brainstorm settled verifiable conditions for this change (design detail lives in the linked spec, NOT here), the resolved `depends_on`/`related`/`adrs`/`discovered_from` from step 3, `stacked_on` when the work builds on another change's **unmerged** branch (set it and **read [stacked-changes.md](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how it is built, merged, and closed out), and the stable `request_id` from step 1. The transaction allocates the id, derives the slug, serializes the canonical `status: proposed` record (`created`/`updated` = the commit's UTC date), renders its `## Artifacts` block, and re-renders the inline board — one metadata commit under an exact-lease push, returning the new `id`/`slug`/`path`. +4. **Create the proposed change** — submit the record through one atomic transaction: the `change.create` operation (resolve argv from the capability catalog) with `--repo-dir --request `. Its closed JSON request carries `title`, `type` (one configured `change_type` — `create` refuses an unknown or empty type, so no created change is ever left `untyped`, and there is no template comment to replace), `priority` (default `medium`), `deliverable: results-artifact` when the work ends in findings, not code (omit it for the default `pr`), the PM-altitude `why`/`what_changes`/`out_of_scope` body distilled from the brainstorm (design detail lives in the linked spec, NOT here), plus an optional `acceptance_criteria` body when the brainstorm settled verifiable conditions for this change, the resolved `depends_on`/`related`/`adrs`/`discovered_from` from step 3, `stacked_on` when the work builds on another change's **unmerged** branch (set it and **read [stacked-changes.md](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how it is built, merged, and closed out), and the stable `request_id` from step 1. The transaction allocates the id, derives the slug, serializes the canonical `status: proposed` record (`created`/`updated` = the commit's UTC date), renders its `## Artifacts` block, and re-renders the inline board — one metadata commit under an exact-lease push, returning the new `id`/`slug`/`path`. **Two draft-time scalars ride in the same request** — `auto_groomable` and `branch_prefix`. When the human says the change may be designed without them, send `auto_groomable: true` (so `docket-auto-groom` carries it to build-ready; `false` opts it out). When they name a branch prefix ("use the `hotfix/` prefix"), send it as typed in `branch_prefix` — the operation normalizes it and refuses an unusable value with `invalid-branch_prefix` before anything is written: show the human that finding and ask for a new value. Omit `auto_groomable` to leave the change not auto-groomable; omit `branch_prefix` to use ``. When the design needs a step a person must carry out, suggest a hold; if the human agrees, send `hold: true` (and an optional `hold_reason`) here for a captured stub, or in the step-5 `change.groom` request.